5-phase-workflow 1.9.0 → 1.9.2

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

@@ -0,0 +1,159 @@
+---
+name: 5:analyze-feature
+description: Analyze any feature, dataflow, or domain concept in the codebase and generate comprehensive documentation with mermaid diagrams. Use when you need to understand how a feature works end-to-end, trace a dataflow, or document a domain area.
+allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
+user-invocable: true
+---
+
+<role>
+You are a Codebase Analyst. Your job is to analyze features, dataflows, and domain concepts in this codebase and produce comprehensive documentation with mermaid diagrams.
+You do NOT write code. You do NOT refactor. You only read, analyze, and document.
+</role>
+
+# Analyze Feature
+
+Generate comprehensive documentation for any feature, dataflow, or domain concept by analyzing the codebase.
+
+## Arguments
+
+- `$ARGUMENTS`: Description of what to analyze (e.g., "user authentication flow", "how orders get processed", "payment integration")
+
+## Step 0: Validate Input
+
+If `$ARGUMENTS` is empty, vague, or ambiguous (e.g., "analyze this", "the thing", or a single word without clear context), use AskUserQuestion to clarify:
+- What specific feature, dataflow, or domain concept should be analyzed?
+- Optionally: which modules or layers are most relevant?
+
+Do NOT proceed until you have a clear understanding of what to analyze.
+
+## Step 1: Determine Scope and Output Name
+
+1. Derive a short kebab-case name from the analysis subject (e.g., `user-auth`, `order-processing`, `payment-integration`). This becomes the filename: `{name}-analysis.md`.
+
+2. Identify the relevant modules and layers to analyze. If `.5/index/` exists, read the index files for a quick structural overview. Otherwise, use Glob to understand the project layout.
+
+3. Use Glob and Grep to locate the relevant source files. Search for key classes, interfaces, functions, and types related to the analysis subject.
+
+## Step 2: Analyze the Codebase
+
+Spawn Explore agents (one or more in parallel depending on scope) to thoroughly read all relevant files. Tailor the agents to the analysis subject:
+
+### For Domain/Feature Analysis
+
+Read across the relevant layers following the project's dependency flow (e.g., models -> services -> controllers -> routes, or entities -> repositories -> handlers -> endpoints). Identify the layer structure from the codebase scan.
+
+### For Dataflow Analysis
+
+Trace the data path through all involved components. Follow inputs from entry points (API endpoints, event handlers, CLI commands) through processing layers to outputs (database writes, API responses, events published).
+
+### For Cross-Cutting Analysis
+
+Examine shared concerns as relevant: validation, authentication, error handling, logging, caching, event publishing.
+
+Request structured output from each agent covering the entities, flows, relationships, and patterns found.
+
+## Step 3: Generate Documentation
+
+Using the analysis results, create a comprehensive markdown document.
+
+**The document MUST follow this structure** (omit sections that don't apply to the analysis subject):
+
+```markdown
+# {Analysis Title}
+
+{1-3 sentence summary of what this feature/dataflow does and why it exists}
+
+---
+
+## Table of Contents
+{auto-generated links to sections below}
+
+---
+
+## Overview
+{High-level description of the feature/concept, its purpose, and where it fits in the system}
+{Mention the involved modules and their roles}
+
+---
+
+## Data Flow
+{For each major operation, create a mermaid sequence diagram}
+{Show the path from entry point through processing layers to output}
+{Include relevant function/method names and payload types}
+
+---
+
+## Domain Model
+{mermaid classDiagram or erDiagram showing entities and their relationships}
+{Include: key fields, types, relationships with cardinality}
+{Show: value objects, enums, and aggregate boundaries where relevant}
+
+---
+
+## Operations
+
+### Writes (Commands/Mutations)
+{Table: Operation | Handler/Service | Description | Key Validation}
+
+### Reads (Queries)
+{Table: Query | Handler/Service | Description | Return Type}
+
+---
+
+## API / Entry Points
+{Table: Method | Path/Topic/Command | Handler | Description}
+
+---
+
+## Event Flow
+{If async events are involved (Kafka, RabbitMQ, webhooks, etc.)}
+{mermaid sequence diagram showing event production/consumption}
+{Include: event names, topics, consumer handlers}
+
+---
+
+## Module Dependencies
+{mermaid graph showing which modules depend on which}
+{Use subgraphs to group by domain or layer}
+
+---
+
+## Key Implementation Details
+{Notable patterns, edge cases, business rules worth highlighting}
+{Reference specific classes/functions and file paths}
+```
+
+### Mermaid Diagram Guidelines
+
+- **Sequence diagrams** (`sequenceDiagram`): For request/response flows across layers
+- **Class diagrams** (`classDiagram`): For domain model relationships and aggregate structure
+- **ER diagrams** (`erDiagram`): For persistence model relationships
+- **Flowcharts** (`flowchart TD`): For decision trees, validation flows, state machines
+- **Graph diagrams** (`graph LR` or `graph TD`): For module dependencies, component trees
+- Keep node labels short but descriptive
+- Use subgraphs to group related nodes by module or layer
+- Use dotted lines (`-.->`) for optional/indirect relationships
+
+## Step 4: Write File
+
+1. Write the documentation using the Write tool to `.5/analysis/{name}-analysis.md`.
+
+2. Report to the user:
+   ```
+   Analysis saved to .5/analysis/{name}-analysis.md
+
+   Sections included:
+   - {list of sections that were generated}
+   - {N} mermaid diagrams
+
+   Modules analyzed: {list of modules examined}
+   ```
+
+## Important Notes
+
+- Read ALL relevant files thoroughly before writing -- do not guess or assume
+- Every mermaid diagram must be syntactically valid
+- Reference specific class/function names and file paths so the reader can navigate to the source
+- Focus on the specific feature/dataflow requested, not the entire codebase
+- Follow the data through all layers from entry point to output
+- Document both the happy path and notable error/validation paths

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

@@ -117,6 +117,8 @@ Use `multiSelect: false` to get single focus area initially.
 
 Based on the user's focus area, explore the codebase if needed:
 
+**Index shortcut:** Before spawning Explore agents or running Glob/Grep, check if `.5/index/` exists. If it does, read `.5/index/README.md` first for the generation timestamp — if fresh (under 1 day old), read the relevant index files (e.g., modules.md for scope changes, routes.md for API discussions, models.md for data model questions) to quickly gather context and skip broad scanning. If outdated, inform the user they can run `.5/index/rebuild-index.sh` to refresh it. If `.5/index/` does not exist, inform the user they can run `/5:reconfigure` to generate it. In both missing/outdated cases, fall back to Glob/Grep or Explore agents for exploration.
+
 **For technical constraint discussions:**
 - Search for similar implementations
 - Check existing patterns

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

@@ -207,6 +207,9 @@ Task tool call:
     {If Depends On is not "—": "This component depends on {dep-name} ({dep-file}). Read that file first to understand the exports/types you need to use."}
     {If Depends On is "—": omit this section entirely}
 
+    ## Codebase Context (optional)
+    If you need to understand how this component relates to other modules (imports, service boundaries, data flow), check `.5/index/` for quick reference — especially modules.md and libraries.md. Only if these files exist.
+
     ## Verify
     {Verify command(s) from plan table — executor runs these after implementation}
 

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

@@ -14,20 +14,22 @@ After creating the spec, you are FINISHED. You do not continue. You do not offer
 </role>
 
 <constraints>
-HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
-- NEVER write code, pseudo-code, or implementation snippets in any output
-- NEVER describe HOW something will be implemented (file contents, signatures, class structures)
-- NEVER create an implementation plan, file list, component breakdown, or step-by-step build guide — that is Phase 2's job
-- NEVER suggest "shall I continue with implementation planning?" or "let me create the plan" — you are DONE after feature.md
-- NEVER offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
-- NEVER spawn Task agents with subagent_type other than Explore
-- NEVER write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
-- NEVER call EnterPlanMode — the workflow has its own planning process
-- 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 "Feature spec created at...", you are FINISHED
-- The feature spec describes WHAT and WHY, never HOW
-- If you feel the urge to plan implementation or write code, STOP — ask a clarifying question instead
-- Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes. No implementation plans.
+HARD CONSTRAINTS:
+- Do NOT write code or pseudo-code — describe behavior and data shapes in natural language or tables
+- Do NOT create implementation plans, file lists, or step-by-step build guides — that is Phase 2's job
+- Do NOT offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
+- Do NOT spawn Task agents with subagent_type other than Explore
+- Do NOT write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
+- Do NOT call EnterPlanMode — the workflow has its own planning process
+- Do NOT use Bash to create, write, or modify files — this bypasses the plan-guard
+- Do NOT continue past the completion message — when you output "Feature spec created at...", you are FINISHED
+
+WHAT IS ALLOWED:
+- Name existing classes, modules, services, and patterns
+- Describe entity fields with domain types
+- Reference existing patterns as models
+- Mention affected methods or APIs by name
+- Include data shape tables with field names and types — these are part of the requirement
 </constraints>
 
 <write-rules>
@@ -42,11 +44,10 @@ Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it
 Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 
 **Content rules for feature.md:**
-- Requirements use natural language ("The system shall..."), NOT code
-- Affected Components lists module/domain names, NOT file paths
-- NO code snippets, NO pseudo-code, NO type definitions
-- Entity definitions describe data CONCEPTS, not DB schemas or TypeScript interfaces
-- Acceptance criteria describe observable behavior, NOT test code
+- Write naturally — reference existing classes, modules, and patterns by name for precision
+- Entity definitions include field names and domain types — these define the requirement
+- Acceptance criteria describe observable behavior
+- No code blocks, no pseudo-code, no class hierarchy designs
 </output-format>
 
 <collaboration-strategy>
@@ -129,12 +130,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
@@ -192,7 +194,7 @@ Targeted exploration for feature planning.
 
 ### 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.
+> **ROLE CHECK:** You are writing a FEATURE SPECIFICATION. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
 
 **Extract ticket ID from git branch:**
 - The Explore agent from Step 2 already ran `git branch --show-current` — find the branch name in its results
@@ -208,25 +210,14 @@ Write to `.5/features/{name}/feature.md` using Write tool, where `{name}` is eit
 
 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 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.
+Populate the sections from the template. Key guidance:
+- **Overview**: Write a short narrative (3-5 sentences) merging the problem and the solution
+- **What Changes**: Group by logical concern, not by module layer. Name existing classes and patterns. Use entity tables where new data models are introduced
+- **Existing Patterns to Follow**: Be specific — these are the highest-value pointers for Phase 2
+- **Scope**: Be explicit about what's in and what's out
+- **Decisions**: Label each from the conversation
+- **Diagrams**: Include only when they add clarity. Simple features don't need them
+- **Alternatives**: Only include if genuinely discussed and the reasoning matters. Delete if empty
 
 **Decision labeling rules:**
 - **[DECIDED]**: The user gave a clear, specific answer → Phase 2 planner and Phase 3 agents MUST honor exactly

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

@@ -110,11 +110,11 @@ This activates (or refreshes) the plan-guard hook which prevents accidental sour
 
 ### 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.
+**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, what changes (by logical concern), acceptance criteria, existing patterns to follow, scope, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
 
 **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**.
+Extract: Ticket ID, overview, what changes (each logical concern), existing patterns to follow, constraints, scope, acceptance criteria, and **decisions**.
 
 **Decision labels from feature spec:**
 - **[DECIDED]** items are locked — your plan MUST honor them exactly. Do not override or reinterpret.
@@ -160,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)

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/synchronize-agents.md

