specdacular 0.5.1 → 0.5.3

package/README.md

@@ -1,13 +1,48 @@
 # Specdacular
 
-**AI-optimized codebase documentation and feature planning for Claude.**
+**AI-optimized feature planning and codebase documentation for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).**
 
-A Claude Code extension that helps you understand codebases and plan features specific enough that an agent can implement without asking questions.
+Plan features specific enough that an agent can implement without asking questions.
 
 ```bash
 npx specdacular
 ```
 
+> [!CAUTION]
+> **Early Discovery Phase.** This project is actively evolving as we explore workflow patterns for AI-assisted feature planning. Commands, file formats, and conventions change frequently between versions. We aim to provide backwards-compatible migrations, but breaking changes may occur. Pin to a specific version if stability matters to you.
+
+> [!WARNING]
+> **Open Source Software.** This is maintained by a small team in their free time. It installs slash commands and workflow files into your `.claude/` directory. Always use version control. Review what gets installed. Back up your work. The software is provided "as is" without warranty of any kind. By using this tool, you accept full responsibility for any changes it makes to your project.
+
+---
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [Feature Commands](#feature-commands-feature)
+  - [Phase Commands](#phase-commands-phase)
+  - [Codebase Documentation](#codebase-documentation)
+  - [Utilities](#utilities)
+- [The Flow in Detail](#the-flow-in-detail)
+  - [Feature-Level Commands](#feature-level-commands)
+  - [Phase-Level Commands](#phase-level-commands)
+- [How It Works](#how-it-works)
+  - [Parallel Agents](#parallel-agents)
+  - [Feature Flow](#feature-flow)
+- [Project Structure](#project-structure)
+- [Philosophy](#philosophy)
+- [Migration Guides](#migration-guides)
+  - [From v0.5](#migrating-from-v05)
+  - [From v0.4](#migrating-from-v04)
+- [Updating](#updating)
+- [Uninstalling](#uninstalling)
+- [Contributing](#contributing)
+- [License](#license)
+
 ---
 
 ## What It Does
@@ -25,15 +60,23 @@ Spawns 4 parallel agents to analyze your codebase and generate AI-optimized docu
 
 ### 2. Plan Features
 
-A structured flow for planning features with enough detail for agent implementation:
+Two commands drive the entire feature lifecycle:
 
 ```
-feature:new -> feature:discuss -> feature:research -> feature:plan (roadmap) ->
-  [for each phase]
-    phase:prepare? -> phase:plan -> phase:execute
-  phase:insert? -> phase:renumber?   <- mid-flight adjustments
+/specd:feature:new my-feature     # Initialize + first discussion
+/specd:feature:next my-feature    # Everything else — discussion, research, planning, execution, review
 ```
 
+`feature:next` reads your feature's current state and offers the natural next step. You never need to remember which command comes next.
+
+---
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and working
+- Node.js >= 16.7.0
+- Git (recommended — Specdacular commits progress automatically)
+
 ---
 
 ## Installation
@@ -55,50 +98,6 @@ In Claude Code:
 
 ---
 
-## Commands
-
-Commands are organized into **feature** and **phase** namespaces.
-
-### Codebase Documentation
-
-| Command | Description |
-|---------|-------------|
-| `/specd:map-codebase` | Analyze codebase with parallel agents |
-
-### Feature Commands (`feature:`)
-
-Work with a feature as a whole — discuss, research, and create a roadmap.
-
-| Command | Description |
-|---------|-------------|
-| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
-| `/specd:feature:discuss [name]` | Continue/deepen discussion (call many times) |
-| `/specd:feature:research [name]` | Research implementation with parallel agents |
-| `/specd:feature:plan [name]` | Create roadmap with phase overview |
-
-### Phase Commands (`phase:`)
-
-Work with individual phases — prepare, plan, and execute one at a time.
-
-| Command | Description |
-|---------|-------------|
-| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
-| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
-| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
-| `/specd:phase:execute [feature]` | Execute plans with progress tracking |
-| `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
-| `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
-
-### Utilities
-
-| Command | Description |
-|---------|-------------|
-| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
-| `/specd:help` | Show available commands |
-| `/specd:update` | Update to latest version |
-
----
-
 ## Quick Start
 
 ### Map a Codebase
@@ -111,40 +110,39 @@ Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude cont
 
 ### Plan a Feature
 
-**Step 1: Initialize and discuss**
+**Step 1: Initialize**
 
 ```
 /specd:feature:new user-dashboard
 ```
 
-Creates `.specd/features/user-dashboard/` and starts the first discussion. Claude asks what you're building, follows the thread, and captures technical requirements.
+Creates `.specd/features/user-dashboard/` and starts the first discussion. Claude asks what you're building, follows the thread, and captures technical requirements. When done, offers to continue discussing or stop.
 
-**Step 2: Refine understanding**
+**Step 2: Drive the lifecycle**
 
 ```
-/specd:feature:discuss user-dashboard    # Clarify gray areas (call many times)
-/specd:feature:research user-dashboard   # Research implementation approaches
+/specd:feature:next user-dashboard
 ```
 
-Discussion and research are iterative — call them as many times as you need. Context accumulates across sessions.
-
-**Step 3: Create a roadmap**
+That's it. `feature:next` reads the current state and guides you through each stage:
 
-```
-/specd:feature:plan user-dashboard
-```
+1. **Discussion** — Probes gray areas until clear
+2. **Research** — Spawns parallel agents for patterns/pitfalls
+3. **Planning** — Creates roadmap with phases
+4. **Phase preparation** — Discusses phase-specific gray areas
+5. **Phase planning** — Creates detailed PLAN.md files
+6. **Phase execution** — Implements with progress tracking
+7. **Phase review** — Compares plans against actual code
 
-Creates `ROADMAP.md` with phases derived from dependency analysis (types -> API -> UI), plus empty phase directories. No detailed plans yet — those come next, per phase.
+After each step, you can continue or stop. Resume anytime with `/specd:feature:next`.
 
-**Step 4: Prepare, plan, and execute each phase**
+**No argument? It picks for you:**
 
 ```
-/specd:phase:prepare user-dashboard 1    # Discuss phase gray areas + optional research
-/specd:phase:plan user-dashboard 1       # Create detailed PLAN.md files
-/specd:phase:execute user-dashboard      # Execute with progress tracking
+/specd:feature:next
 ```
 
-Repeat for each phase. Plans are created just-in-time so they stay fresh.
+Scans for in-progress features and shows a picker.
 
 **Mid-flight adjustments:**
 
@@ -155,27 +153,66 @@ Repeat for each phase. Plans are created just-in-time so they stay fresh.
 
 ---
 
+## Commands
+
+Commands are organized into **feature** and **phase** namespaces.
+
+### Feature Commands (`feature:`)
+
+Work with a feature as a whole — discuss, research, and create a roadmap.
+
+| Command | Description |
+|---------|-------------|
+| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
+| `/specd:feature:next [name]` | **Drive the entire lifecycle** — picks up where you left off |
+
+### Phase Commands (`phase:`)
+
+Work with individual phases — prepare, plan, and execute one at a time.
+
+| Command | Description |
+|---------|-------------|
+| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
+| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
+| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
+| `/specd:phase:execute [feature]` | Execute plans with progress tracking |
+| `/specd:phase:review [feature] [phase]` | Review executed plans against actual code |
+| `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
+| `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
+
+### Codebase Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/specd:status [--all]` | Show feature status dashboard |
+| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
+| `/specd:help` | Show available commands |
+| `/specd:update` | Update to latest version |
+
+---
+
 ## The Flow in Detail
 
 ### Feature-Level Commands
 
-**`feature:new`** creates the feature folder and starts the first discussion. Output:
+**`feature:new`** creates the feature folder and starts the first discussion. After initialization, offers to continue discussing or come back later with `feature:next`. Output:
 - `FEATURE.md` — Technical requirements from the conversation
 - `CONTEXT.md` — Discussion context (accumulates over time)
 - `DECISIONS.md` — Decisions with dates, rationale, and implications
 - `STATE.md` — Progress tracking
 - `config.json` — Feature configuration
 
-**`feature:discuss`** continues the conversation. Can be called many times — each session adds to `CONTEXT.md` and `DECISIONS.md`. Claude identifies gray areas based on what's been discussed so far and probes until clear.
-
-**`feature:research`** spawns 3 parallel agents to investigate:
-1. **Codebase integration** — How does this fit with existing code?
-2. **External patterns** — What libraries/approaches are standard?
-3. **Pitfalls** — What commonly goes wrong?
-
-Output: `RESEARCH.md` with prescriptive guidance.
+**`feature:next`** is the smart state machine. It reads `config.json` and `STATE.md` to determine where the feature is, shows a status summary, and offers the natural next step. After each action it loops back — you keep going until you choose to stop. Under the hood it delegates to these stages:
 
-**`feature:plan`** creates a roadmap with phases. Each phase has a goal, deliverables, and dependencies. Creates `ROADMAP.md` and empty `plans/phase-{NN}/` directories. Does **not** create detailed PLAN.md files — that happens per-phase with `phase:plan`.
+- **Discussion** — Probes gray areas, records decisions. Context accumulates across sessions.
+- **Research** — Spawns 3 parallel agents: codebase integration, external patterns, and pitfalls. Output: `RESEARCH.md`.
+- **Planning** — Creates `ROADMAP.md` with phases derived from dependency analysis, plus empty `plans/phase-{NN}/` directories.
 
 ### Phase-Level Commands
 
@@ -187,8 +224,6 @@ Output: `RESEARCH.md` with prescriptive guidance.
 5. **Offers research** — "Would you like to research implementation patterns?"
 6. If yes, spawns 3 parallel research agents focused on the phase
 
-This replaces the old two-step of discuss-phase then research-phase.
-
 **`phase:research`** is the standalone research command. Use it when you want to research a phase without discussing first. Same research agents as `phase:prepare`, just without the discussion step.
 
 **`phase:plan`** creates detailed PLAN.md files for one phase. Each plan is a self-contained prompt for an implementing agent with:
@@ -206,6 +241,13 @@ Plans are created just-in-time — right before execution — so they incorporat
 - Commits after each task
 - Progress tracking in `STATE.md`
 
+**`phase:review`** reviews executed plans against actual code:
+- Claude inspects each plan's `creates`/`modifies` against actual files
+- Per-plan status table with pass/warn/fail/skip icons
+- User conversation captures additional issues
+- Generates corrective plans if needed (fed back into `phase:execute`)
+- Review cycle tracked in `STATE.md`
+
 **`phase:insert`** adds a new phase using decimal numbering (e.g., Phase 3.1 after Phase 3). The `(INSERTED)` marker in `ROADMAP.md` identifies mid-flight additions.
 
 **`phase:renumber`** cleans up decimal phases to sequential integers after insertions stabilize.
@@ -241,47 +283,46 @@ Specdacular spawns specialized agents that run simultaneously:
 
 ### Feature Flow
 
+**The simple way** — two commands:
+
 ```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│  feature:new │ ──▶ │   feature:   │ ◀─▶ │   feature:   │
-│              │     │   discuss    │     │   research   │
-└──────────────┘     └──────────────┘     └──────────────┘
-                            │
-                            ▼
-                     ┌──────────────┐
-                     │  feature:plan│ (creates roadmap)
-                     └──────────────┘
-                            │
-                            ▼
-              ┌─────────────────────────────┐
-              │     For each phase:         │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │ prepare  │               │
-              │  └──────────┘               │
-              │       │                     │
-              │       ▼                     │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │   plan   │               │
-              │  └──────────┘               │
-              │       │                     │
-              │       ▼                     │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │ execute  │               │
-              │  └──────────┘               │
-              │                             │
-              │  Mid-flight adjustments:    │
-              │  ┌──────────┐               │
-              │  │  phase:  │ ──┐           │
-              │  │  insert  │   │           │
-              │  └──────────┘   │           │
-              │          ┌──────▼────────┐  │
-              │          │    phase:     │  │
-              │          │   renumber   │  │
-              │          └──────────────┘  │
-              └─────────────────────────────┘
+/specd:feature:new          /specd:feature:next
+      │                           │
+      ▼                           ▼
+ Create feature          ┌─── Read state ◀──────────────┐
+ First discussion        │    Show status                │
+ Offer to continue       │    Offer next step            │
+      │                  │         │                     │
+      ▼                  │         ▼                     │
+ "Keep discussing?"      │   ┌──────────────┐           │
+  Yes → discuss loop     │   │  Execute the │           │
+  No  → feature:next     │   │  next action │           │
+                         │   └──────────────┘           │
+                         │         │                     │
+                         │    ┌────┴────┐                │
+                         │    │ Discuss │ Research       │
+                         │    │ Plan    │ Prepare phase  │
+                         │    │ Execute │ Review phase   │
+                         │    └────┬────┘                │
+                         │         │                     │
+                         │         ▼                     │
+                         │   "Continue or stop?"         │
+                         │    Continue ──────────────────┘
+                         │    Stop → clean exit
+                         │
+                         └─── No features? → feature:new
+```
+
+**Under the hood,** `feature:next` delegates to the same workflows as the individual commands:
+
+```
+discussion  → discuss-feature workflow
+research    → research-feature workflow (3 parallel agents)
+planning    → plan-feature workflow
+phase prep  → prepare-phase workflow
+phase plan  → plan-phase workflow
+execution   → execute-plan workflow
+review      → review-phase workflow
 ```
 
 ---
@@ -309,9 +350,9 @@ your-project/
 │           ├── ROADMAP.md     # Phase overview (from feature:plan)
 │           └── plans/
 │               ├── phase-01/
-│               │   ├── CONTEXT.md   # Phase discussion (from phase:prepare)
-│               │   ├── RESEARCH.md  # Phase research (from phase:prepare or phase:research)
-│               │   ├── 01-PLAN.md   # Detailed plans (from phase:plan)
+│               │   ├── CONTEXT.md   # Phase discussion
+│               │   ├── RESEARCH.md  # Phase research
+│               │   ├── 01-PLAN.md   # Detailed plans
 │               │   └── 02-PLAN.md
 │               └── phase-02/
 │                   ├── CONTEXT.md
@@ -348,11 +389,22 @@ Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, c
 
 ---
 
-## Migrating from v0.4
+## Migration Guides
+
+### Migrating from v0.5
+
+**New command: `/specd:feature:next`** — Drives the entire feature lifecycle from a single command. Reads current state and offers the next step automatically.
+
+| Before (v0.5) | After (v0.6) |
+|----------------|--------------|
+| Remember command sequence: `discuss` → `research` → `plan` → `phase:prepare` → `phase:plan` → `phase:execute` → `phase:review` | Just run `/specd:feature:next` — it figures out what's next |
+| `feature:new` ends with list of commands to try | `feature:new` offers to continue discussing or stop with `feature:next` |
 
-If you're upgrading from v0.4, here's what changed:
+**Existing `.specd/` data is fully compatible.** `feature:next` reads the same `config.json`, `STATE.md`, and other files.
 
-**Commands were renamed** into `feature:` and `phase:` namespaces:
+### Migrating from v0.4
+
+Commands were renamed into `feature:` and `phase:` namespaces:
 
 | v0.4 | v0.5 |
 |------|------|
@@ -366,14 +418,14 @@ If you're upgrading from v0.4, here's what changed:
 | `/specd:insert-phase` | `/specd:phase:insert` |
 | `/specd:renumber-phases` | `/specd:phase:renumber` |
 
-**New commands:**
+**New commands in v0.5:**
 - `/specd:phase:prepare` — Replaces `discuss-phase`, adds optional research at the end
 - `/specd:phase:plan` — Creates detailed plans for **one phase** (new command)
 
-**Behavior changes:**
+**Behavior changes in v0.5:**
 - `feature:plan` now creates only `ROADMAP.md` + empty phase directories. It no longer creates `PLAN.md` files for all phases upfront.
-- Detailed `PLAN.md` files are created per-phase with `phase:plan`, right before execution. This prevents plans from going stale.
-- `phase:prepare` combines the old discuss-phase + research-phase into a single command. Discussion always happens; research is offered as an optional step at the end.
+- Detailed `PLAN.md` files are created per-phase with `phase:plan`, right before execution.
+- `phase:prepare` combines the old discuss-phase + research-phase into a single command.
 
 **Existing `.specd/` data is fully compatible.** Your feature files, decisions, and roadmaps work with the new commands.
 
@@ -390,6 +442,8 @@ Or in Claude Code:
 /specd:update
 ```
 
+---
+
 ## Uninstalling
 
 ```bash
@@ -400,6 +454,12 @@ npx specdacular --local --uninstall
 
 ---
 
+## Contributing
+
+Issues and pull requests are welcome at [github.com/victorbalan/specdacular](https://github.com/victorbalan/specdacular).
+
+---
+
 ## License
 
 MIT

package/commands/specd/feature/discuss.md

@@ -12,6 +12,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including discussion.
+
 Continue or deepen understanding of a feature through targeted discussion. Can be called **many times** — context accumulates.
 
 **Updates:**

package/commands/specd/feature/new.md

@@ -12,7 +12,7 @@ allowed-tools:
 ---
 
 <objective>
-Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements.
+Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements. After initialization, offers to continue discussing or stop.
 
 **Creates:**
 - `.specd/features/{name}/FEATURE.md` — Technical requirements from discussion
@@ -21,7 +21,7 @@ Initialize a feature folder and start the first discussion. Creates structure, a
 - `.specd/features/{name}/STATE.md` — Progress tracking
 - `.specd/features/{name}/config.json` — Feature configuration
 
-**This is the entry point.** After this, user controls the loop with discuss/research/plan.
+**This is the entry point.** After this, continue with `/specd:feature:next` to drive the entire lifecycle.
 </objective>
 
 <execution_context>
@@ -63,5 +63,5 @@ Feature name: $ARGUMENTS
 - [ ] STATE.md tracks current position
 - [ ] config.json created
 - [ ] Committed to git
-- [ ] User knows next options: `/specd:feature:discuss`, `/specd:feature:research`, or continue talking
+- [ ] User offered to continue discussing or stop with `/specd:feature:next`
 </success_criteria>

package/commands/specd/feature/next.md

@@ -0,0 +1,84 @@
+---
+name: specd:feature:next
+description: Drive feature lifecycle — picks up where you left off and guides next steps
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Smart state machine that reads current feature state and drives the entire lifecycle. One command from discussion through phase execution.
+
+**How it works:**
+1. Select feature (from argument or picker)
+2. Read current state (STATE.md, config.json, CONTEXT.md, ROADMAP.md)
+3. Show status summary
+4. Offer the natural next step
+5. Execute it (delegating to existing workflows)
+6. Loop back — offer the next step or stop
+
+**Covers the full lifecycle:**
+- Discussion (gray areas, decisions)
+- Research (parallel agents for patterns/pitfalls)
+- Planning (roadmap with phases)
+- Phase preparation (phase-specific discussion + research)
+- Phase planning (detailed PLAN.md files)
+- Phase execution (with progress tracking)
+- Phase review (compare plans vs actual code)
+
+**No need to remember individual commands.** This one command figures out what's next.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/next-feature.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS
+
+**Scans for features:**
+@.specd/features/*/config.json
+
+**Loads feature context (once selected):**
+@.specd/features/{name}/config.json
+@.specd/features/{name}/STATE.md
+@.specd/features/{name}/CONTEXT.md
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/ROADMAP.md (if exists)
+@.specd/features/{name}/RESEARCH.md (if exists)
+
+**Delegates to existing workflows:**
+@~/.claude/specdacular/workflows/discuss-feature.md
+@~/.claude/specdacular/workflows/research-feature.md
+@~/.claude/specdacular/workflows/plan-feature.md
+@~/.claude/specdacular/workflows/prepare-phase.md
+@~/.claude/specdacular/workflows/plan-phase.md
+@~/.claude/specdacular/workflows/execute-plan.md
+@~/.claude/specdacular/workflows/review-phase.md
+</context>
+
+<process>
+1. **Select Feature** — From argument or scan .specd/features/*/config.json
+2. **Read State** — Load config.json, STATE.md, CONTEXT.md, ROADMAP.md
+3. **Show Status** — Concise summary of where things stand
+4. **Determine Next** — Based on stage + phase status
+5. **Offer Choice** — Next step + alternatives + "stop for now"
+6. **Execute** — Delegate to appropriate workflow
+7. **Loop** — Back to step 2 after each action
+</process>
+
+<success_criteria>
+- [ ] Feature selected (from argument or picker)
+- [ ] Current state accurately displayed
+- [ ] Correct next action offered
+- [ ] User can stop at any natural boundary
+- [ ] Delegated to correct workflow for execution
+- [ ] Looped back after completion
+</success_criteria>

package/commands/specd/feature/plan.md

@@ -12,6 +12,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including planning.
+
 Create a roadmap with phase overview and empty phase directories. Detailed PLAN.md files are created later per-phase with `/specd:phase:plan`.
 
 **Creates:**

package/commands/specd/feature/research.md

@@ -13,6 +13,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including research.
+
 Research how to implement a feature before planning. Spawns parallel research agents to investigate:
 
 1. **Codebase Integration** - How does this fit with existing code? (uses Claude Code Explore agent)

package/commands/specd/help.md

@@ -39,6 +39,7 @@ Display available specdacular commands and usage guidance.
 | `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
 | `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
 | `/specd:phase:execute [feature] [plan]` | Execute a plan with progress tracking |
+| `/specd:phase:review [feature] [phase]` | Review executed plans against actual code |
 | `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
 | `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
 
@@ -60,7 +61,7 @@ The feature flow helps you plan features specific enough that an agent can imple
 ```
 feature:new -> feature:discuss -> feature:research -> feature:plan (roadmap) ->
   [for each phase]
-    phase:prepare? -> phase:plan -> phase:execute
+    phase:prepare? -> phase:plan -> phase:execute -> phase:review?
   phase:insert? -> phase:renumber?   <- mid-flight adjustments
 ```
 
@@ -72,6 +73,7 @@ feature:new -> feature:discuss -> feature:research -> feature:plan (roadmap) ->
 - `phase:prepare` — Discuss gray areas + optionally research (per phase)
 - `phase:plan` — Create detailed PLAN.md files for one phase
 - `phase:execute` — Execute plans with progress tracking
+- `phase:review` — Review executed plans, generate corrective plans if needed
 - `phase:insert` — Insert a new phase mid-flight with decimal numbering (e.g., Phase 3.1)
 - `phase:renumber` — Clean up decimal phases to sequential integers
 
@@ -102,6 +104,7 @@ Then for each phase:
 /specd:phase:prepare user-dashboard 1    # Discuss + optionally research
 /specd:phase:plan user-dashboard 1       # Create detailed plans
 /specd:phase:execute user-dashboard      # Execute with progress tracking
+/specd:phase:review user-dashboard 1     # Review phase against actual code
 ```
 
 ---