specdacular 0.2.3 → 0.2.5

package/README.md

@@ -28,7 +28,8 @@ 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
+new-feature → discuss-feature → plan-feature →
+  (discuss-phase? → research-phase? → execute-plan)* per phase
 ```
 
 **You control the rhythm:**
@@ -36,6 +37,9 @@ new-feature → (discuss ↔ research)* → plan-feature
 - `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
 
 ---
 
@@ -74,6 +78,9 @@ In Claude Code:
 | `/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
 
@@ -113,6 +120,13 @@ Then refine and plan:
 /specd:plan-feature user-dashboard       # Create executable plans
 ```
 
+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
+```
+
 ---
 
 ## How It Works
@@ -155,18 +169,32 @@ The feature planning flow accumulates context over multiple sessions:
                             ▼
                      ┌──────────────┐
                      │ plan-feature │
-                     │              │
                      └──────────────┘
                             │
                             ▼
-                     Executable PLAN.md
-                     files for agents
+              ┌─────────────────────────────┐
+              │     For each phase:         │
+              │  ┌─────────┐   ┌─────────┐  │
+              │  │ discuss │ → │research │  │
+              │  │  phase  │   │  phase  │  │
+              │  └─────────┘   └─────────┘  │
+              │         │           │       │
+              │         └─────┬─────┘       │
+              │               ▼             │
+              │        ┌────────────┐       │
+              │        │execute-plan│       │
+              │        └────────────┘       │
+              └─────────────────────────────┘
 ```
 
 Each session updates:
 - `CONTEXT.md` — Resolved questions accumulate
 - `DECISIONS.md` — Decisions with rationale accumulate
 
+**Phase-level commands** (optional but powerful):
+- `discuss-phase` — Just-in-time clarification for a specific phase
+- `research-phase` — Focused research for phase-specific patterns
+
 Plans are prompts for implementing agents with:
 - Specific file paths
 - Code patterns to follow
@@ -191,16 +219,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/
+│               │   ├── 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
 └── ...
 ```

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/help.md

@@ -30,6 +30,8 @@ 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
@@ -46,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 → execute-plan*
+new-feature → discuss-feature → plan-feature →
+  (discuss-phase? → research-phase? → execute-plan)* per phase
 ```
 
 **You control the rhythm:**
