specdacular 0.2.2 → 0.2.3

package/README.md

@@ -1,8 +1,8 @@
 # Specdacular
 
-**Feature planning for existing codebases.**
+**AI-optimized codebase documentation and feature planning for Claude.**
 
-A Claude Code extension that analyzes your codebase and generates structured documentation. Understand any codebase before planning new features.
+A Claude Code extension that helps you understand codebases and plan features specific enough that an agent can implement without asking questions.
 
 ```bash
 npx specdacular
@@ -12,19 +12,30 @@ npx specdacular
 
 ## What It Does
 
-Specdacular spawns 4 parallel AI agents to analyze your codebase and generate 7 structured documents:
+### 1. Map Your Codebase
+
+Spawns 4 parallel agents to analyze your codebase and generate AI-optimized documentation:
 
 | Document | What It Answers |
 |----------|-----------------|
-| `STACK.md` | What languages, frameworks, dependencies? |
-| `ARCHITECTURE.md` | What patterns? How does data flow? |
-| `STRUCTURE.md` | Where do files go? How is it organized? |
-| `CONVENTIONS.md` | How should code be written? Naming? Style? |
-| `TESTING.md` | How are tests structured? What to mock? |
-| `INTEGRATIONS.md` | What external services (DB, APIs, auth)? |
-| `CONCERNS.md` | What's broken? Tech debt? Risks? |
+| `MAP.md` | Where is X? What functions exist? |
+| `PATTERNS.md` | How do I write code that fits here? |
+| `STRUCTURE.md` | Where do I put new code? |
+| `CONCERNS.md` | What will bite me? Gotchas? Tech debt? |
+
+### 2. Plan Features
+
+A structured flow for planning features with enough detail for agent implementation:
+
+```
+new-feature → (discuss ↔ research)* → plan-feature
+```
 
-Output goes to `.specd/codebase/` in your project.
+**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
 
 ---
 
@@ -35,8 +46,8 @@ npx specdacular
 ```
 
 Choose:
-- **Global** (`~/.claude/`) - Available in all projects
-- **Local** (`./.claude/`) - This project only
+- **Global** (`~/.claude/`) — Available in all projects
+- **Local** (`./.claude/`) — This project only
 
 ### Verify Installation
 
@@ -47,36 +58,60 @@ In Claude Code:
 
 ---
 
-## Usage
+## Commands
+
+### Codebase Documentation
 
-### Map Your Codebase
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents |
+
+### Feature Planning
+
+| 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 |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/specd:help` | Show available commands |
+| `/specd:update` | Update to latest version |
+
+---
+
+## Quick Start
+
+### Map a Codebase
 
 ```
 /specd:map-codebase
 ```
 
-This:
-1. Creates `.specd/codebase/` directory
-2. Spawns 4 parallel agents (tech, architecture, quality, concerns)
-3. Each agent explores and writes documents directly
-4. Commits the codebase map
+Creates `.specd/codebase/` with 4 AI-optimized documents.
 
-### Review Generated Docs
+### Plan a Feature
 
-```bash
-cat .specd/codebase/STACK.md
-cat .specd/codebase/ARCHITECTURE.md
-# etc.
+```
+/specd:new-feature user-dashboard
 ```
 
----
-
-## Commands
+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
 
-| Command | Description |
-|---------|-------------|
-| `/specd:map-codebase` | Analyze codebase and generate documentation |
-| `/specd:help` | Show available commands |
+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
+```
 
 ---
 
@@ -84,7 +119,7 @@ cat .specd/codebase/ARCHITECTURE.md
 
 ### Parallel Agents
 
-Instead of one agent doing everything, Specdacular spawns 4 specialized agents that run simultaneously:
+Specdacular spawns specialized agents that run simultaneously:
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -94,58 +129,127 @@ Instead of one agent doing everything, Specdacular spawns 4 specialized agents t
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼               ▼
     ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-    │   Tech   │   │   Arch   │   │ Quality  │   │ Concerns │
+    │   Map    │   │ Patterns │   │Structure │   │ Concerns │
     │  Agent   │   │  Agent   │   │  Agent   │   │  Agent   │
     └──────────┘   └──────────┘   └──────────┘   └──────────┘
           │               │               │               │
           ▼               ▼               ▼               ▼
-     STACK.md        ARCH.md         CONV.md        CONCERNS.md
-     INTEG.md       STRUCT.md       TESTING.md
+      MAP.md       PATTERNS.md     STRUCTURE.md    CONCERNS.md
 ```
 
 **Benefits:**
 - Fresh 200k context per agent (no token pollution)
 - Faster execution (parallel, not sequential)