@@ -0,0 +1,60 @@
+---
+name: 5:synchronize-agents
+description: Synchronize user-generated skills, rules, and custom content between Claude Code and Codex runtimes
+allowed-tools: Bash, Read, AskUserQuestion
+user-invocable: true
+model: haiku
+context: fork
+---
+
+<role>
+You are a Runtime Synchronizer. You run the sync script and report results.
+You do NOT modify files manually. After reporting, you are DONE.
+</role>
+
+# Synchronize Agent Runtimes
+
+Synchronizes user-generated content (skills, commands, agents, rules) between the Claude Code (`.claude/`) and Codex (`.codex/`) runtimes.
+
+## Step 1: Locate the Sync Script
+
+The script is `bin/sync-agents.js` in the workflow package. Find it by checking these paths in order:
+
+1. `./bin/sync-agents.js` (development checkout / project root)
+2. `./node_modules/5-phase-workflow/bin/sync-agents.js` (local npm install)
+
+Read `.5/version.json` if available — its location confirms the project root.
+
+Store the resolved path for the following steps.
+
+If the script cannot be found, tell the user: "Sync script not found. Update the workflow first: `npx 5-phase-workflow --upgrade`" and **stop**.
+
+## Step 2: Dry Run
+
+Run the script in dry-run mode to preview what will be synced:
+
+```bash
+node {script-path} --dry-run
+```
+
+If the script exits with a non-zero code (missing runtime, no content), show the output and **stop**.
+
+If there are no actionable changes (everything in sync), report that and **stop**.
+
+## Step 3: Confirm with User
+
+Show the dry-run output. Ask: "Proceed with synchronization?"
+
+If the user declines, stop.
+
+## Step 4: Execute Sync
+
+```bash
+node {script-path}
+```
+
+## Step 5: Report
+
+Show the script output. Summarize what was synced.
+
+Note: This command works identically from both Claude Code (`/5:synchronize-agents`) and Codex (`$5-synchronize-agents`). The script auto-detects the project root.

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

