specdacular 0.7.0 → 0.7.2

package/specdacular/workflows/review-feature.md

@@ -0,0 +1,316 @@
+<purpose>
+User-guided review of an executed phase. Shows what was built (git diff), provides test guidance, and takes user feedback to generate fix plans.
+
+**Core principle:** Show, don't fix. The user examines the code, reports issues, and the review workflow creates targeted fix plans.
+
+**Output:** Phase approved (status → completed) or fix plans in decimal-numbered phase directories.
+</purpose>
+
+<philosophy>
+
+## Show, Don't Fix
+
+The review workflow does NOT auto-fix code. It presents what was built and lets the user drive. The user has better judgment about code quality, correctness, and fit.
+
+## Git Diff Is Ground Truth
+
+File tracking uses `git diff` against the phase start commit (DEC-012). This captures everything: planned work, auto-fixes, deviations — not just what the plan intended.
+
+## Fix Plans, Not Inline Fixes
+
+When the user reports issues, the review creates proper PLAN.md files in decimal-numbered directories (DEC-006, DEC-014). These fix plans are executed with the same execute-plan workflow as regular plans, maintaining consistency.
+
+## Review Loop
+
+After fix plans execute, the review loops back — showing the updated diff and asking again. This continues until the user approves.
+
+</philosophy>
+
+<process>
+
+<step name="select_feature">
+@~/.claude/specdacular/references/select-feature.md
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Load context needed for review.
+
+**Read feature context:**
+- `config.json` — `phases.current`, `phases.phase_start_commit`, `phases.current_status`
+- `STATE.md` — Completed plans for current phase
+- `ROADMAP.md` — Phase name and goals
+- `CHANGELOG.md` — Deviations from this phase
+
+**Validate:**
+- `phases.current_status` must be `"executed"` (all plans done, pending review)
+- `phases.phase_start_commit` must exist (recorded when execution started)
+
+**If current_status is not "executed":**
+```
+Phase {N} is not in "executed" state (current: {status}).
+
+Run /specd:feature:continue to get to the right step.
+```
+End workflow.
+
+**Read current phase's PLAN.md files:**
+```bash
+ls .specd/features/{feature}/plans/phase-{NN}/*-PLAN.md
+```
+For each plan, extract:
+- Objective
+- Success criteria
+- Files listed in tasks
+
+Continue to show_review.
+</step>
+
+<step name="show_review">
+Present what was built and ask for approval.
+
+**Get files changed:**
+```bash
+git diff {phase_start_commit}..HEAD --stat
+git diff {phase_start_commit}..HEAD --name-status
+```
+
+**Build summary from plan objectives:**
+For each executed plan in this phase, extract the one-line objective.
+
+**Derive test guidance from:**
+- Plan success criteria (what should be verifiable)
+- File types created (e.g., if workflow .md files: "test by running the commands")
+- CHANGELOG.md deviations (anything unusual to check)
+
+**Present:**
+```
+### Phase {N}: {phase-name} — Review
+
+**Files changed:**
+{git diff --stat output}
+
+**What was built:**
+{For each plan: one-line objective summary}
+
+**How to test:**
+{Test guidance derived from success criteria and file types}
+
+**Deviations from plan:**
+{From CHANGELOG.md for this phase, or "None"}
+```
+
+Use AskUserQuestion:
+- header: "Review"
+- question: "Is Phase {N} OK, or do you want to revise?"
+- options:
+  - "Looks good" — Approve phase, mark completed
+  - "I want to revise" — Describe what needs fixing
+  - "Stop for now" — Come back later with /specd:feature:continue
+
+**If "Looks good":**
+→ Go to approve_phase
+
+**If "I want to revise":**
+→ Go to collect_feedback
+
+**If "Stop for now":**
+```
+───────────────────────────────────────────────────────
+
+Progress saved. Phase stays in "executed" state.
+Resume review with /specd:feature:continue {feature-name}
+```
+End workflow.
+</step>
+
+<step name="collect_feedback">
+Gather user feedback on what needs fixing.
+
+**Ask the user to describe issues:**
+```
+Tell me what needs fixing. You can describe:
+- Bugs or incorrect behavior
+- Approach you'd prefer changed
+- Missing functionality
+- Code quality issues
+
+Describe as many issues as you want — I'll create a fix plan for all of them.
+```
+
+Wait for user response.
+
+**Follow up to understand each issue:**
+For each issue mentioned:
+- What file/component is affected?
+- What's wrong (bug, wrong approach, missing)?
+- What should it look like instead?
+
+After understanding all issues, continue to create_fix_plan.
+</step>
+
+<step name="create_fix_plan">
+Create a fix plan from user feedback.
+
+**Determine fix phase number:**
+```bash
+# Check existing decimal phases for current phase
+ls -d .specd/features/{feature}/plans/phase-{N}.* 2>/dev/null | sort -V | tail -1
+```
+
+- If no decimal phases exist → create `phase-{N}.1/`
+- If `phase-{N}.1/` exists → create `phase-{N}.2/`, etc.
+- Increment from the highest existing decimal
+
+**Create fix phase directory:**
+```bash
+mkdir -p .specd/features/{feature}/plans/phase-{N.M}/
+```
+
+**Write fix plan:**
+Write `01-PLAN.md` in the new directory using standard plan format:
+
+```markdown
+---
+feature: {feature-name}
+phase: {N.M}
+plan: 01
+depends_on: []
+creates: []
+modifies:
+  - {files that need fixing}
+---
+
+# Plan 01: Fix Phase {N} Issues
+
+## Objective
+
+Address review feedback for Phase {N}: {phase-name}.
+
+## Context
+
+**User feedback:**
+{Summarize each issue reported}
+
+## Tasks
+
+### Task 1: {Fix description}
+**Files:** `{file}`
+**Action:** {What to change}
+**Verify:** {How to verify the fix}
+**Done when:** {Acceptance criteria}
+
+{Repeat for each issue}
+```
+
+**Update ROADMAP.md:**
+Add the fix phase entry after the parent phase.
+
+**Commit the fix plan:**
+```bash
+git add .specd/features/{feature}/plans/phase-{N.M}/ .specd/features/{feature}/ROADMAP.md
+git commit -m "docs({feature}): create fix plan phase-{N.M}
+
+Review feedback:
+- {issue summaries}"
+```
+
+Present:
+```
+Fix plan created: plans/phase-{N.M}/01-PLAN.md
+{task_count} task(s) to address your feedback.
+```
+
+Continue to offer_execution.
+</step>
+
+<step name="offer_execution">
+Offer to execute the fix plan.
+
+Use AskUserQuestion:
+- header: "Fix Plan"
+- question: "Execute the fix plan now?"
+- options:
+  - "Execute" — Run the fix plan (recommended)
+  - "Stop for now" — Come back later
+
+**If "Execute":**
+Execute the fix plan using the execute-plan workflow logic:
+@~/.claude/specdacular/workflows/execute-plan.md
+
+Pass feature name as argument. The execute-plan workflow will find the fix plan as the next incomplete plan.
+
+After execution completes, loop back to show_review (updated diff will reflect fixes).
+
+**If "Stop for now":**
+```
+───────────────────────────────────────────────────────
+
+Fix plan saved. Resume with /specd:feature:continue {feature-name}
+```
+End workflow.
+</step>
+
+<step name="approve_phase">
+Mark phase as completed and advance to next.
+
+**Update config.json:**
+```json
+{
+  "phases": {
+    "current_status": "completed",
+    "completed": {N},
+    "current": {N+1},
+    "phase_start_commit": null
+  }
+}
+```
+
+Then immediately reset for next phase:
+```json
+{
+  "phases": {
+    "current_status": "pending"
+  }
+}
+```
+
+(In practice: increment completed, advance current, set current_status to "pending", remove phase_start_commit.)
+
+**Update STATE.md:**
+Mark phase as complete in execution progress checkboxes.
+
+**Commit state changes:**
+```bash
+git add .specd/features/{feature}/config.json .specd/features/{feature}/STATE.md
+git commit -m "docs({feature}): phase {N} approved — review complete"
+```
+
+**Present:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE {N} COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {N}: {phase-name} approved.
+{If more phases: "Next: Phase {N+1}: {next-phase-name}"}
+{If all phases done: "All phases complete!"}
+```
+
+End workflow (returns to continue-feature which re-reads state).
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Feature selected (from argument or picker)
+- [ ] Phase validated as "executed" status
+- [ ] Git diff shows actual files changed (DEC-012)
+- [ ] Test guidance derived from plan objectives/success criteria
+- [ ] User can approve or request revisions
+- [ ] Fix plans created in decimal-numbered directories (DEC-006, DEC-014)
+- [ ] Fix plan execution loops back to review
+- [ ] Approval updates config.json and STATE.md (DEC-009, DEC-013)
+- [ ] Phase advances only after explicit user approval
+</success_criteria>

package/specdacular/workflows/review-phase.md

@@ -450,37 +450,11 @@ Continue to commit_and_next.
 <step name="commit_and_next">
 Commit review changes and suggest next steps.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature}/STATE.md, DECISIONS.md, CHANGELOG.md, config.json, plans/phase-{NN}/
-```
-
-Then skip ahead to presenting next steps below.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```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}"
-```
+- **$FILES:** `.specd/features/{feature}/STATE.md .specd/features/{feature}/DECISIONS.md .specd/features/{feature}/CHANGELOG.md .specd/features/{feature}/config.json` (+ `plans/phase-{NN}/` if corrective plans generated)
+- **$MESSAGE:** `docs({feature}): review phase {N} (cycle {C})` with review findings and status
+- **$LABEL:** `review results`
 
 **Present next steps:**
 