-- Agents write directly to files (minimal context transfer)
+- Agents write directly to files
 
----
+### Feature Flow
 
-## Updating
+The feature planning flow accumulates context over multiple sessions:
 
-```bash
-npx specdacular@latest
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│ new-feature  │ ──▶ │   discuss    │ ◀─▶ │   research   │
+│              │     │   feature    │     │   feature    │
+└──────────────┘     └──────────────┘     └──────────────┘
+                            │
+                            ▼
+                     ┌──────────────┐
+                     │ plan-feature │
+                     │              │
+                     └──────────────┘
+                            │
+                            ▼
+                     Executable PLAN.md
+                     files for agents
 ```
 
-## Uninstalling
+Each session updates:
+- `CONTEXT.md` — Resolved questions accumulate
+- `DECISIONS.md` — Decisions with rationale accumulate
 
-```bash
-npx specdacular --global --uninstall
-# or
-npx specdacular --local --uninstall
-```
+Plans are prompts for implementing agents with:
+- Specific file paths
+- Code patterns to follow
+- Verification commands
+- Clear completion criteria
 
 ---
 
 ## Project Structure
 
-After running `/specd:map-codebase`:
+After using Specdacular:
 
 ```
 your-project/
 ├── .specd/
-│   └── codebase/
-│       ├── STACK.md
-│       ├── ARCHITECTURE.md
-│       ├── STRUCTURE.md
-│       ├── CONVENTIONS.md
-│       ├── TESTING.md
-│       ├── INTEGRATIONS.md
-│       └── CONCERNS.md
+│   ├── codebase/              # From /specd:map-codebase
+│   │   ├── MAP.md
+│   │   ├── PATTERNS.md
+│   │   ├── STRUCTURE.md
+│   │   └── CONCERNS.md
+│   │
+│   └── features/              # From feature commands
+│       └── user-dashboard/
+│           ├── FEATURE.md     # Technical requirements
+│           ├── CONTEXT.md     # Discussion context
+│           ├── DECISIONS.md   # Decision log
+│           ├── STATE.md       # Progress tracking
+│           ├── RESEARCH.md    # Research findings
+│           ├── ROADMAP.md     # Phase overview
+│           └── plans/         # Executable plans
+│               ├── phase-01/
+│               │   ├── 01-PLAN.md
+│               │   └── 02-PLAN.md
+│               └── phase-02/
+│                   └── 01-PLAN.md
 └── ...
 ```
 
 ---
 
+## Philosophy
+
+### Documentation Is For Claude
+
+These docs answer questions Claude can't get from reading code:
+- Tribal knowledge
+- Gotchas and pitfalls
+- Patterns and conventions
+- Where things go
+
+**Principle:** Don't document what Claude can grep. Document what requires understanding.
+
+### Plans Are Prompts
+
+Each `PLAN.md` is literally what you'd send to an implementing agent. It contains everything needed to implement without asking questions.
+
+### Decisions Are Permanent
+
+Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, context, rationale, and implications.
+
+---
+
+## Updating
+
+```bash
+npx specdacular@latest
+```
+
+Or in Claude Code:
+```
+/specd:update
+```
+
+## Uninstalling
+
+```bash
+npx specdacular --global --uninstall
+# or
+npx specdacular --local --uninstall
+```
+
+---
+
 ## License
 
 MIT

package/commands/specd/execute-plan.md

