5-phase-workflow 3.0.1 → 3.1.0

package/src/commands/5/plan.md

@@ -1,190 +0,0 @@
----
-name: 5:plan
-description: Plans a feature and persists the approved plan as .5/features/{name}/plan.md. Uses native plan mode when available, otherwise an equivalent prose loop. Implements compact plans inline; hands larger ones to /5:implement. Re-run with an existing feature name to refine that plan.
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion, EnterPlanMode, TaskCreate, TaskUpdate, mcp__claude_ai_Atlassian_Rovo__getJiraIssue
-user-invocable: true
-argument-hint: [feature-name-or-ticket-id-or-description]
----
-
-<role>
-You are a Workflow Planner. Your deliverables are `.5/features/{name}/plan.md` and `.5/features/{name}/codebase-scan.md`.
-Exploration, questions, and the approval gate belong to plan mode — you write no code until the user approves the plan.
-After approval you implement only **compact** plans, inline in this session. Anything larger goes to `/5:implement`.
-</role>
-
-# Plan
-
-## Options
-
-- `--github` - Auto-fetch the feature description from the GitHub issue linked to the current branch.
-- `--jira` - Auto-fetch the feature description from the Jira ticket linked to the current branch.
-
-Current branch: !`git branch --show-current`
-
-## Step 1: Resolve Feature and Description
-
-Run these before entering plan mode.
-
-**Refine mode.** If the argument names an existing `.5/features/{name}/plan.md` — directly, or via a ticket prefix matched with Glob on `.5/features/{prefix}*/plan.md` — read that plan and its `codebase-scan.md`. You are refining an existing plan; skip ticket fetching and go to Step 2. If a ticket prefix matches several features, ask which one.
-
-**New plan.** Otherwise:
-
-1. Only when `--github` or `--jira` was passed, resolve the ticket:
-   - Read `.5/config.json` if it exists and extract `ticket.pattern`.
-   - Match the pattern against the branch name above.
-   - Validate the ID before fetching: `--github` requires digits only (`^[0-9]+$`), `--jira` requires key format (`^[A-Z][A-Z0-9]+-[0-9]+$`).
-   - `--jira`: fetch via `mcp__claude_ai_Atlassian_Rovo__getJiraIssue` using the validated key as a typed parameter.
-   - `--github`: run `gh issue view "$id" --json title,body`.
-   - If no ticket ID is found, ask the user for it, validate, then fetch. If validation or fetching fails, report the reason and continue without fetched content.
-   - Show fetched content to the user and ask whether any context is missing.
-2. Otherwise, ask the user for the feature description.
-3. Determine a short kebab-case feature folder name. With a known ticket ID, use `{ticket-id}-{feature-name}`. Sanitize to alphanumeric, dash, and underscore only.
-
-## Step 2: Plan in Plan Mode
-
-Call `EnterPlanMode`. Plan mode owns codebase exploration, clarifying questions, the plan file, and the approval gate — do not run a parallel discovery pass of your own.
-
-If `.5/index/` exists, read `.claude/skills/use-index/SKILL.md` and follow it to select index files instead of scanning the project broadly. Check the `Generated:` timestamp in `.5/index/README.md` first; if the index is more than a day old, run `.5/index/rebuild-index.sh`.
-
-Carry these three constraints into the planning work:
-
-**Output shape.** Write the plan using the section shape of `.claude/templates/workflow/PLAN.md`. Use `.claude/templates/workflow/PLAN-COMPACT.md` instead for small, low-risk changes with 1-2 components, no data migration, no security/auth change, and no public API contract change. The plan must end with a Component Checklist table of `Component | Action | Target Path | Intent`, where action is `create`, `modify`, `delete`, or `rename`. For `rename`, the target path is the destination and the intent names the original path. Do not add step, model, skill, pattern-file, or verify-command columns — `/5:implement` derives that wiring mechanically.
-
-**Necessity gate.** Apply this to every component before it enters the plan. Ask "does this need to exist?" and prefer the simplest approach that meets the acceptance criteria: reuse the standard library, a native platform/framework feature, or an already-installed dependency before adding anything new. Push speculative or "might need later" work to `[DEFERRED]`. Do not plan abstractions, flexibility, or configurability that no acceptance criterion requires.
-
-**No code.** Requirements and implementation intent only — no code or pseudo-code in the plan.
-
-In refine mode, seed the planning work with the existing plan's content and change only what the discussion actually changes.
-
-## Step 3: Persist the Approved Plan
-
-Once the user approves the plan, write:
-
-1. `.5/features/{name}/plan.md` — the approved plan. In refine mode, overwrite the existing file and append to a `## Discussion History` section:
-
-```markdown
-## Discussion History
-
-### {ISO-date} - {topic}
-
-**Changes made:**
-- {added / clarified / removed}
-
-**Rationale:** {why}
-```
-
-2. `.5/features/{name}/codebase-scan.md` — the exploration findings `/5:implement` needs, under 40 lines:
-
-```markdown
-# Codebase Scan
-
-## Relevant Existing Patterns
-- `{path}` - {one-line reason}
-
-## Similar Implementations
-- `{path}` - {one-line reason}
-
-## Likely Target Paths
-- `{path}`
-
-## Test/Build Setup
-- {command} - {scope}
-
-## Risks or Unknowns
-- {risk}
-```
-
-In refine mode, update this file only where exploration produced new findings.
-
-## Step 4: Self-check
-
-Verify:
-
-- The plan has all required template sections, and optional sections with no useful content were omitted.
-- Acceptance criteria are checkboxes.
-- Decisions are labeled `[DECIDED]`, `[FLEXIBLE]`, or `[DEFERRED]`.
-- Every component traces to scope or acceptance criteria, and none adds abstraction, flexibility, or configurability beyond what an acceptance criterion requires.
-- No implementation code or pseudo-code is present.
-
-## Step 5: Hand Off
-
-Approving a plan means the user wants it built. Branch on the plan format you chose in Step 2 — the point is to spend a fresh delegated run only where it pays for itself.
-
-**Compact plan** (`planFormat: compact`, 1-2 low-risk components): implement it here, in this session. The context is already warm, and spinning up orchestration to edit one or two files costs more than it saves. In refine mode, only do this when the refined plan has not been implemented yet — check `.5/features/{name}/state.json`.
-
-1. Say what you are about to do, then implement the Component Checklist directly. Make the smallest coherent change per component and follow the patterns named in the plan.
-2. Run the verify commands from `.5/config.json`. Skip any set to `none`.
-   Then check scope: `git status --short` must list only the Component Checklist target paths and what they strictly need (their tests, import sites). Revert anything else before continuing, and tell the user in one line what you deliberately left out (`skipped: X — add when Y`).
-3. Write `.5/features/{name}/state.json`:
-
-```json
-{
-  "feature": "{name}",
-  "status": "completed|failed",
-  "completedComponents": ["component-name"],
-  "verification": {"status": "passed|partial|failed", "summary": "one line"},
-  "startedAt": "{ISO-timestamp}",
-  "lastUpdated": "{ISO-timestamp}"
-}
-```
-
-Component names must match the plan's Component Checklist verbatim, so a later `/5:implement` can resume against them. This file is also how `/5:review` finds the feature.
-
-4. If `.5/config.json` `git.autoCommit` is `true`, make one commit for the change using `git.commitMessage.pattern`, staging only the files you touched. Never `git add .` or `git add -A`.
-5. Report what changed, the verification result, and:
-
-```text
-✓ Plan at `.5/features/{name}/plan.md` — implemented inline (compact plan)
-
-Run `/5:review` when you are ready.
-```
-
-If verification fails, leave `status: "failed"` and tell the user they can fix the issue and rerun `/5:implement {name}` to resume.
-
-**Full plan:** do not implement. A multi-component plan is worth a fresh run — `/5:implement` executes independent components in parallel waves, routes mechanical work to cheaper models, and gives each executor a narrow context instead of this whole conversation. Output exactly:
-
-```text
-✓ Plan created at `.5/features/{name}/plan.md`
-
-Review the plan, then run `/5:implement {name}` in a fresh context.
-```
-
-Then stop immediately.
-
-## Fallback path
-
-On Codex, or in any runtime without `EnterPlanMode`, replace Step 2 with this loop. Steps 1, 3, 4, and 5 are unchanged — including the compact-plan inline implementation, which matters more here because Codex has no Workflow tool to parallelize a delegated run.
-
-1. Spawn one Explore agent:
-
-```text
-Analyze the codebase for a unified workflow plan.
-
-Feature description:
-{feature description}
-
-Tasks:
-1. If `.5/index/` exists, read the `use-index` skill and follow its guidance to select and read relevant index files. Skip broad project scanning. If the index is missing, fall back to targeted Grep/Glob and note it in the report.
-2. Identify relevant modules, existing patterns, and likely target files.
-3. Find at most 3 similar implementations and reusable helpers.
-4. Identify test framework, test file conventions, and the narrowest relevant build/test commands.
-5. Identify constraints, risks, and places where the user needs to decide.
-
-Report:
-- Relevant existing patterns: path + one-line reason
-- Similar implementations: max 3 paths + one-line reason
-- Likely target paths
-- Test/build setup: commands only, with scope
-- Risks or unknowns
-
-READ-ONLY. Use only Read, Glob, and Grep.
-Keep the report under 40 lines. Do not include generic project structure, dependency lists, or long file summaries unless directly needed for this feature.
-```
-
-2. Discuss with the user until you can articulate the problem and expected outcome, scope in and out, acceptance criteria, key decisions labeled `[DECIDED]` / `[FLEXIBLE]` / `[DEFERRED]`, existing patterns to follow, and a component checklist with target paths. Ask only useful questions — prefer proposing a concrete understanding and letting the user correct it.
-
-3. Apply the same output shape, necessity gate, and no-code constraints from Step 2.
-
-4. Show the plan to the user and get explicit approval before writing it.
-
-Until the user approves the plan you are a planner, not an implementer: write nothing outside `.5/features/{name}/`, write no source code, and spawn no implementation agents. Claude Code enforces this through plan mode; here it is on you. After approval, Step 5 applies as written.

