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

[williamthorsen]

Problem

9 of 12 codebase-touching agent definitions lack an instruction to read .agents/PROJECT.md (and CLAUDE.md) at the start of their process. Without project context, agents improvise when they encounter project-specific tooling. The most visible symptom: agents resolve CLI tools via filesystem discovery (e.g., node_modules/.bin/nmr test) instead of using the project's canonical invocation (nmr test), triggering a permission prompt for every distinct argument set.

This has been a recurring pain point across projects that use custom CLI tools documented in PROJECT.md.

Current state

Already have the instruction (step 1 of their Process section):

• aspect-code-reviewer.md
• code-simplification-reviewer.md

Both use:

1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions

Missing the instruction (9 agents):

• orchestrated-coder.md
• orchestrated-planner.md
• orchestrated-architect.md
• orchestrated-reviewer.md
• plan-reviewer.md
• plan-reviser.md
• planner.md
• aspect-silent-failure-reviewer.md
• aspect-test-reviewer.md

Correctly excluded:

• savings-analyzer.md — analyzes orchestration artifacts, not the codebase

Why this matters beyond command resolution

PROJECT.md contains directory conventions, architecture context, testing patterns, and naming rules. Every agent that reads code, writes code, or reviews code needs this context to make correct decisions — not just agents that run shell commands.

Approaches considered

1. Have dispatching skills include PROJECT.md content in the prompt. Rejected: duplicates context in every dispatch, inflates token cost, and every new dispatching skill must remember to do it.

2. Add the instruction to each agent's process section. Preferred: follows the established pattern from the two agents that already work correctly. One-time change, no ongoing maintenance burden on skill authors.

Proposed solution

Add a "Read project guidelines" step as the new step 1 in each agent's Process section, before any codebase interaction. Use the same wording as the existing agents:

1. **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions

Renumber subsequent steps accordingly. For agents with multiple operating modes (e.g., orchestrated-coder has "Implementation" and "Review feedback" modes), add the step to each mode's process.

Files to modify

All files are in the agent definitions directory (e.g., ~/.claude/agents/ or the repo equivalent):

File	Current step 1	Change
orchestrated-coder.md	"Read the plan and understand the full scope"	Insert new step 1 before it (both modes)
orchestrated-planner.md	"Understand the task"	Insert new step 1 before it
orchestrated-architect.md	"Understand the task"	Insert new step 1 before it
orchestrated-reviewer.md	"Get the diff"	Insert new step 1 before it
plan-reviewer.md	"Read the plan"	Insert new step 1 before it
plan-reviser.md	"Read the original plan"	Insert new step 1 before it
planner.md	"Understand the story"	Insert new step 1 before it
aspect-silent-failure-reviewer.md	"Get the diff"	Insert new step 1 before it
aspect-test-reviewer.md	"Get the diff"	Insert new step 1 before it

Verification

After the change, deploy the updated agents and run an orchestrated workflow in a project with a PROJECT.md that documents custom CLI tools. Confirm that agents use the documented commands rather than resolving binaries via node_modules/.bin/.

Acceptance criteria

• All 9 listed agents have "Read project guidelines" as step 1 of their Process section(s)
• orchestrated-coder.md has the step in both Mode 1 (Implementation) and Mode 2 (Review response)
• The instruction wording matches the established pattern: **Read project guidelines**: read CLAUDE.md, .agents/PROJECT.md, and any relevant project-specific conventions
• Subsequent steps are renumbered correctly in all modified files
• savings-analyzer.md is not modified (correctly excluded)