5-phase-workflow 1.8.7 → 1.8.9

package/package.json

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

package/src/commands/5/configure.md

@@ -23,7 +23,7 @@ This command is **Phase 1** of the 5-phase workflow applied to project configura
 After running this command, proceed through the standard phases:
 1. **`/5:configure`** (this command) - Plan the configuration feature
 2. `/5:plan-implementation CONFIGURE` - Create implementation plan
-3. `/5:implement-feature CONFIGURE` - Execute configuration (uses `configure-project` skill)
+3. `/5:implement-feature CONFIGURE` - Execute configuration (uses `configure-docs-index` and `configure-skills`)
 4. `/5:verify-implementation` - Verify configuration
 5. `/5:review-code` - Review generated files
 
@@ -307,11 +307,13 @@ Write `.5/features/CONFIGURE/feature.md` containing all gathered data:
 # Feature: Project Configuration
 
 ## Summary
-Generates CLAUDE.md with codebase analysis and creates project-specific skills. (config.json already written.)
+Generates CLAUDE.md, a rebuildable codebase index, and project-specific skills. (config.json already written.)
 
 ## Requirements
 
 ### Requirement 1: Generate Documentation Files
+Handled by: `configure-docs-index`
+
 Analyze the codebase and generate focused documentation capturing only non-derivable knowledge (skip version numbers, dependency lists, directory layouts, linter configs — Claude Code can look these up directly):
 
 **Create documentation files in `.5/` folder:**
@@ -319,9 +321,18 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
 - `.5/TESTING.md` - Test organization, patterns, mocking approach, gotchas
 - `.5/CONCERNS.md` - Tech debt, known issues, security/integration/performance notes (**only if concerns found — skip file entirely if nothing detected**)
 
+**Create a rebuildable codebase index in `.5/index/`:**
+- Generate a repository-local script at `.5/index/rebuild-index.sh`
+- Generate multiple focused Markdown index files in `.5/index/` plus `.5/index/README.md`
+- Keep the index generic and adapted to the actual project
+- Skip empty categories; do not create placeholder index files
+- Re-running the script should fully refresh the index in place
+
 **Create CLAUDE.md:**
 - 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`
+- An explicit instruction that if the codebase index is older than one day, it should be regenerated by running `.5/index/rebuild-index.sh`
 - Workflow rules section (verbatim):
   ```
   ## Workflow Rules
@@ -341,6 +352,7 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
 - If CLAUDE.md already exists, preserve user-written custom sections
 
 ### Requirement 2: Generate Project-Specific Skills
+Handled by: `configure-skills`
 
 **Create-* skills** for each user-selected architectural pattern:
 - Skill name: `create-{pattern}` (e.g., `create-controller`, `create-service`)
@@ -355,6 +367,8 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
 Include only patterns/commands where user selected "Generate".
 
 ### Requirement 3: Generate Scoped Rules (if selected)
+Handled by: `configure-skills`
+
 Generate `.claude/rules/` files with project-specific conventions scoped to relevant file types.
 Rules are concise directives (15-40 lines, NOT documentation) derived from codebase analysis.
 Only generate rules for patterns that were actually detected:
@@ -369,8 +383,14 @@ Only generate rules for patterns that were actually detected:
   - [ ] `.5/ARCHITECTURE.md` — architecture, conventions, where to add code
   - [ ] `.5/TESTING.md` — test patterns and gotchas
   - [ ] `.5/CONCERNS.md` — only if concerns were found (omit if empty)