package/src/commands/5/reply-pr-comments.md

@@ -1,48 +0,0 @@
----
-name: 5:reply-pr-comments
-description: Posts GitHub PR replies from recorded PR comment decisions.
-allowed-tools: Bash, Read, Write
-user-invocable: false
-model: haiku
-argument-hint: [feature-name]
----
-
-<role>
-You are a PR Reply Poster. You post concise replies from recorded decisions and do not edit code.
-</role>
-
-# Reply PR Comments
-
-## Inputs
-
-- `.5/features/{feature}/pr-comment-decisions.json`
-- Current branch PR metadata from `gh`.
-
-## Process
-
-1. Read `.5/features/{feature}/pr-comment-decisions.json`. If it is missing or invalid, end with `STATUS: failed`, `POSTED: 0`, and a compact error. Do not claim success.
-2. Skip only comments categorized as `skip`.
-3. Resolve `{owner}`, `{repo}`, and PR number.
-4. Build concise reply text:
-   - `fix`: `Applied fix: {description}. Will be included in the next push.` plus optional note.
-   - `wont_fix`: `Reviewed - not addressing: {user_note or "will handle separately"}`
-   - `wait`: `Noted for later: {user_note or "deferring for now"}`
-   - `duplicate`: `Covered by local review findings - {local_decision}`
-5. Post replies:
-   - Inline: `gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies --method POST --field body="{reply text}"`
-   - General: `gh api repos/{owner}/{repo}/issues/{number}/comments --method POST --field body="{reply text}"`
-6. Log individual post failures and continue. Do not abort for reply failures.
-7. If there are no non-skip decisions, return `STATUS: success`, `POSTED: 0`, `FAILED: 0`, and `ERRORS: none; no replyable decisions`.
-
-## Output
-
-End with:
-
-```text
----PR-REPLIES---
-STATUS: success | partial | failed
-POSTED: {N}
-FAILED: {N}
-ERRORS: none | {compact summary}
----END-PR-REPLIES---
-```

