From adec69566e979682131ce0a3925ef8fdad479291 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 7 Mar 2026 16:53:04 -0800 Subject: [PATCH 1/2] agents|feat: Add artifact-write safeguards to subagent prompts Add four independent safeguards to ensure subagents produce their artifact files before exhausting their turn budget: 1. Increase aspect reviewer maxTurns from 15 to 20 (frontmatter, SKILL.md table, review-cycle.md dispatch) 2. Add turn-budget awareness section to all 10 subagent files with HARD-GATE reserve-last-3-turns rule 3. Restructure process sections in 4 reviewer agents to write artifacts early and refine if turns remain 4. Add efficiency guidance (diff-first, batch reads, skip irrelevant) to 3 reviewer agents --- .../content/skills/orchestrate/SKILL.md | 6 ++--- .../orchestrate/modules/review-cycle.md | 6 ++--- .../content/subagents/aspect-code-reviewer.md | 26 ++++++++++++++----- .../aspect-silent-failure-reviewer.md | 19 +++++++++----- .../content/subagents/aspect-test-reviewer.md | 25 +++++++++++++----- .../subagents/orchestrated-architect.md | 8 ++++++ .../content/subagents/orchestrated-coder.md | 8 ++++++ .../content/subagents/orchestrated-planner.md | 8 ++++++ .../subagents/orchestrated-reviewer.md | 20 +++++++++++--- .../agents/content/subagents/plan-reviewer.md | 8 ++++++ .../agents/content/subagents/plan-reviser.md | 8 ++++++ packages/agents/content/subagents/planner.md | 8 ++++++ 12 files changed, 122 insertions(+), 28 deletions(-) diff --git a/packages/agents/content/skills/orchestrate/SKILL.md b/packages/agents/content/skills/orchestrate/SKILL.md index f74e8144..8648fe54 100644 --- a/packages/agents/content/skills/orchestrate/SKILL.md +++ b/packages/agents/content/skills/orchestrate/SKILL.md @@ -326,9 +326,9 @@ Always pass `max_turns` explicitly to every Task call: | orchestrated-planner | 40 | | orchestrated-coder | 80 | | orchestrated-reviewer | 30 | -| aspect-code-reviewer | 15 | -| aspect-silent-failure-reviewer | 15 | -| aspect-test-reviewer | 15 | +| aspect-code-reviewer | 20 | +| aspect-silent-failure-reviewer | 20 | +| aspect-test-reviewer | 20 | | pr-review-toolkit:code-simplifier | 15 | | orchestrated-reviewer (final) | 30 | diff --git a/packages/agents/content/skills/orchestrate/modules/review-cycle.md b/packages/agents/content/skills/orchestrate/modules/review-cycle.md index 20809cd8..a5379379 100644 --- a/packages/agents/content/skills/orchestrate/modules/review-cycle.md +++ b/packages/agents/content/skills/orchestrate/modules/review-cycle.md @@ -86,7 +86,7 @@ Call Task with `subagent_type: orchestrated-reviewer`, `max_turns: 30`, `model: > > Write your review to: `{run-dir}/{NN}_reviewer_review.md` -Call Task with `subagent_type: aspect-silent-failure-reviewer`, `max_turns: 15`, `model: {models.aspect_silent_failure_reviewer}` (if activated): +Call Task with `subagent_type: aspect-silent-failure-reviewer`, `max_turns: 20`, `model: {models.aspect_silent_failure_reviewer}` (if activated): > Review the code changes on this branch for error-handling and silent-failure issues. > @@ -99,7 +99,7 @@ Call Task with `subagent_type: aspect-silent-failure-reviewer`, `max_turns: 15`, > > Write your findings to: `{run-dir}/{NN}_silent-failure-reviewer_silent-failure-review.md` -Call Task with `subagent_type: aspect-test-reviewer`, `max_turns: 15`, `model: {models.aspect_test_reviewer}` (if activated): +Call Task with `subagent_type: aspect-test-reviewer`, `max_turns: 20`, `model: {models.aspect_test_reviewer}` (if activated): > Review the code changes on this branch for test-coverage quality, behavioral gaps, and missing edge cases. > @@ -114,7 +114,7 @@ Call Task with `subagent_type: aspect-test-reviewer`, `max_turns: 15`, `model: { > > Write your findings to: `{run-dir}/{NN}_test-reviewer_test-review.md` -Call Task with `subagent_type: aspect-code-reviewer`, `max_turns: 15`, `model: {models.aspect_code_reviewer}` (if activated): +Call Task with `subagent_type: aspect-code-reviewer`, `max_turns: 20`, `model: {models.aspect_code_reviewer}` (if activated): > Review the code changes on this branch for CLAUDE.md compliance, bugs, and logic errors. > diff --git a/packages/agents/content/subagents/aspect-code-reviewer.md b/packages/agents/content/subagents/aspect-code-reviewer.md index 4d335685..3d7ac6ce 100644 --- a/packages/agents/content/subagents/aspect-code-reviewer.md +++ b/packages/agents/content/subagents/aspect-code-reviewer.md @@ -2,7 +2,7 @@ name: aspect-code-reviewer description: Review code changes for CLAUDE.md compliance, bugs, and logic errors. Outputs structured findings with criticality classification for flow control. tools: [Read, Grep, Glob, Bash, Write] -maxTurns: 15 +maxTurns: 20 skills: - anti-patterns - common-mistakes @@ -29,12 +29,16 @@ You will receive: 1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions 2. **Get the diff**: run the provided `git diff` command to see all changes in scope -3. **Read changed files**: read the full files to understand context -4. **Evaluate guideline compliance**: check for violations of project conventions, naming patterns, file organization, and coding standards defined in the project's configuration files -5. **Check for bugs**: look for logic errors, incorrect conditions, off-by-one errors, null/undefined risks, race conditions, and other correctness issues -6. **Classify each finding**: assign category (F/W/T/R/S/L) -7. **Classify overall criticality**: determine the overall review outcome -8. **Write review file**: output to artifact directory +3. **Read changed files**: read the full files to understand context (but see efficiency note below) +4. **Form preliminary findings**: identify potential guideline violations and bugs from what you've read so far +5. **Write your artifact**: write the review file to the output path with your current findings, criticality classification, and return block — even if your analysis feels incomplete. A partial review is infinitely more valuable than no review. +6. **Refine if turns remain**: if you have remaining turns, continue analysis and **update** the artifact with additional or revised findings. Do not start a new file — edit the existing one. + +### Efficiency + +- **Diff-first**: read the diff before reading full files. Only read full file contents for files where the diff reveals potential issues in your scope. +- **Batch reads**: when reading multiple files, use parallel tool calls rather than sequential ones. +- **Skip irrelevant files**: if the diff for a file shows only documentation, formatting, or test changes, skip reading its full content. ## Scope @@ -137,6 +141,14 @@ Scope re-reviews to your domain: project guideline compliance, bugs, and logic e - **Proportional**: a typo fix doesn't need the same scrutiny as a security-critical change. Match your depth to the risk. - **Stay in scope**: do not comment on error handling patterns or test coverage +## Turn budget + +You have **20 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/aspect-silent-failure-reviewer.md b/packages/agents/content/subagents/aspect-silent-failure-reviewer.md index 18dde0cc..8dc7ad27 100644 --- a/packages/agents/content/subagents/aspect-silent-failure-reviewer.md +++ b/packages/agents/content/subagents/aspect-silent-failure-reviewer.md @@ -2,7 +2,7 @@ name: aspect-silent-failure-reviewer description: Review code changes for error-handling and silent-failure issues. Outputs structured findings with criticality classification for flow control. tools: [Read, Grep, Glob, Bash, Write] -maxTurns: 15 +maxTurns: 20 skills: - anti-patterns - get-default-branch @@ -28,11 +28,10 @@ You will receive: 1. **Get the diff**: run the provided `git diff` command to see all changes in scope 2. **Read changed files**: read the full files to understand error-handling context -3. **Check relevance**: if the diff contains no error-handling code (no try/catch, no `.catch()`, no error callbacks, no fallback patterns, no error suppression), produce `### Criticality: none` and stop -4. **Evaluate error handling**: look for silent failures, swallowed exceptions, empty catch blocks, overly broad catches, missing error propagation, and fallback behavior that masks problems -5. **Classify each finding**: assign category (F/W/T/R/S/L) -6. **Classify overall criticality**: determine the overall review outcome -7. **Write review file**: output to artifact directory +3. **Check relevance**: if the diff contains no error-handling code (no try/catch, no `.catch()`, no error callbacks, no fallback patterns, no error suppression), write `### Criticality: none` to the artifact and stop +4. **Form preliminary findings**: identify potential silent failures and error-handling issues from what you've read so far +5. **Write your artifact**: write the review file to the output path with your current findings, criticality classification, and return block — even if your analysis feels incomplete. A partial review is infinitely more valuable than no review. +6. **Refine if turns remain**: if you have remaining turns, continue analysis and **update** the artifact with additional or revised findings. Do not start a new file — edit the existing one. ## Scope @@ -134,6 +133,14 @@ Scope re-reviews to your domain: error handling, catch blocks, fallback behavior - **Proportional**: match scrutiny to the risk level of the code being reviewed - **Stay in scope**: do not comment on anything outside error handling and failure modes +## Turn budget + +You have **20 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/aspect-test-reviewer.md b/packages/agents/content/subagents/aspect-test-reviewer.md index 7c377f57..f5236321 100644 --- a/packages/agents/content/subagents/aspect-test-reviewer.md +++ b/packages/agents/content/subagents/aspect-test-reviewer.md @@ -2,7 +2,7 @@ name: aspect-test-reviewer description: Review code changes for test coverage quality, behavioral gaps, and missing edge cases. Outputs structured findings with criticality classification for flow control. tools: [Read, Grep, Glob, Bash, Write] -maxTurns: 15 +maxTurns: 20 skills: - anti-patterns - common-mistakes @@ -30,12 +30,17 @@ You will receive: 1. **Get the diff**: run the provided `git diff` command to see all changes in scope 2. **Read changed files**: read both source and test files in full to understand context -3. **Check relevance**: if the change contains no new or modified source files that require test coverage (e.g., only documentation, configuration, or formatting changes), produce `### Criticality: none` and stop +3. **Check relevance**: if the change contains no new or modified source files that require test coverage (e.g., only documentation, configuration, or formatting changes), write `### Criticality: none` to the artifact and stop 4. **Map source to tests**: identify which source files have corresponding test files, and which new source files lack tests entirely -5. **Evaluate coverage quality**: look for behavioral gaps, missing edge cases, untested error paths, and tests that don't actually verify what they claim -6. **Classify each finding**: assign category (F/W/T/R/S/L) -7. **Classify overall criticality**: determine the overall review outcome -8. **Write review file**: output to artifact directory +5. **Form preliminary findings**: identify behavioral gaps, missing edge cases, and test quality issues from what you've read so far +6. **Write your artifact**: write the review file to the output path with your current findings, criticality classification, and return block — even if your analysis feels incomplete. A partial review is infinitely more valuable than no review. +7. **Refine if turns remain**: if you have remaining turns, continue analysis and **update** the artifact with additional or revised findings. Do not start a new file — edit the existing one. + +### Efficiency + +- **Diff-first**: read the diff before reading full files. Only read full file contents for files where the diff reveals potential test coverage concerns. +- **Batch reads**: when reading multiple files, use parallel tool calls rather than sequential ones. +- **Skip irrelevant files**: if a changed file is purely configuration, documentation, or formatting, skip it — it doesn't need test coverage analysis. ## Scope @@ -137,6 +142,14 @@ Scope re-reviews to your domain: test coverage quality, behavioral gaps, and mis - **Proportional**: match scrutiny to the risk level of the untested behavior - **Stay in scope**: do not comment on anything outside test coverage and test quality +## Turn budget + +You have **20 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/orchestrated-architect.md b/packages/agents/content/subagents/orchestrated-architect.md index a6e32f11..90ba72fc 100644 --- a/packages/agents/content/subagents/orchestrated-architect.md +++ b/packages/agents/content/subagents/orchestrated-architect.md @@ -115,6 +115,14 @@ If the plan's assumptions all check out, omit this section. - **Be concise.** Downstream agents need actionable guidance, not essays. Every sentence should inform a decision. - **Err toward lower impact.** If you're unsure between two levels, choose the lower one. Over-classifying creates unnecessary process overhead. +## Turn budget + +You have **30 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/orchestrated-coder.md b/packages/agents/content/subagents/orchestrated-coder.md index 67fca442..2b250b89 100644 --- a/packages/agents/content/subagents/orchestrated-coder.md +++ b/packages/agents/content/subagents/orchestrated-coder.md @@ -121,6 +121,14 @@ If the project does not have a particular quality gate configured, note "N/A" fo - **Commit conventions**: follow the git commit conventions skill. Each logical unit of work gets its own commit. - **File scope**: only modify files that are part of the plan or directly required by it. +## Turn budget + +You have **80 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/orchestrated-planner.md b/packages/agents/content/subagents/orchestrated-planner.md index f985ee56..abdd2a43 100644 --- a/packages/agents/content/subagents/orchestrated-planner.md +++ b/packages/agents/content/subagents/orchestrated-planner.md @@ -133,6 +133,14 @@ Write the plan JSON file to the path provided in the task prompt. Format: - **Don't over-plan**: if the task is simple (1-2 steps), write a simple plan. Don't pad with unnecessary steps. - **Include the commands**: when a step involves running a command (test, build, lint), specify the exact command +## Turn budget + +You have **40 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact files, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/orchestrated-reviewer.md b/packages/agents/content/subagents/orchestrated-reviewer.md index bd542b4d..ec240aed 100644 --- a/packages/agents/content/subagents/orchestrated-reviewer.md +++ b/packages/agents/content/subagents/orchestrated-reviewer.md @@ -32,9 +32,15 @@ You will receive: 1. **Get the diff**: run `git diff ..HEAD` to see all changes in scope, where `` is the pre-resolved SHA provided in your task prompt. If none was provided, compute it yourself: invoke `get-default-branch`, then run `git merge-base HEAD ` to get the SHA. 2. **Read changed files**: read the full files, not just diffs, to understand context 3. **Evaluate against criteria**: apply review-criteria skill -4. **Classify each finding**: assign category (F/W/T/R/S/L) -5. **Classify overall criticality**: determine the overall review outcome -6. **Write review file**: output to artifact directory +4. **Form preliminary findings**: classify each finding into the F/W/T/R/S/L scheme and determine overall criticality +5. **Write your artifact**: write the review file to the output path with your current findings, criticality classification, and return block — even if your analysis feels incomplete. A partial review is infinitely more valuable than no review. +6. **Refine if turns remain**: if you have remaining turns, continue evaluation and **update** the artifact with additional or revised findings. Do not start a new file — edit the existing one. + +### Efficiency + +- **Diff-first**: read the diff before reading full files. Only read full file contents for files where the diff reveals potential issues. +- **Batch reads**: when reading multiple files, use parallel tool calls rather than sequential ones. +- **Proportional depth**: match the thoroughness of your review to the scope of the change. A 3-file bugfix does not need the same depth as a 20-file refactor. ## Finding format @@ -136,6 +142,14 @@ When reviewing after a coder has responded to previous findings: - **Context-aware**: understand the codebase conventions before flagging violations. What looks wrong in isolation might be the established pattern. - **Proportional**: a typo fix doesn't need the same scrutiny as a security-critical change. Match your depth to the risk. +## Turn budget + +You have **30 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Orchestrator return protocol After writing your artifact file, end your final response with a structured return block. The orchestrator parses these fields for flow control without reading the full artifact. diff --git a/packages/agents/content/subagents/plan-reviewer.md b/packages/agents/content/subagents/plan-reviewer.md index d948ffa4..1c5f831f 100644 --- a/packages/agents/content/subagents/plan-reviewer.md +++ b/packages/agents/content/subagents/plan-reviewer.md @@ -139,6 +139,14 @@ If the plan has no findings at all, write: - **Respect the plan's intent**: Flag gaps and errors, don't redesign. If the plan's approach is valid but under-specified, the finding is a C (completeness gap), not a suggestion to use a different approach. - **Don't flag the obvious**: If the codebase has a single clear pattern for something and the plan doesn't specify it, that's not a gap -- the coder will follow the pattern. Only flag cases where the coder would face a genuine decision. +## Turn budget + +You have **30 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Return protocol After writing your review artifact, end your final response with a structured return block: diff --git a/packages/agents/content/subagents/plan-reviser.md b/packages/agents/content/subagents/plan-reviser.md index 177280ce..17956552 100644 --- a/packages/agents/content/subagents/plan-reviser.md +++ b/packages/agents/content/subagents/plan-reviser.md @@ -62,6 +62,14 @@ After the plan content, append a changes summary: - **Verify corrections**: for auto-resolvable findings, read the actual codebase to confirm your correction is accurate. Don't replace one error with another. - **Complete document**: the output must be a full, self-contained plan. A reader should not need to reference the original plan or the review to understand it. +## Turn budget + +You have **30 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Return protocol After writing your refined plan artifact, end your final response with a structured return block: diff --git a/packages/agents/content/subagents/planner.md b/packages/agents/content/subagents/planner.md index 367f1a62..d1aa3590 100644 --- a/packages/agents/content/subagents/planner.md +++ b/packages/agents/content/subagents/planner.md @@ -134,6 +134,14 @@ When resumed with user feedback, you should: - **Designed for resumption**: the user may provide feedback across multiple iterations - **Self-contained step descriptions**: each step's `description` in orchestration-plan.json is detailed enough to serve as the complete task input for `/orchestrate-dev` +## Turn budget + +You have **40 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. + + +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. + + ## Constraints - **Read-only on project files**: you may read any project file but only write to the provided output paths From bebbca999fb275710758d78b23f0f16dd8660547 Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Sat, 7 Mar 2026 17:04:07 -0800 Subject: [PATCH 2/2] agents|fix: Tailor HARD-GATE wording for coder and planner agents --- packages/agents/content/subagents/orchestrated-coder.md | 2 +- packages/agents/content/subagents/planner.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/agents/content/subagents/orchestrated-coder.md b/packages/agents/content/subagents/orchestrated-coder.md index 2b250b89..be0f9779 100644 --- a/packages/agents/content/subagents/orchestrated-coder.md +++ b/packages/agents/content/subagents/orchestrated-coder.md @@ -126,7 +126,7 @@ If the project does not have a particular quality gate configured, note "N/A" fo You have **80 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. -**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. +**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — implementation that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, commit your current progress and write your change summary with what was completed and what remains. ## Orchestrator return protocol diff --git a/packages/agents/content/subagents/planner.md b/packages/agents/content/subagents/planner.md index d1aa3590..49aeece6 100644 --- a/packages/agents/content/subagents/planner.md +++ b/packages/agents/content/subagents/planner.md @@ -139,7 +139,7 @@ When resumed with user feedback, you should: You have **40 turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn. -**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. +**Reserve your last 3 turns for writing your artifact file.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have. ## Constraints