specdacular 0.5.0 → 0.5.2

package/README.md

@@ -30,21 +30,10 @@ A structured flow for planning features with enough detail for agent implementat
 ```
 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
 ```
 
-**You control the rhythm:**
-- `feature:new` — Initialize and start first discussion
-- `feature:discuss` — Refine understanding (call many times)
-- `feature:research` — Investigate implementation approaches
-- `feature:plan` — Create roadmap with phase overview
-- `phase:prepare` — Discuss gray areas + optionally research patterns (per phase)
-- `phase:plan` — Create detailed PLAN.md files for one phase
-- `phase:execute` — Execute plans with progress tracking
-- `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
-
 ---
 
 ## Installation
@@ -68,22 +57,28 @@ 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 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 (iterative) |
+| `/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 Commands (`phase:`)
+
+Work with individual phases — prepare, plan, and execute one at a time.
 
 | Command | Description |
 |---------|-------------|
@@ -91,6 +86,7 @@ In Claude Code:
 | `/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 |
 
@@ -98,6 +94,7 @@ In Claude Code:
 
 | 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 |
@@ -112,36 +109,119 @@ In Claude Code:
 /specd:map-codebase
 ```
 
-Creates `.specd/codebase/` with 4 AI-optimized documents.
+Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude context about your codebase's architecture, patterns, structure, and gotchas.
 
 ### Plan a Feature
 
+**Step 1: Initialize and discuss**
+
 ```
 /specd:feature:new user-dashboard
 ```
 
-Creates `.specd/features/user-dashboard/` with:
-- `FEATURE.md` — Technical requirements
-- `CONTEXT.md` — Discussion context (accumulates)
-- `DECISIONS.md` — Decisions with dates and rationale
-- `STATE.md` — Progress tracking
+Creates `.specd/features/user-dashboard/` and starts the first discussion. Claude asks what you're building, follows the thread, and captures technical requirements.
+
+**Step 2: Refine understanding**
 
-Then refine and create a roadmap:
 ```
-/specd:feature:discuss user-dashboard    # Clarify gray areas
-/specd:feature:research user-dashboard   # Research implementation
-/specd:feature:plan user-dashboard       # Create roadmap with phases
+/specd:feature:discuss user-dashboard    # Clarify gray areas (call many times)
+/specd:feature:research user-dashboard   # Research implementation approaches
 ```
 
-Then for each phase, prepare, plan, and execute:
+Discussion and research are iterative — call them as many times as you need. Context accumulates across sessions.
+
+**Step 3: Create a roadmap**
+
+```
+/specd:feature:plan user-dashboard
 ```
-/specd:phase:prepare user-dashboard 1    # Discuss + optionally research
-/specd:phase:plan user-dashboard 1       # Create detailed task plans
+
+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.
+
+**Step 4: Prepare, plan, and execute each phase**
+
+```
+/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:phase:review user-dashboard 1     # Review phase against actual code
+```
+
+Repeat for each phase. Plans are created just-in-time so they stay fresh.
+
+**Mid-flight adjustments:**
+
+```
+/specd:phase:insert user-dashboard 3 "Cache layer"  # Insert Phase 3.1
+/specd:phase:renumber user-dashboard                 # Clean up to integers
 ```
 
 ---
 
+## The Flow in Detail
+
+### Feature-Level Commands
+
+**`feature:new`** creates the feature folder and starts the first discussion. 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: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`.
+
+### Phase-Level Commands
+
+**`phase:prepare`** is the main pre-execution command. It:
+1. Shows the phase overview (goal, deliverables, existing context)
+2. Identifies gray areas based on phase type (Types, API, UI, etc.)
+3. Probes until clear (4 questions max per area)
+4. Records resolutions to phase `CONTEXT.md` and `DECISIONS.md`
+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:
+- Exact file paths to create/modify
+- Code patterns to follow (from codebase docs)
+- Verification commands to run
+- Clear completion criteria
+
+Plans are created just-in-time — right before execution — so they incorporate all context from preparation and earlier phases.
+
+**`phase:execute`** executes plans with:
+- Auto-fix for bugs/blockers (logged to `CHANGELOG.md`)
+- User confirmation for architectural changes
+- Verification after each task
+- 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 ✅/⚠️/❌/⏸️ 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.
+
+---
+
 ## How It Works
 
 ### Parallel Agents
@@ -171,8 +251,6 @@ Specdacular spawns specialized agents that run simultaneously:
 
 ### Feature Flow
 
-The feature planning flow accumulates context over multiple sessions:
-
 ```
 ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
 │  feature:new │ ──▶ │   feature:   │ ◀─▶ │   feature:   │