package/specdacular/workflows/toolbox.md

@@ -0,0 +1,115 @@
+<purpose>
+Menu of advanced feature operations. Presents a picker and dispatches to the appropriate workflow.
+
+**Operations:**
+- Discuss — Explore open questions (feature or phase level)
+- Research — Spawn parallel research agents (feature or phase level)
+- Plan — Create implementation plans (feature or phase level)
+- Review — Review executed work, report issues, generate fix plans
+- Insert phase — Add a new phase with decimal numbering
+
+For discuss, research, and plan: asks scope (whole feature or specific phase) before dispatching.
+</purpose>
+
+<philosophy>
+
+## Thin Dispatcher
+
+This workflow is a menu + dispatcher. It selects a feature, presents operations, asks scope when needed, then hands off to the real workflow. No logic duplication.
+
+## Scope Selection (DEC-007)
+
+Discuss, research, and plan can operate at feature level OR phase level. The toolbox asks which, then routes accordingly.
+
+</philosophy>
+
+<process>
+
+<step name="select_feature">
+@~/.claude/specdacular/references/select-feature.md
+
+Continue to show_menu.
+</step>
+
+<step name="show_menu">
+Present the 5 operations.
+
+Use AskUserQuestion:
+- header: "Toolbox"
+- question: "What would you like to do with {feature-name}?"
+- options:
+  - label: "Discuss"
+    description: "Explore open questions and gray areas about the feature"
+  - label: "Research"
+    description: "Spawn agents to research implementation patterns, libraries, and pitfalls"
+  - label: "Plan"
+    description: "Create phased implementation plans from feature context"
+  - label: "Review"
+    description: "Review executed work — report issues, generate fix plans"
+  - label: "Insert phase"
+    description: "Add a new phase to the roadmap (decimal numbering)"
+
+Route based on selection:
+- Discuss → select_scope (with operation=discuss)
+- Research → select_scope (with operation=research)
+- Plan → select_scope (with operation=plan)
+- Review → dispatch_review
+- Insert phase → dispatch_insert
+</step>
+
+<step name="select_scope">
+Ask scope for discuss/research/plan operations (DEC-007).
+
+Use AskUserQuestion:
+- header: "Scope"
+- question: "Work on the whole feature or a specific phase?"
+- options:
+  - label: "Whole feature"
+    description: "Feature-level {operation}"
+  - label: "Specific phase"
+    description: "Focus on one phase"
+
+**If Whole feature:**
+Route to feature-level workflow:
+- discuss → @~/.claude/specdacular/workflows/discuss-feature.md
+- research → @~/.claude/specdacular/workflows/research-feature.md
+- plan → @~/.claude/specdacular/workflows/plan-feature.md
+
+Pass feature name as argument.
+
+**If Specific phase:**
+@~/.claude/specdacular/references/select-phase.md
+
+Then route to phase-level workflow:
+- discuss → @~/.claude/specdacular/workflows/prepare-phase.md (discussion part)
+- research → @~/.claude/specdacular/workflows/prepare-phase.md (research part)
+- plan → @~/.claude/specdacular/workflows/plan-phase.md
+
+Pass feature name and phase number as arguments.
+</step>
+
+<step name="dispatch_review">
+Execute the review workflow.
+
+@~/.claude/specdacular/workflows/review-feature.md
+
+Pass feature name as argument.
+</step>
+
+<step name="dispatch_insert">
+Execute the insert-phase workflow.
+
+@~/.claude/specdacular/workflows/insert-phase.md
+
+Pass feature name as argument.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Feature selected (from argument or picker)
+- [ ] Menu presented with all 5 operations
+- [ ] Scope selection works for discuss/research/plan (DEC-007)
+- [ ] Routes to correct workflow for each operation
+- [ ] Uses shared references for feature and phase selection (DEC-010)
+</success_criteria>

