specdacular 0.2.5 → 0.5.1

package/README.md

@@ -28,19 +28,12 @@ Spawns 4 parallel agents to analyze your codebase and generate AI-optimized docu
 A structured flow for planning features with enough detail for agent implementation:
 
 ```
-new-feature → discuss-feature → plan-feature →
-  (discuss-phase? → research-phase? → execute-plan)* per phase
+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
 ```
 
-**You control the rhythm:**
-- `new-feature` — Initialize and start first discussion
-- `discuss-feature` — Refine understanding (call many times)
-- `research-feature` — Investigate implementation approaches
-- `plan-feature` — Create executable task plans
-- `discuss-phase` — Optional: dive into phase specifics before execution
-- `research-phase` — Optional: research patterns for a specific phase
-- `execute-plan` — Execute plans with progress tracking
-
 ---
 
 ## Installation
@@ -64,28 +57,43 @@ 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 Planning
+### 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:new-feature [name]` | Initialize a feature, start first discussion |
-| `/specd:discuss-feature [name]` | Continue/deepen discussion (iterative) |
-| `/specd:research-feature [name]` | Research implementation with parallel agents |
-| `/specd:plan-feature [name]` | Create executable task plans |
-| `/specd:discuss-phase [feature] [phase]` | Discuss a phase before execution |
-| `/specd:research-phase [feature] [phase]` | Research patterns for a phase |
-| `/specd:execute-plan [feature]` | Execute plans with progress tracking |
+| `/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 |
 
@@ -99,36 +107,111 @@ 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:new-feature user-dashboard
+/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**
+
+```
+/specd:feature:discuss user-dashboard    # Clarify gray areas (call many times)
+/specd:feature:research user-dashboard   # Research implementation approaches
+```
+
+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
+```
+
+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**
 
-Then refine and plan:
 ```
-/specd:discuss-feature user-dashboard    # Clarify gray areas
-/specd:research-feature user-dashboard   # Research implementation
-/specd:plan-feature user-dashboard       # Create executable plans
+/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
 ```
 
-Optionally, before executing each phase:
+Repeat for each phase. Plans are created just-in-time so they stay fresh.
+
+**Mid-flight adjustments:**
+
 ```
-/specd:discuss-phase user-dashboard 1    # Discuss phase 1 specifics
-/specd:research-phase user-dashboard 1   # Research phase 1 patterns
-/specd:execute-plan user-dashboard       # Execute with phase context
+/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: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
@@ -158,49 +241,49 @@ Specdacular spawns specialized agents that run simultaneously:
 
 ### Feature Flow
 
-The feature planning flow accumulates context over multiple sessions:
-
 ```
 ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│ new-feature  │ ──▶ │   discuss    │ ◀─▶ │   research   │
-│              │     │   feature    │     │   feature    │
+│  feature:new │ ──▶ │   feature:   │ ◀─▶ │   feature:   │
+│              │     │   discuss    │     │   research   │
 └──────────────┘     └──────────────┘     └──────────────┘
                             │
                             ▼
                      ┌──────────────┐
-                     │ plan-feature │
+                     │  feature:plan│ (creates roadmap)
                      └──────────────┘
                             │
                             ▼
               ┌─────────────────────────────┐
               │     For each phase:         │