@@ -203,6 +281,12 @@ The feature planning flow accumulates context over multiple sessions:
               │  │  phase:  │               │
               │  │ execute  │               │
               │  └──────────┘               │
+              │       │                     │
+              │       ▼                     │
+              │  ┌──────────┐               │
+              │  │  phase:  │               │
+              │  │  review  │               │
+              │  └──────────┘               │
               │                             │
               │  Mid-flight adjustments:    │
               │  ┌──────────┐               │
@@ -216,23 +300,6 @@ The feature planning flow accumulates context over multiple sessions:
               └─────────────────────────────┘
 ```
 
-Each session updates:
-- `CONTEXT.md` — Resolved questions accumulate
-- `DECISIONS.md` — Decisions with rationale accumulate
-
-**Phase-level commands:**
-- `phase:prepare` — Just-in-time discussion + optional research for a specific phase
-- `phase:plan` — Create detailed PLAN.md files for one phase (just-in-time, not upfront)
-- `phase:execute` — Execute plans with deviation tracking
-- `phase:insert` — Insert urgent work mid-flight as decimal phase (e.g., 3.1)
-- `phase:renumber` — Clean up decimal numbering to sequential integers
-
-Plans are prompts for implementing agents with:
-- Specific file paths
-- Code patterns to follow
-- Verification commands
-- Clear completion criteria
-
 ---
 
 ## Project Structure
@@ -255,12 +322,12 @@ your-project/
 │           ├── DECISIONS.md   # Decision log (feature + phase)
 │           ├── STATE.md       # Progress tracking
 │           ├── RESEARCH.md    # Feature-level research
-│           ├── ROADMAP.md     # Phase overview
-│           └── plans/         # Executable plans
+│           ├── 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   # From phase:plan
+│               │   ├── 01-PLAN.md   # Detailed plans (from phase:plan)
 │               │   └── 02-PLAN.md
 │               └── phase-02/
 │                   ├── CONTEXT.md
@@ -297,6 +364,37 @@ Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, c
 
 ---
 
+## Migrating from v0.4
+
+If you're upgrading from v0.4, here's what changed:
+
+**Commands were renamed** into `feature:` and `phase:` namespaces:
+
+| v0.4 | v0.5 |
+|------|------|
+| `/specd:new-feature` | `/specd:feature:new` |
+| `/specd:discuss-feature` | `/specd:feature:discuss` |
+| `/specd:research-feature` | `/specd:feature:research` |
+| `/specd:plan-feature` | `/specd:feature:plan` |
+| `/specd:discuss-phase` | `/specd:phase:prepare` |
+| `/specd:research-phase` | `/specd:phase:research` |
+| `/specd:execute-plan` | `/specd:phase:execute` |
+| `/specd:insert-phase` | `/specd:phase:insert` |
+| `/specd:renumber-phases` | `/specd:phase:renumber` |
+
+**New commands:**
+- `/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:**
+- `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.
+
+**Existing `.specd/` data is fully compatible.** Your feature files, decisions, and roadmaps work with the new commands.
+
+---
+
 ## Updating
 
 ```bash

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 |
 
@@ -46,6 +47,7 @@ Display available specdacular commands and usage guidance.
 
 | Command | Description |
 |---------|-------------|
+| `/specd:status [--all]` | Show feature status dashboard |
 | `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
 | `/specd:update` | Update Specdacular to the latest version |
 | `/specd:help` | Show this help |
@@ -59,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
 ```
 
@@ -71,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
 