package/commands/specd/feature/discuss.md

@@ -1,66 +0,0 @@
----
-name: specd:feature:discuss
-description: Continue or deepen feature discussion - can be called multiple times
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<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:**
-- `.specd/features/{name}/CONTEXT.md` — Accumulates resolved questions
-- `.specd/features/{name}/DECISIONS.md` — Accumulates decisions with dates/rationale
-- `.specd/features/{name}/STATE.md` — Tracks discussion progress
-
-**Idempotent:** Calling multiple times builds on previous discussions, doesn't reset.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/discuss-feature.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS
-
-**Load feature context:**
-@.specd/features/{name}/FEATURE.md
-@.specd/features/{name}/CONTEXT.md
-@.specd/features/{name}/DECISIONS.md
-@.specd/features/{name}/STATE.md
-
-**Load codebase context (if available):**
-@.specd/codebase/PATTERNS.md
-@.specd/codebase/STRUCTURE.md
-@.specd/codebase/MAP.md
-</context>
-
-<process>
-1. **Validate** — Check feature exists, has required files
-2. **Load Context** — Read FEATURE.md, CONTEXT.md, DECISIONS.md
-3. **Show Current State** — "Here's what we've discussed so far..."
-4. **Identify Gray Areas** — Based on feature type and existing context
-5. **Let User Select** — Which areas to discuss this session
-6. **Probe Each Area** — Until clear (4 questions, then check)
-7. **Record Decisions** — NEW decisions to DECISIONS.md with date + rationale
-8. **Update CONTEXT.md** — With newly resolved questions
-9. **Present Summary** — Offer next steps
-</process>
-
-<success_criteria>
-- [ ] Feature validated (exists, has required files)
-- [ ] Existing context loaded and summarized
-- [ ] Gray areas identified and presented
-- [ ] User-selected areas discussed
-- [ ] Decisions recorded with date, context, rationale
-- [ ] CONTEXT.md updated with resolved questions
-- [ ] User knows options: discuss more, research, or plan
-</success_criteria>

