5-phase-workflow 1.8.9 → 1.9.1

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
 
@@ -117,12 +129,13 @@ Analyze the codebase for a feature specification session.
 **Feature Description:** {paste the user's feature description}
 
 **Your Task:**
-1. Explore project structure to identify modules/components
-2. Find existing implementations similar to this feature
-3. Identify coding patterns and conventions
-4. Find reusable components or patterns
-5. Identify affected files/modules
-6. Run `git branch --show-current` to get the current branch name
+1. Check if `.5/index/` exists. If it does, read `.5/index/README.md` first — it includes a generation timestamp. If the index is fresh (under 1 day old), read the relevant index files (e.g., modules.md, routes.md, models.md) as your structural overview and skip broad Glob scans for information already covered. If the index is outdated (over 1 day old), note in your report that the user should run `.5/index/rebuild-index.sh` to refresh it, then use it anyway (stale is better than nothing). If `.5/index/` does not exist at all, note in your report that the user can run `/5:reconfigure` to generate it, then proceed with Glob/Grep exploration as below.
+2. Explore project structure to identify modules/components
+3. Find existing implementations similar to this feature
+4. Identify coding patterns and conventions
+5. Find reusable components or patterns
+6. Identify affected files/modules
+7. Run `git branch --show-current` to get the current branch name
 
 **Report Format:**
 - Current git branch name
@@ -140,11 +153,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 +191,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 +212,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 +243,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.
 
@@ -145,13 +160,14 @@ Quick codebase scan for implementation planning.
 Focus scan on {projectType}-relevant directories and patterns.
 
 **Your Task:**
-1. Find source directories and understand project structure
-2. Identify where similar components live (models, services, controllers, tests)
-3. Note naming conventions from existing files
-4. Find example files that can serve as patterns for new components
-5. Identify the project's test framework, test file conventions, and test directory structure (e.g., __tests__/, tests/, *.test.ts, *.spec.ts, test_*.py)
-6. Detect e2e test framework and config (Cypress, Playwright, Selenium, Supertest, etc.) — look for config files like playwright.config.ts, cypress.config.js, e2e/ directories
-7. Detect integration test patterns (test containers, in-memory DBs, API test helpers, fixtures) — look for setup files, docker-compose.test.yml, test utilities
+1. Check if `.5/index/` exists. If it does, read `.5/index/README.md` first — it includes a generation timestamp. If the index is fresh (under 1 day old), read the relevant index files (modules.md, models.md, libraries.md, etc.) for project structure and component locations, then focus Glob/Grep on naming conventions, pattern files, and test framework details not covered by the index. If the index is outdated (over 1 day old), note in your report that the user should run `.5/index/rebuild-index.sh` to refresh it, then use it anyway. If `.5/index/` does not exist at all, note in your report that the user can run `/5:reconfigure` to generate it, then scan from scratch as below.
+2. Find source directories and understand project structure
+3. Identify where similar components live (models, services, controllers, tests)
+4. Note naming conventions from existing files
+5. Find example files that can serve as patterns for new components
+6. Identify the project's test framework, test file conventions, and test directory structure (e.g., __tests__/, tests/, *.test.ts, *.spec.ts, test_*.py)
+7. Detect e2e test framework and config (Cypress, Playwright, Selenium, Supertest, etc.) — look for config files like playwright.config.ts, cypress.config.js, e2e/ directories
+8. Detect integration test patterns (test containers, in-memory DBs, API test helpers, fixtures) — look for setup files, docker-compose.test.yml, test utilities
 
 **Report Format:**
 - Project structure (key directories)
@@ -170,17 +186,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 +245,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 +259,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 +283,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 +320,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/quick-implement.md

@@ -91,7 +91,7 @@ Check if `.5/features/${feature_name}/state.json` already exists:
 
 ### Step 4: Analyze and Scope Check
 
-1. **Identify affected files** using Glob and Grep
+1. **Identify affected files:** If `.5/index/` exists, read `.5/index/README.md` first for the generation timestamp — if fresh (under 1 day old), read the relevant index files (modules.md, routes.md, models.md) to quickly locate affected areas, then confirm with targeted Glob/Grep. If the index is outdated, note that the user can run `.5/index/rebuild-index.sh` to refresh it. If no index exists, note that the user can run `/5:reconfigure` to generate it. In both cases, fall back to Glob and Grep directly.
 2. **Determine skills needed** based on task type
 3. **List components** (max 5 for quick mode)
 
@@ -261,6 +261,7 @@ Task tool call:
     For each component:
 
     **If creating a new file:**
+    0. If `.5/index/` exists, check modules.md or libraries.md to find where similar components live — this narrows your Glob search.
     1. Find a similar file using Glob (e.g., *Service.ts for services)
     2. Read it to understand the pattern (imports, structure, exports)
     3. Create the new file following that pattern

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.