specdacular 0.2.3 → 0.5.0

package/README.md

@@ -28,14 +28,22 @@ 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 ↔ research)* → plan-feature
+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
+- `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
 
 ---
 
@@ -66,19 +74,31 @@ In Claude Code:
 |---------|-------------|
 | `/specd:map-codebase` | Analyze codebase with parallel agents |
 
-### Feature Planning
+### Feature Commands
 
 | 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:feature:new [name]` | Initialize a feature, start first discussion |
+| `/specd:feature:discuss [name]` | Continue/deepen discussion (iterative) |
+| `/specd:feature:research [name]` | Research implementation with parallel agents |
+| `/specd:feature:plan [name]` | Create roadmap with phase overview |
+
+### Phase Commands
+
+| Command | Description |
+|---------|-------------|
+| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
+| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
+| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
+| `/specd:phase:execute [feature]` | Execute plans with progress tracking |
+| `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
+| `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
 
 ### Utilities
 
 | Command | Description |
 |---------|-------------|
+| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
 | `/specd:help` | Show available commands |
 | `/specd:update` | Update to latest version |
 
@@ -97,7 +117,7 @@ Creates `.specd/codebase/` with 4 AI-optimized documents.
 ### Plan a Feature
 
 ```
-/specd:new-feature user-dashboard
+/specd:feature:new user-dashboard
 ```
 
 Creates `.specd/features/user-dashboard/` with:
@@ -106,11 +126,18 @@ Creates `.specd/features/user-dashboard/` with:
 - `DECISIONS.md` — Decisions with dates and rationale
 - `STATE.md` — Progress tracking
 
-Then refine and plan:
+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
+```
+
+Then for each phase, prepare, plan, and execute:
 ```
-/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 + optionally research
+/specd:phase:plan user-dashboard 1       # Create detailed task plans
+/specd:phase:execute user-dashboard      # Execute with progress tracking
 ```
 
 ---
@@ -148,25 +175,58 @@ 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)
                      └──────────────┘
                             │
                             ▼
-                     Executable PLAN.md
-                     files for agents
+              ┌─────────────────────────────┐
+              │     For each phase:         │
+              │  ┌──────────┐               │
+              │  │  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:**
+- `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
@@ -191,16 +251,20 @@ your-project/
 │   └── features/              # From feature commands
 │       └── user-dashboard/
 │           ├── FEATURE.md     # Technical requirements
-│           ├── CONTEXT.md     # Discussion context
-│           ├── DECISIONS.md   # Decision log
+│           ├── CONTEXT.md     # Feature-level discussion
+│           ├── DECISIONS.md   # Decision log (feature + phase)
 │           ├── STATE.md       # Progress tracking
-│           ├── RESEARCH.md    # Research findings
+│           ├── RESEARCH.md    # Feature-level research
 │           ├── ROADMAP.md     # Phase overview
 │           └── plans/         # Executable plans
 │               ├── phase-01/
-│               │   ├── 01-PLAN.md
+│               │   ├── CONTEXT.md   # Phase discussion (from phase:prepare)
+│               │   ├── RESEARCH.md  # Phase research (from phase:prepare or phase:research)
+│               │   ├── 01-PLAN.md   # From phase:plan
 │               │   └── 02-PLAN.md
 │               └── phase-02/
+│                   ├── CONTEXT.md
+│                   ├── RESEARCH.md
 │                   └── 01-PLAN.md
 └── ...
 ```
@@ -223,6 +287,10 @@ 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.

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>

package/commands/specd/help.md

@@ -20,22 +20,33 @@ Display available specdacular commands and usage guidance.
 
 | Command | Description |
 |---------|-------------|
-| `/specd:map-codebase` | Analyze codebase with parallel agents → produce AI-optimized docs |
+| `/specd:map-codebase` | Analyze codebase with parallel agents -> produce AI-optimized docs |
 
-### Feature Flow
+### Feature Commands
 
 | Command | Description |
 |---------|-------------|
-| `/specd:new-feature [name]` | Initialize a feature, start first discussion |
-| `/specd:discuss-feature [name]` | Continue/deepen feature discussion (can call many times) |
-| `/specd:research-feature [name]` | Research implementation with parallel agents |
-| `/specd:plan-feature [name]` | Create executable task plans for agents |
-| `/specd:execute-plan [feature] [plan]` | Execute a plan with progress tracking |
+| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
+| `/specd:feature:discuss [name]` | Continue/deepen feature discussion (can call many times) |
+| `/specd:feature:research [name]` | Research implementation with parallel agents |
+| `/specd:feature:plan [name]` | Create roadmap with phase overview |
 
-### Utilities
+### Phase Commands
 
 | Command | Description |
 |---------|-------------|
+| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
+| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
+| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
+| `/specd:phase:execute [feature] [plan]` | Execute a plan 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 |
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
 | `/specd:update` | Update Specdacular to the latest version |
 | `/specd:help` | Show this help |
 
@@ -46,20 +57,27 @@ Display available specdacular commands and usage guidance.
 The feature flow helps you plan features specific enough that an agent can implement without asking questions.
 
 ```
-new-feature → (discuss ↔ research)* → plan-feature → execute-plan*
+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` — Creates structure, asks initial questions, starts first discussion
-- `discuss-feature` — Can be called **many times** to refine understanding
-- `research-feature` — Can be called **many times** to investigate
-- `plan-feature` — When satisfied, creates executable plans for an agent
-- `execute-plan` — Execute plans with progress tracking and deviation logging
+- `feature:new` — Creates structure, asks initial questions, starts first discussion
+- `feature:discuss` — Can be called **many times** to refine understanding
+- `feature:research` — Can be called **many times** to investigate
+- `feature:plan` — Creates roadmap with phases (no detailed plans yet)
+- `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:insert` — Insert a new phase mid-flight with decimal numbering (e.g., Phase 3.1)
+- `phase:renumber` — Clean up decimal phases to sequential integers
 
 ### Quick Start
 
 ```