+- [ ] `.5/index/` directory exists
+- [ ] `.5/index/rebuild-index.sh` exists and rebuilds the index
+- [ ] `.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
 - [ ] All specified project-specific skills are generated in `.claude/skills/`
 - [ ] Generated skills reference actual project conventions
@@ -395,4 +415,5 @@ Tell the user:
 4. "After that: Continue with `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code` (clearing context between each phase)"
 
 ## Related Documentation
-- [configure-project skill](../../skills/configure-project/SKILL.md)
+- [configure-docs-index skill](../../skills/configure-docs-index/SKILL.md)
+- [configure-skills skill](../../skills/configure-skills/SKILL.md)

package/src/commands/5/eject.md

@@ -3,8 +3,6 @@ name: 5:eject
 description: Eject from the update mechanism — permanently removes update infrastructure
 allowed-tools: Bash, Read, Edit, AskUserQuestion
 user-invocable: true
-model: haiku
-context: fork
 ---
 
 <role>
@@ -14,13 +12,17 @@ After ejecting, you are DONE.
 
 # Eject from Update Mechanism
 
+Determine which runtime is installed before making any changes:
+- Claude Code install: workflow files live in `.claude/`
+- Codex install: workflow files live in `.codex/`
+
+Use runtime-appropriate paths in every step below.
+
 Ejecting permanently removes the update system from this installation. After ejecting:
-- The update check hook (`check-updates.js`) is deleted
-- The update command (`/5:update`) is deleted
-- The eject command (`/5:eject`) is deleted
+- The update infrastructure files are deleted
 - Version tracking (`.5/version.json`) is deleted
 - The update cache (`.5/.update-cache.json`) is deleted
-- The `check-updates.js` hook entry is removed from `.claude/settings.json`
+- Claude Code installs also remove the `check-updates.js` hook entry from `.claude/settings.json`
 
 All other workflow files (commands, skills, hooks, templates) remain untouched.
 
@@ -39,13 +41,19 @@ Tell the user what ejecting means:
 > **Eject from 5-Phase Workflow updates?**
 >
 > This will permanently delete:
+> - `.5/version.json` (version tracking)
+> - `.5/.update-cache.json` (update cache)
+>
+> For Claude Code installs:
 > - `.claude/hooks/check-updates.js` (update check hook)
 > - `.claude/commands/5/update.md` (update command)
 > - `.claude/commands/5/eject.md` (this command)
-> - `.5/version.json` (version tracking)
-> - `.5/.update-cache.json` (update cache)
+> - The `check-updates.js` hook entry in `.claude/settings.json`
 >
-> The `check-updates.js` hook entry will also be removed from `.claude/settings.json`.
+> For Codex installs:
+> - `.codex/skills/5-update/` (update skill)
+> - `.codex/skills/5-eject/` (this skill)
+> - `.codex/instructions.md` is removed only if it is workflow-managed and no longer needed for remaining installed workflow files
 >
 > All other workflow files remain untouched. To restore updates later, reinstall with `npx 5-phase-workflow`.
 
@@ -61,9 +69,18 @@ Run this command to delete the update-related files:
 rm -f .claude/hooks/check-updates.js .claude/commands/5/update.md .claude/commands/5/eject.md .5/version.json .5/.update-cache.json
 ```
 
+For Codex installs, remove the runtime-appropriate files instead:
+
+```bash
+rm -rf .codex/skills/5-update .codex/skills/5-eject
+rm -f .5/version.json .5/.update-cache.json
+```
+
 ## Step 4: Clean Up settings.json
 
-Read `.claude/settings.json`. Remove the hook entry from the `hooks.SessionStart` array where the command is `node .claude/hooks/check-updates.js`.
+Claude Code installs only: read `.claude/settings.json`. Remove the hook entry from the `hooks.SessionStart` array where the command is `node .claude/hooks/check-updates.js`.
+
+Codex installs do not use `.claude/settings.json` or Claude hooks for updates, so skip this step for Codex.
 
 Specifically, find and remove the object in the `SessionStart` array that looks like:
 
@@ -89,3 +106,5 @@ Tell the user:
 > Ejected successfully. Update infrastructure has been removed from this installation (was v{packageVersion}).
 >
 > To restore update functionality, reinstall with: `npx 5-phase-workflow`
+>
+> If this was a Codex install, use: `npx 5-phase-workflow --codex`

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

@@ -4,7 +4,6 @@ description: Plans feature implementation by analyzing requirements, identifying
 allowed-tools: Read, Write, Task, AskUserQuestion
 user-invocable: true
 model: opus
-context: fork
 ---
 
 <role>

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

@@ -4,7 +4,6 @@ description: Creates an implementation plan from a feature spec. Phase 2 of the
 allowed-tools: Read, Write, Task, AskUserQuestion
 user-invocable: true
 model: opus
-context: fork
 ---
 
 <role>

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

@@ -3,7 +3,6 @@ name: 5:quick-implement
 description: Execute small, focused implementations quickly with state tracking and atomic commits. Skips extensive planning phases and verification agents - use for tasks where you know exactly what to do.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
 user-invocable: true
