specdacular 0.7.0 → 0.7.1

package/README.md

@@ -20,13 +20,10 @@ npx specdacular
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Commands](#commands)
-  - [Feature Commands](#feature-commands-feature)
-  - [Phase Commands](#phase-commands-phase)
+  - [Core Flow](#core-flow)
   - [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)
@@ -57,14 +54,17 @@ For monorepos and multi-repo setups, it maps each sub-project in parallel, then
 
 ### 2. Plan Features
 
-Two commands drive the entire feature lifecycle:
+Three commands drive the entire feature lifecycle:
 
 ```
-/specd:feature:new my-feature     # Initialize + first discussion
-/specd:feature:next my-feature    # Everything else — discussion, research, planning, execution, review
+/specd:feature:new my-feature         # Initialize + first discussion
+/specd:feature:continue my-feature    # Everything else — discussion, research, planning, execution, review
+/specd:feature:toolbox my-feature     # Advanced operations menu
 ```
 
-`feature:next` reads your feature's current state and offers the natural next step. You never need to remember which command comes next.
+`feature:continue` reads your feature's current state and offers the natural next step. You never need to remember which command comes next.
+
+`feature:toolbox` gives you direct access to advanced operations — discuss, research, plan, review, or insert a phase — when you want to jump to a specific action outside the normal flow.
 
 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.
 
@@ -120,10 +120,10 @@ Creates `.specd/features/user-dashboard/` and starts the first discussion. Claud
 **Step 2: Drive the lifecycle**
 
 ```
-/specd:feature:next user-dashboard
+/specd:feature:continue user-dashboard
 ```
 
-That's it. `feature:next` reads the current state and guides you through each stage:
+That's it. `feature:continue` reads the current state and guides you through each stage:
 
 1. **Discussion** — Probes gray areas until clear
 2. **Research** — Spawns parallel agents for patterns/pitfalls
@@ -133,51 +133,35 @@ That's it. `feature:next` reads the current state and guides you through each st
 6. **Phase execution** — Implements with progress tracking
 7. **Phase review** — Compares plans against actual code
 
-After each step, you can continue or stop. Resume anytime with `/specd:feature:next`.
+After each step, you can continue or stop. Resume anytime with `/specd:feature:continue`.
 
 **No argument? It picks for you:**
 
 ```
-/specd:feature:next
+/specd:feature:continue
 ```
 
 Scans for in-progress features and shows a picker.
 
-**Mid-flight adjustments:**
+**Need a specific operation?**
 
 ```
-/specd:phase:insert user-dashboard 3 "Cache layer"  # Insert Phase 3.1
-/specd:phase:renumber user-dashboard                 # Clean up to integers
+/specd:feature:toolbox user-dashboard
 ```
 
+Opens a menu with: Discuss, Research, Plan, Review, Insert phase. Useful when you want to jump to a specific action — like running research mid-execution or inserting a phase between existing ones.
+
 ---
 
 ## 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.
+### Core Flow
 
 | 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 |
+| `/specd:feature:continue [name]` | **Drive the entire lifecycle** — picks up where you left off |
+| `/specd:feature:toolbox [name]` | Advanced operations: discuss, research, plan, review, insert |
 
 ### Codebase Documentation
 
@@ -190,7 +174,6 @@ Work with individual phases — prepare, plan, and execute one at a time.
 | 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 |
 
@@ -198,58 +181,30 @@ Work with individual phases — prepare, plan, and execute one at a time.
 
 ## The Flow in Detail
 
-### Feature-Level Commands
-
-**`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:new`** creates the feature folder and starts the first discussion. After initialization, offers to continue discussing or come back later with `feature:continue`. 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: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:continue`** 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:
 
 - **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 preparation** — Discusses phase-specific gray areas, records resolutions to phase `CONTEXT.md` and `DECISIONS.md`. Optionally spawns research agents focused on the phase.
+- **Phase planning** — Creates detailed PLAN.md files. Each plan is a self-contained prompt for an implementing agent with exact file paths, code patterns, verification commands, and completion criteria. Plans are created just-in-time so they incorporate all context from preparation and earlier phases.
+- **Phase execution** — Implements plans with auto-fix for bugs/blockers, user confirmation for architectural changes, verification after each task, commits, and progress tracking in `STATE.md`.
+- **Phase review** — Reviews executed plans against actual code using git diff. Generates corrective plans if needed (fed back into execution). Review cycle tracked in `STATE.md`.
 
-### Phase-Level Commands
-
-**`phase:prepare`** is the main pre-execution command. It:
-1. Shows the phase overview (goal, deliverables, existing context)
-2. Identifies gray areas based on phase type (Types, API, UI, etc.)
-3. Probes until clear (4 questions max per area)
-4. Records resolutions to phase `CONTEXT.md` and `DECISIONS.md`
-5. **Offers research** — "Would you like to research implementation patterns?"
-6. If yes, spawns 3 parallel research agents focused on the 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:
-- Exact file paths to create/modify
-- Code patterns to follow (from codebase docs)
-- Verification commands to run
-- Clear completion criteria
-
-Plans are created just-in-time — right before execution — so they incorporate all context from preparation and earlier phases.
+**`feature:toolbox`** provides direct access to advanced operations outside the normal flow:
 
-**`phase:execute`** executes plans with:
-- Auto-fix for bugs/blockers (logged to `CHANGELOG.md`)
-- User confirmation for architectural changes
-- Verification after each task
-- Commits after each task
-- Progress tracking in `STATE.md`
-
-**`phase:review`** reviews executed plans against actual code:
-- Claude inspects each plan's `creates`/`modifies` against actual files
-- 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`
-
-**`phase:insert`** adds a new phase using decimal numbering (e.g., Phase 3.1 after Phase 3). The `(INSERTED)` marker in `ROADMAP.md` identifies mid-flight additions.
-
-**`phase:renumber`** cleans up decimal phases to sequential integers after insertions stabilize.
+- **Discuss** — Explore open questions at the feature or phase level
+- **Research** — Spawn parallel agents for patterns/pitfalls
+- **Plan** — Create implementation plans for a specific phase
+- **Review** — Review executed work and report issues
+- **Insert phase** — Add a phase mid-development using decimal numbering (e.g., Phase 3.1 after Phase 3)
 
 ---
 
@@ -282,10 +237,8 @@ Specdacular spawns specialized agents that run simultaneously:
 
 ### Feature Flow
 
-**The simple way** — two commands:
-
 ```
-/specd:feature:new          /specd:feature:next
+/specd:feature:new        /specd:feature:continue
       │                           │
       ▼                           ▼
  Create feature          ┌─── Read state ◀──────────────┐
@@ -295,7 +248,7 @@ Specdacular spawns specialized agents that run simultaneously:
       ▼                  │         ▼                     │
  "Keep discussing?"      │   ┌──────────────┐           │
   Yes → discuss loop     │   │  Execute the │           │
-  No  → feature:next     │   │  next action │           │
+  No  → feature:continue │   │  next action │           │
                          │   └──────────────┘           │
                          │         │                     │
                          │    ┌────┴────┐                │
@@ -312,7 +265,7 @@ Specdacular spawns specialized agents that run simultaneously:
                          └─── No features? → feature:new
 ```
 
-**Under the hood,** `feature:next` delegates to the same workflows as the individual commands:
+**Under the hood,** `feature:continue` delegates to the same workflows as the toolbox operations:
 
 ```
 discussion  → discuss-feature workflow
@@ -321,7 +274,7 @@ planning    → plan-feature workflow
 phase prep  → prepare-phase workflow
 phase plan  → plan-phase workflow
 execution   → execute-plan workflow
-review      → review-phase workflow
+review      → review-feature workflow
 ```
 
 ---
@@ -353,15 +306,15 @@ When it detects multiple projects (via `package.json`, `go.mod`, `Cargo.toml`, e
 
 `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.
+Planning 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.
+`feature:continue` 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
+/specd:feature:continue auth-system       # Auto-picks next unblocked phase across projects
+/specd:feature:continue auth-system api   # Target a specific sub-project
 ```
 
 ---

package/commands/specd/feature/{next.md → continue.md}

@@ -1,6 +1,6 @@
 ---
-name: specd:feature:next
-description: Drive feature lifecycle — picks up where you left off and guides next steps
+name: specd:feature:continue
+description: Continue feature lifecycle — picks up where you left off
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -31,13 +31,13 @@ Smart state machine that reads current feature state and drives the entire lifec
 - Phase preparation (phase-specific discussion + research)
 - Phase planning (detailed PLAN.md files)
 - Phase execution (with progress tracking)
-- Phase review (compare plans vs actual code)
+- Phase review (review executed work, user-guided)
 
-**No need to remember individual commands.** This one command figures out what's next.
+**No need to remember individual commands.** This one command figures out what to do.
 </objective>
 
 <execution_context>
-@~/.claude/specdacular/workflows/next-feature.md
+@~/.claude/specdacular/workflows/continue-feature.md
 </execution_context>
 
 <context>
@@ -61,7 +61,7 @@ Feature name: $ARGUMENTS
 @~/.claude/specdacular/workflows/prepare-phase.md
 @~/.claude/specdacular/workflows/plan-phase.md
 @~/.claude/specdacular/workflows/execute-plan.md
-@~/.claude/specdacular/workflows/review-phase.md
+@~/.claude/specdacular/workflows/review-feature.md
 </context>
 
 <process>

package/commands/specd/feature/new.md

@@ -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, continue with `/specd:feature:next` to drive the entire lifecycle.
+**This is the entry point.** After this, continue with `/specd:feature:continue` 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 offered to continue discussing or stop with `/specd:feature:next`
+- [ ] User offered to continue discussing or stop with `/specd:feature:continue`
 </success_criteria>

package/commands/specd/feature/toolbox.md

@@ -0,0 +1,49 @@
+---
+name: specd:feature:toolbox
+description: Advanced feature operations — discuss, research, plan, review, insert
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Menu of advanced feature operations. Presents options and dispatches to the appropriate workflow.
+
+**Operations:**
+- Discuss — Explore open questions (feature or phase level)
+- Research — Spawn parallel research agents (feature or phase level)
+- Plan — Create implementation plans (feature or phase level)
+- Review — Review executed work, report issues, generate fix plans
+- Insert phase — Add a new phase with decimal numbering
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/toolbox.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS
+
+**Delegates to workflows:**
+@~/.claude/specdacular/workflows/discuss-feature.md
+@~/.claude/specdacular/workflows/research-feature.md
+@~/.claude/specdacular/workflows/plan-feature.md
+@~/.claude/specdacular/workflows/review-feature.md
+@~/.claude/specdacular/workflows/insert-phase.md
+@~/.claude/specdacular/workflows/prepare-phase.md
+@~/.claude/specdacular/workflows/plan-phase.md
+</context>
+
+<success_criteria>
+- [ ] Feature selected (from argument or picker)
+- [ ] Menu presented with all 5 operations
+- [ ] Selected operation executed via correct workflow
+- [ ] Scope selection works for discuss/research/plan
+</success_criteria>

package/commands/specd/help.md

@@ -5,149 +5,4 @@ allowed-tools:
   - Read
 ---
 
-<objective>
-Display available specdacular commands and usage guidance.
-</objective>
-
-<output>
-# Specdacular
-
-**AI-optimized codebase documentation and feature planning for Claude.**
-
-## Commands
-
-### Codebase Documentation
-
-| Command | Description |
-|---------|-------------|
-| `/specd:map-codebase` | Analyze codebase with parallel agents -> produce AI-optimized docs |
-
-### Feature Commands
-
-| Command | Description |
-|---------|-------------|
-| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
-| `/specd:feature:discuss [name]` | Continue/deepen feature discussion (can call many times) |
-| `/specd:feature:research [name]` | Research implementation with parallel agents |
-| `/specd:feature:plan [name]` | Create roadmap with phase overview |
-
-### Phase Commands
-
-| 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] [plan]` | Execute a plan 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 |
-
-### Other
-
-| Command | Description |
-|---------|-------------|
-| `/specd:config` | Create or update `.specd/config.json` with commit settings |
-| `/specd:status [--all]` | Show feature status dashboard |
-| `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
-| `/specd:update` | Update Specdacular to the latest version |
-| `/specd:help` | Show this help |
-
----
-
-## Feature Flow
-
-The feature flow helps you plan features specific enough that an agent can implement without asking questions.
-
-```
-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
-```
-
-**You control the rhythm:**
-- `feature:new` — Creates structure, asks initial questions, starts first discussion
-- `feature:discuss` — Can be called **many times** to refine understanding
-- `feature:research` — Can be called **many times** to investigate
-- `feature:plan` — Creates roadmap with phases (no detailed plans yet)
-- `phase:prepare` — Discuss gray areas + optionally research (per phase)
-- `phase:plan` — Create detailed PLAN.md files for one phase
-- `phase:execute` — Execute plans with progress tracking
-- `phase:review` — Review executed plans, generate corrective plans if needed
-- `phase:insert` — Insert a new phase mid-flight with decimal numbering (e.g., Phase 3.1)
-- `phase:renumber` — Clean up decimal phases to sequential integers
-
-### Quick Start
-
-```
-/specd:feature:new user-dashboard
-```
-
-This creates `.specd/features/user-dashboard/` with:
-- `FEATURE.md` — Technical requirements
-- `CONTEXT.md` — Discussion context (accumulates)
-- `DECISIONS.md` — User-driven decisions with dates and rationale
-- `CHANGELOG.md` — Auto-captured implementation decisions during execution
-- `STATE.md` — Progress tracking
-
-After initialization, refine and plan:
-
-```
-/specd:feature:discuss user-dashboard    # Clarify gray areas
-/specd:feature:research user-dashboard   # Research implementation
-/specd:feature:plan user-dashboard       # Create roadmap
-```
-
-Then for each phase:
-
-```
-/specd:phase:prepare user-dashboard 1    # Discuss + optionally research
-/specd:phase:plan user-dashboard 1       # Create detailed plans
-/specd:phase:execute user-dashboard      # Execute with progress tracking
-/specd:phase:review user-dashboard 1     # Review phase against actual code
-```
-
----
-
-## Codebase Documentation
-
-```
-/specd:map-codebase
-```
-
-Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
-
-| Document | What it contains |
-|----------|------------------|
-| **MAP.md** | Navigation: modules, functions, entry points |
-| **PATTERNS.md** | Code examples: services, errors, testing |
-| **STRUCTURE.md** | Organization: where to put new code |
-| **CONCERNS.md** | Warnings: gotchas, anti-patterns, debt |
-
-### Philosophy
-
-These docs are **for Claude, not humans**.
-
-Each document answers a question Claude can't get from reading code:
-- MAP.md -> "Where is X? What functions exist?"
-- PATTERNS.md -> "How do I write code that fits?"
-- STRUCTURE.md -> "Where do I put new code?"
-- CONCERNS.md -> "What will bite me?"
-
-**Principle:** Don't document what Claude can grep. Document tribal knowledge, gotchas, and patterns.
-
----
-
-## Updating
-
-When an update is available, you'll see `update available` in your statusline. Run:
-```
-/specd:update
-```
-Or manually: `npx specdacular@latest`
-
----
-
-GitHub: https://github.com/vlad-ds/specdacular
-</output>
+Read the file at `~/.claude/specdacular/HELP.md` and output its entire contents to the user as-is. Do not summarize, truncate, or add commentary.

package/commands/specd/update.md

@@ -21,22 +21,20 @@ cat ~/.claude/specdacular/VERSION 2>/dev/null || cat .claude/specdacular/VERSION
 npm view specdacular version
 ```
 
-3. If already on latest, inform user and exit.
-
-4. If update available, run the installer:
+3. Always run the installer to ensure old commands are cleaned up and replaced with fresh ones (even if versions match):
 ```bash
 npx specdacular@latest --global
 ```
 
-5. Show new version:
+4. Show new version:
 ```bash
 cat ~/.claude/specdacular/VERSION 2>/dev/null || cat .claude/specdacular/VERSION 2>/dev/null
 ```
 
-6. Clear the update cache:
+5. Clear the update cache:
 ```bash
 rm -f ~/.claude/cache/specd-update-check.json
 ```
 
-7. Inform user the update is complete and they may want to restart Claude Code to pick up any new commands.
+6. If versions were the same, inform user commands were refreshed. If version changed, inform user of the update. Suggest restarting Claude Code to pick up any command changes.
 </process>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
     "specdacular": "bin/install.js"

package/specdacular/HELP.md

@@ -0,0 +1,84 @@
+# Specdacular
+
+**AI-optimized codebase documentation and feature planning for Claude.**
+
+## Commands
+
+### Core Flow
+
+| Command | Description |
+|---------|-------------|
+| `/specd:feature:new [name]` | Initialize a feature, start first discussion |
+| `/specd:feature:continue [name]` | Continue feature lifecycle — picks up where you left off |
+| `/specd:feature:toolbox [name]` | Advanced operations: discuss, research, plan, review, insert |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents → AI-optimized docs |
+| `/specd:status [--all]` | Show feature status dashboard |
+| `/specd:help` | Show this help |
+| `/specd:update` | Update Specdacular to the latest version |
+
+---
+
+## Feature Flow
+
+```
+/specd:feature:new → /specd:feature:continue → continue → continue → done
+```
+
+**You only need three commands:**
+
+1. **`/specd:feature:new [name]`** — Start here. Creates feature folder, asks initial questions.
+2. **`/specd:feature:continue [name]`** — Picks up where you left off. Drives the entire lifecycle:
+   - Discussion → Research → Planning → Phase Execution → Review
+   - After each step, offers the next step or "stop for now"
+   - Works across context windows — reads state fresh each time
+3. **`/specd:feature:toolbox [name]`** — Advanced operations menu:
+   - **Discuss** — Explore open questions (feature or phase level)
+   - **Research** — Spawn parallel agents for patterns/pitfalls
+   - **Plan** — Create implementation plans
+   - **Review** — Review executed work, report issues
+   - **Insert phase** — Add a phase mid-development (decimal numbering)
+
+### Quick Start
+
+```
+/specd:feature:new user-dashboard
+/specd:feature:continue user-dashboard
+```
+
+After initialization, just keep running `continue`. It figures out what's next.
+
+---
+
+## Codebase Documentation
+
+```
+/specd:map-codebase
+```
+
+Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
+
+| Document | What it contains |
+|----------|------------------|
+| **MAP.md** | Navigation: modules, functions, entry points |
+| **PATTERNS.md** | Code examples: services, errors, testing |
+| **STRUCTURE.md** | Organization: where to put new code |
+| **CONCERNS.md** | Warnings: gotchas, anti-patterns, debt |
+
+---
+
+## Updating
+
+When an update is available, you'll see `update available` in your statusline. Run:
+```
+/specd:update
+```
+Or manually: `npx specdacular@latest`
+
+---
+
+GitHub: https://github.com/vlad-ds/specdacular

package/specdacular/references/commit-code.md

@@ -0,0 +1,34 @@
+<shared name="commit_code">
+
+## Auto-Commit Code
+
+Commit implementation code changes, respecting the user's auto-commit setting.
+
+**Before using this reference, you must have ready:**
+- `$FILES` — the files to `git add` (space-separated paths)
+- `$MESSAGE` — the commit message
+
+**Check auto-commit setting:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_code": true}'
+```
+
+**If `auto_commit_code` is `false`:**
+Do NOT run git commands. Instead print:
+
+```
+Auto-commit disabled for code — changes not committed.
+Modified files: $FILES
+```
+
+Then skip ahead to the next step in your workflow.
+
+**If `auto_commit_code` is `true` or not set (default):**
+
+```bash
+git add $FILES
+git commit -m "$MESSAGE"
+```
+
+</shared>