-/specd:new-feature user-dashboard
+/specd:feature:new user-dashboard
 ```
 
 This creates `.specd/features/user-dashboard/` with:
@@ -69,12 +87,20 @@ This creates `.specd/features/user-dashboard/` with:
 - `CHANGELOG.md` — Auto-captured implementation decisions during execution
 - `STATE.md` — Progress tracking
 
-After initialization, refine with discussion and research, then create plans:
+After initialization, refine and plan:
+
+```
+/specd:feature:discuss user-dashboard    # Clarify gray areas
+/specd:feature:research user-dashboard   # Research implementation
+/specd:feature:plan user-dashboard       # Create roadmap
+```
+
+Then for each phase:
 
 ```
-/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 + optionally research
+/specd:phase:plan user-dashboard 1       # Create detailed plans
+/specd:phase:execute user-dashboard      # Execute with progress tracking
 ```
 
 ---
@@ -99,10 +125,10 @@ Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`
 These docs are **for Claude, not humans**.
 
 Each document answers a question Claude can't get from reading code:
-- MAP.md → "Where is X? What functions exist?"
-- PATTERNS.md → "How do I write code that fits?"
-- STRUCTURE.md → "Where do I put new code?"
-- CONCERNS.md → "What will bite me?"
+- MAP.md -> "Where is X? What functions exist?"
+- PATTERNS.md -> "How do I write code that fits?"
+- STRUCTURE.md -> "Where do I put new code?"
+- CONCERNS.md -> "What will bite me?"
 
 **Principle:** Don't document what Claude can grep. Document tribal knowledge, gotchas, and patterns.
 
@@ -110,7 +136,7 @@ Each document answers a question Claude can't get from reading code:
 
 ## Updating
 
-When an update is available, you'll see `⬆ /specd:update` in your statusline. Run:
+When an update is available, you'll see `update available` in your statusline. Run:
 ```
 /specd:update
 ```

package/commands/specd/{execute-plan.md → phase/execute.md}

@@ -1,5 +1,5 @@
 ---
-name: specd:execute-plan
+name: specd:phase:execute
 description: Execute a feature plan with progress tracking
 argument-hint: "[feature-name] [plan-path]"
 allowed-tools:
@@ -19,10 +19,10 @@ Execute a plan from a feature, tracking progress and logging deviations.
 1. Load context — STATE.md, DECISIONS.md, RESEARCH.md, codebase patterns
 2. Find next plan — First incomplete plan, or accept path as argument
 3. Execute tasks with:
-   - Auto-fix blockers/bugs → log to CHANGELOG.md
-   - Ask about architectural changes → wait for user
+   - Auto-fix blockers/bugs -> log to CHANGELOG.md
+   - Ask about architectural changes -> wait for user
    - Run verification after each task
-   - Stop on verification failure → ask user (retry/skip/stop)
+   - Stop on verification failure -> ask user (retry/skip/stop)
    - Commit after each task
 4. Update progress — STATE.md with completed tasks
 5. Suggest next — Next plan to execute

package/commands/specd/phase/insert.md

@@ -0,0 +1,62 @@
+---
+name: specd:phase:insert
+description: Insert a new phase after an existing one (decimal numbering)
+argument-hint: "[feature-name] [after-phase] [description...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Insert a new phase after an existing one using decimal numbering (e.g., Phase 03.1 after Phase 03).
+
+**What it does:**
+1. Parse arguments — feature name, target phase number, description
+2. Validate — Feature exists, ROADMAP.md exists, target phase exists
+3. Find next decimal — Scan existing decimals, calculate next (03.1, 03.2, etc.)
+4. Create phase directory — `plans/phase-{NN.M}/`
+5. Update ROADMAP.md — Insert new phase section with `(INSERTED)` marker
+6. Update STATE.md — Add roadmap evolution note, add unchecked phase checkbox
+7. Update config.json — Increment `phases_count`
+8. Show next steps
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/insert-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (expects: feature-name after-phase description...)
+
+**Load feature context:**
+@.specd/features/{name}/ROADMAP.md
+@.specd/features/{name}/STATE.md
+@.specd/features/{name}/config.json
+</context>
+
+<process>
+1. **Parse Arguments** — Extract feature-name, after-phase (integer), description
+2. **Validate** — Feature exists, ROADMAP.md exists, target phase exists
+3. **Find Next Decimal** — Scan for existing decimal directories, calculate next
+4. **Create Phase Directory** — `plans/phase-{NN.M}/`
+5. **Update ROADMAP.md** — Insert after target phase with `(INSERTED)` marker
+6. **Update STATE.md** — Add evolution note and unchecked checkbox
+7. **Update config.json** — Increment `phases_count`
+8. **Completion** — Show summary with next steps
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly (feature, phase number, description)
+- [ ] Feature and target phase validated
+- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] Phase directory created: `plans/phase-{NN.M}/`
+- [ ] ROADMAP.md updated with new phase entry (includes `(INSERTED)` marker)
+- [ ] Phase inserted in correct position (after target phase, before next phase)
+- [ ] STATE.md updated with roadmap evolution note and unchecked checkbox
+- [ ] config.json `phases_count` incremented
+- [ ] User informed of next steps
+</success_criteria>