@@ -54,6 +57,8 @@ new-feature → (discuss ↔ research)* → plan-feature → execute-plan*
 - `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

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.3",
+  "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/config.json

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

package/specdacular/workflows/discuss-phase.md

@@ -0,0 +1,389 @@
+<purpose>
+Discuss a specific phase before executing it. Enables just-in-time clarification focused on the phase's scope.
+
+**Key behaviors:**
+- Phase-specific gray areas based on phase type (Types, API, UI, Integration, etc.)
+- Builds on feature-level context but focuses narrowly
+- Output lives alongside phase plans for easy reference during execution
+
+**Output:** `plans/phase-{NN}/CONTEXT.md` with resolved questions, updated DECISIONS.md
+</purpose>
+
+<philosophy>
+
+## Just-in-Time Clarification
+
+Don't try to clarify everything upfront. Discuss each phase right before executing it, when the context is freshest and questions are most concrete.
+
+## Phase-Type Specific
+
+Different phase types have different gray areas. A Types phase has different concerns than a UI phase. Tailor questions to what's actually being built.
+
+## Focused Context
+
+Unlike feature-level discussion which covers everything, phase discussion is narrow. Only discuss what's relevant to THIS phase's deliverables.
+
+</philosophy>
+
+<phase_type_gray_areas>
+
+## Types/Schema Phase
+- Data model completeness — Are all fields defined?
+- Naming conventions — Consistent with codebase?
+- Relationships — How do types relate to each other?
+- Validation rules — What constraints apply?
+- Nullable fields — What can be undefined/null?
+
+## API/Data Phase
+- Endpoint design — REST conventions, URL structure
+- Error responses — Format, status codes, messages
+- Pagination approach — Cursor vs offset, page size
+- Auth requirements — What auth is needed?
+- Rate limiting — Any throttling needed?
+
+## Business Logic Phase
+- Edge cases — What unusual inputs can occur?
+- Validation rules — What makes data valid/invalid?
+- Error handling — How to handle failures?
+- Transaction boundaries — What operations are atomic?
+
+## UI/Components Phase
+- Component hierarchy — How do components nest?
+- State management — Local vs global state
+- Loading states — What to show while loading?
+- Error states — How to display errors?
+- Accessibility — ARIA, keyboard navigation
+
+## Integration Phase
+- Wiring points — Where does this connect?
+- Initialization order — What depends on what?
+- Dependency injection — How are deps provided?
+- Entry points — Where is this invoked from?
+
+</phase_type_gray_areas>
+
+<process>
+
+<step name="validate">
+Validate feature exists and phase exists.
+
+**Parse arguments:**
+Split $ARGUMENTS into feature-name and phase-number.
+- First word: feature-name
+- Second word: phase-number (numeric, e.g., "1", "2")
+
+```bash
+# Check feature exists
+[ -d ".specd/features/$FEATURE_NAME" ] || { echo "Feature not found"; exit 1; }
+
+# Check ROADMAP.md exists
+[ -f ".specd/features/$FEATURE_NAME/ROADMAP.md" ] || { echo "No roadmap"; exit 1; }
+
+# Check phase directory exists
+PHASE_DIR=".specd/features/$FEATURE_NAME/plans/phase-$(printf '%02d' $PHASE_NUMBER)"
+[ -d "$PHASE_DIR" ] || { echo "Phase not found"; exit 1; }
+```
+
+**If feature not found:**
+```
+Feature '{name}' not found.
+
+Run /specd:new-feature {name} to create it.
+```
+
+**If phase not found:**
+```
+Phase {N} not found for feature '{name}'.
+
+Available phases in ROADMAP.md:
+{list phases from ROADMAP.md}
+```
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Load all context needed for phase discussion.
+
+**Read feature context:**
+- `FEATURE.md` — Overall feature requirements
+- `CONTEXT.md` — Feature-level resolutions (already discussed)
+- `DECISIONS.md` — All decisions so far
+- `ROADMAP.md` — Phase overview, understand this phase's role
+
+**Read phase context:**
+- All plan files in `plans/phase-{NN}/`
+- Existing `plans/phase-{NN}/CONTEXT.md` if it exists (prior phase discussion)
+- Existing `plans/phase-{NN}/RESEARCH.md` if it exists
+
+**Extract from ROADMAP.md:**
+- Phase title and goal
+- Phase type (Types, API, UI, Integration, Business Logic, etc.)
+- Files to be created/modified
+- Dependencies on other phases
+
+**Extract from plan files:**
+- Specific tasks
+- Files and changes
+- Verification criteria
+
+Continue to show_phase_state.
+</step>
+
+<step name="show_phase_state">
+Present phase context to user.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DISCUSS PHASE {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phase:** {N} — {Phase Title}
+**Type:** {Phase Type}
+
+## Phase Goal
+
+{Goal from ROADMAP.md}
+
+## Deliverables
+
+Files to create:
+- {file 1}
+- {file 2}
+
+Files to modify:
+- {file 3}
+
+## Plans in This Phase
+
+- {plan 1 title}
+- {plan 2 title}
+
+{If phase CONTEXT.md exists:}
+## Previously Discussed
+
+{Summary from existing phase CONTEXT.md}
+
+{If feature CONTEXT.md has relevant resolutions:}
+## Relevant Feature Decisions
+
+{Decisions from feature-level that affect this phase}
+```
+
+Continue to identify_gray_areas.
+</step>
+
+<step name="identify_gray_areas">
+Identify gray areas based on phase type.
+
+**Determine phase type** from ROADMAP.md or infer from:
+- "types", "schema", "models" → Types/Schema
+- "api", "endpoint", "route" → API/Data
+- "component", "ui", "page" → UI/Components
+- "logic", "service", "util" → Business Logic
+- "integration", "wiring", "setup" → Integration
+
+**Select gray areas** from phase_type_gray_areas section based on type.
+
+**Filter out already-resolved:**
+- Check feature CONTEXT.md for resolutions that apply
+- Check phase CONTEXT.md if it exists
+- Remove any gray areas that are already clear
+
+**Present:**
+```
+## Areas to Discuss
+
+Based on this {Phase Type} phase, these areas could use clarity:
+
+1. **{Gray area}** — {Why it matters for this phase}
+2. **{Gray area}** — {Why it matters for this phase}
+3. **{Gray area}** — {Why it matters for this phase}
+4. **{Gray area}** — {Why it matters for this phase}
+
+Which would you like to discuss? (Or describe something else)
+```
+
+Use AskUserQuestion:
+- header: "Phase Discussion"
+- question: "Which area would you like to discuss for this phase?"
+- options: List identified gray areas (up to 4)
+- Add "Something else" as final option
+
+Continue to probe_area.
+</step>
+
+<step name="probe_area">
+Probe selected gray area until clear.
+
+**For each selected area, ask up to 4 questions:**
+
+**Question 1:** Open-ended
+"For this phase's {area}, how do you see this working?"
+
+**Question 2:** Clarify specifics
+"When you say X, do you mean Y or Z?"
+
+**Question 3:** Edge cases
+"What should happen when {edge case specific to this phase}?"
+
+**Question 4:** Confirm
+"So for phase {N}, the approach would be {summary}. Correct?"
+
+**After 4 questions (or earlier if clear):**
+```
+Let me capture what we've resolved for phase {N}:
+
+**{Area}:**
+- {Key point 1}
+- {Key point 2}
+- {Any code pattern implied}
+
+Does that capture it?
+```
+
+**If user confirms:** Continue to record
+**If user corrects:** Adjust and confirm again
+**If user wants another area:** Return to identify_gray_areas
+
+Continue to record.
+</step>
+
+<step name="record">
+Record phase discussion to CONTEXT.md and DECISIONS.md.
+
+**Create/Update plans/phase-{NN}/CONTEXT.md:**
+
+```markdown
+# Phase {N} Context: {Phase Title}
+
+**Feature:** {feature-name}
+**Phase Type:** {type}
+**Discussed:** {today}
+
+## Phase Overview
+
+{Brief description of what this phase accomplishes}
+
+## Resolved Questions
+
+### {Question title}
+
+**Question:** {What was unclear}
+**Resolution:** {The answer/decision}
+**Details:**
+- {Detail 1}
+- {Detail 2}
+
+{If code pattern implied:}
+**Code Pattern:**
+```{language}
+{code example}
+```
+
+**Related Decisions:** DEC-XXX
+
+---
+
+{Repeat for each resolved question}
+
+## Gray Areas Remaining
+
+{Any areas still unclear, or "None" if all resolved}
+
+## Implications for Plans
+
+{How these resolutions affect the plan execution}
+```
+
+**Update DECISIONS.md:**
+
+For any new decisions made during phase discussion:
+
+```markdown
+### DEC-{NNN}: {Title}
+
+**Date:** {today}
+**Status:** Active
+**Phase:** {N} — {Phase Title}
+**Context:** {What situation required this decision — from phase discussion}
+**Decision:** {What was decided}
+**Rationale:**
+- {Why this choice}
+**Implications:**
+- {What this means for phase implementation}
+```
+
+Continue to commit.
+</step>
+
+<step name="commit">
+Commit the phase discussion.
+
+```bash
+# Add phase CONTEXT.md
+git add ".specd/features/{feature}/plans/phase-{NN}/CONTEXT.md"
+
+# Add updated DECISIONS.md if modified
+git add ".specd/features/{feature}/DECISIONS.md"
+
+git commit -m "docs({feature}): discuss phase {N} - {phase title}
+
+Resolved:
+- {Area 1}
+- {Area 2}
+
+New decisions: {count}"
+```
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present summary and next options.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE DISCUSSION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phase:** {N} — {Phase Title}
+
+## Resolved
+
+- **{Area 1}:** {Brief resolution}
+- **{Area 2}:** {Brief resolution}
+
+## Files Created/Updated
+
+- `plans/phase-{NN}/CONTEXT.md`
+- `DECISIONS.md` ({count} new decisions)
+
+───────────────────────────────────────────────────────
+
+## What's Next
+
+**/specd:research-phase {feature} {N}** — Research implementation patterns for this phase
+
+**/specd:execute-plan {feature}** — Execute this phase (will load phase context)
+
+**/specd:discuss-phase {feature} {N}** — Continue discussing this phase
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- Feature and phase validated
+- Phase context loaded (plans, goals, type)
+- Phase-type-specific gray areas identified
+- User-selected areas probed (4 questions max)
+- Phase CONTEXT.md created/updated
+- DECISIONS.md updated with phase-specific decisions
+- Committed to git
+- User knows next steps (research-phase or execute-plan)
+</success_criteria>

