specdacular 0.5.1 → 0.5.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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 |
@@ -74,13 +81,7 @@
 
 {What the user should do next based on current state.}
 
-**Options:**
-- `/specd:feature:discuss {feature-name}` — Continue refining understanding
-- `/specd:feature:research {feature-name}` — Research implementation approach
-- `/specd:feature:plan {feature-name}` — Create roadmap with phase overview (when ready)
-- `/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
+**Resume:** `/specd:feature:next {feature-name}` — Picks up where you left off and guides the next step automatically.
 
 ---
 

package/specdacular/workflows/new-feature.md

@@ -288,7 +288,7 @@ Continue to completion.
 </step>
 
 <step name="completion">
-Present what was created and next options.
+Present what was created and offer to continue.
 
 **Output:**
 ```
@@ -315,23 +315,51 @@ Present what was created and next options.
 **Open areas to discuss:**
 - {Gray area 1}
 - {Gray area 2}
+```
 
-───────────────────────────────────────────────────────
+Continue to continuation_offer.
+</step>
+
+<step name="continuation_offer">
+Offer to continue discussing or stop.
+
+**If gray areas remain:**
+
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Want to keep discussing the open areas, or come back later?"
+- options:
+  - "Keep discussing" — Dive into the gray areas now
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
 
-## What's Next
+**If Keep discussing:**
+Execute the discuss-feature workflow logic:
+@~/.claude/specdacular/workflows/discuss-feature.md
 
-You control the rhythm. Options:
+After discussion completes (commit done), return to this step (continuation_offer) — re-read CONTEXT.md to check if gray areas remain, and offer again.
 
-**/specd:feature:discuss {feature-name}** — Dive deeper into specific areas
-  {Suggested if gray areas remain}
+**If no gray areas remain:**
 
-**/specd:feature:research {feature-name}** — Research implementation approach
-  {Suggested if technology choices are unclear}
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Discussion looks solid. Want to keep going or come back later?"
+- options:
+  - "Continue" — Move to the next step (research or planning)
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
+
+**If Continue:**
+Hand off to the next-feature workflow logic to determine next action:
+@~/.claude/specdacular/workflows/next-feature.md
+
+Start from the read_state step with the current feature.
+
+**If Stop for now:**
+```
+───────────────────────────────────────────────────────
 
-**/specd:feature:plan {feature-name}** — Create roadmap with phase overview
-  {Only when discussion + research are sufficient}
+Progress saved. Pick up where you left off anytime:
 