-context: fork
 ---
 
 <role>

package/src/commands/5/reconfigure.md

@@ -1,6 +1,6 @@
 ---
 name: 5:reconfigure
-description: Lightweight refresh of project documentation and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, 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 CLAUDE.md, and refreshes all skills.
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 user-invocable: true
 context: fork
@@ -9,7 +9,7 @@ context: fork
 <role>
 You are a Project Reconfigurer. You refresh documentation and skills using existing config.json preferences.
 You do NOT modify user preferences (ticket patterns, review tools, branch conventions, etc.).
-You detect codebase changes, confirm with the user, invoke configure-project skill, then report.
+You detect codebase changes, confirm with the user, invoke the configuration refresh skills, then report.
 After reporting what was updated, you are DONE.
 </role>
 
@@ -37,7 +37,7 @@ Your job:
 ✅ Re-detect codebase patterns and commands (same as configure Steps 1b-1h)
 ✅ Compare detected state with config.json skill selections
 ✅ Show summary and ask for confirmation
-✅ Invoke configure-project skill in refresh mode
+✅ Invoke `configure-docs-index` and `configure-skills` in refresh mode
 ✅ Update version.json with artifacts and timestamps
 ✅ Clean up .reconfig-reminder flag
 ✅ Report what was updated
@@ -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) + 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 `CLAUDE.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?"
@@ -134,10 +134,14 @@ New skills will be created and stale skills removed based on the user's choices.
 
 ### Step 5: Regenerate
 
-Invoke the `configure-project` skill in **refresh mode** via the Task tool:
+Invoke the refresh skills in **refresh mode** via the Task tool:
 
 ```
-Task prompt: "Run configure-project skill in REFRESH MODE.
+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."
+
+Task prompt 2: "Run configure-skills skill in REFRESH MODE.
 
 Refresh ALL existing skills in .claude/skills/:
 - Existing create-* skills: [list from Step 2e]
@@ -150,18 +154,13 @@ Refresh rules in .claude/rules/ (if rules.generate is true):
 - Existing workflow rules: [list from Step 2f]
 - Rules to remove: [list from user confirmation, if any]
 - New rules to create: [if applicable]
-
-Re-analyze the entire codebase (A1 analysis) and:
-1. Rewrite .5/ARCHITECTURE.md and .5/TESTING.md
-2. Rewrite .5/CONCERNS.md (or delete if no concerns found)
-3. Delete legacy docs if they exist: .5/STACK.md, .5/STRUCTURE.md, .5/CONVENTIONS.md, .5/INTEGRATIONS.md
-4. Update CLAUDE.md (preserve user-written sections)
-5. Refresh ALL skills in .claude/skills/ — read current conventions from codebase and update each skill
-6. Create new skills for newly-added patterns
-7. Remove skills the user chose to drop
-8. Refresh all workflow-generated rule files in .claude/rules/ with updated conventions
-9. Create new rule files for newly-detected patterns
-10. Remove rule files the user chose to drop"
+Re-analyze the codebase and:
+1. Refresh ALL skills in .claude/skills/ — read current conventions from codebase and update each skill
+2. Create new skills for newly-added patterns
+3. Remove skills the user chose to drop
+4. Refresh all workflow-generated rule files in .claude/rules/ with updated conventions
+5. Create new rule files for newly-detected patterns
+6. Remove rule files the user chose to drop"
 ```
 
 Use `subagent_type: "general-purpose"` for the Task.
@@ -186,6 +185,7 @@ rm -f .5/.reconfig-reminder
 
 Show the user a summary:
 - List of documentation files updated
+- Mention whether the codebase index script and index files were regenerated
 - List of skills refreshed
 - List of new skills created (if any)
 - List of skills removed (if any)
@@ -197,4 +197,5 @@ Show the user a summary:
 
 ## Related Documentation
 - [configure command](./configure.md) — full Q&A configuration
-- [configure-project skill](../../skills/configure-project/SKILL.md) — the skill that does the heavy lifting
+- [configure-docs-index skill](../../skills/configure-docs-index/SKILL.md)
+- [configure-skills skill](../../skills/configure-skills/SKILL.md)

package/src/commands/5/update.md

@@ -25,6 +25,12 @@ Read `.5/version.json` and note the current `installedVersion`.
 npx 5-phase-workflow@latest --upgrade
 ```
 