package/specdacular/workflows/execute-plan.md

@@ -81,11 +81,16 @@ Continue to load_context.
 Load ALL context needed for execution.
 
 **Read feature context:**
+- `config.json` — Feature settings (check `execution.auto_commit`)
 - `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 phase context (if available):**
+- `plans/phase-{NN}/CONTEXT.md` — Phase-specific discussion resolutions
+- `plans/phase-{NN}/RESEARCH.md` — Phase-specific research findings
+
 **Read codebase context (if available):**
 - `PATTERNS.md` — Code patterns to follow
 - `STRUCTURE.md` — Where files go
@@ -96,6 +101,7 @@ Load ALL context needed for execution.
 - Which phase we're in
 - Key decisions affecting implementation
 - Patterns to follow
+- Phase-specific context and research (if discuss-phase/research-phase were run)
 
 Continue to find_plan.
 </step>
@@ -134,6 +140,13 @@ Feature execution finished. Review:
 - STATE.md: {phase X, N plans executed}
 - DECISIONS.md: {N} decisions
 - ROADMAP.md: {N} phases, {M} plans total
+{If phase CONTEXT.md exists:}
+- Phase CONTEXT.md: {N} gray areas resolved
+{If phase RESEARCH.md exists:}
+- Phase RESEARCH.md: patterns identified
+
+**Settings:**
+- Auto-commit: {yes | no} (from config.json)
 
 **Next plan:** {plans/phase-XX/YY-PLAN.md}
 **Objective:** {one-line from plan}
@@ -279,12 +292,27 @@ Use AskUserQuestion:
 - **Files:** `{affected files}`
 ```
 
