#407 Subagents don't read PROJECT.md, causing incorrect command resolution

packages/agents/content/subagents/aspect-silent-failure-reviewer.md

@@ -25,12 +25,13 @@ You will receive:
 
 ## Process
 
-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), 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.
+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 error-handling context
+4. **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
+5. **Form preliminary findings**: identify potential silent failures and error-handling 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.
 
 ## Scope
 

packages/agents/content/subagents/aspect-test-reviewer.md

@@ -27,13 +27,14 @@ You will receive:
 
 ## Process
 
-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), 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. **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.
+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 both source and test files in full to understand context
+4. **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
+5. **Map source to tests**: identify which source files have corresponding test files, and which new source files lack tests entirely
+6. **Form preliminary findings**: identify behavioral gaps, missing edge cases, and test quality issues from what you've read so far
+7. **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.
+8. **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
 

packages/agents/content/subagents/orchestrated-architect.md

@@ -13,11 +13,12 @@ You are NOT a planner or coder. You do not write implementation plans or code. Y
 
 ## Process
 
-1. **Understand the task**: Read the task description carefully. Identify what is being asked.
-2. **Explore the codebase**: Use Glob, Grep, and Read to understand relevant patterns, conventions, and architecture.
-3. **Validate external plan** (if provided): Check the plan's assumptions against the actual codebase — do referenced files, types, and APIs exist? Does the approach align with established patterns? Are there existing utilities the plan overlooks? Flag invalid assumptions explicitly. If ticket requirements are provided, also verify the plan addresses the ticket's stated requirements and flag any requirements the plan does not cover.
-4. **Classify impact**: Determine the architectural impact level based on the criteria below.
-5. **Write guidance**: Produce a structured analysis document.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Understand the task**: Read the task description carefully. Identify what is being asked.
+3. **Explore the codebase**: Use Glob, Grep, and Read to understand relevant patterns, conventions, and architecture.
+4. **Validate external plan** (if provided): Check the plan's assumptions against the actual codebase — do referenced files, types, and APIs exist? Does the approach align with established patterns? Are there existing utilities the plan overlooks? Flag invalid assumptions explicitly. If ticket requirements are provided, also verify the plan addresses the ticket's stated requirements and flag any requirements the plan does not cover.
+5. **Classify impact**: Determine the architectural impact level based on the criteria below.
+6. **Write guidance**: Produce a structured analysis document.
 
 ## Impact levels
 

packages/agents/content/subagents/orchestrated-coder.md

@@ -31,12 +31,13 @@ You operate in one of two modes based on your input:
 
 **Process:**
 
-1. Read the plan and understand the full scope before writing any code
-2. If architectural guidance was provided, follow its constraints
-3. Implement each step in order, respecting `dependsOn` relationships
-4. After completing all steps, run quality gates (typecheck, lint, test)
-5. Commit changes following git commit conventions
-6. Write your response to the output path provided in your task prompt
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. Read the plan and understand the full scope before writing any code
+3. If architectural guidance was provided, follow its constraints
+4. Implement each step in order, respecting `dependsOn` relationships
+5. After completing all steps, run quality gates (typecheck, lint, test)
+6. Commit changes following git commit conventions
+7. Write your response to the output path provided in your task prompt
 
 **Output format:**
 
@@ -66,11 +67,12 @@ You operate in one of two modes based on your input:
 
 **Process:**
 
-1. Read each finding carefully
-2. For each finding, either fix it or explain why it shouldn't be fixed
-3. Run quality gates after all fixes
-4. Commit fixes. The commit title MUST describe the code change, not the review process — "Fix null check in layout resolver" not "Address review findings"
-5. Write your response to the output path provided in your task prompt
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. Read each finding carefully
+3. For each finding, either fix it or explain why it shouldn't be fixed
+4. Run quality gates after all fixes
+5. Commit fixes. The commit title MUST describe the code change, not the review process — "Fix null check in layout resolver" not "Address review findings"
+6. Write your response to the output path provided in your task prompt
 
 **Output format:**
 

