specdacular 0.5.2 → 0.5.3

package/README.md

@@ -1,13 +1,48 @@
 # Specdacular
 
-**AI-optimized codebase documentation and feature planning for Claude.**
+**AI-optimized feature planning and codebase documentation for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).**
 
-A Claude Code extension that helps you understand codebases and plan features specific enough that an agent can implement without asking questions.
+Plan features specific enough that an agent can implement without asking questions.
 
 ```bash
 npx specdacular
 ```
 
+> [!CAUTION]
+> **Early Discovery Phase.** This project is actively evolving as we explore workflow patterns for AI-assisted feature planning. Commands, file formats, and conventions change frequently between versions. We aim to provide backwards-compatible migrations, but breaking changes may occur. Pin to a specific version if stability matters to you.
+
+> [!WARNING]
+> **Open Source Software.** This is maintained by a small team in their free time. It installs slash commands and workflow files into your `.claude/` directory. Always use version control. Review what gets installed. Back up your work. The software is provided "as is" without warranty of any kind. By using this tool, you accept full responsibility for any changes it makes to your project.
+
+---
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [Feature Commands](#feature-commands-feature)
+  - [Phase Commands](#phase-commands-phase)
+  - [Codebase Documentation](#codebase-documentation)
+  - [Utilities](#utilities)
+- [The Flow in Detail](#the-flow-in-detail)
+  - [Feature-Level Commands](#feature-level-commands)
+  - [Phase-Level Commands](#phase-level-commands)
+- [How It Works](#how-it-works)
+  - [Parallel Agents](#parallel-agents)
+  - [Feature Flow](#feature-flow)
+- [Project Structure](#project-structure)
+- [Philosophy](#philosophy)
+- [Migration Guides](#migration-guides)
+  - [From v0.5](#migrating-from-v05)
+  - [From v0.4](#migrating-from-v04)
+- [Updating](#updating)
+- [Uninstalling](#uninstalling)
+- [Contributing](#contributing)
+- [License](#license)
+
 ---
 
 ## What It Does
@@ -25,15 +60,23 @@ Spawns 4 parallel agents to analyze your codebase and generate AI-optimized docu
 
 ### 2. Plan Features
 
-A structured flow for planning features with enough detail for agent implementation:
+Two commands drive the entire feature lifecycle:
 
 ```
-feature:new -> feature:discuss -> feature:research -> feature:plan (roadmap) ->
-  [for each phase]
-    phase:prepare? -> phase:plan -> phase:execute -> phase:review?
-  phase:insert? -> phase:renumber?   <- mid-flight adjustments
+/specd:feature:new my-feature     # Initialize + first discussion
+/specd:feature:next my-feature    # Everything else — discussion, research, planning, execution, review
 ```
 
+`feature:next` reads your feature's current state and offers the natural next step. You never need to remember which command comes next.
+
+---
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and working
+- Node.js >= 16.7.0
+- Git (recommended — Specdacular commits progress automatically)
+
 ---
 
 ## Installation
@@ -55,52 +98,6 @@ In Claude Code:
 
 ---
 
-## Commands
-
-Commands are organized into **feature** and **phase** namespaces.
-
-### Codebase Documentation
-
-| Command | Description |
-|---------|-------------|
-| `/specd:map-codebase` | Analyze codebase with parallel agents |
-
-### Feature Commands (`feature:`)
-
-Work with a feature as a whole — discuss, research, and create a roadmap.
-
-| Command | Description |
-|---------|-------------|
-| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
-| `/specd:feature:discuss [name]` | Continue/deepen discussion (call many times) |
-| `/specd:feature:research [name]` | Research implementation with parallel agents |
-| `/specd:feature:plan [name]` | Create roadmap with phase overview |
-
-### Phase Commands (`phase:`)
-
-Work with individual phases — prepare, plan, and execute one at a time.
-
-| Command | Description |
-|---------|-------------|
-| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
-| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
-| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
-| `/specd:phase:execute [feature]` | Execute plans with progress tracking |
-| `/specd:phase:review [feature] [phase]` | Review executed plans against actual code |
-| `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
-| `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
-
-### Utilities
-
-| Command | Description |
-|---------|-------------|
-| `/specd:status [--all]` | Show feature status dashboard |
-| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
-| `/specd:help` | Show available commands |
-| `/specd:update` | Update to latest version |
-
----
-
 ## Quick Start
 
 ### Map a Codebase
@@ -113,41 +110,39 @@ Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude cont
 
 ### Plan a Feature
 
-**Step 1: Initialize and discuss**
+**Step 1: Initialize**
 
 ```
 /specd:feature:new user-dashboard
 ```
 
-Creates `.specd/features/user-dashboard/` and starts the first discussion. Claude asks what you're building, follows the thread, and captures technical requirements.
+Creates `.specd/features/user-dashboard/` and starts the first discussion. Claude asks what you're building, follows the thread, and captures technical requirements. When done, offers to continue discussing or stop.
 
-**Step 2: Refine understanding**
+**Step 2: Drive the lifecycle**
 
 ```
-/specd:feature:discuss user-dashboard    # Clarify gray areas (call many times)
-/specd:feature:research user-dashboard   # Research implementation approaches
+/specd:feature:next user-dashboard
 ```
 
-Discussion and research are iterative — call them as many times as you need. Context accumulates across sessions.
-
-**Step 3: Create a roadmap**
+That's it. `feature:next` reads the current state and guides you through each stage:
 
-```
-/specd:feature:plan user-dashboard
-```
+1. **Discussion** — Probes gray areas until clear
+2. **Research** — Spawns parallel agents for patterns/pitfalls
+3. **Planning** — Creates roadmap with phases
+4. **Phase preparation** — Discusses phase-specific gray areas
+5. **Phase planning** — Creates detailed PLAN.md files
+6. **Phase execution** — Implements with progress tracking
+7. **Phase review** — Compares plans against actual code
 
-Creates `ROADMAP.md` with phases derived from dependency analysis (types -> API -> UI), plus empty phase directories. No detailed plans yet — those come next, per phase.
+After each step, you can continue or stop. Resume anytime with `/specd:feature:next`.
 
-**Step 4: Prepare, plan, and execute each phase**
+**No argument? It picks for you:**
 
 ```
-/specd:phase:prepare user-dashboard 1    # Discuss phase gray areas + optional research
-/specd:phase:plan user-dashboard 1       # Create detailed PLAN.md files
-/specd:phase:execute user-dashboard      # Execute with progress tracking
-/specd:phase:review user-dashboard 1     # Review phase against actual code
+/specd:feature:next
 ```
 
-Repeat for each phase. Plans are created just-in-time so they stay fresh.
+Scans for in-progress features and shows a picker.
 
 **Mid-flight adjustments:**
 
@@ -158,27 +153,66 @@ Repeat for each phase. Plans are created just-in-time so they stay fresh.
 
 ---
 
+## Commands
+
+Commands are organized into **feature** and **phase** namespaces.
+
+### Feature Commands (`feature:`)
+
+Work with a feature as a whole — discuss, research, and create a roadmap.
+
+| Command | Description |
+|---------|-------------|
+| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
+| `/specd:feature:next [name]` | **Drive the entire lifecycle** — picks up where you left off |
+
+### Phase Commands (`phase:`)
+
+Work with individual phases — prepare, plan, and execute one at a time.
+
+| Command | Description |
+|---------|-------------|
+| `/specd:phase:prepare [feature] [phase]` | Discuss gray areas + optionally research patterns |
+| `/specd:phase:research [feature] [phase]` | Research patterns for a phase (standalone) |
+| `/specd:phase:plan [feature] [phase]` | Create detailed PLAN.md files for one phase |
+| `/specd:phase:execute [feature]` | Execute plans with progress tracking |
+| `/specd:phase:review [feature] [phase]` | Review executed plans against actual code |
+| `/specd:phase:insert [feature] [after] [desc]` | Insert a new phase after an existing one |
+| `/specd:phase:renumber [feature]` | Renumber phases to clean integer sequence |
+
+### Codebase Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/specd:status [--all]` | Show feature status dashboard |
+| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
+| `/specd:help` | Show available commands |
+| `/specd:update` | Update to latest version |
+
+---
+
 ## The Flow in Detail
 
 ### Feature-Level Commands
 
-**`feature:new`** creates the feature folder and starts the first discussion. Output:
+**`feature:new`** creates the feature folder and starts the first discussion. After initialization, offers to continue discussing or come back later with `feature:next`. Output:
 - `FEATURE.md` — Technical requirements from the conversation
 - `CONTEXT.md` — Discussion context (accumulates over time)
 - `DECISIONS.md` — Decisions with dates, rationale, and implications
 - `STATE.md` — Progress tracking
 - `config.json` — Feature configuration
 
-**`feature:discuss`** continues the conversation. Can be called many times — each session adds to `CONTEXT.md` and `DECISIONS.md`. Claude identifies gray areas based on what's been discussed so far and probes until clear.
-
-**`feature:research`** spawns 3 parallel agents to investigate:
-1. **Codebase integration** — How does this fit with existing code?
-2. **External patterns** — What libraries/approaches are standard?
-3. **Pitfalls** — What commonly goes wrong?
+**`feature:next`** is the smart state machine. It reads `config.json` and `STATE.md` to determine where the feature is, shows a status summary, and offers the natural next step. After each action it loops back — you keep going until you choose to stop. Under the hood it delegates to these stages:
 
-Output: `RESEARCH.md` with prescriptive guidance.
-
-**`feature:plan`** creates a roadmap with phases. Each phase has a goal, deliverables, and dependencies. Creates `ROADMAP.md` and empty `plans/phase-{NN}/` directories. Does **not** create detailed PLAN.md files — that happens per-phase with `phase:plan`.
+- **Discussion** — Probes gray areas, records decisions. Context accumulates across sessions.
+- **Research** — Spawns 3 parallel agents: codebase integration, external patterns, and pitfalls. Output: `RESEARCH.md`.
+- **Planning** — Creates `ROADMAP.md` with phases derived from dependency analysis, plus empty `plans/phase-{NN}/` directories.
 
 ### Phase-Level Commands
 
@@ -190,8 +224,6 @@ Output: `RESEARCH.md` with prescriptive guidance.
 5. **Offers research** — "Would you like to research implementation patterns?"
 6. If yes, spawns 3 parallel research agents focused on the phase
 
-This replaces the old two-step of discuss-phase then research-phase.
-
 **`phase:research`** is the standalone research command. Use it when you want to research a phase without discussing first. Same research agents as `phase:prepare`, just without the discussion step.
 
 **`phase:plan`** creates detailed PLAN.md files for one phase. Each plan is a self-contained prompt for an implementing agent with:
@@ -211,7 +243,7 @@ Plans are created just-in-time — right before execution — so they incorporat
 
 **`phase:review`** reviews executed plans against actual code:
 - Claude inspects each plan's `creates`/`modifies` against actual files
-- Per-plan status table with ✅/⚠️/❌/⏸️ icons
+- Per-plan status table with pass/warn/fail/skip icons
 - User conversation captures additional issues
 - Generates corrective plans if needed (fed back into `phase:execute`)
 - Review cycle tracked in `STATE.md`
@@ -251,53 +283,46 @@ Specdacular spawns specialized agents that run simultaneously:
 
 ### Feature Flow
 
+**The simple way** — two commands:
+
 ```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│  feature:new │ ──▶ │   feature:   │ ◀─▶ │   feature:   │
-│              │     │   discuss    │     │   research   │
-└──────────────┘     └──────────────┘     └──────────────┘
-                            │
-                            ▼
-                     ┌──────────────┐
-                     │  feature:plan│ (creates roadmap)
-                     └──────────────┘
-                            │
-                            ▼
-              ┌─────────────────────────────┐
-              │     For each phase:         │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │ prepare  │               │
-              │  └──────────┘               │
-              │       │                     │
-              │       ▼                     │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │   plan   │               │
-              │  └──────────┘               │
-              │       │                     │
-              │       ▼                     │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │ execute  │               │
-              │  └──────────┘               │
-              │       │                     │
-              │       ▼                     │
-              │  ┌──────────┐               │
-              │  │  phase:  │               │
-              │  │  review  │               │
-              │  └──────────┘               │
-              │                             │
-              │  Mid-flight adjustments:    │
-              │  ┌──────────┐               │
-              │  │  phase:  │ ──┐           │
-              │  │  insert  │   │           │
-              │  └──────────┘   │           │
-              │          ┌──────▼────────┐  │
-              │          │    phase:     │  │
-              │          │   renumber   │  │
-              │          └──────────────┘  │
-              └─────────────────────────────┘
+/specd:feature:new          /specd:feature:next
+      │                           │
+      ▼                           ▼
+ Create feature          ┌─── Read state ◀──────────────┐
+ First discussion        │    Show status                │
+ Offer to continue       │    Offer next step            │
+      │                  │         │                     │
+      ▼                  │         ▼                     │
+ "Keep discussing?"      │   ┌──────────────┐           │
+  Yes → discuss loop     │   │  Execute the │           │
+  No  → feature:next     │   │  next action │           │
+                         │   └──────────────┘           │
+                         │         │                     │
+                         │    ┌────┴────┐                │
+                         │    │ Discuss │ Research       │
+                         │    │ Plan    │ Prepare phase  │
+                         │    │ Execute │ Review phase   │
+                         │    └────┬────┘                │
+                         │         │                     │
+                         │         ▼                     │
+                         │   "Continue or stop?"         │
+                         │    Continue ──────────────────┘
+                         │    Stop → clean exit
+                         │
+                         └─── No features? → feature:new
+```
+
+**Under the hood,** `feature:next` delegates to the same workflows as the individual commands:
+
+```
+discussion  → discuss-feature workflow
+research    → research-feature workflow (3 parallel agents)
+planning    → plan-feature workflow
+phase prep  → prepare-phase workflow
+phase plan  → plan-phase workflow
+execution   → execute-plan workflow
+review      → review-phase workflow
 ```
 
 ---
@@ -325,9 +350,9 @@ your-project/
 │           ├── ROADMAP.md     # Phase overview (from feature:plan)
 │           └── plans/
 │               ├── phase-01/
-│               │   ├── CONTEXT.md   # Phase discussion (from phase:prepare)
-│               │   ├── RESEARCH.md  # Phase research (from phase:prepare or phase:research)
-│               │   ├── 01-PLAN.md   # Detailed plans (from phase:plan)
+│               │   ├── CONTEXT.md   # Phase discussion
+│               │   ├── RESEARCH.md  # Phase research
+│               │   ├── 01-PLAN.md   # Detailed plans
 │               │   └── 02-PLAN.md
 │               └── phase-02/
 │                   ├── CONTEXT.md
@@ -364,11 +389,22 @@ Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, c
 
 ---
 
-## Migrating from v0.4
+## Migration Guides
+
+### Migrating from v0.5
+
+**New command: `/specd:feature:next`** — Drives the entire feature lifecycle from a single command. Reads current state and offers the next step automatically.
+
+| Before (v0.5) | After (v0.6) |
+|----------------|--------------|
+| Remember command sequence: `discuss` → `research` → `plan` → `phase:prepare` → `phase:plan` → `phase:execute` → `phase:review` | Just run `/specd:feature:next` — it figures out what's next |
+| `feature:new` ends with list of commands to try | `feature:new` offers to continue discussing or stop with `feature:next` |
 
-If you're upgrading from v0.4, here's what changed:
+**Existing `.specd/` data is fully compatible.** `feature:next` reads the same `config.json`, `STATE.md`, and other files.
 
-**Commands were renamed** into `feature:` and `phase:` namespaces:
+### Migrating from v0.4
+
+Commands were renamed into `feature:` and `phase:` namespaces:
 
 | v0.4 | v0.5 |
 |------|------|
@@ -382,14 +418,14 @@ If you're upgrading from v0.4, here's what changed:
 | `/specd:insert-phase` | `/specd:phase:insert` |
 | `/specd:renumber-phases` | `/specd:phase:renumber` |
 
-**New commands:**
+**New commands in v0.5:**
 - `/specd:phase:prepare` — Replaces `discuss-phase`, adds optional research at the end
 - `/specd:phase:plan` — Creates detailed plans for **one phase** (new command)
 
-**Behavior changes:**
+**Behavior changes in v0.5:**
 - `feature:plan` now creates only `ROADMAP.md` + empty phase directories. It no longer creates `PLAN.md` files for all phases upfront.
-- Detailed `PLAN.md` files are created per-phase with `phase:plan`, right before execution. This prevents plans from going stale.
-- `phase:prepare` combines the old discuss-phase + research-phase into a single command. Discussion always happens; research is offered as an optional step at the end.
+- Detailed `PLAN.md` files are created per-phase with `phase:plan`, right before execution.
+- `phase:prepare` combines the old discuss-phase + research-phase into a single command.
 
 **Existing `.specd/` data is fully compatible.** Your feature files, decisions, and roadmaps work with the new commands.
 
@@ -406,6 +442,8 @@ Or in Claude Code:
 /specd:update
 ```
 
+---
+
 ## Uninstalling
 
 ```bash
@@ -416,6 +454,12 @@ npx specdacular --local --uninstall
 
 ---
 
+## Contributing
+
+Issues and pull requests are welcome at [github.com/victorbalan/specdacular](https://github.com/victorbalan/specdacular).
+
+---
+
 ## License
 
 MIT

package/commands/specd/feature/discuss.md

@@ -12,6 +12,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including discussion.
+
 Continue or deepen understanding of a feature through targeted discussion. Can be called **many times** — context accumulates.
 
 **Updates:**

package/commands/specd/feature/new.md

@@ -12,7 +12,7 @@ allowed-tools:
 ---
 
 <objective>
-Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements.
+Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements. After initialization, offers to continue discussing or stop.
 
 **Creates:**
 - `.specd/features/{name}/FEATURE.md` — Technical requirements from discussion
@@ -21,7 +21,7 @@ Initialize a feature folder and start the first discussion. Creates structure, a
 - `.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.
+**This is the entry point.** After this, continue with `/specd:feature:next` to drive the entire lifecycle.
 </objective>
 
 <execution_context>
@@ -63,5 +63,5 @@ Feature name: $ARGUMENTS
 - [ ] STATE.md tracks current position
 - [ ] config.json created
 - [ ] Committed to git
-- [ ] User knows next options: `/specd:feature:discuss`, `/specd:feature:research`, or continue talking
+- [ ] User offered to continue discussing or stop with `/specd:feature:next`
 </success_criteria>

package/commands/specd/feature/next.md

@@ -0,0 +1,84 @@
+---
+name: specd:feature:next
+description: Drive feature lifecycle — picks up where you left off and guides next steps
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Smart state machine that reads current feature state and drives the entire lifecycle. One command from discussion through phase execution.
+
+**How it works:**
+1. Select feature (from argument or picker)
+2. Read current state (STATE.md, config.json, CONTEXT.md, ROADMAP.md)
+3. Show status summary
+4. Offer the natural next step
+5. Execute it (delegating to existing workflows)
+6. Loop back — offer the next step or stop
+
+**Covers the full lifecycle:**
+- Discussion (gray areas, decisions)
+- Research (parallel agents for patterns/pitfalls)
+- Planning (roadmap with phases)
+- Phase preparation (phase-specific discussion + research)
+- Phase planning (detailed PLAN.md files)
+- Phase execution (with progress tracking)
+- Phase review (compare plans vs actual code)
+
+**No need to remember individual commands.** This one command figures out what's next.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/next-feature.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS
+
+**Scans for features:**
+@.specd/features/*/config.json
+
+**Loads feature context (once selected):**
+@.specd/features/{name}/config.json
+@.specd/features/{name}/STATE.md
+@.specd/features/{name}/CONTEXT.md
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/ROADMAP.md (if exists)
+@.specd/features/{name}/RESEARCH.md (if exists)
+
+**Delegates to existing workflows:**
+@~/.claude/specdacular/workflows/discuss-feature.md
+@~/.claude/specdacular/workflows/research-feature.md
+@~/.claude/specdacular/workflows/plan-feature.md
+@~/.claude/specdacular/workflows/prepare-phase.md
+@~/.claude/specdacular/workflows/plan-phase.md
+@~/.claude/specdacular/workflows/execute-plan.md
+@~/.claude/specdacular/workflows/review-phase.md
+</context>
+
+<process>
+1. **Select Feature** — From argument or scan .specd/features/*/config.json
+2. **Read State** — Load config.json, STATE.md, CONTEXT.md, ROADMAP.md
+3. **Show Status** — Concise summary of where things stand
+4. **Determine Next** — Based on stage + phase status
+5. **Offer Choice** — Next step + alternatives + "stop for now"
+6. **Execute** — Delegate to appropriate workflow
+7. **Loop** — Back to step 2 after each action
+</process>
+
+<success_criteria>
+- [ ] Feature selected (from argument or picker)
+- [ ] Current state accurately displayed
+- [ ] Correct next action offered
+- [ ] User can stop at any natural boundary
+- [ ] Delegated to correct workflow for execution
+- [ ] Looped back after completion
+</success_criteria>

package/commands/specd/feature/plan.md

@@ -12,6 +12,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including planning.
+
 Create a roadmap with phase overview and empty phase directories. Detailed PLAN.md files are created later per-phase with `/specd:phase:plan`.
 
 **Creates:**

package/commands/specd/feature/research.md

@@ -13,6 +13,8 @@ allowed-tools:
 ---
 
 <objective>
+> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including research.
+
 Research how to implement a feature before planning. Spawns parallel research agents to investigate:
 
 1. **Codebase Integration** - How does this fit with existing code? (uses Claude Code Explore agent)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.5.2",
+  "version": "0.5.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/STATE.md

@@ -81,14 +81,7 @@
 
 {What the user should do next based on current state.}
 
-**Options:**
-- `/specd:feature:discuss {feature-name}` — Continue refining understanding
-- `/specd:feature:research {feature-name}` — Research implementation approach
-- `/specd:feature:plan {feature-name}` — Create roadmap with phase overview (when ready)
-- `/specd:phase:prepare {feature-name} {N}` — Prepare a specific phase
-- `/specd:phase:plan {feature-name} {N}` — Create detailed plans for a phase
-- `/specd:phase:execute {feature-name}` — Execute plans with progress tracking
-- `/specd:phase:review {feature-name} {N}` — Review executed plans against actual code
+**Resume:** `/specd:feature:next {feature-name}` — Picks up where you left off and guides the next step automatically.
 
 ---
 

package/specdacular/workflows/new-feature.md

@@ -288,7 +288,7 @@ Continue to completion.
 </step>
 
 <step name="completion">
-Present what was created and next options.
+Present what was created and offer to continue.
 
 **Output:**
 ```
@@ -315,23 +315,51 @@ Present what was created and next options.
 **Open areas to discuss:**
 - {Gray area 1}
 - {Gray area 2}
+```
 
-───────────────────────────────────────────────────────
+Continue to continuation_offer.
+</step>
+
+<step name="continuation_offer">
+Offer to continue discussing or stop.
+
+**If gray areas remain:**
+
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Want to keep discussing the open areas, or come back later?"
+- options:
+  - "Keep discussing" — Dive into the gray areas now
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
 
-## What's Next
+**If Keep discussing:**
+Execute the discuss-feature workflow logic:
+@~/.claude/specdacular/workflows/discuss-feature.md
 
-You control the rhythm. Options:
+After discussion completes (commit done), return to this step (continuation_offer) — re-read CONTEXT.md to check if gray areas remain, and offer again.
 
-**/specd:feature:discuss {feature-name}** — Dive deeper into specific areas
-  {Suggested if gray areas remain}
+**If no gray areas remain:**
 
-**/specd:feature:research {feature-name}** — Research implementation approach
-  {Suggested if technology choices are unclear}
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Discussion looks solid. Want to keep going or come back later?"
+- options:
+  - "Continue" — Move to the next step (research or planning)
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
+
+**If Continue:**
+Hand off to the next-feature workflow logic to determine next action:
+@~/.claude/specdacular/workflows/next-feature.md
+
+Start from the read_state step with the current feature.
+
+**If Stop for now:**
+```
+───────────────────────────────────────────────────────
 
-**/specd:feature:plan {feature-name}** — Create roadmap with phase overview
-  {Only when discussion + research are sufficient}
+Progress saved. Pick up where you left off anytime:
 
-Or just **keep talking** — this conversation continues naturally.
+/specd:feature:next {feature-name}
 ```
 
 End workflow.

package/specdacular/workflows/next-feature.md

@@ -0,0 +1,497 @@
+<purpose>
+Smart state machine that reads current feature state and drives the entire lifecycle. After each action, loops back and offers the next step. User can stop at any natural boundary.
+
+**One command for the entire lifecycle:** discussion, research, planning, phase preparation, phase planning, phase execution, phase review.
+
+**Core loop:**
+```
+read state → show status → determine next action → execute → loop
+```
+
+The user only needs to remember `/specd:feature:next`. The state machine figures out what to do.
+</purpose>
+
+<philosophy>
+
+## Guide, Don't Force
+
+Show the user where they are and what the natural next step is. Always offer alternatives and a "stop for now" option. The user controls the rhythm.
+
+## DRY — Delegate to Existing Workflows
+
+This workflow is a dispatcher. It reads state, determines the next action, then delegates to existing workflow files for the actual work. It does NOT duplicate logic from other workflows.
+
+## Natural Boundaries
+
+After each significant action (discussion session, research, planning, phase completion), offer the user a chance to stop. These are natural context-window boundaries too.
+
+## Feature Selection
+
+When no argument is given, scan for in-progress features and let the user pick. Always show the picker, even for a single feature — it confirms intent.
+
+</philosophy>
+
+<process>
+
+<step name="select_feature">
+Determine which feature to work on.
+
+**If $ARGUMENTS provided:**
+Use as feature name. Normalize to kebab-case.
+
+```bash
+[ -d ".specd/features/$ARGUMENTS" ] || { echo "not found"; exit 1; }
+```
+
+**If no arguments:**
+Scan for in-progress features:
+
+```bash
+# List feature directories with config.json
+for dir in .specd/features/*/config.json; do
+  [ -f "$dir" ] && echo "$dir"
+done
+```
+
+Read each `config.json` and filter where `stage != "complete"`.
+
+**If no features found:**
+```
+No features in progress.
+
+Start one with /specd:feature:new
+```
+End workflow.
+
+**If features found:**
+Use AskUserQuestion:
+- header: "Feature"
+- question: "Which feature would you like to work on?"
+- options: List each feature with its current stage (e.g., "my-feature (discussion)", "other-feature (execution)")
+
+Use the selected feature name.
+
+Continue to read_state.
+</step>
+
+<step name="read_state">
+Load all feature context to determine current position.
+
+**Read:**
+- `.specd/features/{name}/config.json` — Stage, phases info
+- `.specd/features/{name}/STATE.md` — Detailed progress
+- `.specd/features/{name}/CONTEXT.md` — Discussion context, gray areas
+- `.specd/features/{name}/ROADMAP.md` — If exists, phase overview
+- `.specd/features/{name}/FEATURE.md` — Requirements summary
+
+**Parse from config.json:**
+- `stage` — discussion | research | planned | execution | complete
+- `phases.total` — Number of phases (if planned)
+- `phases.current` — Current phase number (if in execution)
+- `phases.completed` — Number of completed phases
+
+**Parse from CONTEXT.md:**
+- Gray areas remaining (from "Gray Areas Remaining" section)
+
+**Parse from ROADMAP.md (if exists):**
+- Phase list with status
+
+**Parse from STATE.md:**
+- Execution progress (which plans are complete)
+- Review cycles
+
+**Determine phase status (if in planned/execution stage):**
+For the current/next phase, check:
+```bash
+# Check if phase directory has CONTEXT.md (prepared)
+[ -f ".specd/features/{name}/plans/phase-{NN}/CONTEXT.md" ] && echo "prepared"
+
+# Check if phase has PLAN.md files (planned)
+ls .specd/features/{name}/plans/phase-{NN}/*-PLAN.md 2>/dev/null | head -1
+
+# Check STATE.md for completed plans in this phase
+```
+
+Continue to show_status.
+</step>
+
+<step name="show_status">
+Present a concise status summary.
+
+```
+## {feature-name}
+
+**Stage:** {stage}
+**Last updated:** {date}
+
+{Stage-specific summary — see below}
+```
+
+**If stage=discussion:**
+```
+**Discussion sessions:** {N}
+**Decisions made:** {N}
+**Gray areas remaining:** {count}
+{If count > 0: list them}
+```
+
+**If stage=research:**
+```
+**Research:** Complete
+**Key findings:** {2-3 bullet points from RESEARCH.md}
+```
+
+**If stage=planned:**
+```
+**Phases:** {total}
+{List phases with one-liner goals}
+```
+
+**If stage=execution:**
+```
+**Phases:** {completed}/{total}
+**Current phase:** {N} — {name}
+**Phase status:** {prepared | planned | executing | executed}
+```
+
+Continue to determine_action.
+</step>
+
+<step name="determine_action">
+Based on current state, determine and offer the next action.
+
+Route to the appropriate sub-step based on state:
+
+**stage=discussion, gray areas remain:**
+→ Go to action_discuss
+
+**stage=discussion, no gray areas (or user wants to skip):**
+→ Go to action_research_offer
+
+**stage=research (RESEARCH.md exists):**
+→ Go to action_plan_offer
+
+**stage=planned, no phases started:**
+→ Go to action_phase_prepare
+
+**stage=planned or stage=execution, current phase prepared but not planned:**
+→ Go to action_phase_plan
+
+**stage=execution, current phase planned but not all plans executed:**
+→ Go to action_phase_execute
+
+**stage=execution, current phase all plans executed:**
+→ Go to action_phase_review
+
+**stage=execution, all phases done:**
+→ Go to action_complete
+
+</step>
+
+<step name="action_discuss">
+Offer discussion when gray areas remain.
+
+```
+### Open Areas
+
+These areas could use more clarity:
+
+{List gray areas from CONTEXT.md}
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Want to discuss these areas, or skip ahead?"
+- options:
+  - "Discuss" — Probe open areas (recommended if gray areas exist)
+  - "Skip to research" — Move to researching implementation patterns
+  - "Skip to planning" — Jump to creating the roadmap (only if enough context)
+  - "Stop for now" — Save progress, come back with /specd:feature:next
+
+**If Discuss:**
+Execute the discuss-feature workflow logic:
+@~/.claude/specdacular/workflows/discuss-feature.md
+
+After discussion completes (commit done), loop back to read_state.
+
+**If Skip to research:**
+→ Go to action_research_offer
+
+**If Skip to planning:**
+→ Go to action_plan_execute
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_research_offer">
+Offer research when discussion is sufficient.
+
+**If RESEARCH.md already exists:**
+```
+Research has already been conducted.
+```
+→ Go to action_plan_offer
+
+**If no RESEARCH.md:**
+```
+### Discussion Looks Solid
+
+You've resolved the key gray areas. Next step is usually research — investigating implementation patterns, libraries, and pitfalls.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Research implementation patterns?"
+- options:
+  - "Research" — Spawn parallel agents to investigate patterns (recommended)
+  - "Skip to planning" — Jump straight to roadmap creation
+  - "Discuss more" — Go back to discussion
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Research:**
+Execute the research-feature workflow logic:
+@~/.claude/specdacular/workflows/research-feature.md
+
+After research completes (commit done), loop back to read_state.
+
+**If Skip to planning:**
+→ Go to action_plan_offer
+
+**If Discuss more:**
+→ Go to action_discuss
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_plan_offer">
+Offer roadmap creation.
+
+```
+### Ready to Plan
+
+{If RESEARCH.md exists: "Research is complete. "}Time to create the roadmap — breaking the feature into ordered phases.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Create the roadmap?"
+- options:
+  - "Create roadmap" — Derive phases and write ROADMAP.md (recommended)
+  - "Discuss more" — Go back to discussion
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Create roadmap:**
+→ Go to action_plan_execute
+
+**If Discuss more:**
+→ Go to action_discuss
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_plan_execute">
+Execute the plan-feature workflow.
+
+Execute the plan-feature workflow logic:
+@~/.claude/specdacular/workflows/plan-feature.md
+
+After planning completes (commit done), loop back to read_state.
+</step>
+
+<step name="action_phase_prepare">
+Offer to prepare the next phase.
+
+**Determine next phase:** First phase without a CONTEXT.md in its directory (not yet prepared), or phase 1 if none started.
+
+```
+### Roadmap Ready
+
+{total} phases planned. Time to prepare Phase {N}: {phase-name}.
+
+Phase preparation involves discussing phase-specific gray areas and optionally researching implementation patterns.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Prepare Phase {N}?"
+- options:
+  - "Prepare phase" — Discuss gray areas + optional research (recommended)
+  - "Skip to planning" — Jump to creating detailed plans
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Prepare phase:**
+Execute the prepare-phase workflow logic:
+@~/.claude/specdacular/workflows/prepare-phase.md
+
+Pass feature name and phase number as arguments.
+
+After preparation completes (commit done), loop back to read_state.
+
+**If Skip to planning:**
+→ Go to action_phase_plan
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_plan">
+Offer to create detailed plans for the current phase.
+
+**Determine phase:** Current phase that has been prepared (or not) but doesn't have PLAN.md files yet.
+
+```
+### Phase {N} Ready for Planning
+
+Time to create detailed, executable plans for Phase {N}: {phase-name}.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Create detailed plans for Phase {N}?"
+- options:
+  - "Create plans" — Write executable PLAN.md files (recommended)
+  - "Prepare first" — Go back to phase preparation
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Create plans:**
+Execute the plan-phase workflow logic:
+@~/.claude/specdacular/workflows/plan-phase.md
+
+Pass feature name and phase number as arguments.
+
+After planning completes (commit done), loop back to read_state.
+
+**If Prepare first:**
+→ Go to action_phase_prepare
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_execute">
+Offer to execute plans for the current phase.
+
+**Determine:** Which plans exist and which are not yet executed.
+
+```
+### Phase {N} Has Plans Ready
+
+{count} plan(s) ready to execute for Phase {N}: {phase-name}.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Execute Phase {N} plans?"
+- options:
+  - "Execute" — Run the next plan with progress tracking (recommended)
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Execute:**
+Execute the execute-plan workflow logic:
+@~/.claude/specdacular/workflows/execute-plan.md
+
+Pass feature name as argument (it finds the next incomplete plan).
+
+After execution completes (commit done), loop back to read_state.
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_phase_review">
+Offer to review the completed phase.
+
+```
+### Phase {N} Execution Complete
+
+All plans for Phase {N} have been executed. Review compares what was planned against what was actually built.
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Review Phase {N}?"
+- options:
+  - "Review" — Compare plans against actual code (recommended)
+  - "Skip to next phase" — Move on to Phase {N+1}
+  - "Stop for now" — Come back with /specd:feature:next
+
+**If Review:**
+Execute the review-phase workflow logic:
+@~/.claude/specdacular/workflows/review-phase.md
+
+Pass feature name and phase number as arguments.
+
+After review completes (commit done):
+
+**If there are more phases:**
+Loop back to read_state (will pick up next phase).
+
+**If all phases done:**
+→ Go to action_complete
+
+**If Skip to next phase:**
+Loop back to read_state (will pick up next phase).
+
+**If Stop for now:**
+→ Go to action_stop
+</step>
+
+<step name="action_complete">
+Feature is complete.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ FEATURE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Phases completed:** {total}
+**Decisions made:** {count}
+
+All phases have been executed{and reviewed, if applicable}.
+```
+
+**Update config.json:**
+Set `stage` to `"complete"`.
+
+**Update STATE.md:**
+Set stage to `complete`.
+
+```bash
+git add .specd/features/{name}/config.json .specd/features/{name}/STATE.md
+git commit -m "docs({feature-name}): feature complete
+
+All {N} phases executed."
+```
+
+End workflow.
+</step>
+
+<step name="action_stop">
+Clean exit with resume instructions.
+
+```
+───────────────────────────────────────────────────────
+
+Progress saved. Resume anytime with:
+
+/specd:feature:next {feature-name}
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- Feature selected (from argument or picker)
+- Current state accurately read and displayed
+- Correct next action determined from state
+- Delegated to appropriate workflow for execution
+- Looped back after action completion
+- User could stop at any natural boundary
+- Clean exit with resume instructions
+</success_criteria>