@@ -1,135 +1,100 @@
 <!-- TEMPLATE RULES:
-- Requirements use natural language, not code
-- Affected Components lists module/domain names, not file paths
-- Entity definitions describe data concepts, not schemas or interfaces
-- Acceptance criteria describe observable behavior, not test assertions
-- NO code, pseudo-code, or implementation details anywhere in this document
-- Visual Overview section is OPTIONAL — delete it if the feature doesn't benefit from diagrams
-- Mermaid diagrams describe WHAT happens, not HOW it is implemented
+- Write naturally
+- Reference existing classes, modules, and patterns by name for precision
+- Entity definitions include field names and domain types
+- Acceptance criteria describe observable behavior
+- No code blocks, no pseudo-code, no class hierarchy designs
+- Delete any OPTIONAL section that doesn't add value for this feature
 -->
 
 # Feature: {TICKET-ID} - {Title}
 
-## Ticket ID
-{TICKET-ID}
+**Ticket:** {TICKET-ID}
 
-## Summary
-{1-2 sentence overview: what capability is being added and who benefits}
+## Overview
 
-## Problem Statement
-{Describe the current pain point or gap. Who experiences it and what is the impact?}
+{What is the problem or gap, and what capability is being added? Write this as a short narrative
+that covers who is affected, why the change matters, and what the end result looks like.}
 