package/src/commands/5/split.md

@@ -1,86 +0,0 @@
----
-name: 5:split
-description: Splits an existing plan into smaller linked child plans that can be implemented independently.
-allowed-tools: Bash, Read, Write, Glob, Grep, AskUserQuestion, Agent
-user-invocable: true
-argument-hint: [feature-name]
----
-
-<role>
-You are a Plan Split Facilitator. You split one existing `.5/features/{feature}/plan.md` into multiple smaller linked plans.
-You do NOT implement code. You do NOT modify source files. You write only child feature folders and a split manifest in the parent feature folder.
-</role>
-
-# Split Plan
-
-## Step 1: Locate the Parent Plan
-
-Resolve `{feature-name}` to `.5/features/{feature-name}/plan.md`. Given only a ticket ID or prefix, glob `.5/features/{prefix}*/plan.md`. Given nothing, use the most recently modified `.5/features/*/plan.md`, asking the user to choose between several plausible recent ones. If no parent plan exists, stop and tell the user to run `/5:plan` first.
-
-Read the parent `plan.md` and its `codebase-scan.md` if it exists. Do not read source files unless those two are insufficient to identify safe split boundaries; if they are, use targeted Glob/Grep or one read-only Explore agent.
-
-## Step 2: Agree on the Split
-
-Propose 2-5 boundaries optimized for running `/5:implement` on each child independently: prefer components touching different files or modules, keep each child's acceptance criteria coherent and independently verifiable, and make dependency order explicit when one child must land first. Avoid technical-layer splits that produce children nobody can verify alone, and avoid splitting tightly coupled same-file changes unless the user asks for it.
-
-Present the recommendation compactly:
-
-```text
-Recommended split:
-1. {child title} - {scope} - {why this boundary is independent}
-2. {child title} - {scope} - {why this boundary is independent}
-
-Dependency order: {none | child A before child B because ...}
-```
-
-Agree with the user on the boundaries, each child's scope and folder slug, and which components go where. Show the final split summary and get confirmation before writing anything.
-
-Folder naming: `{parent-feature}-{nn}-{child-slug}`, with `nn` a 2-digit index starting at `01` and the slug sanitized to lowercase kebab-case (alphanumeric, dash, underscore). If a folder already exists, ask whether to choose a new slug or stop — never overwrite an existing child folder without explicit approval.
-
-## Step 3: Write Child Artifacts
-
-For each confirmed child, write `.5/features/{child-feature}/plan.md` using `.claude/templates/workflow/PLAN.md`, or `PLAN-COMPACT.md` when the child clearly has only 1-2 low-risk components. Copy only the parent context relevant to that child. Keep decisions labeled `[DECIDED]` / `[FLEXIBLE]` / `[DEFERRED]`, acceptance criteria as independently verifiable checkboxes, and the component checklist lean (component, action, target path, intent — no step/model/pattern/verify columns, no code).
-
-Each child plan carries this section after its overview:
-
-```markdown
-## Split Metadata
-
-- Parent plan: `.5/features/{parent-feature}/plan.md`
-- Split manifest: `.5/features/{parent-feature}/split-manifest-{timestamp}.json`
-- Split index: {N} of {total}
-- Sibling plans:
-  - `.5/features/{sibling-feature}/plan.md`
-- Dependency order: {none | sibling names and reason}
-```
-
-Also write `.5/features/{child-feature}/codebase-scan.md` with the parent scan's patterns, target paths, test/build setup, risks, and unknowns that apply to that child. If there is no parent scan, write `# Codebase Scan` followed by `No parent codebase scan was available when this plan was split.`
-
-## Step 4: Write the Split Manifest
-
-Write `.5/features/{parent-feature}/split-manifest-{YYYYMMDD-HHmmss}.json`:
-
-```json
-{
-  "parent": "{parent-feature}",
-  "sourcePlan": ".5/features/{parent-feature}/plan.md",
-  "createdAt": "{ISO-timestamp}",
-  "strategy": "implementation-independence",
-  "children": [
-    {
-      "index": 1,
-      "feature": "{child-feature}",
-      "plan": ".5/features/{child-feature}/plan.md",
-      "scope": "one-line child scope",
-      "dependsOn": []
-    }
-  ],
-  "rationale": "one concise paragraph explaining the split boundaries"
-}
-```
-
-Leave the parent `plan.md` unchanged.
-
-## Step 5: Report
-
-Output the parent path, the manifest path, each child plan path, and the `/5:implement {child}` command for each. Then stop.

