centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 06:18:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #23926 from dvdksn/cagent-docfixer-improvements

Browse Source 
agent: improvements to cagent issue fixer workflow
This commit is contained in:
David Karlsson
2026-01-07 13:51:28 +01:00
committed by GitHub
parent b9dfbbd757 e628c62978
commit d4dc754a94
3 changed files with 71 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
.github/workflows/agent.yml vendored
View File

@@ -21,18 +21,9 @@ jobs:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Configure Git
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
- name: Install dependencies
run: npm ci
- name: Create branch
run: |
git checkout -b agent/issue-${{ github.event.issue.number }}
- name: Run agent
uses: docker/cagent-action@v1.0.3
timeout-minutes: 15
@@ -44,11 +35,27 @@ jobs:
Work on GitHub issue: ${{ github.event.issue.html_url }}
Fetch the issue, analyze what documentation changes are needed, and
implement them following your standard workflow.
implement them.
If you identify any upstream coordination issues (broken links from
vendored content, missing CLI flags, etc.), document them in
.upstream-issues.md as specified in your instructions.
When complete, write .pr-body.md following this structure:
## Summary
One sentence describing what was fixed/added/changed.
## Changes
Bulleted list of specific changes (be concise, focus on what matters).
## Upstream coordination needed
Only include this section if there are issues requiring fixes in upstream
repos (docker/cli, moby/moby, etc.). Otherwise omit it entirely.
Fixes #${{ github.event.issue.number }}
---
🤖 Generated with [cagent](https://github.com/docker/cagent)
Keep the PR body brief and practical. Don't over-explain or add sections
that aren't needed.
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -56,15 +63,22 @@ jobs:
- name: Check for changes
id: changes
run: |
if [[ -n $(git status --porcelain) ]]; then
echo "has_changes=true" >> $GITHUB_OUTPUT
else
if git diff --quiet; then
echo "has_changes=false" >> $GITHUB_OUTPUT
else
echo "has_changes=true" >> $GITHUB_OUTPUT
fi
- name: Commit changes
- name: Commit and push
if: steps.changes.outputs.has_changes == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
BRANCH="agent/issue-${{ github.event.issue.number }}"
git checkout -b "$BRANCH"
git add .
git commit -m "docs: address issue #${{ github.event.issue.number }}
@@ -73,41 +87,17 @@ jobs:
🤖 Generated with cagent"
- name: Push changes
if: steps.changes.outputs.has_changes == 'true'
run: |
git push -u origin agent/issue-${{ github.event.issue.number }}
git push origin "$BRANCH"
- name: Create pull request
if: steps.changes.outputs.has_changes == 'true'
env:
GH_TOKEN: ${{ github.token }}
PR_BODY: |
## Summary
This PR addresses #${{ github.event.issue.number }}.
## Changes
The documentation agent team analyzed the issue and implemented the requested changes.
🤖 Generated with [cagent](https://github.com/docker/cagent)
Closes #${{ github.event.issue.number }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# Add upstream coordination section if file exists
if [[ -f .upstream-issues.md ]]; then
UPSTREAM_SECTION=$(cat .upstream-issues.md)
FULL_PR_BODY="${PR_BODY/Closes #/$UPSTREAM_SECTION\n\nCloses #}"
else
FULL_PR_BODY="$PR_BODY"
fi
gh pr create \
--title "docs: address issue #${{ github.event.issue.number }}" \
--body "$FULL_PR_BODY" \
--base main \
--head agent/issue-${{ github.event.issue.number }}
--body-file .pr-body.md \
--label agent/generated
- name: Comment on issue (success)
if: steps.changes.outputs.has_changes == 'true'

2
.gitignore vendored
View File

@@ -15,5 +15,5 @@ tmp
cagent
# cagent tmp files
.cagent
.upstream-issues.md
.pr-body.md
.validation.log

143
agent.yml
View File

@@ -26,25 +26,23 @@ agents:
3. **Read for context**: Use filesystem tools to read specific files and
understand the current state.
4. **Hand off to writer**: Use the handoff tool to switch to the writer
agent with clear task description:
4. **Delegate to writer**: Delegate to the writer sub-agent with clear
instructions:
- What needs to be written/updated
- Which files are involved
- Related docs to consider
- Any specific requirements
The writer will hand off directly to editor, who will hand off to
reviewer. You'll be involved again if issues need triage or the work is
complete.
5. **Delegate to editor**: After the writer completes their work, delegate
to the editor sub-agent to polish, validate, and fix any issues.
5. **Handle completion**: When the reviewer is done, analyze results:
6. **Handle completion**: When the editor is done, analyze results:
- **Validation passed**: Work is complete
- **Local issues remain**: Coordinate fixes (rare - editor should
handle)
- **Local issues remain**: Delegate back to editor to fix
- **Upstream coordination issues**: Document for follow-up, don't block
completion
6. **Complete**: When validation passes OR only upstream issues remain,
7. **Complete**: When validation passes OR only upstream issues remain,
the work is done
## Documentation context
@@ -103,21 +101,9 @@ agents:
**When you identify upstream issues:**
1. Verify it's truly an upstream issue (check file path and source)
2. Document what upstream work is needed:
- Which repo owns the content (docker/cli, docker/buildx, moby/moby)
- What needs to be fixed (broken link, missing anchor, etc.)
- The specific file/command involved
3. Write upstream issues to `.upstream-issues.md` in this format:
```markdown
## Upstream coordination needed
### [Repo name]
- **Issue**: Brief description
- **Location**: Specific file/command
- **Action needed**: What needs to be fixed upstream
```
4. **Do not block completion** - if local changes are correct, upstream
2. Note briefly what upstream work is needed (which repo, what needs
fixing)
3. **Do not block completion** - if local changes are correct, upstream
work is separate
**How to identify upstream vs local issues:**
@@ -141,13 +127,6 @@ agents:
- Dockerfile reference → moby/buildkit
- Engine API reference → moby/moby
## Tracking work
Use the todo toolset for multi-step work:
- Create todos for each major step before starting
- Update status as work progresses
- Check list_todos regularly to ensure nothing is missed
toolsets:
- type: filesystem
- type: todo
@@ -156,11 +135,6 @@ agents:
sub_agents:
- writer
- editor
- reviewer
handoffs:
- writer
- editor
- reviewer
writer:
model: sonnet
@@ -251,39 +225,27 @@ agents:
1. If updating existing content, read it first
2. Understand the topic and what needs to be documented
3. Search for related content and examples (use your RAG search tool)
3. Use filesystem tools (glob, grep, read) to find related content and
examples
4. Write clear, conversational content following the principles above
5. Focus on content - the editor handles formatting, syntax, and style
6. When done, hand off to the editor using the handoff tool
6. When done, your work returns to the root agent
Write files directly. Don't just provide drafts.
## Using the RAG search tool
You have access to search the documentation repository. Use it to:
- Find how similar topics are documented
- Learn from well-written examples
- Discover patterns and conventions
- Check what already exists
Search by concept ("how to document prerequisites") or exact terms
("Docker Compose").
toolsets:
- type: filesystem
- type: shell
rag:
- docs
handoffs:
- editor
- root
# rag:
# - docs # Disabled: queries sometimes hang, needs investigation
editor:
model: sonnet
description: Editor that polishes documentation for formatting and style
description: Editor that polishes, validates, and fixes documentation
instruction: |
You polish documentation to meet strict formatting and style standards.
The writer creates content; you make it perfect.
You polish documentation to meet strict formatting and style standards,
then validate it passes all automated checks. The writer creates content;
you make it perfect and ensure it's ready to ship.
## What you fix
@@ -347,64 +309,32 @@ agents:
5. Polish style (voice, tense, punctuation, conciseness)
6. Run prettier: `npx prettier --write <file>`
7. Write the polished version
8. Hand off to the reviewer using the handoff tool
8. Use the validate tool to run automated checks
9. Read the validation log at .validation.log (first 2000 lines to start)
10. If validation passes: Report success and return to root agent
11. If validation fails: Fix the issues and repeat from step 8
Be thorough but don't change the meaning or add new content. You're
polishing what the writer created, not rewriting it.
The validate tool runs markdownlint, HTML validation, link checking, and
other structural checks. Vale (prose linting) runs separately in CI and
is not included to avoid excessive output.
If you need to see more of the validation log, use the Read tool with
offset/limit parameters.
The complete style guide is in content/contribute/style/ if you need
reference.
toolsets:
- type: filesystem
- type: shell
handoffs:
- reviewer
- writer
- root
reviewer:
model: haiku
description: Documentation validator that runs automated checks
instruction: |
You validate documentation by running the validation suite. The writer
creates content, the editor polishes it, and you verify it passes all
automated checks.
## Your workflow
When asked to review documentation:
1. Run validation and save output to a file in the working directory:
`docker buildx bake validate > .validation.log 2>&1`
2. Read the log file to check for errors.
The file can be large - read the first 2000 lines to start.
3. Analyze results:
- **No errors**: Confirm validation passed and explain that work is
complete
- **Errors found**: Report them with specific details (file names, line
numbers, what's wrong)
4. For errors, suggest next steps:
- **Fixable locally**: Hand off to editor to fix
- **Unclear if upstream**: Explain the issue so root agent can triage
The validate target runs markdownlint, HTML validation, link checking, and
other structural checks. Vale (prose linting) runs separately in CI and
is not included to avoid excessive output.
If you need to see more of the log, use the Read tool with offset/limit
parameters.
toolsets:
- type: filesystem
- type: shell
handoffs:
- editor
- writer
- root
- type: script
shell:
validate:
cmd: "docker buildx bake validate > .validation.log 2>&1"
description: Run documentation validation checks (markdownlint, HTML validation, link checking)
rag:
docs:
@@ -421,9 +351,6 @@ rag:
limit: 10
models:
haiku:
provider: anthropic
model: claude-haiku-4-5
sonnet:
provider: anthropic
model: claude-sonnet-4-5