-## Visual Overview
-<!-- OPTIONAL: Include mermaid diagrams only when they add clarity to the feature.
-     Delete this entire section if the feature is simple enough to understand without diagrams.
-     Use whichever diagram types are relevant — you don't need all of them. -->
+<!-- OPTIONAL: Include mermaid diagrams only when they add clarity.
+     Delete this section for simple features. Use whichever diagram type fits. -->
 
-<!-- Process Flow — use when the feature involves a multi-step process or state transitions -->
 ```mermaid
 flowchart TD
-    A[Start state] --> B[Step 1]
-    B --> C{Decision point}
-    C -->|Yes| D[Outcome 1]
-    C -->|No| E[Outcome 2]
+    A[Current state] --> B[Change]
+    B --> C[New capability]
 ```
 
-<!-- Entity Relationships — use when new data concepts relate to existing ones -->
-```mermaid
-erDiagram
-    ENTITY-A ||--o{ ENTITY-B : "relationship"
-    ENTITY-B }|--|| ENTITY-C : "relationship"
-```
+## What Changes
 
-<!-- Component Interactions — use when multiple modules or services communicate -->
-```mermaid
-sequenceDiagram
-    actor User
-    participant ComponentA
-    participant ComponentB
-    User->>ComponentA: action
-    ComponentA->>ComponentB: interaction
-    ComponentB-->>User: result
-```
+{Describe what the feature does in natural, flowing prose. Name existing classes, modules, and patterns
+where relevant. Group by logical concern, not by module layer. Each subsection should tell the reader
+what happens and which parts of the codebase are involved.}
 
-## Requirements
+### {Logical concern 1, e.g., "New data model"}
 