+If this installation is running in Codex (workflow files live in `.codex/` or the workflow command was invoked as a `$5-...` skill), run this instead:
+
+```bash
+npx 5-phase-workflow@latest --codex --upgrade
+```
+
 ## Step 3: Confirm Upgrade
 
 Read `.5/version.json` again. Compare the new `installedVersion` to the previous one.
@@ -34,14 +40,16 @@ Read `.5/version.json` again. Compare the new `installedVersion` to the previous
 
 ## Step 4: Show What Changed
 
-Run `git status` to show the files modified by the upgrade. Summarize the changes for the user (e.g., "Updated 12 files in `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`").
+Run `git status` to show the files modified by the upgrade. Summarize the changes for the user using the correct runtime paths:
+- Claude Code installs typically update files in `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`
+- Codex installs typically update files in `.codex/skills/`, `.codex/templates/`, `.codex/references/`, `.codex/instructions.md`, and `.5/version.json`
 
 ## Step 5: Ask to Commit
 
 Ask the user: "Would you like to commit the upgraded workflow files?"
 
 Options:
-1. **Yes** - commit the changes, do not mention claude
+1. **Yes** - commit the changes, do not mention Claude Code
 2. **No** - leave changes uncommitted
 
 If the user chooses **No**, stop here.
@@ -56,6 +64,11 @@ Build the commit message by applying the pattern:
 - If the pattern is the conventional format (`feat({ticket-id}): {short-description}`), use: `chore: update 5-Phase Workflow to {new-version}`
 - If no config or no pattern, use: `update 5-Phase Workflow to {new-version}`
 
-Stage **only** the workflow-managed files shown in `git status` (inside `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`). Never use `git add .` or `git add -A`.
+Stage **only** the workflow-managed files shown in `git status`.
+
+- For Claude Code installs, this usually means files inside `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`
+- For Codex installs, this usually means files inside `.codex/skills/`, `.codex/templates/`, `.codex/references/`, `.codex/instructions.md`, and `.5/version.json`
+
+Never use `git add .` or `git add -A`.
 
 Create the commit. Report success to the user.

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

