From f7b2cc073e3a16c74b7cef118ef67f6714c09602 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Sat, 27 Dec 2025 15:36:45 +0100 Subject: [PATCH 1/2] chore(cagent): use sub_agents, streamline instructions Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- agent.yml | 141 +++++++++++++----------------------------------------- 1 file changed, 34 insertions(+), 107 deletions(-) diff --git a/agent.yml b/agent.yml index 44017970a839..6aab1d8701a5 100644 --- a/agent.yml +++ b/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 ` 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 From e628c6297821184a89b244915f96bd45d79fa4a8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Sat, 27 Dec 2025 15:37:50 +0100 Subject: [PATCH 2/2] ci: improve agent/fix workflow Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .github/workflows/agent.yml | 80 ++++++++++++++++--------------------- .gitignore | 2 +- 2 files changed, 36 insertions(+), 46 deletions(-) diff --git a/.github/workflows/agent.yml b/.github/workflows/agent.yml index 87cf400614b1..9b418b050d96 100644 --- a/.github/workflows/agent.yml +++ b/.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/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. + + 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 }} @@ -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' diff --git a/.gitignore b/.gitignore index 60699f1d6b4a..9b19ea74843f 100644 --- a/.gitignore +++ b/.gitignore @@ -14,5 +14,5 @@ tmp cagent # cagent tmp files .cagent -.upstream-issues.md +.pr-body.md .validation.log