@@ -0,0 +1,68 @@
+---
+name: specd:execute-plan
+description: Execute a feature plan with progress tracking
+argument-hint: "[feature-name] [plan-path]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Execute a plan from a feature, tracking progress and logging deviations.
+
+**What it does:**
+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
+   - Run verification after each task
+   - 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
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/execute-plan.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS (first argument)
+Plan path: $ARGUMENTS (optional second argument)
+
+**Load ALL feature context:**
+@.specd/features/{name}/STATE.md — Progress tracking
+@.specd/features/{name}/DECISIONS.md — Constraints to follow
+@.specd/features/{name}/RESEARCH.md — Implementation notes (if exists)
+@.specd/features/{name}/ROADMAP.md — Phase overview
+
+**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 with plans
+2. **Load Context** — Read all feature and codebase docs
+3. **Find Plan** — Next incomplete or specified plan
+4. **Execute Tasks** — With verification and deviation handling
+5. **Complete Plan** — Update STATE.md, suggest next
+</process>
+
+<success_criteria>
+- [ ] Feature validated with plans
+- [ ] Context loaded (feature, codebase)
+- [ ] Tasks executed in order
+- [ ] Verification run after each task
+- [ ] Deviations logged to CHANGELOG.md
+- [ ] STATE.md updated with progress
+- [ ] Commits made after each task
+- [ ] Next plan suggested
+</success_criteria>

package/commands/specd/help.md

@@ -30,6 +30,7 @@ Display available specdacular commands and usage guidance.
 | `/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 |
 
 ### Utilities
 
@@ -45,7 +46,7 @@ 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
+new-feature → (discuss ↔ research)* → plan-feature → execute-plan*
 ```
 
 **You control the rhythm:**