@@ -0,0 +1,196 @@
+---
+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.
+allowed-tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+context: fork
+user-invocable: false
+---
+
+# Configure Docs And Index Skill
+
+## 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`.
+
+It handles one task:
+
+- **Analyze Codebase and Create/Update Documentation + Index** - Maps codebase, writes `.5/*.md`, generates `.5/index/*`, and updates `CLAUDE.md`
+
+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.
+
+### 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
+
+### 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`
+- **Trigger:** Task prompt includes "REFRESH MODE"
+
+In both modes, the analysis and generation logic is identical.
+
+---
+
+## A. Analyze Codebase and Create/Update CLAUDE.md
+
+**Process:**
+
+### A1. Codebase Analysis
+
+Perform focused analysis to gather data for documentation templates. Only capture information that **cannot be derived** by reading project files directly — skip version numbers, dependency lists, directory layouts, linter configs, and other facts that Claude Code can look up on demand.
+
+**Architecture Analysis** (for ARCHITECTURE.md):
+- Identify architectural pattern (MVC, layered, modular, microservices) from directory structure
+- Map layers by directory structure (controllers/, services/, models/, routes/, etc.)
+- Trace data flow patterns (read 2-3 example files from different layers)
+- Identify key abstractions (interfaces, base classes, common patterns)
+- Identify non-obvious conventions: implicit rules not enforced by tooling (e.g., "all services extend BaseService", "barrel exports required per module"). Skip anything in .eslintrc, .prettierrc, tsconfig, etc.
+- Determine where new code should go (new features, tests, utilities)
+
+**Testing Analysis** (for TESTING.md):
+- Determine test organization (co-located vs separate `test/` or `spec/`)
+- Identify mocking framework and project-specific mocking conventions
+- Find fixture/factory patterns
+- Note gotchas: setup/teardown quirks, env requirements, flaky areas
+
+**Concerns Analysis** (for CONCERNS.md — conditional):
+- Grep for TODO/FIXME/HACK/XXX/DEPRECATED comments across all code
+- Check for common security issues (SQL injection patterns, XSS vulnerabilities)
+- Identify non-obvious integration details: auth flows, required env vars not documented elsewhere, webhook contracts, gotchas with external services
+- Look for performance bottlenecks or scaling limits mentioned in comments/docs
+
+### A2. Fill Templates
+
+For each template in `.claude/templates/`:
+
+1. Read template content with Read tool
+2. Replace placeholders with analyzed data from A1
+3. **Omit sections entirely if no data was found** — do not write "Not detected" or "None found"
+4. For CONCERNS.md: if ALL sections would be empty, **do not create the file at all**
+
+**Placeholder mapping examples**:
+
+ARCHITECTURE.md:
+- `{Pattern name}` → "Layered Architecture" or "MVC" or "Modular Monolith"
+- `{Layer}` → "Controllers", "Services", "Repositories"
+- `{path}` → "src/controllers/", "src/services/"
+
+TESTING.md:
+- Describe actual patterns observed, not framework names/versions (those are in config files)
+
+CONCERNS.md:
+- `{file paths}` → Actual file paths from grep results
+
+### A3. Write Documentation Files
+
+Write filled templates to `.5/` folder:
+
+1. Ensure `.5/` directory exists: `mkdir -p .5`
+2. Write filled templates:
+   - `.5/ARCHITECTURE.md` — always created
+   - `.5/TESTING.md` — always created
+   - `.5/CONCERNS.md` — **only if concerns were found** (skip if all sections empty)
+
+### A3.5. Generate Codebase Index Script and Index Files
+
+Generate a repository-local codebase index that stays generic and works for any language or framework detected in the project.
+
+**Requirements:**
+- Create `.5/index/` if it does not exist
+- Generate a script that rebuilds the index at `.5/index/rebuild-index.sh`
+- Make the script self-contained and dependency-light:
+  - Prefer portable shell plus standard tools already expected in a dev environment
+  - If the project clearly has a better built-in runtime already available (for example Node.js or Python), it is acceptable to generate a small script in that runtime instead, but keep it local to the repo and avoid adding new dependencies
+- The script must inspect the current codebase and write multiple focused Markdown index files into `.5/index/`
+- Include `.5/index/README.md` as a manifest describing what each generated index file contains and how to rebuild the index
+- Group content by concern and adapt to the actual project. Each file should be compact, easy to scan, and optimized for AI/context loading rather than prose documentation.
+- Each generated index file should follow this style:
+  - Short title and 1-line purpose statement
+  - Bulleted or table-like entries only
+  - One entry per route/component/module/model/command as applicable
+  - Each entry should include the path and a short descriptor
+  - Prefer signatures, exported names, HTTP methods, key fields, and relationships over long explanations
+  - Keep entries factual and compact; avoid narrative paragraphs
+- Suggested file shapes:
+  - `commands.md` — runnable commands, entrypoints, scripts, key developer workflows
+  - `routes.md` — routes, handlers, API endpoints, HTTP methods, notable middleware
+  - `modules.md` — modules/packages/components/services and what they own
+  - `models.md` — schemas, entities, tables, migrations, key relationships
+  - `libraries.md` — shared utilities, helpers, exported functions/classes
+- Suggested categories to create when applicable:
+  - Entrypoints / runnable commands
+  - Routes / handlers / API surface
+  - Components / modules / packages
+  - Data models / schemas / migrations
+  - Libraries / utilities / shared code
+- 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
+
+Generate CLAUDE.md:
+
+CLAUDE.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:
+  ```
+  ## Workflow Rules
+  When running `/5:` workflow commands, follow the command instructions exactly as written.
+  Do not skip steps, combine phases, or proceed to actions not specified in the current command.
+  Each phase produces a specific artifact — do not create artifacts belonging to other phases.
+  ```
+- **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
+
+### A5. Preserve Existing Content
+
+If CLAUDE.md already exists:
+- Read current content
+- Identify user-written custom sections (not matching template structure)
+- Preserve under "Custom Documentation" section in new CLAUDE.md
+- Ensure 6 mandatory coding guidelines are retained
+
+---
+
+## Output Contract
+
+Returns structured results for each component:
+
+```
+Component A (Documentation + Index): SUCCESS - Created documentation files, codebase index, and CLAUDE.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)
+```
+
+Or on failure:
+
+```
+Component A (Documentation + Index): FAILED - Unable to read template files
+```
+
+## DO NOT
+
+- DO NOT overwrite existing user-written CLAUDE.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