specdacular 0.5.2 → 0.6.0

package/README.md

@@ -1,13 +1,46 @@
 # 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)
+- [Multi-Project Support](#multi-project-support)
+- [Project Structure](#project-structure)
+- [Philosophy](#philosophy)
+- [Updating](#updating)
+- [Uninstalling](#uninstalling)
+- [Contributing](#contributing)
+- [License](#license)
+
 ---
 
 ## What It Does
@@ -23,17 +56,29 @@ Spawns 4 parallel agents to analyze your codebase and generate AI-optimized docu
 | `STRUCTURE.md` | Where do I put new code? |
 | `CONCERNS.md` | What will bite me? Gotchas? Tech debt? |
 
+For monorepos and multi-repo setups, it maps each sub-project in parallel, then produces system-level docs (`PROJECTS.md`, `TOPOLOGY.md`, `CONTRACTS.md`, `CONCERNS.md`) at the orchestrator level.
+
 ### 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.
+
+Works with single projects and multi-project setups (monorepos, multi-repo). In multi-project mode, features are discussed at the system level and routed to the relevant sub-projects, with cross-project dependency tracking and contract validation.
+
+---
+
+## 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 +100,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
@@ -109,45 +108,43 @@ Work with individual phases — prepare, plan, and execute one at a time.
 /specd:map-codebase
 ```
 
-Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude context about your codebase's architecture, patterns, structure, and gotchas.
+Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude context about your codebase's architecture, patterns, structure, and gotchas. For multi-project setups, it detects sub-projects automatically and maps each one in parallel before producing system-level documentation.
 
 ### 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.
+That's it. `feature:next` reads the current state and guides you through each stage:
 
-**Step 3: Create a roadmap**
-
-```
-/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 +155,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?
-
-Output: `RESEARCH.md` with prescriptive guidance.
+**`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:
 
-**`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 +226,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 +245,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,60 +285,93 @@ 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
+```
+
+---
+
+## Multi-Project Support
+
+Specdacular supports monorepos and multi-repo setups through an orchestrator layer. All existing commands gain multi-project awareness automatically — no new commands to learn.
+
+### Setup
+
+```
+/specd:map-codebase
+```
+
+When it detects multiple projects (via `package.json`, `go.mod`, `Cargo.toml`, etc.), it offers to enable multi-project mode. This:
+
+1. Registers sub-projects in an orchestrator `.specd/config.json`
+2. Spawns 4 mapper agents per sub-project in parallel
+3. Runs an orchestrator mapper that produces system-level docs:
+
+| Document | What It Answers |
+|----------|-----------------|
+| `PROJECTS.md` | What projects exist, their tech stacks and purposes? |
+| `TOPOLOGY.md` | How do projects communicate? What's the data flow? |
+| `CONTRACTS.md` | What are the cross-project relationships and shared domains? |
+| `CONCERNS.md` | What are the system-level gotchas? |
+
+### Feature Planning
+
+`feature:new` conducts a system-level discussion, identifies which projects are involved, and creates per-project features with self-contained requirements. Each sub-project's `.specd/` works identically whether standalone or part of a multi-project setup.
+
+`feature:plan` creates per-project roadmaps plus a cross-project dependency graph (`DEPENDENCIES.md`) with cycle validation.
+
+### Execution & Scheduling
+
+`feature:next` schedules across projects, respecting cross-project dependencies. After each phase, it performs contract review — comparing what was implemented against system-level expectations and flagging deviations before they cascade to downstream projects.
+
+```
+/specd:feature:next auth-system       # Auto-picks next unblocked phase across projects
+/specd:feature:next auth-system api   # Target a specific sub-project
 ```
 
 ---
 
 ## Project Structure
 
-After using Specdacular:
+### Single Project
 
 ```
 your-project/
@@ -325,9 +392,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
@@ -336,6 +403,44 @@ your-project/
 └── ...
 ```
 
+### Multi-Project
+
+```
+monorepo/
+├── .specd/                         # Orchestrator level
+│   ├── config.json                 # type: "orchestrator", projects list
+│   ├── codebase/                   # System-level docs
+│   │   ├── PROJECTS.md
+│   │   ├── TOPOLOGY.md
+│   │   ├── CONTRACTS.md
+│   │   └── CONCERNS.md
+│   └── features/
+│       └── auth-system/
+│           ├── FEATURE.md          # System-level requirements
+│           ├── DEPENDENCIES.md     # Cross-project dependency graph
+│           └── STATE.md            # Cross-project progress
+│
+├── api/
+│   └── .specd/                     # Sub-project (works standalone too)
+│       ├── config.json             # type: "project"
+│       ├── codebase/
+│       │   ├── MAP.md
+│       │   ├── PATTERNS.md
+│       │   ├── STRUCTURE.md
+│       │   └── CONCERNS.md
+│       └── features/
+│           └── auth-system/
+│               ├── FEATURE.md      # Project-specific requirements
+│               ├── ROADMAP.md      # Per-project phases
+│               └── plans/...
+│
+└── web/
+    └── .specd/                     # Another sub-project
+        ├── config.json
+        ├── codebase/...
+        └── features/...
+```
+
 ---
 
 ## Philosophy
@@ -364,37 +469,6 @@ Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, c
 
 ---
 
-## Migrating from v0.4
-
-If you're upgrading from v0.4, here's what changed:
-
-**Commands were renamed** into `feature:` and `phase:` namespaces:
-
-| v0.4 | v0.5 |
-|------|------|
-| `/specd:new-feature` | `/specd:feature:new` |
-| `/specd:discuss-feature` | `/specd:feature:discuss` |
-| `/specd:research-feature` | `/specd:feature:research` |
-| `/specd:plan-feature` | `/specd:feature:plan` |
-| `/specd:discuss-phase` | `/specd:phase:prepare` |
-| `/specd:research-phase` | `/specd:phase:research` |
-| `/specd:execute-plan` | `/specd:phase:execute` |
-| `/specd:insert-phase` | `/specd:phase:insert` |
-| `/specd:renumber-phases` | `/specd:phase:renumber` |
-
-**New commands:**
-- `/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:**
-- `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.
-
-**Existing `.specd/` data is fully compatible.** Your feature files, decisions, and roadmaps work with the new commands.
-
----
-
 ## Updating
 
 ```bash
@@ -406,6 +480,8 @@ Or in Claude Code:
 /specd:update
 ```
 
+---
+
 ## Uninstalling
 
 ```bash
@@ -416,6 +492,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>