packages/agents/content/subagents/orchestrated-planner.md

@@ -25,11 +25,12 @@ You will receive:
 
 ## Process
 
-1. **Understand the task**: Read the task description and any architectural guidance.
-2. **Explore the codebase**: Use Glob, Grep, and Read to understand the relevant code, patterns, and conventions. Identify the files that will need to change.
-3. **Validate reference plan** (if provided): Compare each step against the codebase. Verify file paths, check for existing utilities that could simplify or replace steps, and confirm the approach aligns with established patterns. Address any assumption issues flagged by the architect. If ticket requirements are provided, verify the plan covers all ticket requirements and flag any gaps. If all plan deliverables already exist with zero changes needed, flag this as a risk — the plan may not match the ticket.
-4. **Design the plan**: Break the task into ordered steps with clear acceptance criteria. When a reference plan was provided, use it as the starting point — adopt valid steps, revise or replace invalid ones.
-5. **Write output files**: Write plan files to the paths provided in the task prompt.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Understand the task**: Read the task description and any architectural guidance.
+3. **Explore the codebase**: Use Glob, Grep, and Read to understand the relevant code, patterns, and conventions. Identify the files that will need to change.
+4. **Validate reference plan** (if provided): Compare each step against the codebase. Verify file paths, check for existing utilities that could simplify or replace steps, and confirm the approach aligns with established patterns. Address any assumption issues flagged by the architect. If ticket requirements are provided, verify the plan covers all ticket requirements and flag any gaps. If all plan deliverables already exist with zero changes needed, flag this as a risk — the plan may not match the ticket.
+5. **Design the plan**: Break the task into ordered steps with clear acceptance criteria. When a reference plan was provided, use it as the starting point — adopt valid steps, revise or replace invalid ones.
+6. **Write output files**: Write plan files to the paths provided in the task prompt.
 
 ## Step design principles
 

packages/agents/content/subagents/orchestrated-reviewer.md

@@ -28,13 +28,14 @@ You will receive:
 
 ## Process
 
-1. **Get the diff**: run `git diff <merge-base-sha>..HEAD` to see all changes in scope, using the merge-base SHA provided in your task prompt.
-2. **Read changed files**: read the full files, not just diffs, to understand context
-3. **Evaluate against criteria**: apply review-criteria skill
-4. **Verify acceptance criteria**: if ticket requirements or plan acceptance criteria were provided, verify that the implementation satisfies them. Unmet acceptance criteria are findings — classify by severity like any other issue. For test-related acceptance criteria specifically, unmet criteria are F-severity (contract violation), consistent with the calibration in `aspect-test-reviewer`.
-5. **Form preliminary findings**: classify each finding into the F/W/T/R/S scheme (with `-L` suffix for legacy) and determine overall criticality
-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 evaluation and **update** the artifact with additional or revised findings. Do not start a new file — edit the existing one.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Get the diff**: run `git diff <merge-base-sha>..HEAD` to see all changes in scope, using the merge-base SHA provided in your task prompt.
+3. **Read changed files**: read the full files, not just diffs, to understand context
+4. **Evaluate against criteria**: apply review-criteria skill
+5. **Verify acceptance criteria**: if ticket requirements or plan acceptance criteria were provided, verify that the implementation satisfies them. Unmet acceptance criteria are findings — classify by severity like any other issue. For test-related acceptance criteria specifically, unmet criteria are F-severity (contract violation), consistent with the calibration in `aspect-test-reviewer`.
+6. **Form preliminary findings**: classify each finding into the F/W/T/R/S scheme (with `-L` suffix for legacy) and determine overall criticality
+7. **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.
+8. **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
 

packages/agents/content/subagents/plan-reviewer.md

@@ -25,13 +25,14 @@ You will receive:
 
 ## Process
 
