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

agent: improvements to cagent issue fixer workflow

Author: dvdksn

.github/workflows/agent.yml

@@ -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/[email protected]
         timeout-minutes: 15
@@ -44,27 +35,50 @@ 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.
+
+            When complete, write .pr-body.md following this structure:
 
-            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.
+            ## 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 }}
 
       - 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'

.gitignore

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

agent.yml

@@ -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 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
+      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 log, use the Read tool with offset/limit
-      parameters.
+      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:
-      - 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