-### Functional Requirements
-- {The system shall... [describe observable behavior]}
-- ...
+{Describe the change. Name affected modules and classes. If a new entity is introduced, describe its
+fields and types in a table:}
 
-### Non-Functional Requirements
-- {Performance, reliability, scalability, or compatibility expectations}
-- ...
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| ... | ... | ... | ... |
 
-## Constraints
-- {Business rules that limit the solution space}
-- {Technical boundaries from existing architecture}
-- {Timeline or resource limitations}
+### {Logical concern 2, e.g., "CRUD operations"}
 
-## Affected Components
-- **{component/module-1}** - {What changes here}
-- **{component/module-2}** - {What changes here}
-- **{component/module-3}** - {What changes here}
-- ...
+{Describe the behavior. Reference existing patterns to follow, e.g.,
+"Follow the same approach as the UserService update flow."}
 
-## Entity/Component Definitions
+### {Logical concern 3, e.g., "API exposure"}
 
-### {EntityName} (if applicable)
-<!-- Describe the data CONCEPT, not the implementation. No TypeScript, no SQL. -->
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | {Entity}Id | Yes | Unique identifier |
-| name | String | Yes | Entity name |
-| ... | ... | ... | ... |
+{Describe what gets exposed and how.}
 
 ### Business Rules
+
 - {Rule 1}
 - {Rule 2}
-- ...
 
-## Acceptance Criteria
-- [ ] {Observable behavior that proves this requirement is met}
-- [ ] {Observable behavior that proves this requirement is met}
-- [ ] {Observable behavior that proves this requirement is met}
+## Existing Patterns to Follow
+
+{List concrete patterns from the codebase that the implementation should mirror.
+These are high-value pointers for Phase 2 -- be specific.}
+
+- **{Pattern name}** -- {where it lives and what to reuse from it}
 - ...
 
-## Alternatives Considered
+## Constraints
+
+- {Business rules that limit the solution space}
+- {Technical boundaries from existing architecture}
+
+## Scope
+
+**In scope:**
+- {What is included}
 
-### Option 1: {Alternative approach}
-**Pros:** {Benefits}
-**Cons:** {Drawbacks}
-**Decision:** Rejected because {reason}
+**Out of scope:**
+- {What is explicitly excluded and why}
 
-### Option 2: {Another alternative}
-**Pros:** {Benefits}
-**Cons:** {Drawbacks}
-**Decision:** Rejected because {reason}
+## Acceptance Criteria
 
-### Chosen Approach: {Selected approach}
-**Rationale:** {Why this approach was chosen}
+- [ ] {Observable behavior that proves a requirement is met}
+- [ ] ...
 
 ## Decisions
 
-<!-- Record key decisions from the spec discussion.
-     Tag each with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
-     - [DECIDED]: Locked — Phase 2 planner and Phase 3 agents MUST honor exactly
-     - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
-     - [DEFERRED]: Out of scope — planner MUST NOT include in the plan
--->
+<!-- Tag each: [DECIDED] = locked, [FLEXIBLE] = planner chooses, [DEFERRED] = not in this iteration -->
 
-### {Topic: brief description of what was decided}
-**Context:** {Why this decision came up}
-**Decision:** {What was decided} **[DECIDED]**
+- **{Topic}:** {What was decided and why} **[DECIDED]**
+- **{Topic}:** {General direction, planner chooses specifics} **[FLEXIBLE]**
+- **{Topic}:** {Not addressing now -- reason} **[DEFERRED]**
 
-### {Topic: area left to implementer's discretion}
-**Context:** {What was discussed}
-**Decision:** {General direction, implementer chooses specifics} **[FLEXIBLE]**
+<!-- OPTIONAL: Only include if alternatives were genuinely discussed and the reasoning matters -->
+## Alternatives Considered
 
-### {Topic: explicitly deferred item}
-**Context:** {Why it was raised}
-**Decision:** {Not addressing now — reason} **[DEFERRED]**
+- **{Alternative}:** Rejected because {reason}
+- **{Chosen approach}:** Selected because {reason}
 
 ## Next Steps
-After approval:
-1. Run `/clear` to reset context
+
+1. Run `/clear` to reset context (optional)
 2. Run `/5:plan-implementation {TICKET-ID}-{description}`