@@ -101,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
 ```
 
 ---

package/commands/specd/phase/review.md

@@ -0,0 +1,80 @@
+---
+name: specd:phase:review
+description: Review executed plans against actual code and identify deviations
+argument-hint: "[feature-name] [phase-number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Review executed plans for a phase, comparing intended changes against actual code. Surfaces deviations, captures decisions, and generates corrective plans when needed.
+
+**What it does:**
+1. Load context — STATE.md, plans, DECISIONS.md, codebase docs
+2. Filter plans — Only review plans with status Complete (DEC-006)
+3. Inspect each plan — Compare creates/modifies frontmatter against actual files
+4. Present findings — Per-plan status table with expandable details (DEC-005)
+5. Gather user input — Ask about satisfaction, additional issues (DEC-001)
+6. Record decisions — New decisions to DECISIONS.md
+7. Generate correctives — Corrective plans if issues found (DEC-003)
+8. Update state — Review Cycles in STATE.md (DEC-004)
+9. Commit and suggest next steps
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/review-phase.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS (first argument)
+Phase number: $ARGUMENTS (second argument)
+
+**Load ALL feature context:**
+@.specd/features/{name}/STATE.md — Progress tracking, completed plans
+@.specd/features/{name}/DECISIONS.md — Existing decisions
+@.specd/features/{name}/RESEARCH.md — Implementation notes (if exists)
+@.specd/features/{name}/ROADMAP.md — Phase overview
+@.specd/features/{name}/CHANGELOG.md — Existing deviations (if exists)
+
+**Load plan files for the phase:**
+@.specd/features/{name}/plans/phase-{NN}/*.md — All plan files
+
+**Load codebase context:**
+@.specd/codebase/PATTERNS.md — Code patterns
+@.specd/codebase/STRUCTURE.md — File locations
+@.specd/codebase/MAP.md — System overview
+</context>
+
+<process>
+1. **Validate** — Feature exists, phase exists, has execution history
+2. **Load Context** — Read all feature, plan, and codebase docs
+3. **Filter Plans** — Get only completed plans for this phase
+4. **Inspect Phase** — Compare each plan's intent against actual code
+5. **Present Findings** — Per-plan status table + deviation details
+6. **Gather User Input** — Ask about satisfaction, additional issues
+7. **Record Decisions** — Save new decisions to DECISIONS.md
+8. **Generate Correctives** — Create corrective plans if needed
+9. **Update State** — Update Review Cycles section in STATE.md
+10. **Update Changelog** — Log deviations to CHANGELOG.md
+11. **Commit and Next** — Commit changes, suggest next steps
+</process>
+
+<success_criteria>
+- [ ] Feature and phase validated with execution history
+- [ ] All completed plans inspected against actual code
+- [ ] Per-plan status table displayed (✅/⚠️/❌/⏸️)
+- [ ] Deviations surfaced with planned vs actual comparison
+- [ ] User input captured (satisfaction, additional issues)
+- [ ] New decisions recorded in DECISIONS.md
+- [ ] Corrective plans generated if issues identified
+- [ ] Review Cycles section updated in STATE.md
+- [ ] Deviations logged in CHANGELOG.md
+- [ ] Changes committed
+- [ ] Next steps suggested
+</success_criteria>

package/commands/specd/status.md

@@ -0,0 +1,20 @@
+---
+name: specd:status
+description: Show feature status dashboard
+argument-hint: "[--all]"
+allowed-tools:
+  - Read
+  - Glob
+  - Bash
+---
+
+<objective>
+Display a dashboard showing all features and their current status, stage, plan progress, and recommended next action.
+
+- By default, hide completed features
+- With `--all` flag, show completed features in a separate section
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/status.md
+</execution_context>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
     "specdacular": "bin/install.js"

package/specdacular/templates/features/STATE.md

@@ -41,6 +41,13 @@
 
 ---
 
+## Review Cycles
+
+| Phase | Cycle | Date | Findings | Corrective Plans | Status |
+|-------|-------|------|----------|------------------|--------|
+
+---
+
 ## Discussion Sessions
 
 | Date | Focus | Outcome |
@@ -81,6 +88,7 @@
 - `/specd:phase:prepare {feature-name} {N}` — Prepare a specific phase
 - `/specd:phase:plan {feature-name} {N}` — Create detailed plans for a phase
 - `/specd:phase:execute {feature-name}` — Execute plans with progress tracking
+- `/specd:phase:review {feature-name} {N}` — Review executed plans against actual code
 
 ---
 

package/specdacular/workflows/review-phase.md

@@ -0,0 +1,555 @@
+<purpose>
+Review executed plans for a phase by comparing intended changes against actual code.
+Surfaces deviations, captures user feedback, records decisions, and generates corrective plans.
+
+**Key principles:**
+- Inspect semantically, not literally — did the code achieve what the plan intended?
+- Claude inspects first, then asks the user (DEC-001)
+- Support partial review — only inspect completed plans (DEC-006)
+- Progressive disclosure — summary, then details, then conversation (DEC-005)
+
+**Output:** Review findings, updated STATE.md (Review Cycles), CHANGELOG.md entries, corrective plans (if needed)
+</purpose>
+
+<philosophy>
+
+## Semantic Review, Not Literal Diff
+
+Plans describe intent. Code implements intent. The review checks whether intent was fulfilled,
+not whether every word matches. A plan saying "create user service" that results in `users.service.ts`
+instead of `user-service.ts` is a match, not a deviation.
+
+Use plan `creates`/`modifies` frontmatter for file-level verification.
+Use Claude's understanding for intent-level verification.
+
+## Deviations Are Neutral
+
+A deviation means code differs from the plan. It might be an improvement, a mistake, or an
+intentional change. The review surfaces it; the user decides if it matters.
+
+## Corrective Plans Fix Gaps, Not Add Features
+
+When generating corrective plans, scope them to what the original plan intended but didn't achieve.
+Don't use review as a backdoor to add features or refactor code.
+
+## Iteration Has Limits
+
+Max 3 review cycles per phase. If findings increase between cycles, stop and discuss.
+Show progress: "Cycle 2/3: 2 issues (down from 5)".
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+Validate feature exists, phase exists, and has execution history.
+
+**Check feature:**
+- `.specd/features/{feature}` directory exists
+- `STATE.md`, `DECISIONS.md`, `ROADMAP.md` exist
+
+**Check phase:**
+- Phase {N} exists in ROADMAP.md
+- `.specd/features/{feature}/plans/phase-{NN}/` directory exists
+- At least one plan file exists in the phase directory
+
+**Check execution:**
+- STATE.md has at least one plan from this phase in the Completed Plans table
+- If no completed plans: show error and suggest running `/specd:phase:execute` first
+
+**Check git state:**
+- Warn if uncommitted changes exist (review may not reflect actual state)
+
+**If feature not found:**
+```
+Feature '{name}' not found.
+
+Run /specd:feature:new {name} to create it.
+```
+
+**If no executed plans:**
+```
+No executed plans found for {feature} phase {N}.
+
+Run /specd:phase:execute {feature} to execute plans first.
+```
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Load ALL context needed for review.
+
+**Read feature context:**
+- `config.json` — Feature settings
+- `STATE.md` — Current progress, completed plans, existing review cycles
+- `DECISIONS.md` — Active decisions to be aware of
+- `RESEARCH.md` — Implementation notes, pitfalls (if exists)
+- `ROADMAP.md` — Phase overview, success criteria
+- `CHANGELOG.md` — Existing logged deviations (if exists, to avoid duplicates)
+
+**Read phase context:**
+- `plans/phase-{NN}/CONTEXT.md` — Phase-specific discussion resolutions (if exists)
+- `plans/phase-{NN}/RESEARCH.md` — Phase-specific research findings (if exists)
+
+**Read ALL plan files for this phase:**
+- `plans/phase-{NN}/*-PLAN.md` — Every plan file, including any corrective plans
+- Parse YAML frontmatter: `creates`, `modifies`, `corrects`, `depends_on`
+- Parse plan objectives and task descriptions
+
+**Read codebase context (if available):**
+- `PATTERNS.md` — Code patterns to follow
+- `STRUCTURE.md` — Where files go
+- `MAP.md` — System overview
+
+**Internalize:**
+- Which plans are complete vs pending (from STATE.md Completed Plans table)
+- What files each plan was supposed to create or modify
+- Phase success criteria from ROADMAP.md
+- Existing review cycles (to determine cycle number)
+- Existing CHANGELOG.md entries (to avoid duplicate logging)
+
+Continue to filter_plans.
+</step>
+
+<step name="filter_plans">
+Separate completed and pending plans for this phase (DEC-006).
+
+**From STATE.md Completed Plans table:**
+1. Identify plans from this phase with status "Complete"
+2. These are the plans to inspect
+
+**Remaining plans:**
+- Plans without a completion entry are "pending" (not yet executed)
+- Show as ⏸️ in the status table but don't inspect
+
+**Build plan list:**
+For each completed plan, collect:
+- Plan path (e.g., `phase-01/01-PLAN.md`)
+- Plan title
+- `creates` list from frontmatter
+- `modifies` list from frontmatter
+- `corrects` list from frontmatter (if corrective plan)
+- Completion date from STATE.md
+
+**If corrective plans exist (have `corrects` frontmatter):**
+- Note which original plans they correct
+- Inspection of corrective plans follows the same process
+
+Continue to inspect_phase.
+</step>
+
+<step name="inspect_phase">
+For each completed plan, compare intended changes against actual code.
+
+**For each completed plan:**
+
+### 1. File-level verification
+For each file in `creates`:
+- Check if file exists on disk
+- If missing: mark ❌ Incomplete
+
+For each file in `modifies`:
+- Check if file exists on disk
+- If missing: mark ❌ Incomplete (file may have been deleted)
+
+### 2. Intent-level verification
+For each file that exists:
+- Read the file content
+- Read the plan's task descriptions for that file
+- Compare semantically: did the code achieve what the plan described?
+- Consider:
+  - Does the file fulfill the plan's stated objective?
+  - Are the key structures/patterns the plan specified present?
+  - Are there significant omissions vs what the plan described?
+
+### 3. Classify each plan
+Assign a status based on findings:
+
+| Status | Icon | Criteria |
+|--------|------|----------|
+| Match | ✅ | All files exist, intent fulfilled, no significant deviations |
+| Deviation | ⚠️ | Files exist and work, but implementation differs from plan |
+| Incomplete | ❌ | Missing files, or plan objectives clearly not met |
+| Not executed | ⏸️ | Plan not in Completed Plans table (pending) |
+
+### 4. Collect deviation details
+For each deviation (⚠️) or incomplete (❌):
+- **Plan reference:** Which plan, which task
+- **Planned:** What the plan specified
+- **Actual:** What was actually implemented (or what's missing)
+- **Files:** Affected file paths
+- **Impact:** Low (cosmetic/naming), Medium (behavioral), High (missing functionality)
+
+### 5. Check phase success criteria
+Read phase success criteria from ROADMAP.md.
+For each criterion, assess if it's been met by the executed plans.
+Flag unmet criteria as additional findings.
+
+Continue to present_findings.
+</step>
+
+<step name="present_findings">
+Present review findings using progressive disclosure (DEC-005).
+
+**Display review header:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phase:** {N} — {phase title}
+**Review Cycle:** {cycle number}
+**Plans reviewed:** {completed count} of {total count}
+```
+
+**1. Summary line:**
+```
+Summary: {N} ✅ | {N} ⚠️ | {N} ❌ | {N} ⏸️
+```
+
+**2. Per-plan status table:**
+```
+| Plan | Title | Status | Files |
+|------|-------|--------|-------|
+| 01 | {title} | ✅ Match | {N} files checked |
+| 02 | {title} | ⚠️ Deviation | {N} of {M} files match |
+| 03 | {title} | ❌ Incomplete | {N} files missing |
+| 04 | {title} | ⏸️ Not executed | — |
+```
+
+**3. Expanded details (only for ⚠️ and ❌):**
+
+For each plan with deviations or incomplete status:
+```
+───────────────────────────────────────────────────────
+Plan {NN}: {Title} — {⚠️ Deviation | ❌ Incomplete}
+───────────────────────────────────────────────────────
+
+**Finding 1: {Short description}**
+- **Planned:** {What the plan specified}
+- **Actual:** {What was implemented or what's missing}
+- **Files:** `{file paths}`
+- **Impact:** {Low | Medium | High}
+
+**Finding 2: {Short description}**
+...
+```
+
+**4. Phase success criteria check:**
+```
+Phase Success Criteria:
+- [x] {Met criterion}
+- [ ] {Unmet criterion} — {brief explanation}
+```
+
+**If all clean (no ⚠️ or ❌):**
+```
+All executed plans match their intended implementation. Phase {N} is clean.
+```
+
+Continue to gather_user_input.
+</step>
+
+<step name="gather_user_input">
+Ask the user for feedback on the review findings (DEC-001).
+
+**If findings exist (⚠️ or ❌):**
+
+Use AskUserQuestion:
+- header: "Review"
+- question: "How would you like to handle these findings?"
+- options:
+  - "Generate corrective plans" — Create corrective plans for all issues
+  - "Discuss findings" — Talk through each finding before deciding
+  - "Accept all deviations" — Mark all deviations as intentional, phase is clean
+  - "Accept some, fix others" — Go through findings one by one
+
+**If "Discuss findings" or "Accept some, fix others":**
+For each finding, ask:
+- header: "Finding"
+- question: "{Finding description} — how to handle?"
+- options:
+  - "Accept as-is" — Deviation is intentional, no action needed
+  - "Generate corrective plan" — Create a plan to fix this
+  - "Record as decision" — This is a deliberate choice, record in DECISIONS.md
+
+Collect user's response for each finding.
+
+**If clean (no ⚠️ or ❌):**
+
+Use AskUserQuestion:
+- header: "Review"
+- question: "Review is clean. Any additional issues to flag?"
+- options:
+  - "No, phase looks good" — Mark phase as clean
+  - "Yes, I have concerns" — Capture user's additional issues
+
+**If user has additional concerns:**
+Ask them to describe the issues. For each issue:
+- Classify as deviation or new requirement
+- Add to findings list for corrective plan generation
+
+Continue to record_decisions.
+</step>
+
+<step name="record_decisions">
+Record any new decisions made during the review conversation.
+
+**Collect decisions from:**
+- User accepting deviations as intentional ("we meant to do it this way")
+- User choosing a different approach than the plan specified
+- User flagging issues that reveal design choices
+
+**For each new decision:**
+Append to `.specd/features/{feature}/DECISIONS.md`:
+```markdown
+### DEC-{NNN}: {Decision title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Active
+**Context:** Discovered during phase {N} review (cycle {C})
+**Decision:** {What was decided}
+**Rationale:**
+- {Why this decision was made}
+**Implications:**
+- {What this means for implementation}
+```
+
+**Update decision count** in `config.json`.
+
+**If no new decisions:** Skip this step.
+
+Continue to generate_correctives.
+</step>
+
+<step name="generate_correctives">
+Generate corrective plans for findings that need fixes (DEC-003).
+
+**Skip if:** All findings were accepted or no findings exist.
+
+**Determine next plan number:**
+- Count existing plan files in the phase directory
+- Next corrective plan number = max existing number + 1
+
+**For each group of findings to fix:**
+
+Create a corrective plan file at `plans/phase-{NN}/{MM}-PLAN.md`:
+
+```yaml
+---
+feature: {feature-name}
+phase: {N}
+plan: {MM}
+depends_on:
+  - phase-{NN}/{last-executed}-PLAN.md
+creates:
+  - {any new files needed}
+modifies:
+  - {files that need fixing}
+corrects:
+  - {original plan numbers being corrected, e.g., [01, 03]}
+---
+```
+
+**Corrective plan content:**
+- Objective: Fix specific deviations/issues from review cycle {C}
+- Reference the original plan's intent
+- Tasks scoped to fixing gaps, not adding features
+- Each task has verification
+- Include the planned vs actual from review findings
+
+**Scoping rules (CAPA framework):**
+- Corrective plans should modify fewer files than the original plans, not more
+- Fix what was intended but not done — don't add features
+- If a finding spans multiple original plans, one corrective plan can reference multiple via `corrects: [01, 03]`
+- Ask user before generating if scope seems large
+
+**Present generated plans:**
+```
+Generated corrective plans:
+
+| Plan | Corrects | Title | Files |
+|------|----------|-------|-------|
+| {MM}-PLAN.md | Plan(s) {NN} | {title} | {file count} |
+
+These will be picked up by /specd:phase:execute automatically.
+```
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update STATE.md with review cycle data (DEC-004).
+
+**Determine cycle number:**
+- Read existing Review Cycles table in STATE.md
+- If section doesn't exist, create it
+- Cycle number = max existing cycle for this phase + 1
+
+**Add/create Review Cycles section** (after "Execution Progress", before "Discussion Sessions"):
+
+```markdown
+## Review Cycles
+
+| Phase | Cycle | Date | Findings | Corrective Plans | Status |
+|-------|-------|------|----------|------------------|--------|
+| {N} | {C} | {YYYY-MM-DD} | {summary, e.g., "2 deviations, 1 incomplete"} | {plan refs or "—"} | {clean or fixes-pending} |
+```
+
+**Status values:**
+- `clean` — No unresolved findings, all accepted or no deviations
+- `fixes-pending` — Corrective plans generated, awaiting execution
+
+**If status is `clean` and all plans executed:**
+- Update Execution Progress to mark phase as complete:
+  ```markdown
+  - [x] Phase {N} complete
+  ```
+
+**If this is a subsequent cycle (cycle > 1):**
+- Show progress: "Cycle {C}: {N} findings (down from {M})"
+- If findings increased, add warning: "Findings increased from {M} to {N}. Consider discussing before continuing."
+
+Continue to update_changelog.
+</step>
+
+<step name="update_changelog">
+Log deviations to CHANGELOG.md.
+
+**Skip if:** No deviations found, or all deviations already logged from a previous review cycle.
+
+**Check for duplicates:**
+- Read existing CHANGELOG.md entries
+- Skip any deviation already logged (compare file paths and descriptions)
+
+**Add review entry:**
+```markdown
+### {YYYY-MM-DD} - Review {feature}/phase-{NN} (Cycle {C})
+
+**[Deviation] {Short description}**
+- **Planned:** {What plan specified}
+- **Actual:** {What was actually implemented}
+- **Files:** `{affected file paths}`
+- **Impact:** {Low | Medium | High}
+```
+
+**For accepted deviations (user said "accept as-is"):**
+```markdown
+**[Accepted] {Short description}**
+- **Planned:** {What plan specified}
+- **Actual:** {What was actually implemented}
+- **Files:** `{affected file paths}`
+- **Reason:** {User's reason for accepting}
+```
+
+Continue to commit_and_next.
+</step>
+
+<step name="commit_and_next">
+Commit review changes and suggest next steps.
+
+**Commit changes:**
+```bash
+git add .specd/features/{feature}/STATE.md
+git add .specd/features/{feature}/DECISIONS.md
+git add .specd/features/{feature}/CHANGELOG.md
+# If corrective plans were generated:
+git add .specd/features/{feature}/plans/phase-{NN}/
+git add .specd/features/{feature}/config.json
+
+git commit -m "docs({feature}): review phase {N} (cycle {C})
+
+Review findings: {summary}
+Status: {clean | fixes-pending}
+{If corrective plans:}Corrective plans: {list}"
+```
+
+**Present next steps:**
+
+**If status = `fixes-pending`:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REVIEW COMPLETE — Fixes Pending
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Review cycle {C} recorded. Corrective plans ready for execution.
+
+**Next steps:**
+- `/specd:phase:execute {feature}` — Execute corrective plans
+- Then `/specd:phase:review {feature} {N}` — Re-review after fixes
+```
+
+**If status = `clean` and phase complete:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REVIEW COMPLETE — Phase Clean
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {N} review is clean. All executed plans match their intent.
+
+{If all plans executed:}
+Phase {N} is complete!
+
+**Next steps:**
+{If next phase exists:}
+- `/specd:phase:prepare {feature} {N+1}` — Prepare next phase
+- `/specd:phase:plan {feature} {N+1}` — Plan next phase
+
+{If last phase:}
+Feature '{feature}' implementation is complete!
+Review STATE.md for full summary.
+```
+
+**If status = `clean` but partial execution:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REVIEW COMPLETE — Clean (Partial)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Reviewed {M} of {N} plans. All reviewed plans are clean.
+
+**Next steps:**
+- `/specd:phase:execute {feature}` — Continue executing remaining plans
+- `/specd:phase:review {feature} {N}` — Re-review after more execution
+```
+
+End workflow.
+</step>
+
+</process>
+
+<changelog_format>
+When logging to CHANGELOG.md during review, use these types:
+
+```markdown
+### {YYYY-MM-DD} - Review {feature}/phase-{NN} (Cycle {C})
+
+**[{Type}] {Short description}**
+- **Planned:** {What plan specified}
+- **Actual:** {What was implemented or missing}
+- **Files:** `{comma-separated file paths}`
+- **Impact:** {Low | Medium | High}
+```
+
+Types:
+- `[Deviation]` — Code works but differs from plan
+- `[Incomplete]` — Plan objective not fully met
+- `[Accepted]` — User accepted deviation as intentional
+- `[User-flagged]` — Issue raised by user during conversation phase
+</changelog_format>
+
+<success_criteria>
+- Feature and phase validated with execution history
+- All completed plans inspected against actual code
+- Per-plan status table displayed with correct icons
+- Deviations surfaced with planned vs actual comparison
+- User input captured and processed
+- New decisions recorded in DECISIONS.md
+- Corrective plans generated with `corrects` frontmatter (if needed)
+- Review Cycles section updated in STATE.md
+- Deviations logged in CHANGELOG.md (no duplicates)
+- Changes committed
+- Next steps suggested based on review outcome
+</success_criteria>

package/specdacular/workflows/status.md

@@ -0,0 +1,85 @@
+# Workflow: Feature Status Dashboard
+
+## Input
+
+- `$ARGUMENTS` — may contain `--all` flag
+
+## Steps
+
+### 1. Parse arguments
+
+Check if `$ARGUMENTS` contains `--all`. If so, completed features will be shown in a separate section.
+
+### 2. Check for features directory
+
+Use Glob to check if `.specd/features/*/config.json` matches anything.
+
+If no matches: output the following and stop:
+
+```
+No features found. Start one with `/specd:feature:new [name]`.
+```
+
+### 3. Gather feature data
+
+For each feature directory in `.specd/features/`:
+
+1. **Read `config.json`** — extract: `feature_name`, `created`, `stage`, `phases_count`, `plans_count`
+2. **Read `STATE.md`** — extract:
+   - **Authoritative stage**: Look for `**Stage:** <value>` in the Current Position section. This overrides `config.json` stage. A feature is complete when stage is `complete`.
+   - **Plan completion**: From the `Plan Status` table, count rows with Status = `Complete` vs total rows. Format as `completed/total` (e.g. `5/8`). If no Plan Status table or no rows, use `—`.
+   - **Next action**: Extract the first meaningful line from the `## Next Steps` section. Keep it short — take just the **Recommended:** line if present, otherwise the first line. Strip markdown formatting like `**Recommended:**` prefix. Truncate to ~50 chars if needed.
+
+### 4. Sort features
+
+Sort active features by stage priority (highest first), then by created date (oldest first):
+
+1. `execution` (most advanced)
+2. `planning`
+3. `research`
+4. `discussion` (least advanced)
+
+### 5. Format output
+
+**Count features:** Calculate total count and in-progress count (non-complete).
+
+**Output header:**
+
+```
+# Feature Status
+
+_{total} features, {in_progress} in progress_
+```
+
+**Active features table:**
+
+```
+| Feature | Stage | Plans | Created | Next Action |
+|---------|-------|-------|---------|-------------|
+| {name} | {stage} | {plans} | {created} | {next_action} |
+```
+
+- `Plans` shows the completed/total count from Plan Status table, or `—` if pre-planning
+- `Next Action` is the extracted recommendation from STATE.md Next Steps
+
+**If `--all` flag is NOT set and there are completed features:**
+
+```
+Run `/specd:status --all` to include completed features.
+```
+
+**If `--all` flag IS set and there are completed features, add:**
+
+```
+### Completed
+
+| Feature | Plans | Completed |
+|---------|-------|-----------|
+| {name} | {completed}/{total} | {last_updated} |
+```
+
+Where `Completed` date comes from the `**Last Updated:**` field in STATE.md.
+
+### 6. Output
+
+Print the formatted dashboard directly. No file writes. No Task agents. No AskUserQuestion.