-              │  ┌─────────┐   ┌─────────┐  │
-              │  │ discuss │ → │research │  │
-              │  │  phase  │   │  phase  │  │
-              │  └─────────┘   └─────────┘  │
-              │         │           │       │
-              │         └─────┬─────┘       │
-              │               ▼             │
-              │        ┌────────────┐       │
-              │        │execute-plan│       │
-              │        └────────────┘       │
+              │  ┌──────────┐               │
+              │  │  phase:  │               │
+              │  │ prepare  │               │
+              │  └──────────┘               │
+              │       │                     │
+              │       ▼                     │
+              │  ┌──────────┐               │
+              │  │  phase:  │               │
+              │  │   plan   │               │
+              │  └──────────┘               │
+              │       │                     │
+              │       ▼                     │
+              │  ┌──────────┐               │
+              │  │  phase:  │               │
+              │  │ execute  │               │
+              │  └──────────┘               │
+              │                             │
+              │  Mid-flight adjustments:    │
+              │  ┌──────────┐               │
+              │  │  phase:  │ ──┐           │
+              │  │  insert  │   │           │
+              │  └──────────┘   │           │
+              │          ┌──────▼────────┐  │
+              │          │    phase:     │  │
+              │          │   renumber   │  │
+              │          └──────────────┘  │
               └─────────────────────────────┘
 ```
 
-Each session updates:
-- `CONTEXT.md` — Resolved questions accumulate
-- `DECISIONS.md` — Decisions with rationale accumulate
-
-**Phase-level commands** (optional but powerful):
-- `discuss-phase` — Just-in-time clarification for a specific phase
-- `research-phase` — Focused research for phase-specific patterns
-
-Plans are prompts for implementing agents with:
-- Specific file paths
-- Code patterns to follow
-- Verification commands
-- Clear completion criteria
-
 ---
 
 ## Project Structure
@@ -223,12 +306,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 (optional)
-│               │   ├── RESEARCH.md  # Phase research (optional)
-│               │   ├── 01-PLAN.md
+│               │   ├── 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)
 │               │   └── 02-PLAN.md
 │               └── phase-02/
 │                   ├── CONTEXT.md
@@ -255,12 +338,47 @@ These docs answer questions Claude can't get from reading code:
 
 Each `PLAN.md` is literally what you'd send to an implementing agent. It contains everything needed to implement without asking questions.
 
+### Just-in-Time Planning
+
+Detailed plans are created per-phase, not all at once. This keeps plans fresh — earlier phases inform later ones, and context doesn't go stale.
+
 ### Decisions Are Permanent
 
 Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, context, rationale, and implications.
 
 ---
 
+## 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/blueprint.md

@@ -0,0 +1,64 @@
+---
+name: specd:blueprint
+description: Generate visual blueprint for a feature
+argument-hint: "[feature-name] [wireframes|diagrams]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Generate a visual HTML blueprint for exploring feature artifacts.
+
+**Base command:** `/specd:blueprint {feature}`
+- Creates `.specd/features/{feature}/blueprint/index.html`
+- Shows Overview, Decisions, Context, Plans tabs
+- Opens in browser
+
+**Subcommands:**
+- `/specd:blueprint {feature} wireframes` — Add wireframes tab
+- `/specd:blueprint {feature} diagrams` — Add diagrams tab with Mermaid
+
+**Output:** Self-contained HTML file that opens in browser. Regenerate to update.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/blueprint.md
+</execution_context>
+
+<context>
+Feature name: First argument ($ARGUMENTS before space)
+Subcommand: Second argument (wireframes, diagrams, or empty)
+
+**Load feature context:**
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/CONTEXT.md
+@.specd/features/{name}/DECISIONS.md
+@.specd/features/{name}/plans/ (if exists)
+
+**Load codebase context (if available):**
+@.specd/codebase/PATTERNS.md
+</context>
+
+<process>
+1. **Parse Arguments** — Extract feature name and optional subcommand
+2. **Validate** — Check feature exists with required files
+3. **Route Subcommand:**
+   - No subcommand → Generate base blueprint
+   - `wireframes` → Generate/update with wireframes tab
+   - `diagrams` → Generate/update with diagrams tab
+4. **Generate HTML** — Read files, parse content, embed in template
+5. **Open Browser** — Run `open` command to display
+</process>
+
+<success_criteria>
+- [ ] Feature validated (exists, has FEATURE.md, CONTEXT.md, DECISIONS.md)
+- [ ] HTML generated at `.specd/features/{name}/blueprint/index.html`
+- [ ] All content properly embedded (decisions, context, plans if exist)
+- [ ] Browser opens with the blueprint
+- [ ] Wireframes/Diagrams tabs enabled if generated
+</success_criteria>

package/commands/specd/{discuss-feature.md → feature/discuss.md}

@@ -1,5 +1,5 @@
 ---
-name: specd:discuss-feature
+name: specd:feature:discuss
 description: Continue or deepen feature discussion - can be called multiple times
 argument-hint: "[feature-name]"
 allowed-tools:

package/commands/specd/{new-feature.md → feature/new.md}

@@ -1,6 +1,6 @@
 ---
-name: specd:new-feature
-description: Initialize a new feature with technical questioning and start the first discussion
+name: specd:feature:new
+description: Initialize a new feature and start the first discussion
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -63,5 +63,5 @@ Feature name: $ARGUMENTS
 - [ ] STATE.md tracks current position
 - [ ] config.json created
 - [ ] Committed to git
-- [ ] User knows next options: discuss-feature, research-feature, or continue talking
+- [ ] User knows next options: `/specd:feature:discuss`, `/specd:feature:research`, or continue talking
 </success_criteria>

package/commands/specd/{plan-feature.md → feature/plan.md}

@@ -1,6 +1,6 @@
 ---
-name: specd:plan-feature
-description: Create executable task plans for implementing a feature
+name: specd:feature:plan
+description: Create roadmap with phase overview (no detailed plans)
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -12,17 +12,13 @@ allowed-tools:
 ---
 
 <objective>
-Create executable task plans that an agent can implement without asking clarifying questions.
+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 dependencies
-- `.specd/features/{name}/plans/phase-{NN}/{NN}-PLAN.md` — Executable task plans
+- `.specd/features/{name}/ROADMAP.md` — Phase overview with goals, deliverables, dependencies
+- `.specd/features/{name}/plans/phase-{NN}/` — Empty phase directories
 
-**Each PLAN.md is a prompt** for an implementing agent with:
-- Files to create/modify with specific paths
-- Code patterns to follow (from codebase)
-- Verification commands
-- Clear completion criteria
+**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>
@@ -50,10 +46,10 @@ Feature name: $ARGUMENTS
 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. **Break Into Tasks** — 2-3 tasks per plan, sized for agent execution
-6. **Write PLAN Files** — As prompts for implementing agent
-7. **Write ROADMAP.md** — Phase overview
+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>
 
@@ -61,9 +57,10 @@ Feature name: $ARGUMENTS
 - [ ] Feature validated with sufficient context
 - [ ] All context loaded (feature, codebase, research)
 - [ ] Phases derived from dependency analysis
-- [ ] Tasks are specific (files, actions, verification)
-- [ ] PLAN.md files are self-contained prompts
-- [ ] ROADMAP.md provides clear overview
+- [ ] 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 how to execute plans
+- [ ] User knows next step: `/specd:phase:prepare` or `/specd:phase:plan` for first phase
 </success_criteria>

package/commands/specd/{research-feature.md → feature/research.md}

@@ -1,5 +1,5 @@
 ---
-name: specd:research-feature
+name: specd:feature:research
 description: Research how to implement a feature - spawns parallel agents for codebase, external, and pitfalls research
 argument-hint: "[feature-name]"
 allowed-tools:
@@ -48,7 +48,7 @@ Feature name: $ARGUMENTS
 
 ```bash
 # Check feature exists
-[ -d ".specd/features/$ARGUMENTS" ] || { echo "Feature not found. Run /specd:new-feature first."; exit 1; }
+[ -d ".specd/features/$ARGUMENTS" ] || { echo "Feature not found. Run /specd:feature:new first."; exit 1; }
 
 # Check if RESEARCH.md exists
 [ -f ".specd/features/$ARGUMENTS/RESEARCH.md" ] && echo "existing"
@@ -419,7 +419,7 @@ Present completion:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Feature:** {name}
 **Confidence:** {level}
@@ -437,7 +437,7 @@ Present completion:
 
 ## Next Steps
 
-/specd:plan-feature {name} — Create executable task plans
+/specd:feature:plan {name} — Create roadmap with phase overview
 
 <sub>/clear first — fresh context window</sub>
 ```
@@ -453,5 +453,5 @@ Present completion:
 - [ ] Results synthesized into RESEARCH.md
 - [ ] Decisions recorded in DECISIONS.md
 - [ ] Files committed
-- [ ] User knows next step is /specd:plan-feature
+- [ ] User knows next step is `/specd:feature:plan`
 </success_criteria>