package/commands/specd/feature/plan.md

@@ -1,68 +0,0 @@
----
-name: specd:feature:plan
-description: Create roadmap with phase overview (no detailed plans)
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<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:**
-- `.specd/features/{name}/ROADMAP.md` — Phase overview with goals, deliverables, dependencies
-- `.specd/features/{name}/plans/phase-{NN}/` — Empty phase directories
-
-**Does NOT create PLAN.md files.** Those are created just-in-time with `/specd:phase:plan` before executing each phase.
-
-**Prerequisite:** Feature should have sufficient discussion context (FEATURE.md, CONTEXT.md, DECISIONS.md). Research (RESEARCH.md) recommended but optional.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/plan-feature.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS
-
-**Load ALL feature context:**
-@.specd/features/{name}/FEATURE.md — Technical requirements
-@.specd/features/{name}/CONTEXT.md — Resolved gray areas
-@.specd/features/{name}/DECISIONS.md — Implementation decisions
-@.specd/features/{name}/RESEARCH.md — Research findings (if exists)
-
-**Load codebase context:**
-@.specd/codebase/PATTERNS.md — Code patterns to follow
-@.specd/codebase/STRUCTURE.md — Where files go
-@.specd/codebase/MAP.md — System overview
-</context>
-
-<process>
-1. **Validate** — Check feature exists, has required context
-2. **Load Context** — Read ALL feature and codebase docs
-3. **Assess Readiness** — Check if enough context to plan
-4. **Derive Phases** — Based on dependencies (types->API->UI pattern)
-5. **Write ROADMAP.md** — Phase overview with goals, deliverables, dependencies
-6. **Create Phase Directories** — Empty `plans/phase-{NN}/` directories
-7. **Update STATE.md** — Stage moves to "planned"
-8. **Commit and Present**
-</process>
-
-<success_criteria>
-- [ ] Feature validated with sufficient context
-- [ ] All context loaded (feature, codebase, research)
-- [ ] Phases derived from dependency analysis
-- [ ] ROADMAP.md provides clear phase overview
-- [ ] Empty phase directories created
-- [ ] No PLAN.md files created (that's `/specd:phase:plan`)
-- [ ] STATE.md updated to "planned" stage
-- [ ] Committed to git
-- [ ] User knows next step: `/specd:phase:prepare` or `/specd:phase:plan` for first phase
-</success_criteria>