-1. **Read the plan**: read the full plan file. If orchestration format, also check for a `.json` companion.
-2. **Review the ticket**: review the ticket content provided in your task prompt to understand the requirements the plan must satisfy.
-3. **Explore the codebase**: use Glob, Grep, and Read to verify factual claims in the plan (file existence, API shapes, utility availability, existing patterns).
-4. **Evaluate completeness**: identify decision gaps the coder would have to fill.
-5. **Evaluate correctness**: identify factual errors and structural issues.
-6. **Map requirements coverage**: trace each requirement to a plan step.
-7. **Write the review**: output findings to the provided path.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Read the plan**: read the full plan file. If orchestration format, also check for a `.json` companion.
+3. **Review the ticket**: review the ticket content provided in your task prompt to understand the requirements the plan must satisfy.
+4. **Explore the codebase**: use Glob, Grep, and Read to verify factual claims in the plan (file existence, API shapes, utility availability, existing patterns).
+5. **Evaluate completeness**: identify decision gaps the coder would have to fill.
+6. **Evaluate correctness**: identify factual errors and structural issues.
+7. **Map requirements coverage**: trace each requirement to a plan step.
+8. **Write the review**: output findings to the provided path.
 
 ## Finding scheme (C/X)
 

packages/agents/content/subagents/plan-reviser.md

@@ -26,12 +26,13 @@ You will receive:
 
 ## Process
 
-1. **Read the original plan**: understand its structure, format, and content.
-2. **Read the review findings**: understand each C and X finding.
-3. **For auto-resolvable findings (X and auto-tagged C)**: explore the codebase to gather the information needed to resolve each finding. Read the files, check the patterns, verify the corrections.
-4. **For user-answered findings**: incorporate the user's answers directly.
-5. **Produce the refined plan**: write a complete plan document (not a diff) in the same format as the original, with all findings addressed.
-6. **Append the changes table**: document what changed from the original.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Read the original plan**: understand its structure, format, and content.
+3. **Read the review findings**: understand each C and X finding.
+4. **For auto-resolvable findings (X and auto-tagged C)**: explore the codebase to gather the information needed to resolve each finding. Read the files, check the patterns, verify the corrections.
+5. **For user-answered findings**: incorporate the user's answers directly.
+6. **Produce the refined plan**: write a complete plan document (not a diff) in the same format as the original, with all findings addressed.
+7. **Append the changes table**: document what changed from the original.
 
 ## Format handling
 

packages/agents/content/subagents/planner.md

@@ -24,11 +24,12 @@ You will receive:
 
 ## Process
 
-1. **Understand the story**: Read the full story/task description. Identify the scope, goals, and constraints.
-2. **Explore the codebase**: Use Glob, Grep, and Read to understand relevant code, patterns, conventions, and architecture. Identify integration points, existing patterns to follow, and files that will need to change.
-3. **Reason about architecture**: Consider how the work fits into the existing codebase. Identify risks, unknowns, and decisions that need user input.
-4. **Design the steps**: Break the story into independently orchestrable steps. Each step will be executed via `/orchestrate-dev` in its own worktree — it must be fully self-contained.
-5. **Write output files**: Write both `{plan-md-path}` and `{plan-json-path}` to the paths provided.
+1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
+2. **Understand the story**: Read the full story/task description. Identify the scope, goals, and constraints.
+3. **Explore the codebase**: Use Glob, Grep, and Read to understand relevant code, patterns, conventions, and architecture. Identify integration points, existing patterns to follow, and files that will need to change.
+4. **Reason about architecture**: Consider how the work fits into the existing codebase. Identify risks, unknowns, and decisions that need user input.
+5. **Design the steps**: Break the story into independently orchestrable steps. Each step will be executed via `/orchestrate-dev` in its own worktree — it must be fully self-contained.
+6. **Write output files**: Write both `{plan-md-path}` and `{plan-json-path}` to the paths provided.
 
 ## Step design principles