5-phase-workflow 1.8.9 → 1.9.0

package/bin/install.js

@@ -280,8 +280,7 @@ const LEGACY_REMOVED_FILES = [
   'templates/STACK.md',
   'templates/STRUCTURE.md',
   'templates/CONVENTIONS.md',
-  'templates/INTEGRATIONS.md',
-  'skills/configure-project'
+  'templates/INTEGRATIONS.md'
 ];
 
 // Get list of workflow-owned files/directories (not user-created)
@@ -298,6 +297,7 @@ function getWorkflowManagedFiles() {
     // Skills: specific skill directories
     skills: [
       'configure-docs-index',
+      'configure-project',
       'configure-skills',
       'generate-readme'
     ],
@@ -651,7 +651,12 @@ function cleanupOrphanedFiles(targetPath, dataDir) {
     for (const entry of LEGACY_REMOVED_FILES) {
       const fullPath = path.join(targetPath, entry);
       if (fs.existsSync(fullPath)) {
-        fs.unlinkSync(fullPath);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+          removeDir(fullPath);
+        } else {
+          fs.unlinkSync(fullPath);
+        }
         log.info(`Removed legacy orphan: ${entry}`);
       }
     }
@@ -1270,7 +1275,12 @@ function uninstall() {
   for (const entry of LEGACY_REMOVED_FILES) {
     const fullPath = path.join(targetPath, entry);
     if (fs.existsSync(fullPath)) {
-      fs.unlinkSync(fullPath);
+      const stat = fs.statSync(fullPath);
+      if (stat.isDirectory()) {
+        removeDir(fullPath);
+      } else {
+        fs.unlinkSync(fullPath);
+      }
       log.info(`Removed legacy orphan: ${entry}`);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/commands/5/configure.md

@@ -9,7 +9,7 @@ context: fork
 
 <role>
 You are a Project Configurator. You analyze a project, gather preferences, and write config.json plus a feature spec.
-You do NOT generate CLAUDE.md, documentation files, or skills directly — those are Phase 3's job.
+You do NOT generate AGENTS.md, CLAUDE.md, documentation files, or skills directly — those are Phase 3's job.
 You write ONLY to: .5/config.json, .5/version.json, .5/features/CONFIGURE/feature.md, and .gitignore.
 After writing config.json and the feature spec, you are DONE. Exit immediately.
 </role>
@@ -39,7 +39,7 @@ Your job in this command:
 ✅ Tell user to run /5:plan-implementation CONFIGURE
 
 Your job is NOT:
-❌ Create CLAUDE.md directly (Phase 3 does this)
+❌ Create AGENTS.md or CLAUDE.md directly (Phase 3 does this)
 ❌ Generate documentation files directly (Phase 3 does this)
 ❌ Generate skills directly (Phase 3 does this)
 ❌ Skip user interaction
@@ -47,7 +47,7 @@ Your job is NOT:
 
 **After writing config.json, creating the feature spec, and informing the user, YOUR JOB IS COMPLETE. EXIT IMMEDIATELY.**
 
-**If you find yourself creating CLAUDE.md, documentation files, or skills, STOP IMMEDIATELY. You should only be writing config.json and the feature spec.**
+**If you find yourself creating AGENTS.md, CLAUDE.md, documentation files, or skills, STOP IMMEDIATELY. You should only be writing config.json and the feature spec.**
 
 ## Configuration Process
 
@@ -92,8 +92,9 @@ fi
 # Set skill_creator_available=true if any skill-creator tool is found.
 ```
 
-**1e. Check CLAUDE.md:**
-- If `CLAUDE.md` exists, read its content
+**1e. Check AGENTS.md / CLAUDE.md:**
+- If `AGENTS.md` exists, read its content
+- If `AGENTS.md` does not exist but `CLAUDE.md` exists with real content (not just `@AGENTS.md`), read it — this is a legacy setup that will be migrated to AGENTS.md during Phase 3
 
 **1f. Scan existing skills:**
 - Check `.claude/skills/` for existing project-specific skills
@@ -169,7 +170,7 @@ If "Cancel": Exit immediately with message "Configuration unchanged."
 **2h. Review tool preference:**
 - "Which code review tool would you like to use?"
   - Options:
-    1. "Claude (built-in, no setup needed)" — always available
+    1. "Native (built-in agent review, no setup needed)" — always available, works with any AI coding tool
     2. "CodeRabbit CLI (requires installation)" — external tool
     3. "None (skip automated review)"
 - If user selects CodeRabbit and it was not detected in Step 1d:
@@ -207,14 +208,14 @@ The skill-creator plugin from the official Claude store helps generate higher-qu
   - If user selects "Install now": execute the install command, then set `tools.skillCreator.available = true` in the config
   - If user selects "Skip": `tools.skillCreator.available` remains `false`
 
-**2k. Confirm CLAUDE.md generation:**
-- "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
+**2k. Confirm AGENTS.md generation:**
+- "Generate/update AGENTS.md? This will analyze your codebase to document structure and conventions. (A CLAUDE.md shim will also be created for Claude Code compatibility.)"
   - Options: "Yes (recommended)", "Skip"
 
 **2k2. Confirm rules generation:**
-- "Generate `.claude/rules/` files? These are scoped instruction files that automatically load when Claude works with matching file types (e.g., testing rules load only when editing test files, code-style rules load only for source files)."
+- "Generate `.claude/rules/` files? These are scoped instruction files that automatically load when the agent works with matching file types (e.g., testing rules load only when editing test files, code-style rules load only for source files)."
   - Options: "Yes (recommended)", "Skip"
-- Note: Rules complement CLAUDE.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
+- Note: Rules complement AGENTS.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
 
 **2l. Review detected patterns for skill generation:**
 
@@ -307,7 +308,7 @@ Write `.5/features/CONFIGURE/feature.md` containing all gathered data:
 # Feature: Project Configuration
 
 ## Summary
-Generates CLAUDE.md, a rebuildable codebase index, and project-specific skills. (config.json already written.)
+Generates AGENTS.md, CLAUDE.md shim, a rebuildable codebase index, and project-specific skills. (config.json already written.)
 
 ## Requirements
 
@@ -328,7 +329,7 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
 - Skip empty categories; do not create placeholder index files
 - Re-running the script should fully refresh the index in place
 
-**Create CLAUDE.md:**
+**Create AGENTS.md** (provider-agnostic instructions file):
 - Project overview and build commands
 - Links to whichever `.5/` documentation files were created
 - Links to `.5/index/README.md`, the generated index files, and `.5/index/rebuild-index.sh`
@@ -348,8 +349,12 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
   5. Respect SRP and DRY
   6. Make code maintainable and modular
 
-**Preserve existing content:**
-- If CLAUDE.md already exists, preserve user-written custom sections
+**Create CLAUDE.md shim:**
+- Contains only `@AGENTS.md` (Claude Code include syntax)
+
+**Migrate and preserve existing content:**
+- If AGENTS.md already exists, preserve user-written custom sections
+- If CLAUDE.md exists with real content (not just `@AGENTS.md`), migrate content to AGENTS.md and replace CLAUDE.md with the shim
 
 ### Requirement 2: Generate Project-Specific Skills
 Handled by: `configure-skills`
@@ -388,13 +393,14 @@ Only generate rules for patterns that were actually detected:
 - [ ] `.5/index/README.md` exists and documents the generated index files
 - [ ] Multiple focused `.5/index/*.md` files are generated for applicable codebase concerns
 - [ ] Empty sections omitted (no "Not detected" / "None found" placeholders)
-- [ ] `CLAUDE.md` exists with references to created `.5/` files
-- [ ] `CLAUDE.md` links to the codebase index and rebuild script
-- [ ] `CLAUDE.md` says to regenerate the index if it is older than one day
-- [ ] CLAUDE.md contains 6 coding guidelines
+- [ ] `AGENTS.md` exists with references to created `.5/` files
+- [ ] `AGENTS.md` links to the codebase index and rebuild script
+- [ ] `AGENTS.md` says to regenerate the index if it is older than one day
+- [ ] `AGENTS.md` contains 6 coding guidelines
+- [ ] `CLAUDE.md` exists and contains only `@AGENTS.md`
 - [ ] All specified project-specific skills are generated in `.claude/skills/`
 - [ ] Generated skills reference actual project conventions
-- [ ] If CLAUDE.md existed before, user-written sections are preserved
+- [ ] If AGENTS.md or CLAUDE.md existed before, user-written sections are preserved in AGENTS.md
 - [ ] `.claude/rules/` directory exists with scoped rule files (if rules generation selected)
 - [ ] Generated rules use `paths:` frontmatter for scoping where applicable
 - [ ] Rules contain concise directives, not documentation

package/src/commands/5/discuss-feature.md

@@ -92,7 +92,7 @@ Extract current state:
 - Business rules
 - Acceptance criteria
 - Alternatives considered
-- Questions & Answers
+- Decisions (with [DECIDED]/[FLEXIBLE]/[DEFERRED] labels)
 
 ### Step 3: Initial Discussion Prompt
 
@@ -162,7 +162,7 @@ When user indicates they're done discussing, update `.5/features/{feature-name}/
 7. **Business Rules** - If logic clarified
 8. **Acceptance Criteria** - Add/refine verification criteria
 9. **Alternatives Considered** - Document discussed alternatives
-10. **Questions & Answers** - Append new Q&A from this session
+10. **Decisions** - Append new decisions from this session, tagged [DECIDED], [FLEXIBLE], or [DEFERRED] using Context/Decision format
 
 **Preserve existing content** - Only update sections that changed during discussion.
 

package/src/commands/5/implement-feature.md

@@ -163,7 +163,8 @@ Before executing step N (where N > 1), verify that prior steps' outputs exist on
    - Log: `"⚠ Pre-step check: {file} from step {M} component {name} not found on disk"`
    - Move the component back from `completedComponents` to `pendingComponents`
    - STOP execution for this step. Report to user: `"Step {N} blocked: prior step output missing. Re-run step {M} or fix manually."`
-3. If all files verified, proceed to 3a
+3. **Depends On check:** For each component in step N that has a `Depends On` value (not `—`), verify the named dependency component is in `completedComponents`. If a dependency is in `failedAttempts`, STOP and report: `"Step {N} component {name} blocked: dependency {dep} failed."`
+4. If all files and dependencies verified, proceed to 3a
 
 This prevents cascading failures where step N assumes step N-1's outputs exist but they don't.
 
@@ -202,11 +203,17 @@ Task tool call:
     ## Read First
     {Pattern File value(s) from plan table — executor MUST read these before writing any code}
 
+    ## Dependencies
+    {If Depends On is not "—": "This component depends on {dep-name} ({dep-file}). Read that file first to understand the exports/types you need to use."}
+    {If Depends On is "—": omit this section entirely}
+
     ## Verify
     {Verify command(s) from plan table — executor runs these after implementation}
 
     ## Implementation Notes
-    {relevant notes from plan}
+    {ONLY notes relevant to this step/component — filter by [Step N] or [component-name] prefix.
+     Include untagged notes only if they are globally relevant (e.g., "all services use dependency injection").
+     Do NOT send all notes to every agent — this wastes context.}
 ```
 
 The agent file defines the implementation process, output format, and deviation rules. If the agent file is not found (local install), fall back to `.claude/agents/component-executor.md` relative to the project root.
@@ -238,9 +245,16 @@ Mark the current step's TaskCreate task as `completed`. Mark the next step's tas
 
 For each component that returned `STATUS: failed`:
 
-1. **Assess the error:**
-   - **Small fix** (missing import, wrong path, syntax error): Fix with Edit tool directly in main context. Mark as completed. This counts as retry 1.
-   - **Large fix** (logic error, wrong pattern, missing context): Re-spawn the component-executor agent with the same prompt plus an `## Error Context` block describing the previous failure. This counts as retry 1.
+1. **Always re-spawn an agent** — NEVER fix code directly in the orchestrator context, not even for small fixes like missing imports or wrong paths. The orchestrator stays slim and delegates ALL code work.
+
+   Re-spawn the component-executor agent with the same prompt plus an `## Error Context` block describing the previous failure.
+
+   **Model upgrade on retry:** Bump the model one tier up from the original complexity:
+   - `simple` (haiku) → retry with `sonnet`
+   - `moderate` (haiku/sonnet) → retry with `sonnet`
+   - `complex` (sonnet) → retry with `sonnet` (already max)
+
+   This gives the retry agent better reasoning to solve what the first attempt couldn't.
 
 2. If the retry also fails:
    - Update `retryCount: 2` in the component's `failedAttempts` entry

package/src/commands/5/plan-feature.md

@@ -49,21 +49,34 @@ Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 - Acceptance criteria describe observable behavior, NOT test code
 </output-format>
 
-<question-strategy>
-Ask 5-10 clarifying questions using AskUserQuestion.
-
-**Rules:**
-- ONE question at a time — wait for answer before next
-- Use sub-agent findings to ask informed questions
-- At least 5 questions before creating the spec
-- Provide 2-4 options where meaningful
-
-**Categories:** Requirements clarity, scope boundaries, edge cases, performance expectations,
-testing strategy, integration points (from findings), alternative approaches, complexity trade-offs.
-
-**Challenge assumptions:** "Is this the simplest solution?", "Could we reuse existing X?",
-"What happens when Y fails?"
-</question-strategy>
+<collaboration-strategy>
+You are a collaborative thought partner, not an interviewer conducting a checklist.
+
+**Approach:**
+- After the Explore agent returns, propose a draft understanding of the feature (2-3 sentences).
+  Ask the user to confirm, correct, or expand. This anchors the conversation.
+- Use AskUserQuestion — one exchange at a time — but frame questions as a colleague's follow-ups,
+  not a numbered interrogation.
+- When the codebase exploration reveals an obvious pattern or approach, propose it:
+  "Based on how X works, I think this feature would involve Y — does that match your thinking?"
+- When something is genuinely ambiguous, ask openly.
+- Challenge assumptions naturally: "Is this the simplest solution?", "Could we reuse existing X?",
+  "What happens when Y fails?"
+
+**Adaptive depth:**
+- Simple features (config change, small UI tweak) may need 2-3 exchanges.
+- Complex features (new subsystem, multi-component integration) may need 10+.
+- Let the complexity drive the conversation length, not a fixed question count.
+
+**Readiness signal — you are ready to write the spec when you can articulate:**
+1. The problem being solved
+2. Clear functional requirements
+3. Scope boundaries (what is in, what is out)
+4. Acceptance criteria (how to verify success)
+5. Key decisions and their labels ([DECIDED], [FLEXIBLE], [DEFERRED])
+
+If any of these are unclear, keep discussing.
+</collaboration-strategy>
 
 # Plan Feature (Phase 1)
 
@@ -74,12 +87,11 @@ Follow these steps IN ORDER. Do NOT skip steps. Do NOT proceed to a later step u
 - [ ] Step 0: Activate planning guard — write `.5/.planning-active`
 - [ ] Step 1: Gather feature description — ask developer via AskUserQuestion
 - [ ] Step 2: Explore codebase — spawn Explore sub-agent, wait for results, cache to codebase-scan.md
-- [ ] Step 3: Ask 5+ clarifying questions — one at a time, minimum 5 before proceeding
-- [ ] Step 3b: Pre-write checkpoint — verify ≥5 Q&A pairs exist, no code in spec
-- [ ] Step 4: Write feature specification — create `.5/features/{name}/feature.md`
+- [ ] Step 3: Collaborative spec development — discuss with the user until the spec is clear
+- [ ] Step 4: Write feature specification — create `.5/features/{name}/feature.md` (with optional mermaid diagrams)
 - [ ] Output completion message and STOP
 
-> **MANDATORY:** After each step, output `✓ Step N complete` before moving on. This is your progress anchor — if you cannot say which step you just completed, you are skipping ahead. If Step 3b fails (< 5 Q&A), return to Step 3.
+> **MANDATORY:** After completing Steps 0, 1, 2, and 4, output `✓ Step N complete` before moving on. Step 3 is open-ended — it completes when you and the user agree the spec is ready to write.
 
 ## Process
 
@@ -140,11 +152,34 @@ Wait for the sub-agent to return before proceeding.
 
 **Cache the results:** Write the Explore agent's full output to `.5/features/{name}/codebase-scan.md` using the Write tool. This saves Phase 2 from re-scanning the same codebase and saves significant tokens.
 
-### Step 3: Intensive Q&A
+### Step 3: Collaborative Spec Development
+
+> **ROLE CHECK:** You are gathering requirements, NOT designing solutions. Discussion covers WHAT and WHY, never HOW.
+
+**Begin by sharing your understanding.** Based on the user's description (Step 1) and the codebase exploration (Step 2), propose a concise summary of the feature:
+- What problem it solves
+- What the key capabilities are
+- Which existing components are relevant
+
+Ask the user: "Here's my understanding of the feature — [summary]. Does this capture it, or should I adjust anything?"
+
+**Then discuss naturally.** Use AskUserQuestion to explore:
+- Ambiguities or gaps in the description
+- Scope boundaries (what is explicitly NOT included)
+- Edge cases the codebase exploration surfaced
+- Decisions that need to be made now vs. deferred
+- Whether existing patterns can be reused
 
-> **ROLE CHECK:** You are gathering requirements, NOT designing solutions. Questions ask WHAT and WHY, never HOW.
+**Adapt to complexity.** A simple feature may be clear after 2-3 exchanges. A complex one may need extended discussion. Do not rush to write the spec and do not artificially prolong the conversation.
 
-Ask 5-10 clarifying questions using AskUserQuestion. ONE question at a time — wait for the answer before asking the next. Use the sub-agent findings to inform questions. Cover: requirements clarity, scope boundaries, edge cases, performance expectations, testing strategy, integration points, alternative approaches, and complexity trade-offs. Challenge assumptions: "Is this the simplest solution?", "Could we reuse existing X?", "What happens when Y fails?"
+**You are ready to write the spec when you can confidently articulate:**
+1. The problem being solved (Problem Statement)
+2. Clear functional requirements
+3. Scope boundaries (what is in, what is out)
+4. Acceptance criteria (how to verify success)
+5. Key decisions and their labels ([DECIDED], [FLEXIBLE], [DEFERRED])
+
+If any of these are unclear, keep discussing. When you believe clarity has been reached, tell the user: "I think I have a clear picture — ready to write the spec. Anything else before I do?" Then proceed to Step 4.
 
 **Optional re-exploration:** If the user mentions components not covered in the initial report, spawn a targeted Explore agent:
 
@@ -155,14 +190,6 @@ Targeted exploration for feature planning.
 **READ-ONLY.** Only use Read, Glob, and Grep tools.
 ```
 
-### Step 3b: Pre-Write Checkpoint
-
-Before writing the feature spec, verify:
-1. You asked at least 5 questions and received answers
-2. You can summarize the feature in 1-2 sentences without mentioning files, classes, or functions
-
-If you have fewer than 5 Q&A pairs, go back to Step 3 and ask more questions.
-
 ### Step 4: Create Feature Specification
 
 > **ROLE CHECK:** You are writing a SPECIFICATION (WHAT/WHY), not a design document (HOW). Zero code, zero file paths to create, zero signatures. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
@@ -184,12 +211,22 @@ Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 Populate all sections:
 - Ticket ID & Summary
 - Problem Statement
+- Visual Overview (optional mermaid diagrams — see below)
 - Requirements (functional and non-functional)
 - Constraints
 - Affected Components (from exploration)
 - Acceptance Criteria
 - Alternatives Considered
-- Decisions (from Q&A session) — label each with **[DECIDED]**, **[FLEXIBLE]**, or **[DEFERRED]**
+- Decisions (from the conversation) — label each with **[DECIDED]**, **[FLEXIBLE]**, or **[DEFERRED]**
+
+**Visual Overview (optional mermaid diagrams):**
+Include mermaid diagrams in the spec when they add clarity. Use your judgment:
+- **Flow diagrams**: When the feature involves a multi-step process or state transitions
+- **Entity relationship diagrams**: When new data concepts relate to existing ones
+- **Component interaction diagrams**: When multiple modules/services communicate
+- **Sequence diagrams**: When the order of operations between actors matters
+
+Simple features (single-component changes, straightforward CRUD) typically do not need diagrams. Do not add diagrams for the sake of having them. Diagrams describe WHAT happens, not HOW it is implemented. No class diagrams, no file-level architecture diagrams, no code-level sequence diagrams.
 
 **Decision labeling rules:**
 - **[DECIDED]**: The user gave a clear, specific answer → Phase 2 planner and Phase 3 agents MUST honor exactly
@@ -205,7 +242,8 @@ After writing feature.md, output ONLY this message — no additional text, no su
 ✓ Feature spec created at `.5/features/{name}/feature.md`
 
 To review or refine: /5:discuss-feature {name}
-To proceed: /clear → /5:plan-implementation {name}
+To proceed: /5:plan-implementation {name}
+  (optional: /clear first to free context — plan-implementation adapts either way)
 ```
 
 **YOU ARE NOW FINISHED.** This is a hard stop. Do not:

package/src/commands/5/plan-implementation.md

@@ -22,7 +22,7 @@ HARD CONSTRAINTS — violations get blocked by plan-guard:
 - NEVER use Bash to create, write, or modify files — this bypasses the plan-guard and is a constraint violation
 - NEVER continue past the completion message — when you output "Plan created at...", you are DONE
 - The plan describes WHAT to build and WHERE. Agents figure out HOW by reading existing code.
-- Each component in the table gets: name, action, file path, one-sentence description, pattern file, verify command, complexity
+- Each component in the table gets: name, action, file path, one-sentence description, pattern file, verify command, complexity, depends on
 - **Pattern File** (required for "create" actions): Path to an existing file the executor reads before implementing. For "modify" actions, this is the target file itself. Helps executor match conventions exactly.
 - **Verify** (required): A concrete command or grep check the executor runs after implementing. Examples: `grep -q 'export class UserService' src/services/user.service.ts`, `npm test -- --testPathPattern=user`, `npx tsc --noEmit`. Never use vague checks like "works correctly".
 - If a component needs more than one sentence to describe, split it into multiple components
@@ -61,21 +61,32 @@ Assign complexity per component using this rubric:
 
 # Plan Implementation (Phase 2)
 
+## Context Detection
+
+Before starting, determine whether you have **live context from Phase 1**:
+
+**Live context = YES** if ALL of the following are true:
+- `/5:plan-feature` was run earlier in THIS conversation (not a previous one)
+- The feature spec discussion, codebase exploration results, and user decisions are visible in your conversation history
+- No `/clear` was run between Phase 1 and now
+
+**Live context = NO** if any of the above is false (e.g., user ran `/clear`, or this is a fresh conversation).
+
 ## Progress Checklist
 
-Follow these steps IN ORDER. Do NOT skip steps. Do NOT proceed to a later step until the current one is complete. After completing each step, output a status line: `✓ Step N complete`.
+Follow these steps IN ORDER. Steps marked *(skip if live context)* should be skipped when you have live context from Phase 1.
 
 - [ ] Step 0: Activate planning guard — write `.5/.planning-active`
-- [ ] Step 1: Load feature spec — read `.5/features/{name}/feature.md`
+- [ ] Step 1: Load feature spec *(skip if live context)* — read `.5/features/{name}/feature.md`
 - [ ] Step 1b: Load project configuration — read `.5/config.json` if it exists
-- [ ] Step 2: Load or generate codebase scan — reuse cached scan from Phase 1, or spawn Explore if missing
-- [ ] Step 3: Ask 2-3 technical questions — one at a time via AskUserQuestion
+- [ ] Step 2: Load or generate codebase scan *(skip if live context)* — reuse cached scan from Phase 1, or spawn Explore if missing
+- [ ] Step 3: Ask technical questions *(conditional)* — only if the feature spec leaves technical ambiguity
 - [ ] Step 4: Design components — identify files, order, step grouping
 - [ ] Step 5: Write the plan — create `.5/features/{name}/plan.md`
 - [ ] Step 5b: Plan self-check — verify format, no code, scope, completeness, tests
 - [ ] Output completion message and STOP
 
-> **MANDATORY:** After each step, output `✓ Step N complete` before moving on. This is your progress anchor — if you cannot say which step you just completed, you are skipping ahead. If Step 5b fails, fix plan.md before outputting completion.
+> **MANDATORY:** After each step (including skipped ones), output `✓ Step N complete` (or `✓ Step N skipped (live context)`) before moving on. This is your progress anchor — if you cannot say which step you just completed, you are skipping ahead. If Step 5b fails, fix plan.md before outputting completion.
 
 ## Output Format
 
@@ -97,9 +108,11 @@ Write (or refresh) the planning guard marker to `.5/.planning-active` using the
 
 This activates (or refreshes) the plan-guard hook which prevents accidental source file edits during planning. The marker is removed automatically when implementation starts (`/5:implement-feature`), expires after 4 hours, or can be cleared manually with `/5:unlock`.
 
-### Step 1: Load Feature Spec
+### Step 1: Load Feature Spec *(skip if live context)*
+
+**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, requirements, acceptance criteria, affected components, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
 
-Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
+**If no live context:** Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
 
 Extract: Ticket ID, requirements (functional and non-functional), acceptance criteria, affected components, and **decisions**.
 
@@ -119,11 +132,13 @@ Read `.5/config.json` if it exists. Extract:
 
 If config.json doesn't exist, proceed without it.
 
-### Step 2: Load or Generate Codebase Scan
+### Step 2: Load or Generate Codebase Scan *(skip if live context)*
 
 > **ROLE CHECK:** You are an Implementation Planner. Your ONLY output is plan.md. You do NOT write code, create source files, or start implementation. If you feel the urge to implement, STOP — that is Phase 3's job.
 
-**First, check for a cached scan from Phase 1:**
+**If live context:** The codebase exploration results from Phase 1 are already in your conversation history. Output `✓ Step 2 skipped (live context)` and proceed to Step 3.
+
+**If no live context — first, check for a cached scan from Phase 1:**
 
 Read `.5/features/{feature-name}/codebase-scan.md`. If it exists and is non-empty, use it as the codebase scan results. This was generated during Phase 1 (`/5:plan-feature`) and contains project structure, naming conventions, pattern files, and test framework detection.
 
@@ -170,17 +185,19 @@ Wait for the sub-agent to return before proceeding.
 
 **If a fresh scan was spawned**, write the results to `.5/features/{feature-name}/codebase-scan.md` for future reference.
 
-### Step 3: Ask 2-3 Technical Questions (One at a Time)
+### Step 3: Ask Technical Questions (Conditional)
 
-Use AskUserQuestion to clarify:
-- Data layer decisions (if applicable)
-- Key implementation choices
-- Anything unclear from the feature spec
+**Evaluate whether questions are needed.** Review what you know from the feature spec (and live context if available). Ask questions ONLY if:
+- A technical decision is genuinely ambiguous (not already labeled [DECIDED] or [FLEXIBLE])
+- The feature spec lacks information needed to identify files, components, or ordering
+- The codebase scan revealed multiple conflicting patterns and you need guidance
 
-**Rules:**
-- ONE question at a time — wait for answer before next
-- Max 3 questions — don't over-question
-- Don't repeat questions already answered in Phase 1
+**If no ambiguity exists** (all decisions are clear, codebase patterns are obvious), skip this step entirely. Output `✓ Step 3 skipped (no ambiguity)` and proceed to Step 4.
+
+**If questions are needed:**
+- Use AskUserQuestion — ONE question at a time
+- Max 2 questions — be surgical, don't over-question
+- NEVER re-ask something already answered in Phase 1 or labeled [DECIDED] in the feature spec
 
 **Optional re-exploration:** If user mentions patterns not in the initial scan, spawn a targeted Explore agent:
 
@@ -227,6 +244,8 @@ If no e2e or integration framework was detected, do NOT plan components for them
 
 Not every feature needs all non-test steps. Use what makes sense. But testable components always need unit tests, and features touching endpoints or cross-module flows should include integration/e2e tests when the infrastructure exists.
 
+**Depends On:** For each component, identify if it has a data dependency on a specific component from a prior step. Use the component name from the Depends On column (or `—` if none). This is for cross-step dependencies where a component needs a specific export, type, or interface from another component. File-level existence is already checked by the orchestrator — Depends On captures *semantic* dependencies (e.g., "auth-service depends on auth-types because it imports AuthToken").
+
 **Parallel execution:** Components in the same step run in parallel. Group independent components together, separate dependent ones into different steps.
 
 ### Step 5: Write the Plan
@@ -239,9 +258,22 @@ Include:
 - YAML frontmatter (ticket, feature, created)
 - One-sentence summary
 - Components table
-- Implementation Notes (references to existing pattern files + business rules)
+- Implementation Notes — **scoped by step or component** (see below)
 - Verification commands
 
+**Scoped Implementation Notes:**
+Each note MUST be prefixed with a scope tag so the orchestrator can filter notes per agent:
+- `[Step N]` — applies to all components in that step
+- `[component-name]` — applies to a specific component
+- `[global]` — applies to all components (use sparingly: project-wide conventions like DI patterns, naming schemes)
+
+Example:
+```
+- [global] All services use constructor-based dependency injection
+- [Step 1] Follow the pattern from src/models/User.ts for entity definitions
+- [schedule-service] endDate must be > startDate, throw ValidationError if not
+```
+
 **Verification section — prefer config.json values:**
 - Build: {build.command from config.json, or explore agent value, or "auto"}
 - Test: {build.testCommand from config.json, or explore agent value, or "auto"}
@@ -250,7 +282,7 @@ Include:
 
 Read plan.md back and verify:
 
-1. **Format:** Every row in the Components table has all 8 columns filled (Step, Component, Action, File, Description, Pattern File, Verify, Complexity)
+1. **Format:** Every row in the Components table has all 9 columns filled (Step, Component, Action, File, Description, Pattern File, Verify, Complexity, Depends On)
 2. **No code:** Implementation Notes contain ONLY references to existing files and business rules
 3. **Scope:** Every component traces back to a requirement in feature.md — if not, remove it
 4. **Completeness:** Every functional requirement from feature.md has at least one component
@@ -287,7 +319,7 @@ Plan created at `.5/features/{feature-name}/plan.md`
 
 Next steps:
 1. Review the plan
-2. /clear to reset context
+2. /clear to reset context (recommended before implementation)
 3. /5:implement-feature {feature-name}
 ```
 

package/src/commands/5/reconfigure.md

@@ -1,6 +1,6 @@
 ---
 name: 5:reconfigure
-description: Lightweight refresh of project documentation, codebase index, and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, rebuilds .5/index/, updates CLAUDE.md, and refreshes all skills.
+description: Lightweight refresh of project documentation, codebase index, and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, rebuilds .5/index/, updates AGENTS.md, and refreshes all skills.
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 user-invocable: true
 context: fork
@@ -117,7 +117,7 @@ Use the existing skills in `.claude/skills/` (from Step 2e) as the source of tru
 
 Use `AskUserQuestion` to show a summary and get confirmation. Present:
 
-1. **Documentation files that will be rewritten** — list `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional), `.5/index/rebuild-index.sh`, `.5/index/*.md`, and `CLAUDE.md`
+1. **Documentation files that will be rewritten** — list `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional), `.5/index/rebuild-index.sh`, `.5/index/*.md`, and `AGENTS.md`
 2. **Skills that will be refreshed** — list ALL skills found in `.claude/skills/` (both workflow-generated and user-created)
 3. **Rules that will be refreshed** (if rules enabled) — list workflow-generated rule files in `.claude/rules/`
 4. **New patterns detected** (if any) — "These patterns were found in your codebase but don't have skills yet: [list]. Create skills for them?"
@@ -139,7 +139,7 @@ Invoke the refresh skills in **refresh mode** via the Task tool:
 ```
 Task prompt 1: "Run configure-docs-index skill in REFRESH MODE.
 
-Refresh the generated documentation, rebuild the codebase index in `.5/index/`, delete legacy docs if they exist, and update `CLAUDE.md` while preserving user-written sections."
+Refresh the generated documentation, rebuild the codebase index in `.5/index/`, delete legacy docs if they exist, and update `AGENTS.md` (plus CLAUDE.md shim) while preserving user-written sections."
 
 Task prompt 2: "Run configure-skills skill in REFRESH MODE.
 

package/src/commands/5/review-code.md

@@ -1,6 +1,6 @@
 ---
 name: 5:review-code
-description: Reviews code changes using Claude (built-in) or CodeRabbit CLI. Categorizes findings and saves them for /5:address-review-findings.
+description: Reviews code changes using native agent review or CodeRabbit CLI. Categorizes findings and saves them for /5:address-review-findings.
 allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
 user-invocable: true
 model: sonnet
@@ -21,8 +21,8 @@ After saving the findings file, you are DONE.
 
 Two review tools are supported (configured in `.5/config.json` field `reviewTool`):
 
-- **Claude** (default) — Built-in, zero setup. A fresh-context agent reviews code blind.
-- **CodeRabbit** — External CLI. Requires `coderabbit` installed and authenticated.
+- **native** (default) — Built-in, zero setup. A fresh-context agent reviews code blind. Works with any AI coding tool (Claude Code, Codex, etc.).
+- **coderabbit** — External CLI. Requires `coderabbit` installed and authenticated.
 
 Both produce the same structured output format.
 
@@ -32,7 +32,7 @@ Both produce the same structured output format.
 
 Read `.5/config.json` and check the `reviewTool` field.
 
-- If not set or missing, default to `"claude"`
+- If not set, missing, or `"claude"` (legacy value), default to `"native"`
 - If `"none"`, inform user that automated review is disabled and STOP
 
 **If CodeRabbit:** Check prerequisites via Bash:
@@ -40,7 +40,7 @@ Read `.5/config.json` and check the `reviewTool` field.
 which coderabbit && coderabbit auth status
 ```
 If not installed or not authenticated, ask user via AskUserQuestion:
-- "Switch to Claude for this review? (Recommended)" / "I'll install CodeRabbit first"
+- "Switch to native review for this review? (Recommended)" / "I'll install CodeRabbit first"
 - If they choose CodeRabbit setup, provide install instructions and STOP
 
 ### Step 2: Determine What to Review
@@ -102,13 +102,13 @@ Task tool call:
     - Include ALL findings
 ```
 
-#### 3B: Claude Review Agent
+#### 3B: Native Review Agent
 
 ```
 Task tool call:
   subagent_type: general-purpose
   model: sonnet
-  description: "Run Claude code review"
+  description: "Run native code review"
   prompt: |
     You are a code reviewer. You have NO prior knowledge of what was built or why.
     Review this code blind, purely on its merits.

package/src/references/configure-tables.md

@@ -100,7 +100,7 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
       "available": false
     }
   },
-  "reviewTool": "claude",
+  "reviewTool": "native",
   "git": {
     "autoCommit": false,
     "commitMessage": {

package/src/skills/configure-docs-index/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configure-docs-index
-description: Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates CLAUDE.md. Used during /5:implement-feature CONFIGURE.
+description: Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates AGENTS.md. Used during /5:implement-feature CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 context: fork
@@ -11,11 +11,11 @@ user-invocable: false
 
 ## Overview
 
-This skill handles the documentation and indexing work during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create the project docs, codebase index, and `CLAUDE.md`.
+This skill handles the documentation and indexing work during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create the project docs, codebase index, and `AGENTS.md`.
 
 It handles one task:
 
-- **Analyze Codebase and Create/Update Documentation + Index** - Maps codebase, writes `.5/*.md`, generates `.5/index/*`, and updates `CLAUDE.md`
+- **Analyze Codebase and Create/Update Documentation + Index** - Maps codebase, writes `.5/*.md`, generates `.5/index/*`, and updates `AGENTS.md`
 
 Note: config.json is written directly by `/5:configure` during the Q&A phase.
 
@@ -23,28 +23,28 @@ Note: config.json is written directly by `/5:configure` during the Q&A phase.
 
 ## Modes
 
-This skill supports two modes. The analysis (A1), template filling (A2-A3), index generation (A3.5), and CLAUDE.md update (A4-A5) logic is the same in both modes — only the **input source** changes.
+This skill supports two modes. The analysis (A1), template filling (A2-A3), index generation (A3.5), and AGENTS.md update (A4-A5) logic is the same in both modes — only the **input source** changes.
 
 ### Full Mode (default)
 
 Used by `/5:configure` → `/5:implement-feature CONFIGURE` flow.
 
 - **Input:** Pattern/command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
-- **Behavior:** Creates documentation, index files, and `CLAUDE.md` from scratch based on feature spec requirements
+- **Behavior:** Creates documentation, index files, and `AGENTS.md` from scratch based on feature spec requirements
 
 ### Refresh Mode
 
 Used by `/5:reconfigure` for lightweight refresh.
 
 - **Input:** The Task prompt tells it to refresh documentation and the codebase index
-- **Behavior:** Re-analyzes codebase and overwrites docs, index files, and `CLAUDE.md`
+- **Behavior:** Re-analyzes codebase and overwrites docs, index files, and `AGENTS.md`
 - **Trigger:** Task prompt includes "REFRESH MODE"
 
 In both modes, the analysis and generation logic is identical.
 
 ---
 
-## A. Analyze Codebase and Create/Update CLAUDE.md
+## A. Analyze Codebase and Create/Update AGENTS.md
 
 **Process:**
 
@@ -139,11 +139,11 @@ Generate a repository-local codebase index that stays generic and works for any
 - Skip categories that do not apply. Do not generate empty placeholder files.
 - The script should overwrite previously generated index files on each run so rebuild is idempotent.
 
-### A4. Create CLAUDE.md
+### A4. Create AGENTS.md
 
-Generate CLAUDE.md:
+Generate `AGENTS.md` — the provider-agnostic instructions file that works with any AI coding tool:
 
-CLAUDE.md structure:
+AGENTS.md structure:
 - **Project Overview:** 1-2 sentences from README/package.json
 - **Build & Run Commands:** Build, test, and other detected commands
 - **Workflow Rules:** Include this section verbatim:
@@ -156,16 +156,33 @@ CLAUDE.md structure:
 - **Coding Guidelines:** The 6 mandatory principles (types, concise docs, short files, extract methods, SRP/DRY, maintainable/modular)
 - **Project Documentation:** Links to whichever `.5/` files were created (only list files that exist)
 - **Codebase Index:** Add a section linking `.5/index/README.md`, the generated index files, and the rebuild script
-- **Index Freshness Rule:** State clearly that if the index files are more than one day old, Claude should regenerate them by running `.5/index/rebuild-index.sh` before relying on them
+- **Index Freshness Rule:** State clearly that if the index files are more than one day old, the agent should regenerate them by running `.5/index/rebuild-index.sh` before relying on them
 
-### A5. Preserve Existing Content
+### A5. Migrate and Preserve Existing Content
 
-If CLAUDE.md already exists:
+**Run this step BEFORE writing the CLAUDE.md shim** to avoid data loss.
+
+**If `AGENTS.md` already exists:**
 - Read current content
 - Identify user-written custom sections (not matching template structure)
-- Preserve under "Custom Documentation" section in new CLAUDE.md
+- Preserve under "Custom Documentation" section in new AGENTS.md
 - Ensure 6 mandatory coding guidelines are retained
 
+**If `CLAUDE.md` already exists with real content (not just `@AGENTS.md`):**
+- Read current CLAUDE.md content
+- Identify user-written custom sections (not matching template structure)
+- Migrate all content into the new AGENTS.md (preserve under "Custom Documentation" section)
+
+### A6. Create CLAUDE.md shim (Claude Code only)
+
+After migration is complete (A5), create or overwrite `CLAUDE.md` with only:
+
+```
+@AGENTS.md
+```
+
+This single line uses Claude Code's include syntax to pull in the full AGENTS.md content. This way Claude Code users get the instructions automatically, while other AI tools (Codex, etc.) read AGENTS.md directly.
+
 ---
 
 ## Output Contract
@@ -173,13 +190,14 @@ If CLAUDE.md already exists:
 Returns structured results for each component:
 
 ```
-Component A (Documentation + Index): SUCCESS - Created documentation files, codebase index, and CLAUDE.md
+Component A (Documentation + Index): SUCCESS - Created documentation files, codebase index, and AGENTS.md
   - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
   - .5/TESTING.md (mocking patterns, gotchas documented)
   - .5/CONCERNS.md (3 TODO items, 1 security note) [or "skipped — no concerns found"]
   - .5/index/rebuild-index.sh (generated index rebuild script)
   - .5/index/*.md (focused codebase index files)
-  - CLAUDE.md (updated with references)
+  - AGENTS.md (updated with references)
+  - CLAUDE.md (shim: @AGENTS.md)
 ```
 
 Or on failure:
@@ -190,7 +208,7 @@ Component A (Documentation + Index): FAILED - Unable to read template files
 
 ## DO NOT
 
-- DO NOT overwrite existing user-written CLAUDE.md sections
+- DO NOT overwrite existing user-written AGENTS.md sections
 - DO NOT include `steps` in config.json
 - DO NOT hardcode conventions - always derive from actual project analysis
 - DO NOT generate empty or placeholder index files

package/src/skills/configure-skills/SKILL.md

@@ -219,7 +219,7 @@ For each applicable rule:
 1. **Derive `paths:` globs** from detected file locations (e.g., if tests are at `src/**/*.test.ts` and `tests/**/*.spec.ts`, use those patterns)
 2. **Convert analysis observations into imperative directives** — "Use X", "Always Y", "Never Z"
 3. **Keep each file 15-40 lines** — be concise and actionable
-4. **Do not repeat** the 6 mandatory coding guidelines from `CLAUDE.md`
+4. **Do not repeat** the 6 mandatory coding guidelines from `AGENTS.md`
 
 Write files to `.claude/rules/`:
 
@@ -311,4 +311,4 @@ Component D (Rules): SKIPPED - rules.generate is false in config
 - DO NOT hardcode conventions - always derive from actual project analysis
 - DO NOT generate empty or placeholder skill or rule files
 - DO NOT assume command syntax - always read from actual config files (package.json, Makefile, etc.)
-- DO NOT repeat the 6 mandatory coding guidelines from `CLAUDE.md` in rule files
+- DO NOT repeat the 6 mandatory coding guidelines from `AGENTS.md` in rule files

package/src/skills/generate-readme/SKILL.md

@@ -78,7 +78,7 @@ Look for patterns in project documentation:
 
 - Check `.5/ARCHITECTURE.md` for architectural patterns and non-obvious conventions
 - Check `.5/TESTING.md` for test patterns and conventions
-- Fall back to CLAUDE.md if `.5/` documentation not present
+- Fall back to AGENTS.md if `.5/` documentation not present
 - Check module-specific documentation
 
 Use these patterns to identify what's critical for the module README.

package/src/skills/generate-readme/TEMPLATE.md

@@ -75,7 +75,7 @@ Examples:
 
 **DO NOT include:**
 
-- General patterns covered in CLAUDE.md
+- General patterns covered in AGENTS.md
 - Obvious patterns like "use builders for construction"
 - Implementation details
 
@@ -95,8 +95,8 @@ Examples:
 
 **Don't include:**
 
-- Links to CLAUDE.md sections relevant to this module
-- Don't repeat things and patterns already documented in CLAUDE.md
+- Links to AGENTS.md sections relevant to this module
+- Don't repeat things and patterns already documented in AGENTS.md
 
 **Include for:**
 
@@ -112,7 +112,7 @@ Examples:
 
 1. List every validator, query, or handler class individually
 2. Document implementation details
-3. Copy content from CLAUDE.md
+3. Copy content from AGENTS.md
 4. Include exhaustive method signatures
 5. Create walls of text
 6. Document every package
@@ -122,7 +122,7 @@ Examples:
 
 1. Focus on top-level overview
 2. List 3-5 key components only
-3. Reference CLAUDE.md for patterns
+3. Reference AGENTS.md for patterns
 4. Keep it under 100 lines
 5. Use examples sparingly
 6. Use package references for groups

package/src/templates/workflow/FEATURE-SPEC.md

@@ -4,6 +4,8 @@
 - Entity definitions describe data concepts, not schemas or interfaces
 - Acceptance criteria describe observable behavior, not test assertions
 - NO code, pseudo-code, or implementation details anywhere in this document
+- Visual Overview section is OPTIONAL — delete it if the feature doesn't benefit from diagrams
+- Mermaid diagrams describe WHAT happens, not HOW it is implemented
 -->
 
 # Feature: {TICKET-ID} - {Title}
@@ -12,27 +14,57 @@
 {TICKET-ID}
 
 ## Summary
-{1-2 sentence overview of what will be implemented}
+{1-2 sentence overview: what capability is being added and who benefits}
 
 ## Problem Statement
-{Why is this feature needed? What problem does it solve?}
+{Describe the current pain point or gap. Who experiences it and what is the impact?}
+
+## Visual Overview
+<!-- OPTIONAL: Include mermaid diagrams only when they add clarity to the feature.
+     Delete this entire section if the feature is simple enough to understand without diagrams.
+     Use whichever diagram types are relevant — you don't need all of them. -->
+
+<!-- Process Flow — use when the feature involves a multi-step process or state transitions -->
+```mermaid
+flowchart TD
+    A[Start state] --> B[Step 1]
+    B --> C{Decision point}
+    C -->|Yes| D[Outcome 1]
+    C -->|No| E[Outcome 2]
+```
+
+<!-- Entity Relationships — use when new data concepts relate to existing ones -->
+```mermaid
+erDiagram
+    ENTITY-A ||--o{ ENTITY-B : "relationship"
+    ENTITY-B }|--|| ENTITY-C : "relationship"
+```
+
+<!-- Component Interactions — use when multiple modules or services communicate -->
+```mermaid
+sequenceDiagram
+    actor User
+    participant ComponentA
+    participant ComponentB
+    User->>ComponentA: action
+    ComponentA->>ComponentB: interaction
+    ComponentB-->>User: result
+```
 
 ## Requirements
 
 ### Functional Requirements
-- {Requirement 1}
-- {Requirement 2}
+- {The system shall... [describe observable behavior]}
 - ...
 
 ### Non-Functional Requirements
-- {Performance requirements}
-- {Compatibility requirements}
+- {Performance, reliability, scalability, or compatibility expectations}
 - ...
 
 ## Constraints
-- {Business constraints}
-- {Technical constraints}
-- {Time/resource constraints}
+- {Business rules that limit the solution space}
+- {Technical boundaries from existing architecture}
+- {Timeline or resource limitations}
 
 ## Affected Components
 - **{component/module-1}** - {What changes here}
@@ -56,9 +88,9 @@
 - ...
 
 ## Acceptance Criteria
-- [ ] {Criterion 1 - how to verify success}
-- [ ] {Criterion 2}
-- [ ] {Criterion 3}
+- [ ] {Observable behavior that proves this requirement is met}
+- [ ] {Observable behavior that proves this requirement is met}
+- [ ] {Observable behavior that proves this requirement is met}
 - ...
 
 ## Alternatives Considered
@@ -78,22 +110,24 @@
 
 ## Decisions
 
-<!-- Tag every Q&A with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
-  - [DECIDED]: Locked decision — Phase 2 planner and Phase 3 agents MUST honor exactly
-  - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
-  - [DEFERRED]: Explicitly out of scope — planner MUST NOT include in the plan
+<!-- Record key decisions from the spec discussion.
+     Tag each with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
+     - [DECIDED]: Locked — Phase 2 planner and Phase 3 agents MUST honor exactly
+     - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
+     - [DEFERRED]: Out of scope — planner MUST NOT include in the plan
 -->
 
-### Q1: {Question from collaboration phase}
-**A:** {Answer from developer} **[DECIDED]**
+### {Topic: brief description of what was decided}
+**Context:** {Why this decision came up}
+**Decision:** {What was decided} **[DECIDED]**
 
-### Q2: {Question}
-**A:** {Answer} **[FLEXIBLE]**
+### {Topic: area left to implementer's discretion}
+**Context:** {What was discussed}
+**Decision:** {General direction, implementer chooses specifics} **[FLEXIBLE]**
 
-### Q3: {Question about a nice-to-have}
-**A:** {Answer — let's skip this for now} **[DEFERRED]**
-
-...
+### {Topic: explicitly deferred item}
+**Context:** {Why it was raised}
+**Decision:** {Not addressing now — reason} **[DEFERRED]**
 
 ## Next Steps
 After approval:

package/src/templates/workflow/PLAN.md

@@ -10,7 +10,8 @@ created: {ISO-timestamp}
 - Description column: one action-oriented sentence per component
 - Pattern File column: path to an existing file the executor MUST read before implementing (establishes conventions)
 - Verify column: a concrete command or check the executor runs after implementing (grep pattern, test command, build check)
-- Implementation Notes: reference existing files as patterns, no code snippets
+- Depends On column: name of a component this one depends on (for cross-step data dependencies), or "—" if none
+- Implementation Notes: scoped with [global], [Step N], or [component-name] prefixes — the orchestrator filters per agent
 - Components table must cover all functional requirements from feature.md
 - Three test tiers: unit (always required for logic), integration (when framework detected + cross-module/DB/API), e2e (when framework detected + endpoints/UI flows)
 - Every "create" component with logic (services, controllers, repositories, utilities) must have a corresponding unit test component
@@ -24,16 +25,16 @@ created: {ISO-timestamp}
 
 ## Components
 
-| Step | Component | Action | File | Description | Pattern File | Verify | Complexity |
-|------|-----------|--------|------|-------------|-------------|--------|------------|
-| 1 | {name} | create | {path} | {what it does} | {existing file to read first} | {grep/test command} | simple |
-| 1 | {name} | create | {path} | {what it does} | {pattern} | {verify} | simple |
-| 2 | {name} | create | {path} | {what it does} | {pattern} | {verify} | moderate |
-| 2 | {name} | modify | {path} | {what to change} | {target file} | {verify} | moderate |
-| 3 | {name} | create | {path} | {what it does} | {pattern} | {verify} | complex |
-| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | {existing test} | {test command} | moderate |
-| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | {existing test} | {test command} | moderate |
-| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | {existing test} | {test command} | moderate |
+| Step | Component | Action | File | Description | Pattern File | Verify | Complexity | Depends On |
+|------|-----------|--------|------|-------------|-------------|--------|------------|------------|
+| 1 | {name} | create | {path} | {what it does} | {existing file to read first} | {grep/test command} | simple | — |
+| 1 | {name} | create | {path} | {what it does} | {pattern} | {verify} | simple | — |
+| 2 | {name} | create | {path} | {what it does} | {pattern} | {verify} | moderate | {step-1-component} |
+| 2 | {name} | modify | {path} | {what to change} | {target file} | {verify} | moderate | — |
+| 3 | {name} | create | {path} | {what it does} | {pattern} | {verify} | complex | {step-2-component} |
+| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | {existing test} | {test command} | moderate | {tested-component} |
+| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | {existing test} | {test command} | moderate | {tested-component} |
+| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | {existing test} | {test command} | moderate | {tested-component} |
 
 ## Testing Strategy
 
@@ -41,9 +42,9 @@ created: {ISO-timestamp}
 
 ## Implementation Notes
 
-- Follow the pattern from {existing-file} for {component-type}
-- {Key business rule to remember}
-- {Integration point to wire up}
+- [global] Follow the pattern from {existing-file} for {component-type}
+- [Step N] {Convention or context relevant to all components in step N}
+- [{component-name}] {Key business rule or integration point specific to this component}
 
 ## Verification