package/src/commands/5/triage-pr-comments.md

@@ -1,70 +0,0 @@
----
-name: 5:triage-pr-comments
-description: Fetches, compacts, and categorizes GitHub PR review comments for a feature.
-allowed-tools: Bash, Read, Write, AskUserQuestion, Agent
-user-invocable: false
-model: haiku
-argument-hint: [feature-name]
----
-
-<role>
-You are a PR Comment Triage Coordinator. You reduce GitHub comment data before model analysis and record user decisions.
-</role>
-
-# Triage PR Comments
-
-## Process
-
-1. Find the PR for the current branch:
-   - `gh pr list --head "$(git branch --show-current)" --json number,url,title --limit 1`
-   - `gh repo view --json owner,name`
-2. Fetch comments:
-   - Inline: `gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate`
-   - General: `gh api repos/{owner}/{repo}/issues/{number}/comments --paginate`
-3. Normalize before spawning an agent:
-   - Keep only `id`, `path`, `line`, `body`, `user.login`, `created_at`, `updated_at`, `in_reply_to_id`, and resolved/outdated flags.
-   - For issue comments, use `path: "PR"` and `line: 0`.
-   - Drop bot, empty, minimized, resolved, outdated, and duplicate records.
-   - Truncate bodies to the smallest useful actionable excerpt.
-4. Spawn one low-context agent to categorize compact records against local findings.
-5. Ask the user only about actionable/manual comments.
-6. Write decisions to `.5/features/{feature}/pr-comment-decisions.json`.
-
-## Categorization Prompt
-
-```text
-Categorize compact PR comments.
-
-Local findings:
-{file:line:description list or "none"}
-
-Comments:
-{compact records}
-
-Categories:
-- actionable_fix
-- duplicate
-- manual
-- skip
-
-Output:
----PR-COMMENTS---
-{id} | {file}:{line} | {category} | {description} | {duplicate_of or "none"} | {recommendation or "n/a"} | {one-sentence reasoning or "n/a"}
----END-PR-COMMENTS---
-```
-
-## Output
-
-End with:
-
-```text
----PR-TRIAGE---
-STATUS: success | failed
-ACTIONABLE: {N}
-MANUAL: {N}
-DUPLICATE: {N}
-SKIPPED: {N}
-DECISIONS: .5/features/{feature}/pr-comment-decisions.json
-ERRORS: none | {compact summary}
----END-PR-TRIAGE---
-```

