specdacular 0.2.2 → 0.2.5

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,34 @@ 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-feature → plan-feature →
+  (discuss-phase? → research-phase? → execute-plan)* per phase
+```
 
-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
+- `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
 
 ---
 
@@ -35,8 +50,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 +62,70 @@ In Claude Code:
 
 ---
 
-## Usage
+## Commands
+
+### Codebase Documentation
+
+| 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 |
+| `/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 |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/specd:help` | Show available commands |
+| `/specd:update` | Update to latest version |
+
+---
+
+## Quick Start
 
-### Map Your Codebase
+### 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
 ```
 
----
+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
 
-## 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
+```
 
-| Command | Description |
-|---------|-------------|
-| `/specd:map-codebase` | Analyze codebase and generate documentation |
-| `/specd:help` | Show available commands |
+Optionally, before executing each phase:
+```
+/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
+```
 
 ---
 
@@ -84,7 +133,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 +143,145 @@ 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 │
+                     └──────────────┘
+                            │
+                            ▼
+              ┌─────────────────────────────┐
+              │     For each phase:         │
+              │  ┌─────────┐   ┌─────────┐  │
+              │  │ discuss │ → │research │  │
+              │  │  phase  │   │  phase  │  │
+              │  └─────────┘   └─────────┘  │
+              │         │           │       │
+              │         └─────┬─────┘       │
+              │               ▼             │
+              │        ┌────────────┐       │
+              │        │execute-plan│       │
+              │        └────────────┘       │
+              └─────────────────────────────┘
 ```
 
-## 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
-```
+**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
 
-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     # Feature-level discussion
+│           ├── DECISIONS.md   # Decision log (feature + phase)
+│           ├── STATE.md       # Progress tracking
+│           ├── RESEARCH.md    # Feature-level research
+│           ├── ROADMAP.md     # Phase overview
+│           └── plans/         # Executable plans
+│               ├── phase-01/
+│               │   ├── CONTEXT.md   # Phase discussion (optional)
+│               │   ├── RESEARCH.md  # Phase research (optional)
+│               │   ├── 01-PLAN.md
+│               │   └── 02-PLAN.md
+│               └── phase-02/
+│                   ├── CONTEXT.md
+│                   ├── RESEARCH.md
+│                   └── 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/discuss-phase.md

@@ -0,0 +1,63 @@
+---
+name: specd:discuss-phase
+description: Discuss a specific phase before execution
+argument-hint: "[feature-name] [phase-number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Discuss a specific phase before executing it. Enables just-in-time clarification focused on the phase's scope rather than the entire feature.
+
+**Updates:**
+- `.specd/features/{name}/plans/phase-{NN}/CONTEXT.md` — Phase-specific discussion resolutions
+- `.specd/features/{name}/DECISIONS.md` — Accumulates decisions with dates/rationale
+
+**Why phase-level discussion?** Instead of researching/discussing the entire feature upfront, dive deeper into each phase's specifics right before executing it. Smaller context, more focused.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/discuss-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (expects: feature-name phase-number)
+
+**Load feature context:**
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/CONTEXT.md
+@.specd/features/{name}/DECISIONS.md
+@.specd/features/{name}/ROADMAP.md
+
+**Load phase context:**
+@.specd/features/{name}/plans/phase-{NN}/*.md (plan files)
+
+**Load codebase context (if available):**
+@.specd/codebase/PATTERNS.md
+@.specd/codebase/STRUCTURE.md
+@.specd/codebase/MAP.md
+</context>
+
+<process>
+1. **Validate** — Feature exists, phase exists in ROADMAP.md
+2. **Load Context** — Phase details from ROADMAP.md, plans in phase, feature DECISIONS.md
+3. **Identify Gray Areas** — Phase-type-specific concerns
+4. **Probe Gray Areas** — 4 questions per area, then move on
+5. **Record** — Save to `plans/phase-{NN}/CONTEXT.md`, update DECISIONS.md
+6. **Commit**
+</process>
+
+<success_criteria>
+- [ ] Feature and phase validated
+- [ ] Phase context loaded (plans, goals, files to create/modify)
+- [ ] Phase-type-specific gray areas identified
+- [ ] User-selected areas discussed
+- [ ] Decisions recorded with date, context, rationale
+- [ ] Phase CONTEXT.md created/updated with resolved questions
+- [ ] Committed to git
+</success_criteria>

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,9 @@ 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:discuss-phase [feature] [phase]` | Discuss a phase before execution |
+| `/specd:research-phase [feature] [phase]` | Research patterns for a phase |
+| `/specd:execute-plan [feature] [plan]` | Execute a plan with progress tracking |
 
 ### Utilities
 
@@ -45,7 +48,8 @@ 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-feature → plan-feature →
+  (discuss-phase? → research-phase? → execute-plan)* per phase
 ```
 
 **You control the rhythm:**
@@ -53,6 +57,9 @@ 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
+- `discuss-phase` — Optional: dive deeper into phase specifics before execution
+- `research-phase` — Optional: research patterns for a specific phase
+- `execute-plan` — Execute plans with progress tracking and deviation logging
 
 ### Quick Start
 
@@ -63,7 +70,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/commands/specd/research-phase.md

@@ -0,0 +1,63 @@
+---
+name: specd:research-phase
+description: Research implementation patterns for a phase
+argument-hint: "[feature-name] [phase-number]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Research implementation patterns for a specific phase before executing it. Spawns parallel research agents focused on the phase's scope.
+
+**Output:** `.specd/features/{name}/plans/phase-{NN}/RESEARCH.md` with phase-specific guidance.
+
+**Why phase-level research?** Instead of researching the entire feature upfront, investigate each phase's specifics right before executing it. Smaller scope, more focused, fresher context.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/research-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (expects: feature-name phase-number)
+
+**Load feature context:**
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/DECISIONS.md
+@.specd/features/{name}/ROADMAP.md
+@.specd/features/{name}/RESEARCH.md (if exists, feature-level research)
+
+**Load phase context:**
+@.specd/features/{name}/plans/phase-{NN}/CONTEXT.md (if exists)
+@.specd/features/{name}/plans/phase-{NN}/*.md (plan files)
+
+**Load codebase context:**
+@.specd/codebase/PATTERNS.md
+@.specd/codebase/STRUCTURE.md
+@.specd/codebase/MAP.md
+</context>
+
+<process>
+1. **Validate** — Feature and phase exist
+2. **Load Context** — Phase goals, files to create/modify, previous phase research
+3. **Spawn Research Agents** — 3 parallel agents for phase-specific research
+4. **Synthesize** — Combine into `plans/phase-{NN}/RESEARCH.md`
+5. **Record Decisions** — Technology choices to DECISIONS.md
+6. **Commit**
+</process>
+
+<success_criteria>
+- [ ] Feature and phase validated
+- [ ] Phase context loaded (goals, files, type)
+- [ ] Research agents spawned (codebase, patterns, pitfalls)
+- [ ] Results synthesized into phase RESEARCH.md
+- [ ] Decisions recorded in DECISIONS.md
+- [ ] Committed to git
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "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/templates/features/config.json

@@ -13,5 +13,8 @@
     "v1_count": 0,
     "v2_count": 0,
     "completed": 0
+  },
+  "execution": {
+    "auto_commit": false
   }
 }