-Or just **keep talking** — this conversation continues naturally.
+/specd:feature:next {feature-name}
 ```
 
 End workflow.

package/specdacular/workflows/next-feature.md

@@ -0,0 +1,497 @@
+<purpose>
+Smart state machine that reads current feature state and drives the entire lifecycle. After each action, loops back and offers the next step. User can stop at any natural boundary.
+
+**One command for the entire lifecycle:** discussion, research, planning, phase preparation, phase planning, phase execution, phase review.
+
+**Core loop:**
+```
+read state → show status → determine next action → execute → loop
+```
+
+The user only needs to remember `/specd:feature:next`. The state machine figures out what to do.
+</purpose>
+
+<philosophy>
+
+## Guide, Don't Force
+
+Show the user where they are and what the natural next step is. Always offer alternatives and a "stop for now" option. The user controls the rhythm.
+
+## DRY — Delegate to Existing Workflows
+
+This workflow is a dispatcher. It reads state, determines the next action, then delegates to existing workflow files for the actual work. It does NOT duplicate logic from other workflows.
+
+## Natural Boundaries
+
+After each significant action (discussion session, research, planning, phase completion), offer the user a chance to stop. These are natural context-window boundaries too.
+
+## Feature Selection
+
+When no argument is given, scan for in-progress features and let the user pick. Always show the picker, even for a single feature — it confirms intent.
+
+</philosophy>
+
+<process>
+
+<step name="select_feature">
+Determine which feature to work on.
+
+**If $ARGUMENTS provided:**
+Use as feature name. Normalize to kebab-case.
+
+```bash
+[ -d ".specd/features/$ARGUMENTS" ] || { echo "not found"; exit 1; }
+```
+
+**If no arguments:**
+Scan for in-progress features:
+
+```bash
+# List feature directories with config.json
+for dir in .specd/features/*/config.json; do
+  [ -f "$dir" ] && echo "$dir"
+done
+```
+
+Read each `config.json` and filter where `stage != "complete"`.
+
+**If no features found:**
+```
+No features in progress.
+
+Start one with /specd:feature:new
+```
+End workflow.
+
+**If features found:**
+Use AskUserQuestion:
+- header: "Feature"
+- question: "Which feature would you like to work on?"
+- options: List each feature with its current stage (e.g., "my-feature (discussion)", "other-feature (execution)")
+
+Use the selected feature name.
+
+Continue to read_state.
+</step>
+
+<step name="read_state">
+Load all feature context to determine current position.
+
+**Read:**
+- `.specd/features/{name}/config.json` — Stage, phases info
+- `.specd/features/{name}/STATE.md` — Detailed progress
+- `.specd/features/{name}/CONTEXT.md` — Discussion context, gray areas
+- `.specd/features/{name}/ROADMAP.md` — If exists, phase overview
+- `.specd/features/{name}/FEATURE.md` — Requirements summary
+
+**Parse from config.json:**
+- `stage` — discussion | research | planned | execution | complete
+- `phases.total` — Number of phases (if planned)
+- `phases.current` — Current phase number (if in execution)
+- `phases.completed` — Number of completed phases
+
+**Parse from CONTEXT.md:**
+- Gray areas remaining (from "Gray Areas Remaining" section)
+
+**Parse from ROADMAP.md (if exists):**
+- Phase list with status
+
+**Parse from STATE.md:**
+- Execution progress (which plans are complete)
+- Review cycles
+
+**Determine phase status (if in planned/execution stage):**
+For the current/next phase, check:
+```bash
+# Check if phase directory has CONTEXT.md (prepared)
+[ -f ".specd/features/{name}/plans/phase-{NN}/CONTEXT.md" ] && echo "prepared"
+
+# Check if phase has PLAN.md files (planned)
+ls .specd/features/{name}/plans/phase-{NN}/*-PLAN.md 2>/dev/null | head -1
+
+# Check STATE.md for completed plans in this phase
+```
+
+Continue to show_status.
+</step>
+
+<step name="show_status">
+Present a concise status summary.
+
+```
+## {feature-name}
+
+**Stage:** {stage}
+**Last updated:** {date}
+
+{Stage-specific summary — see below}
+```
+
+**If stage=discussion:**
+```
+**Discussion sessions:** {N}
+**Decisions made:** {N}
+**Gray areas remaining:** {count}
+{If count > 0: list them}
+```
+
+**If stage=research:**
+```
+**Research:** Complete
+**Key findings:** {2-3 bullet points from RESEARCH.md}
+```
+
+**If stage=planned:**
+```
+**Phases:** {total}
+{List phases with one-liner goals}
+```
+
+**If stage=execution:**
+```
+**Phases:** {completed}/{total}
+**Current phase:** {N} — {name}
+**Phase status:** {prepared | planned | executing | executed}
+```
+
+Continue to determine_action.
+</step>
+
+<step name="determine_action">
+Based on current state, determine and offer the next action.
+
+Route to the appropriate sub-step based on state:
+
+**stage=discussion, gray areas remain:**
+→ Go to action_discuss
+
+**stage=discussion, no gray areas (or user wants to skip):**
+→ Go to action_research_offer
+
+**stage=research (RESEARCH.md exists):**
+→ Go to action_plan_offer
+
+**stage=planned, no phases started:**
+→ Go to action_phase_prepare
+
+**stage=planned or stage=execution, current phase prepared but not planned:**
+→ Go to action_phase_plan
+
+**stage=execution, current phase planned but not all plans executed:**
+→ Go to action_phase_execute
+
+**stage=execution, current phase all plans executed:**
+→ Go to action_phase_review
+
+**stage=execution, all phases done:**
+→ Go to action_complete
+
+</step>
+
+<step name="action_discuss">
+Offer discussion when gray areas remain.
+
+```
+### Open Areas
+
+These areas could use more clarity:
+
+{List gray areas from CONTEXT.md}
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Want to discuss these areas, or skip ahead?"
+- options:
+  - "Discuss" — Probe open areas (recommended if gray areas exist)
+  - "Skip to research" — Move to researching implementation patterns
+  - "Skip to planning" — Jump to creating the roadmap (only if enough context)
+  - "Stop for now" — Save progress, come back with /specd:feature:next
+
+**If Discuss:**
+Execute the discuss-feature workflow logic:
+@~/.claude/specdacular/workflows/discuss-feature.md
+
+After discussion completes (commit done), loop back to read_state.
+
+**If Skip to research:**
+→ Go to action_research_offer
+
+**If Skip to planning:**
+→ Go to action_plan_execute
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_research_offer">
+Offer research when discussion is sufficient.
+
+**If RESEARCH.md already exists:**
+```
+Research has already been conducted.
+```
+→ Go to action_plan_offer
+
+**If no RESEARCH.md:**
+```
+### Discussion Looks Solid
+
+You've resolved the key gray areas. Next step is usually research — investigating implementation patterns, libraries, and pitfalls.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Research implementation patterns?"
+- options:
+  - "Research" — Spawn parallel agents to investigate patterns (recommended)
+  - "Skip to planning" — Jump straight to roadmap creation
+  - "Discuss more" — Go back to discussion
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Research:**
+Execute the research-feature workflow logic:
+@~/.claude/specdacular/workflows/research-feature.md
+
+After research completes (commit done), loop back to read_state.
+
+**If Skip to planning:**
+→ Go to action_plan_offer
+
+**If Discuss more:**
+→ Go to action_discuss
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_plan_offer">
+Offer roadmap creation.
+
+```
+### Ready to Plan
+
+{If RESEARCH.md exists: "Research is complete. "}Time to create the roadmap — breaking the feature into ordered phases.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Create the roadmap?"
+- options:
+  - "Create roadmap" — Derive phases and write ROADMAP.md (recommended)
+  - "Discuss more" — Go back to discussion
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Create roadmap:**
+→ Go to action_plan_execute
+
+**If Discuss more:**
+→ Go to action_discuss
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_plan_execute">
+Execute the plan-feature workflow.
+
+Execute the plan-feature workflow logic:
+@~/.claude/specdacular/workflows/plan-feature.md
+
+After planning completes (commit done), loop back to read_state.
+</step>
+
+<step name="action_phase_prepare">
+Offer to prepare the next phase.
+
+**Determine next phase:** First phase without a CONTEXT.md in its directory (not yet prepared), or phase 1 if none started.
+
+```
+### Roadmap Ready
+
+{total} phases planned. Time to prepare Phase {N}: {phase-name}.
+
+Phase preparation involves discussing phase-specific gray areas and optionally researching implementation patterns.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Prepare Phase {N}?"
+- options:
+  - "Prepare phase" — Discuss gray areas + optional research (recommended)
+  - "Skip to planning" — Jump to creating detailed plans
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Prepare phase:**
+Execute the prepare-phase workflow logic:
+@~/.claude/specdacular/workflows/prepare-phase.md
+
+Pass feature name and phase number as arguments.
+
+After preparation completes (commit done), loop back to read_state.
+
+**If Skip to planning:**
+→ Go to action_phase_plan
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_plan">
+Offer to create detailed plans for the current phase.
+
+**Determine phase:** Current phase that has been prepared (or not) but doesn't have PLAN.md files yet.
+
+```
+### Phase {N} Ready for Planning
+
+Time to create detailed, executable plans for Phase {N}: {phase-name}.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Create detailed plans for Phase {N}?"
+- options:
+  - "Create plans" — Write executable PLAN.md files (recommended)
+  - "Prepare first" — Go back to phase preparation
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Create plans:**
+Execute the plan-phase workflow logic:
+@~/.claude/specdacular/workflows/plan-phase.md
+
+Pass feature name and phase number as arguments.
+
+After planning completes (commit done), loop back to read_state.
+
+**If Prepare first:**
+→ Go to action_phase_prepare
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_execute">
+Offer to execute plans for the current phase.
+
+**Determine:** Which plans exist and which are not yet executed.
+
+```
+### Phase {N} Has Plans Ready
+
+{count} plan(s) ready to execute for Phase {N}: {phase-name}.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Execute Phase {N} plans?"
+- options:
+  - "Execute" — Run the next plan with progress tracking (recommended)
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Execute:**
+Execute the execute-plan workflow logic:
+@~/.claude/specdacular/workflows/execute-plan.md
+
+Pass feature name as argument (it finds the next incomplete plan).
+
+After execution completes (commit done), loop back to read_state.
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_review">
+Offer to review the completed phase.
+
+```
+### Phase {N} Execution Complete
+
+All plans for Phase {N} have been executed. Review compares what was planned against what was actually built.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Review Phase {N}?"
+- options:
+  - "Review" — Compare plans against actual code (recommended)
+  - "Skip to next phase" — Move on to Phase {N+1}
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Review:**
+Execute the review-phase workflow logic:
+@~/.claude/specdacular/workflows/review-phase.md
+
+Pass feature name and phase number as arguments.
+
+After review completes (commit done):
+
+**If there are more phases:**
+Loop back to read_state (will pick up next phase).
+
+**If all phases done:**
+→ Go to action_complete
+
+**If Skip to next phase:**
+Loop back to read_state (will pick up next phase).
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_complete">
+Feature is complete.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ FEATURE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phases completed:** {total}
+**Decisions made:** {count}
+
+All phases have been executed{and reviewed, if applicable}.
+```
+
+**Update config.json:**
+Set `stage` to `"complete"`.
+
+**Update STATE.md:**
+Set stage to `complete`.
+
+```bash
+git add .specd/features/{name}/config.json .specd/features/{name}/STATE.md
+git commit -m "docs({feature-name}): feature complete
+
+All {N} phases executed."
+```
+
+End workflow.
+</step>
+
+<step name="action_stop">
+Clean exit with resume instructions.
+
+```
+───────────────────────────────────────────────────────
+
+Progress saved. Resume anytime with:
+
+/specd:feature:next {feature-name}
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- Feature selected (from argument or picker)
+- Current state accurately read and displayed
+- Correct next action determined from state
+- Delegated to appropriate workflow for execution
+- Looped back after action completion
+- User could stop at any natural boundary
+- Clean exit with resume instructions
+</success_criteria>