specdacular 0.2.1 → 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/discuss-feature.md

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

package/commands/specd/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

@@ -12,24 +12,80 @@ Display available specdacular commands and usage guidance.
 <output>
 # Specdacular
 
-**AI-optimized codebase documentation for Claude.**
+**AI-optimized codebase documentation and feature planning for Claude.**
 
 ## Commands
 
+### Codebase Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents → produce AI-optimized docs |
+
+### Feature Flow
+
+| 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 |
+
+### Utilities
+
 | Command | Description |
 |---------|-------------|
-| `/specd:map-codebase` | Analyze codebase → produce 4 AI-optimized docs |
-| `/specd:new-feature` | Initialize a feature with requirements and roadmap |
 | `/specd:update` | Update Specdacular to the latest version |
 | `/specd:help` | Show this help |
 
-## Quick Start
+---
+
+## Feature Flow
+
+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*
+```
+
+**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
+
+### Quick Start
+
+```
+/specd:new-feature user-dashboard
+```
+
+This creates `.specd/features/user-dashboard/` with:
+- `FEATURE.md` — Technical requirements
+- `CONTEXT.md` — Discussion context (accumulates)
+- `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:
+
+```
+/specd:discuss-feature user-dashboard    # Clarify gray areas
+/specd:research-feature user-dashboard   # Research implementation
+/specd:plan-feature user-dashboard       # Create executable plans
+```
+
+---
+
+## Codebase Documentation
 
 ```
 /specd:map-codebase
 ```
 
-This spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
+Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
 
 | Document | What it contains |
 |----------|------------------|
@@ -38,7 +94,7 @@ This spawns 4 parallel agents to analyze your codebase and creates `.specd/codeb
 | **STRUCTURE.md** | Organization: where to put new code |
 | **CONCERNS.md** | Warnings: gotchas, anti-patterns, debt |
 
-## Philosophy
+### Philosophy
 
 These docs are **for Claude, not humans**.
 
@@ -50,6 +106,8 @@ Each document answers a question Claude can't get from reading code:
 
 **Principle:** Don't document what Claude can grep. Document tribal knowledge, gotchas, and patterns.
 
+---
+
 ## Updating
 
 When an update is available, you'll see `⬆ /specd:update` in your statusline. Run:

package/commands/specd/new-feature.md

@@ -1,6 +1,6 @@
 ---
 name: specd:new-feature
-description: Initialize a new feature with deep questioning, requirements, and roadmap
+description: Initialize a new feature with technical questioning and start the first discussion
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -12,14 +12,16 @@ allowed-tools:
 ---
 
 <objective>
-Initialize a feature folder with structured planning documents through a conversational workflow.
+Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements.
 
-Creates `.specd/features/{feature-name}/` with:
-- FEATURE.md - What this feature does, core value, constraints
-- REQUIREMENTS.md - Scoped requirements with REQ-IDs (v1/v2/out-of-scope)
-- ROADMAP.md - Phases with success criteria and requirement mapping
-- STATE.md - Project memory, current position, decisions
-- config.json - Mode (yolo/interactive), depth (quick/standard/comprehensive)
+**Creates:**
+- `.specd/features/{name}/FEATURE.md` — Technical requirements from discussion
+- `.specd/features/{name}/CONTEXT.md` — Discussion context (accumulates over time)
+- `.specd/features/{name}/DECISIONS.md` — Memory file for decisions with rationale
+- `.specd/features/{name}/STATE.md` — Progress tracking
+- `.specd/features/{name}/config.json` — Feature configuration
+
+**This is the entry point.** After this, user controls the loop with discuss/research/plan.
 </objective>
 
 <execution_context>
@@ -30,46 +32,36 @@ Creates `.specd/features/{feature-name}/` with:
 Feature name: $ARGUMENTS
 
 **Codebase context discovery:**
-1. Check for `.specd/config.json` - if exists, read `codebase_docs` path
+1. Check for `.specd/config.json` — if exists, read `codebase_docs` path
 2. If no config, check for `.specd/codebase/` (default location)
-3. If neither found, ask user for custom location or suggest `/specd:map-codebase`
+3. If neither found, offer `/specd:map-codebase`
 
 **Referenced docs (when available):**
-- `ARCHITECTURE.md` - Understand existing patterns for integration
-- `CONVENTIONS.md` - Ensure requirements follow coding standards
-- `STRUCTURE.md` - Know where new code should go
+- `ARCHITECTURE.md` or `MAP.md` — System structure
+- `CONVENTIONS.md` or `PATTERNS.md` — Code patterns
+- `STRUCTURE.md` — Directory layout
 </context>
 
-<when_to_use>
-**Use new-feature for:**
-- Starting a new feature or enhancement
-- When you need structured planning documents
-- Before implementing non-trivial functionality
-- When multiple people will work on a feature
-
-**Skip new-feature for:**
-- Bug fixes (just fix them)
-- Trivial changes (<1 hour of work)
-- Exploratory spikes
-</when_to_use>
-
 <process>
-1. Setup - Get feature name, check if exists
-2. Codebase Context - Look for codebase docs
-3. Complexity Assessment - Ask light/moderate/complicated
-4. Deep Questioning - Adaptive depth based on complexity
-5. Write FEATURE.md - Capture context from conversation
-6. Configuration - Ask mode/depth preferences
-7. Define Requirements - Scope v1/v2/out-of-scope
-8. Create Roadmap - Derive phases, map requirements
-9. Initialize State - Create STATE.md
-10. Completion - Summary and next steps
+1. **Validate** — Check name, check if exists
+2. **Codebase Context** — Look for codebase docs (offer map-codebase if missing)
+3. **First Discussion** — "What are you building?"
+4. **Follow the Thread** — Collaborative, not interrogative
+5. **Probe Until Clear** — What creates, what integrates with, constraints
+6. **Write FEATURE.md** — Technical requirements
+7. **Write CONTEXT.md** — Initial discussion state
+8. **Initialize DECISIONS.md** — With any decisions made so far
+9. **Initialize STATE.md** — Feature created, ready for more discussion
+10. **Commit and Present Options**
 </process>
 
 <success_criteria>
 - [ ] Feature folder created at `.specd/features/{name}/`
-- [ ] All 5 files created (FEATURE.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json)
-- [ ] Requirements have REQ-IDs in format `{FEAT}-{CAT}-{NUM}`
-- [ ] Roadmap phases map to requirements
-- [ ] Commits made at key milestones
+- [ ] FEATURE.md captures technical requirements
+- [ ] CONTEXT.md initialized with discussion context
+- [ ] DECISIONS.md initialized (possibly with initial decisions)
+- [ ] STATE.md tracks current position
+- [ ] config.json created
+- [ ] Committed to git
+- [ ] User knows next options: discuss-feature, research-feature, or continue talking
 </success_criteria>