@@ -53,6 +54,7 @@ new-feature → (discuss ↔ research)* → plan-feature
 - `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
 
 ### Quick Start
 
@@ -63,7 +65,8 @@ new-feature → (discuss ↔ research)* → plan-feature
 This creates `.specd/features/user-dashboard/` with:
 - `FEATURE.md` — Technical requirements
 - `CONTEXT.md` — Discussion context (accumulates)
-- `DECISIONS.md` — Decisions with dates and rationale
+- `DECISIONS.md` — User-driven decisions with dates and rationale
+- `CHANGELOG.md` — Auto-captured implementation decisions during execution
 - `STATE.md` — Progress tracking
 
 After initialization, refine with discussion and research, then create plans:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.2.2",
+  "version": "0.2.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/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog: {feature-name}
+
+Implementation log - auto-captured decisions and deviations during execution.
+
+---
+
+## Phase 1: {Phase Name}
+
+### {YYYY-MM-DD} - Plan 01
+
+**{Brief title}**
+- **What:** {What was decided/changed}
+- **Why:** {Reason}
+- **Files:** `{path/to/file}`
+
+---
+
+**{Another decision}**
+- **What:** {Description}
+- **Why:** {Reason}
+
+---
+
+## Compacted Summary
+
+{Space for human review - summarize key decisions after implementation}
+
+---
+
+## Notes
+
+- Entries are auto-captured by executing agent
+- Review after each phase to extract important decisions
+- Move significant decisions to DECISIONS.md if needed

package/specdacular/templates/features/PLAN.md

@@ -148,6 +148,33 @@ When this plan is complete:
 
 ---
 
+## Implementation Log
+
+During implementation, capture decisions and deviations to `.specd/features/{feature-name}/CHANGELOG.md`.
+
+**When to log:**
+- Choosing a different approach than specified
+- Adding functionality not in the plan
+- Skipping or modifying a task
+- Discovering issues that change the approach
+
+**Format:**
+```markdown
+### {YYYY-MM-DD} - Plan {NN}
+
+**{Brief title}**
+- **What:** {What you decided/changed}
+- **Why:** {Reason for the change}
+- **Files:** `{affected files}`
+```
+
+**Don't log:**
+- Minor implementation details
+- Standard coding patterns
+- Things working as planned
+
+---
+
 ## Notes
 
 {Space for the implementing agent to record discoveries, blockers, or decisions made during implementation. Leave empty in template.}

package/specdacular/templates/features/STATE.md

@@ -28,6 +28,19 @@
 
 ---
 
+## Execution Progress
+
+### Current Plan
+- Plan: none
+- Task: —
+- Started: —
+
+### Completed Plans
+| Plan | Completed | Tasks | Deviations |
+|------|-----------|-------|------------|
+
+---
+
 ## Discussion Sessions
 
 | Date | Focus | Outcome |
@@ -65,6 +78,7 @@
 - `/specd:discuss-feature {feature-name}` — Continue refining understanding
 - `/specd:research-feature {feature-name}` — Research implementation approach
 - `/specd:plan-feature {feature-name}` — Create executable plans (when ready)
+- `/specd:execute-plan {feature-name}` — Execute plans with progress tracking
 
 ---
 

package/specdacular/workflows/execute-plan.md

@@ -0,0 +1,395 @@
+<purpose>
+Execute a plan from a feature, tracking progress and logging deviations.
+
+**Key principles:**
+- Execute tasks in order with verification
+- Auto-fix bugs/blockers, log to CHANGELOG.md
+- Ask before architectural changes
+- Stop on verification failure, let user decide
+- Commit after each successful task
+
+**Output:** Completed tasks, updated STATE.md, CHANGELOG.md entries
+</purpose>
+
+<philosophy>
+
+## Deviations Are Normal
+
+Plans are written in advance. Reality differs. The goal is controlled deviation:
+- Small fixes: Just do it, log it
+- Big changes: Ask first
+
+## Auto-fix vs Ask First
+
+**Auto-fix (log to CHANGELOG.md):**
+- Bugs — Code doesn't work, logic errors, crashes
+- Blockers — Missing imports, wrong paths, missing deps
+- Missing critical — Error handling, validation needed for correctness
+
+**Ask first:**
+- New files not specified in plan
+- Different approach than specified
+- Architectural changes — new patterns, new dependencies
+
+## Verification Is Non-Negotiable
+
+Every task has verification. If it fails:
+1. Show the output
+2. Ask user: Retry / Skip / Stop
+3. Log skips to CHANGELOG.md
+
+## Progress Is Persistent
+
+STATE.md tracks exactly where we are. If interrupted, we can resume.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+Validate feature exists and has plans.
+
+```bash
+# Check feature exists
+[ -d ".specd/features/$ARGUMENTS" ] || { echo "not found"; exit 1; }
+
+# Check plans exist
+[ -d ".specd/features/$ARGUMENTS/plans" ] || { echo "no plans"; exit 1; }
+
+# Check ROADMAP exists
+[ -f ".specd/features/$ARGUMENTS/ROADMAP.md" ] || { echo "no roadmap"; exit 1; }
+```
+
+**If feature not found:**
+```
+Feature '{name}' not found.
+
+Run /specd:new-feature {name} to create it.
+```
+
+**If no plans:**
+```
+Feature '{name}' has no plans yet.
+
+Run /specd:plan-feature {name} to create plans.
+```
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Load ALL context needed for execution.
+
+**Read feature context:**
+- `STATE.md` — Current progress, completed plans
+- `DECISIONS.md` — Constraints to follow during implementation
+- `RESEARCH.md` — Implementation notes, pitfalls (if exists)
+- `ROADMAP.md` — Phase overview, plan order
+
+**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 (from STATE.md)
+- Which phase we're in
+- Key decisions affecting implementation
+- Patterns to follow
+
+Continue to find_plan.
+</step>
+
+<step name="find_plan">
+Determine which plan to execute.
+
+**If plan path provided in arguments:**
+- Use that plan directly
+- Verify it exists
+
+**Else find next plan:**
+1. Read STATE.md for current progress
+2. Read ROADMAP.md for plan order
+3. Find first plan without completion marker in STATE.md
+4. Or first plan file in current phase directory
+
+**If no plan found:**
+```
+All plans complete for '{name}'!
+
+Feature execution finished. Review:
+- STATE.md for summary
+- CHANGELOG.md for deviations
+```
+
+**Present plan to execute:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EXECUTE PLAN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+
+**Context loaded:**
+- STATE.md: {phase X, N plans executed}
+- DECISIONS.md: {N} decisions
+- ROADMAP.md: {N} phases, {M} plans total
+
+**Next plan:** {plans/phase-XX/YY-PLAN.md}
+**Objective:** {one-line from plan}
+
+Proceed? [Y/n]
+```
+
+Use AskUserQuestion:
+- header: "Execute"
+- question: "Proceed with this plan?"
+- options:
+  - "Yes, execute" — Continue to execute_tasks
+  - "Show plan first" — Read and display plan content, then ask again
+  - "Skip to different plan" — Ask for plan path
+  - "Cancel" — Exit workflow
+
+Continue to execute_tasks.
+</step>
+
+<step name="execute_tasks">
+Execute each task in the plan.
+
+**Read plan file:**
+Parse the plan to extract:
+- Objective
+- Tasks (numbered)
+- For each task: files, action, pattern, verification, done criteria
+
+**Update STATE.md:**
+Set current plan and task:
+```markdown
+### Current Plan
+- Plan: {path to current plan}
+- Task: 1 of {N}
+- Started: {YYYY-MM-DD HH:MM}
+```
+
+**For each task:**
+
+### 1. Announce task
+```
+───────────────────────────────────────────────────────
+Executing Task {N}: {Title}
+Files: {file list}
+───────────────────────────────────────────────────────
+```
+
+### 2. Implement task
+Follow the plan's instructions:
+- Create/modify specified files
+- Follow patterns from codebase docs
+- Reference DECISIONS.md for constraints
+- Use code patterns from PATTERNS.md
+
+### 3. Handle deviations during implementation
+
+**If bug/blocker discovered:**
+- Fix it immediately
+- Log to CHANGELOG.md:
+```markdown
+### {YYYY-MM-DD} - Plan {phase-XX/YY}
+
+**[Auto-fix] {Short description}**
+- **What:** {What was fixed}
+- **Why:** {Why it was needed}
+- **Files:** `{affected files}`
+```
+- Continue implementation
+
+**If architectural change needed:**
+- Stop implementation
+- Present to user:
+```
+Architectural change needed:
+
+**What:** {Description of change}
+**Why:** {Why plan approach won't work}
+**Proposed:** {Alternative approach}
+
+This differs from the plan. How to proceed?
+```
+
+Use AskUserQuestion:
+- header: "Change"
+- question: "This requires a change from the plan. Approve?"
+- options:
+  - "Approve change" — Implement and log to CHANGELOG.md
+  - "Try plan approach" — Attempt original approach
+  - "Stop and discuss" — Pause execution
+
+**If user approves change:**
+- Implement the change
+- Log to CHANGELOG.md:
+```markdown
+### {YYYY-MM-DD} - Plan {phase-XX/YY}
+
+**[User-approved] {Short description}**
+- **What:** {What was changed}
+- **Why:** {Why plan approach didn't work}
+- **Decision:** User approved alternative
+- **Files:** `{affected files}`
+```
+
+### 4. Run verification
+Execute the verification command from the task:
+```bash
+{verification command from plan}
+```
+
+**If verification passes:**
+- Show: `Verification: {command} ✓`
+- Continue to commit
+
+**If verification fails:**
+- Show output:
+```
+Verification failed for Task {N}: {Title}
+
+Command: {verification command}
+Output:
+{actual output}
+
+How to proceed?
+```
+
+Use AskUserQuestion:
+- header: "Failed"
+- question: "Verification failed. How to proceed?"
+- options:
+  - "Retry task" — Go back to step 2 for this task
+  - "Skip task" — Log to CHANGELOG.md and continue
+  - "Stop execution" — Pause, save progress
+
+**If skip:**
+- Log to CHANGELOG.md:
+```markdown
+### {YYYY-MM-DD} - Plan {phase-XX/YY}
+
+**[Skipped] Task {N}: {Title}**
+- **Reason:** Verification failed, user chose to skip
+- **Command:** `{verification command}`
+- **Output:** {truncated output}
+- **Files:** `{affected files}`
+```
+
+### 5. Commit task
+```bash
+git add {files from task}
+git commit -m "feat({feature}): {task description}"
+```
+
+### 6. Update STATE.md
+Update current task number:
+```markdown
+- Task: {N+1} of {M}
+```
+
+**Continue to next task.**
+
+After all tasks, continue to complete_plan.
+</step>
+
+<step name="complete_plan">
+Mark plan complete and suggest next.
+
+**Update STATE.md:**
+
+1. Clear current plan section:
+```markdown
+### Current Plan
+- Plan: none
+- Task: —
+- Started: —
+```
+
+2. Add to completed plans table:
+```markdown
+### Completed Plans
+| Plan | Completed | Tasks | Deviations |
+|------|-----------|-------|------------|
+| {path} | {YYYY-MM-DD} | {N} | {count} |
+```
+
+3. Update stage progress checkboxes
+
+**Commit STATE.md update:**
+```bash
+git add .specd/features/{feature}/STATE.md
+git commit -m "docs({feature}): complete plan {phase-XX/YY}"
+```
+
+**Find next plan:**
+- Check ROADMAP.md for next plan in sequence
+- Or next phase if current phase complete
+
+**Present summary:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Plan:** {path}
+**Tasks executed:** {N}
+**Deviations logged:** {count}
+
+{If deviations:}
+## Deviations
+
+{List from CHANGELOG.md for this plan}
+
+───────────────────────────────────────────────────────
+
+**Next plan:** {path or "None - all plans complete"}
+
+{If next plan exists:}
+Run `/specd:execute-plan {feature}` to continue.
+
+{If all complete:}
+All plans complete! Feature '{feature}' is implemented.
+Review STATE.md and CHANGELOG.md for summary.
+```
+
+End workflow.
+</step>
+
+</process>
+
+<changelog_format>
+When logging to CHANGELOG.md, use this format:
+
+```markdown
+### {YYYY-MM-DD} - Plan {phase-XX/YY}
+
+**[{Type}] {Short description}**
+- **What:** {Description of change}
+- **Why:** {Reason for deviation}
+- **Files:** `{comma-separated file paths}`
+
+{If relevant:}
+- **Decision:** {User decision if asked}
+- **Output:** {Truncated verification output if skipped}
+```
+
+Types:
+- `[Auto-fix]` — Bug, blocker, or missing critical item fixed automatically
+- `[User-approved]` — Architectural change approved by user
+- `[Skipped]` — Task skipped due to verification failure
+</changelog_format>
+
+<success_criteria>
+- Feature validated with plans
+- All context loaded and internalized
+- Tasks executed in plan order
+- Verification run after each task
+- Deviations logged appropriately
+- Commits made with proper format
+- STATE.md updated with progress
+- Next plan identified or completion announced
+</success_criteria>

package/specdacular/workflows/new-feature.md

@@ -8,7 +8,7 @@ new-feature → (discuss ↔ research)* → plan-feature
 
 The user controls the rhythm after initialization. This command is just the entry point.
 
-**Output:** `.specd/features/{feature-name}/` folder with FEATURE.md, CONTEXT.md, DECISIONS.md, STATE.md, config.json
+**Output:** `.specd/features/{feature-name}/` folder with FEATURE.md, CONTEXT.md, DECISIONS.md, CHANGELOG.md, STATE.md, config.json
 </purpose>
 
 <philosophy>
@@ -229,6 +229,17 @@ If any decisions were made during discussion (technology choices, scope decision
 
 If no decisions yet, leave with just the template structure.
 
+Continue to initialize_changelog.
+</step>
+
+<step name="initialize_changelog">
+Initialize CHANGELOG.md (empty, ready for implementation).
+
+**Write CHANGELOG.md:**
+Use template at `~/.claude/specdacular/templates/features/CHANGELOG.md`
+
+Replace `{feature-name}` with actual feature name. Leave the rest as template structure — entries will be added during plan execution.
+
 Continue to initialize_state.
 </step>
 
@@ -268,6 +279,7 @@ Creates feature structure with:
 - FEATURE.md: Technical requirements
 - CONTEXT.md: Discussion context
 - DECISIONS.md: Decision log ({N} decisions)
+- CHANGELOG.md: Implementation log (empty)
 - STATE.md: Progress tracking
 - config.json: Configuration"
 ```
@@ -291,6 +303,7 @@ Present what was created and next options.
 - `.specd/features/{feature-name}/FEATURE.md` — Technical requirements
 - `.specd/features/{feature-name}/CONTEXT.md` — Discussion context
 - `.specd/features/{feature-name}/DECISIONS.md` — {N} decisions recorded
+- `.specd/features/{feature-name}/CHANGELOG.md` — Implementation log (empty)
 - `.specd/features/{feature-name}/STATE.md` — Progress tracking
 - `.specd/features/{feature-name}/config.json` — Configuration
 
@@ -331,6 +344,7 @@ End workflow.
 - FEATURE.md has specific technical requirements (files to create, integrations)
 - CONTEXT.md captures the discussion state
 - DECISIONS.md initialized (with any decisions made)
+- CHANGELOG.md initialized (empty, ready for implementation)
 - STATE.md tracks current stage
 - config.json created
 - Committed to git