-### 5. Commit task
+### 5. Commit task (if auto_commit enabled)
+
+**Check config.json `execution.auto_commit`:**
+
+**If auto_commit is true:**
 ```bash
 git add {files from task}
 git commit -m "feat({feature}): {task description}"
 ```
 
+**If auto_commit is false:**
+- Do NOT commit
+- Show message:
+```
+Task {N} complete. Changes ready for review.
+Files modified: {file list}
+
+Commit when ready:
+git add {files} && git commit -m "feat({feature}): {task description}"
+```
+
 ### 6. Update STATE.md
 Update current task number:
 ```markdown
@@ -319,12 +347,18 @@ Mark plan complete and suggest next.
 
 3. Update stage progress checkboxes
 
-**Commit STATE.md update:**
+**Commit STATE.md update (if auto_commit enabled):**
+
+**If auto_commit is true:**
 ```bash
 git add .specd/features/{feature}/STATE.md
 git commit -m "docs({feature}): complete plan {phase-XX/YY}"
 ```
 
+**If auto_commit is false:**
+- Do NOT commit
+- Include STATE.md in the list of modified files for user to review
+
 **Find next plan:**
 - Check ROADMAP.md for next plan in sequence
 - Or next phase if current phase complete

package/specdacular/workflows/research-phase.md

@@ -0,0 +1,583 @@
+<purpose>
+Research implementation patterns for a specific phase before executing it.
+
+Uses three parallel research tracks tailored to the phase:
+1. **Codebase Integration** - How phase deliverables integrate with existing code
+2. **Phase-Type Patterns** - Patterns specific to this phase type (API, UI, etc.)
+3. **Phase-Type Pitfalls** - What goes wrong with this type of work
+
+Output: `plans/phase-{NN}/RESEARCH.md` that execute-plan consumes.
+</purpose>
+
+<philosophy>
+
+## Phase-Focused Research
+
+Don't research the whole feature again. Focus narrowly on what THIS phase creates/modifies. If phase 1 creates types, research type patterns. If phase 2 creates APIs, research API patterns.
+
+## Builds on Feature Research
+
+If feature-level RESEARCH.md exists, don't duplicate it. Reference it and add phase-specific details.
+
+## Codebase First
+
+The most valuable research is understanding how this phase's files integrate with existing code. External patterns matter, but integration patterns matter more.
+
+## Decisions Get Recorded
+
+Any choice made during research goes into DECISIONS.md with phase context.
+
+</philosophy>
+
+<phase_type_research>
+
+## Types/Schema Phase Research
+- Existing type patterns in codebase
+- TypeScript/schema best practices
+- Type relationships and composition
+- Validation library patterns (zod, etc.)
+
+## API/Data Phase Research
+- Existing API patterns in codebase
+- REST/GraphQL conventions
+- Error handling patterns
+- Auth integration patterns
+- Pagination patterns
+
+## Business Logic Phase Research
+- Existing service patterns
+- Error handling approaches
+- Transaction patterns
+- Testing patterns for logic
+
+## UI/Components Phase Research
+- Existing component patterns
+- State management approach
+- Form handling patterns
+- Loading/error state patterns
+- Accessibility patterns
+
+## Integration Phase Research
+- Existing integration patterns
+- Provider/context patterns
+- Initialization patterns
+- Entry point conventions
+
+</phase_type_research>
+
+<process>
+
+<step name="validate">
+Validate feature exists and phase exists.
+
+**Parse arguments:**
+Split $ARGUMENTS into feature-name and phase-number.
+
+```bash
+# Check feature exists
+[ -d ".specd/features/$FEATURE_NAME" ] || { echo "Feature not found"; exit 1; }
+
+# Check ROADMAP.md exists
+[ -f ".specd/features/$FEATURE_NAME/ROADMAP.md" ] || { echo "No roadmap"; exit 1; }
+
+# Check phase directory exists
+PHASE_DIR=".specd/features/$FEATURE_NAME/plans/phase-$(printf '%02d' $PHASE_NUMBER)"
+[ -d "$PHASE_DIR" ] || { echo "Phase not found"; exit 1; }
+
+# Check if RESEARCH.md already exists
+[ -f "$PHASE_DIR/RESEARCH.md" ] && echo "existing"
+```
+
+**If RESEARCH.md exists:**
+Use AskUserQuestion:
+- header: "Research Exists"
+- question: "Phase research already exists. What would you like to do?"
+- options:
+  - "Update research" — Re-run research, incorporate new findings
+  - "View existing" — Show current RESEARCH.md
+  - "Continue anyway" — Skip research, use existing
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Load all context needed for phase research.
+
+**Read feature context:**
+- `FEATURE.md` — Overall feature requirements
+- `DECISIONS.md` — All decisions so far
+- `ROADMAP.md` — Phase overview
+- `RESEARCH.md` — Feature-level research if exists
+
+**Read phase context:**
+- All plan files in `plans/phase-{NN}/`
+- `plans/phase-{NN}/CONTEXT.md` if exists (from discuss-phase)
+- Previous phases' RESEARCH.md files for continuity
+
+**Read codebase context:**
+- `PATTERNS.md` — Code patterns to follow
+- `STRUCTURE.md` — Where files go
+- `MAP.md` — System overview
+
+**Extract from ROADMAP.md:**
+- Phase title and goal
+- Phase type (Types, API, UI, Integration, Business Logic)
+- Files to be created/modified
+
+**Determine phase type** from ROADMAP.md or infer from files:
+- `.ts` types files → Types/Schema
+- `route.ts`, `api/` → API/Data
+- `.tsx` components → UI/Components
+- `service`, `util` → Business Logic
+- `provider`, `setup` → Integration
+
+Continue to present_research_plan.
+</step>
+
+<step name="present_research_plan">
+Present research plan to user.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RESEARCH PHASE {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phase:** {N} — {Phase Title}
+**Type:** {Phase Type}
+
+## Phase Deliverables
+
+Files to create:
+- {file 1}
+- {file 2}
+
+Files to modify:
+- {file 3}
+
+## Research Dimensions
+
+I'll research these areas for this {Phase Type} phase:
+
+1. **Codebase Integration** — How these files fit with existing code
+   - Existing patterns for {phase type}
+   - Files to import from
+   - Integration points
+
+2. **{Phase Type} Patterns** — Standard approaches
+   - Best practices for {phase type}
+   - Library patterns
+   - Code examples
+
+3. **{Phase Type} Pitfalls** — What goes wrong
+   - Common mistakes
+   - Performance issues
+   - Integration gotchas
+
+Estimated: 3 parallel research agents
+
+[Start research] / [Adjust scope]
+```
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "Start phase research?"
+- options:
+  - "Start research" — Spawn agents
+  - "Adjust scope" — Modify research dimensions
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn three parallel research agents.
+
+### Agent 1: Codebase Integration (using Explore agent)
+
+```
+Task(
+  prompt="Research how phase {N} of {feature-name} should integrate with the existing codebase.
+
+<phase_context>
+Phase: {N} — {Phase Title}
+Type: {Phase Type}
+Goal: {Phase goal from ROADMAP.md}
+
+Files to create:
+{list of files}
+
+Files to modify:
+{list of files}
+</phase_context>
+
+<locked_decisions>
+{Relevant decisions from DECISIONS.md}
+</locked_decisions>
+
+<research_questions>
+1. What existing files/modules will this phase's files need to import from?
+2. What patterns do similar {phase type} files in this codebase follow?
+3. Where exactly should new files be created?
+4. What types/interfaces already exist that should be reused?
+5. What utility functions or hooks can be leveraged?
+</research_questions>
+
+<output_format>
+Return findings as structured markdown:
+
+## Codebase Integration for Phase {N}
+
+### Import Dependencies
+- `path/to/file` — what it provides, why needed
+
+### Patterns to Follow
+- Pattern name: description, example file reference
+
+### File Locations
+- Exactly where each new file should go
+
+### Reusable Code
+- Types: list with paths
+- Utilities: list with paths
+
+### Integration Points
+- Where this phase's code connects to existing code
+</output_format>
+",
+  subagent_type="Explore",
+  description="Phase codebase integration"
+)
+```
+
+### Agent 2: Phase-Type Patterns Research
+
+```
+Task(
+  prompt="First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
+
+<research_type>
+{Phase Type} patterns research for phase {N} of {feature-name}.
+</research_type>
+
+<phase_context>
+Phase: {N} — {Phase Title}
+Type: {Phase Type}
+Goal: {Phase goal}
+
+Files to create:
+{list of files}
+</phase_context>
+
+<codebase_stack>
+{From .specd/codebase/ if available}
+</codebase_stack>
+
+<research_questions>
+1. What's the standard approach for {phase type} in this stack?
+2. What libraries are commonly used for {phase type}?
+3. What code patterns work well for {phase type}?
+4. What should NOT be hand-rolled?
+</research_questions>
+
+<tool_strategy>
+1. Context7 first for any library questions
+2. Official docs via WebFetch for gaps
+3. WebSearch for patterns (include current year)
+4. Verify all findings
+</tool_strategy>
+
+<output_format>
+Return findings as structured markdown with confidence levels.
+
+## {Phase Type} Patterns
+
+### Standard Approach
+{Recommended approach with rationale}
+
+### Libraries
+| Library | Version | Purpose | Confidence |
+
+### Code Patterns
+{Code examples with sources}
+
+### Don't Hand-Roll
+| Problem | Use Instead | Why |
+</output_format>
+",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Phase type patterns"
+)
+```
+
+### Agent 3: Phase-Type Pitfalls Research
+
+```
+Task(
+  prompt="First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
+
+<research_type>
+Pitfalls research for {Phase Type} work in phase {N} of {feature-name}.
+</research_type>
+
+<phase_context>
+Phase: {N} — {Phase Title}
+Type: {Phase Type}
+Goal: {Phase goal}
+
+Files to create:
+{list of files}
+</phase_context>
+
+<research_questions>
+1. What do developers commonly get wrong with {phase type}?
+2. What are the performance pitfalls for {phase type}?
+3. What security issues should be avoided?
+4. What integration mistakes happen with {phase type}?
+</research_questions>
+
+<tool_strategy>
+1. WebSearch for common mistakes (include current year)
+2. Look for post-mortems, issue discussions
+3. Check official docs for warnings/caveats
+</tool_strategy>
+
+<output_format>
+Return pitfalls as structured markdown:
+
+## {Phase Type} Pitfalls
+
+### Critical (causes failures/rewrites)
+- Pitfall: description
+  - Why it happens
+  - Prevention
+  - Detection
+
+### Moderate (causes bugs/debt)
+- Pitfall: description
+  - Prevention
+
+### Minor (causes friction)
+- Pitfall: description
+  - Prevention
+</output_format>
+",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Phase type pitfalls"
+)
+```
+
+Wait for all agents to complete.
+
+Continue to synthesize.
+</step>
+
+<step name="synthesize">
+Combine agent results into single RESEARCH.md.
+
+**Create plans/phase-{NN}/RESEARCH.md:**
+
+```markdown
+# Phase {N} Research: {Phase Title}
+
+**Feature:** {feature-name}
+**Phase Type:** {Phase Type}
+**Researched:** {today}
+
+## Summary
+
+{2-3 paragraphs synthesizing all findings for this phase}
+
+**Key recommendation:** {One-liner actionable guidance}
+
+---
+
+## Codebase Integration
+
+{From Agent 1 — Explore findings}
+
+### Import From
+| Module | Provides | Path |
+|--------|----------|------|
+| ... | ... | ... |
+
+### Patterns to Follow
+{Patterns with file references}
+
+### File Locations
+```
+{exact paths for new files}
+```
+
+### Reusable Code
+- **Types:** {list with @paths}
+- **Utilities:** {list with @paths}
+
+### Integration Points
+{Where this phase connects to existing code}
+
+---
+
+## {Phase Type} Patterns
+
+{From Agent 2 — Pattern findings}
+
+### Standard Approach
+{Recommended approach with rationale}
+
+### Libraries
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+| ... | ... | ... | HIGH/MED |
+
+### Code Patterns
+```typescript
+// Pattern name - source: {Context7/docs URL}
+{code example}
+```
+
+### Don't Hand-Roll
+| Problem | Use Instead | Why |
+|---------|-------------|-----|
+| ... | ... | ... |
+
+---
+
+## Pitfalls
+
+{From Agent 3 — Pitfalls findings}
+
+### Critical
+{List with prevention strategies}
+
+### Moderate
+{List with prevention strategies}
+
+### Phase-Specific Warnings
+| When Implementing | Watch Out For | Prevention |
+|-------------------|---------------|------------|
+| ... | ... | ... |
+
+---
+
+## Confidence Assessment
+
+| Area | Level | Reason |
+|------|-------|--------|
+| Codebase integration | {level} | {reason} |
+| {Phase type} patterns | {level} | {reason} |
+| Pitfalls | {level} | {reason} |
+
+## Open Questions
+
+{Anything that couldn't be resolved}
+
+## Sources
+
+### Codebase (from Explore)
+- {file references used}
+
+### External (verified)
+- {Context7 queries}
+- {Official docs URLs}
+```
+
+Continue to record_decisions.
+</step>
+
+<step name="record_decisions">
+Record any technology choices from research.
+
+**Identify decisions from synthesis:**
+- Library choices
+- Pattern choices
+- Approach choices
+
+**For each new decision, add to DECISIONS.md:**
+
+```markdown
+### DEC-{NNN}: {Title}
+
+**Date:** {today}
+**Status:** Active
+**Phase:** {N} — {Phase Title}
+**Context:** Identified during phase research
+**Decision:** {What was decided}
+**Rationale:** {From research findings}
+**Implications:** {What this means for implementation}
+**References:** {Sources}
+```
+
+Continue to commit.
+</step>
+
+<step name="commit">
+Commit the phase research.
+
+```bash
+git add ".specd/features/{feature}/plans/phase-{NN}/RESEARCH.md"
+git add ".specd/features/{feature}/DECISIONS.md"
+
+git commit -m "docs({feature}): research phase {N} - {phase title}
+
+Research dimensions:
+- Codebase integration
+- {Phase type} patterns
+- {Phase type} pitfalls
+
+Key findings:
+- {one-liner from summary}"
+```
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present summary and next options.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE RESEARCH COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phase:** {N} — {Phase Title}
+**Confidence:** {overall level}
+
+## Key Findings
+
+- {Finding 1}
+- {Finding 2}
+- {Finding 3}
+
+## Files Created
+
+- `plans/phase-{NN}/RESEARCH.md`
+- Updated `DECISIONS.md` with {N} new decisions
+
+───────────────────────────────────────────────────────
+
+## What's Next
+
+**/specd:execute-plan {feature}** — Execute this phase (will load phase research)
+
+**/specd:discuss-phase {feature} {N}** — Discuss this phase further
+
+<sub>/clear first — fresh context window for execution</sub>
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- Feature and phase validated
+- Phase context loaded (goals, files, type)
+- Research agents spawned in parallel
+- Results synthesized into phase RESEARCH.md
+- Decisions recorded in DECISIONS.md
+- Committed to git
+- User knows next step is execute-plan
+</success_criteria>