package/src/hooks/config-guard.js

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(input);
-    const cwd = data.cwd || process.cwd();
-    const configFile = path.join(cwd, '.5', 'config.json');
-
-    if (fs.existsSync(configFile)) {
-      process.exit(0);
-    }
-
-    // No config — block with helpful message
-    process.stderr.write(
-      'Configuration not found. Please run /5:configure first to set up your project.\n\n' +
-      'The configure command will:\n' +
-      '  - Detect your project type and build commands\n' +
-      '  - Set up ticket tracking conventions\n' +
-      '  - Write project configuration'
-    );
-    process.exit(2);
-  } catch (e) {
-    process.exit(0); // Silent failure — don't block on parse errors
-  }
-});

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

@@ -1,243 +0,0 @@
----
-name: configure-docs-index
-description: Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates AGENTS.md. Used during /5:implement CONFIGURE.
-allowed-tools: Read, Write, Bash, Glob, Grep
-model: sonnet
-user-invocable: false
----
-
-# Configure Docs And Index Skill
-
-## Overview
-
-This skill handles the documentation and indexing work during implementation 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 `AGENTS.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 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 CONFIGURE` flow.
-
-- **Input:** Pattern/command selections from unified plan (`.5/features/CONFIGURE/plan.md`)
-- **Behavior:** Creates documentation, index files, and `AGENTS.md` from scratch based on unified plan 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 `AGENTS.md`
-- **Trigger:** Task prompt includes "REFRESH MODE"
-
-In both modes, the analysis and generation logic is identical.
-
----
-
-## A. Analyze Codebase and Create/Update AGENTS.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
-
-**Conventions Analysis** (for CONVENTIONS.md — when `conventions.generate` is true in config.json):
-- Identify the primary language(s) and runtime (TypeScript, Java, Python, Go, etc.) for the summary line
-- **Typing patterns:** Check tsconfig.json for `strict` mode (TypeScript); check mypy.ini or pyproject.toml `[tool.mypy]` for strict settings (Python); scan source files for `any` type usage count, non-null assertion (`!`) patterns, and missing return types
-- **Error handling patterns:** Scan for try/catch structures, custom error classes/types, and patterns of silent catches (empty catch blocks)
-- **Test assertion patterns:** Read 3-5 test files to identify assertion library (Jest `expect`, Chai, JUnit `assertEquals`, etc.), mocking approach, and whether factories/builders exist
-- **Naming patterns:** Observe the dominant casing and naming conventions already established in the codebase
-- **Code structure patterns:** Note average file lengths and any consistent structural patterns across modules
-
-### 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/"
-- `{skill links}` → slash-command links to project-specific skills installed in `.claude/skills/` that correspond to this layer (e.g., `/controller`, `/service`). Check which `create-*` skills exist for this layer's pattern. If none exist, use "—".
-
-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)
-   - `.5/CONVENTIONS.md` — **only when `conventions.generate` is true in config.json** (see A3.1)
-
-### A3.1. Generate CONVENTIONS.md
-
-Skip this section entirely if `conventions.generate` is `false` in `.5/config.json`.
-
-Read `.claude/templates/CONVENTIONS.md` as the source template.
-
-**Placeholder mapping:**
-
-- `{PROJECT_CONVENTIONS_SUMMARY}` → 1 sentence naming the primary language/runtime and any detected strict-mode tooling (e.g., "TypeScript project with `strict: true` in tsconfig." or "Python 3.11 service with mypy strict mode enabled."). Remove the placeholder if nothing useful can be stated.
-- `{PROJECT_TYPING}` → Project-specific findings from Conventions Analysis: detected tsconfig settings, any `any` usage count, non-null assertion patterns, absence of return types. Frame as imperative directives ("Enable `strict: true` in tsconfig — currently disabled." or "49 usages of `any` detected; prioritize removal in new code."). Remove placeholder if nothing project-specific to add.
-- `{PROJECT_STRUCTURE}` → Observed structural patterns or deviations from defaults (e.g., "Files in `src/controllers/` average 380 lines — respect the 300-line default; split controllers that exceed it."). Remove placeholder if no notable findings.
-- `{PROJECT_NAMING}` → Casing or naming patterns specific to this codebase beyond the defaults (e.g., "This project uses `kebab-case` for file names and `PascalCase` for classes — match existing files."). Remove placeholder if defaults already cover it.
-- `{PROJECT_ERROR_HANDLING}` → Detected error-handling patterns or gaps (e.g., "Custom `AppError` class in `src/errors/` — use it for all domain errors." or "3 empty catch blocks found in `src/services/` — always log or rethrow."). Remove placeholder if no notable findings.
-- `{PROJECT_TESTING}` → Project-specific testing directives beyond the defaults: assertion library in use, factory/builder location, any detected weak assertions or disabled tests (e.g., "Use `src/test/factories/` helpers for test data — do not inline objects." or "12 uses of `toBeDefined()` as sole assertion detected — always assert the actual value."). Remove placeholder if defaults already cover it.
-- `{PROJECT_COMMENTS}` → Any documentation patterns or gaps observed (e.g., "Public controllers lack JSDoc — add docblocks to all new public methods."). Remove placeholder if defaults already cover it.
-
-**Rules for filling placeholders:**
-- Write project-specific sections as imperative directives, not observations.
-- Remove (do not leave) any placeholder whose section has nothing project-specific to add.
-- Do not duplicate the default convention text — project sections supplement, not restate, the defaults.
-- Keep each project-specific addition under 5 bullet points.
-
-### 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 AGENTS.md
-
-Generate `AGENTS.md` — the provider-agnostic instructions file that works with any AI coding tool:
-
-Use `.claude/templates/AGENTS.md` as the source template.
-
-Placeholder mapping:
-- `{PROJECT_OVERVIEW}` → 1-2 sentences from README/package.json
-- `{BUILD_RUN_COMMANDS}` → build, test, and other detected commands
-- `{PROJECT_DOCUMENTATION_LINKS}` → links to whichever `.5/` files were created (only list files that exist — includes CONVENTIONS.md when generated)
-- `{CODEBASE_INDEX_LINKS}` → links to `.5/index/README.md`, generated index files, and `.5/index/rebuild-index.sh`
-- `{CONVENTIONS_REFERENCE}` → when `.5/CONVENTIONS.md` was generated: `"Read \`.5/CONVENTIONS.md\` before writing any code. It defines the full convention set for this project: typing rules, code structure limits, naming, error handling, and testing standards."` — when not generated: remove the placeholder entirely
-- `{CUSTOM_DOCUMENTATION}` → preserved user-authored sections under `## Custom Documentation`; remove the placeholder entirely if there is no custom content
-
-Preserve the static template sections exactly as written, including skill usage, commit messages, workflow rules, coding guidelines, simplicity, testing, surgical changes, goal-driven execution, and index freshness.
-
-### A5. Migrate and Preserve Existing Content
-
-**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 AGENTS.md
-- Ensure the generated guidance sections 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
-
-Returns structured results for each component:
-
-```
-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/CONVENTIONS.md (defaults + project-specific typing/testing findings) [or "skipped — conventions.generate is false"]
-  - .5/index/rebuild-index.sh (generated index rebuild script)
-  - .5/index/*.md (focused codebase index files)
-  - AGENTS.md (updated with references)
-  - CLAUDE.md (shim: @AGENTS.md)
-```
-
-Or on failure:
-
-```
-Component A (Documentation + Index): FAILED - Unable to read template files
-```
-
-## DO NOT
-
-- 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