specdacular 0.8.1 → 0.9.2

package/README.md

@@ -25,8 +25,10 @@ npx specdacular
   - [Utilities](#utilities)
 - [The Flow in Detail](#the-flow-in-detail)
 - [How It Works](#how-it-works)
+  - [The Brain](#the-brain)
+  - [Pipeline Configuration](#pipeline-configuration)
+  - [Hooks](#hooks)
   - [Parallel Agents](#parallel-agents)
-  - [Task Flow](#task-flow)
 - [Multi-Project Support](#multi-project-support)
 - [Project Structure](#project-structure)
 - [Philosophy](#philosophy)
@@ -64,7 +66,7 @@ Three commands drive the entire task lifecycle:
 
 `continue` reads your task's current state and offers the natural next step. You never need to remember which command comes next.
 
-`toolbox` gives you direct access to advanced operations — discuss, research, plan, execute, review — when you want to jump to a specific action outside the normal flow.
+`toolbox` gives you direct access to advanced operations — discuss, research, plan, execute, review — and codebase context management (status dashboard, section-by-section review with edit/re-map/add).
 
 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.
 
@@ -127,8 +129,8 @@ That's it. `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
-3. **Planning** — Creates roadmap with phases, one PLAN.md per phase
-4. **Phase execution** — Implements with progress tracking
+3. **Planning** — Creates roadmap with phase goals
+4. **Phase execution** — Plans each phase just-in-time, then implements with progress tracking
 5. **Phase review** — Code review agent compares plans against actual code
 
 After each step, you can continue or stop. Resume anytime with `/specd:continue`.
@@ -136,8 +138,8 @@ After each step, you can continue or stop. Resume anytime with `/specd:continue`
 **Execution modes:**
 
 ```
-/specd:continue user-dashboard                # Interactive (default) — pause after each step
-/specd:continue user-dashboard --semi-auto    # Auto through planning, pause after review
+/specd:continue user-dashboard                # Default — auto-runs, pauses at phase steps
+/specd:continue user-dashboard --interactive  # Prompt at every step with skip/jump options
 /specd:continue user-dashboard --auto         # Run everything, stop only on review issues
 ```
 
@@ -155,7 +157,7 @@ Scans for in-progress tasks and shows a picker.
 /specd:toolbox user-dashboard
 ```
 
-Opens a menu with: Discuss, Research, Plan, Execute, Review. Useful when you want to jump to a specific action outside the normal flow.
+Opens a menu with task operations (Discuss, Research, Plan, Execute, Review) and context management (Status, Review). Useful when you want to jump to a specific action outside the normal flow.
 
 ---
 
@@ -166,14 +168,15 @@ Opens a menu with: Discuss, Research, Plan, Execute, Review. Useful when you wan
 | Command | Description |
 |---------|-------------|
 | `/specd:new [name]` | Initialize a task, start first discussion |
-| `/specd:continue [name] [--semi-auto\|--auto]` | **Drive the entire lifecycle** — picks up where you left off |
-| `/specd:toolbox [name]` | Advanced operations: discuss, research, plan, execute, review |
+| `/specd:continue [name] [--interactive\|--auto]` | **Drive the entire lifecycle** — picks up where you left off |
+| `/specd:toolbox [tasks name\|context]` | Task operations or codebase context management |
 
 ### Codebase Documentation
 
 | Command | Description |
 |---------|-------------|
 | `/specd:map-codebase` | Analyze codebase with parallel agents |
+| `/specd:toolbox context` | Status dashboard or section-by-section review |
 
 ### Utilities
 
@@ -195,26 +198,170 @@ Opens a menu with: Discuss, Research, Plan, Execute, Review. Useful when you wan
 - `STATE.md` — Progress tracking
 - `config.json` — Task configuration
 
-**`continue`** is the smart state machine. It reads `config.json` and `STATE.md` to determine where the task 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:
+**`continue`** delegates to the brain — a config-driven orchestrator that reads `pipeline.json` and drives the lifecycle. It determines the next step from task state, executes pre-hooks → step workflow → post-hooks, updates state, and loops. The default pipeline 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 one `phases/phase-NN/PLAN.md` per phase. Plans are self-contained prompts for an implementing agent.
-- **Phase execution** — Implements plans with verification after each task, commits per task, and progress tracking in `STATE.md`.
-- **Phase review** — Code review agent inspects executed code against plan intent using semantic analysis and git diff. Generates fix plans (decimal phases like `phase-01.1`) if needed.
+- **Planning** — Creates `ROADMAP.md` with phases derived from dependency analysis. Phase goals only — no detailed PLAN.md files yet.
+- **Phase execution** — Nested sub-pipeline that loops per phase: plan → execute → review → revise. Each phase gets just-in-time planning (detailed PLAN.md from ROADMAP.md goal), then implementation with verification, commits per task, and progress tracking. Later phases can adapt based on earlier execution.
+- **Phase review** — Code review agent inspects executed code against plan intent. Generates fix plans (decimal phases like `phase-01.1`) if needed.
+- **Revise** — Collects feedback from review, creates fix plans, signals brain to re-execute.
 
-**`toolbox`** provides direct access to advanced operations outside the normal flow:
+**`toolbox`** provides direct access to advanced operations outside the normal flow. Two subdomains:
 
+**Tasks** (`/specd:toolbox tasks my-feature`):
 - **Discuss** — Explore open questions, record decisions
 - **Research** — Spawn parallel agents for patterns/pitfalls
 - **Plan** — Create execution phases from task context
 - **Execute** — Execute the next phase's plan
 - **Review** — Review executed phase, approve or request fixes
 
+**Context** (`/specd:toolbox context`):
+- **Status** — Dashboard showing all context files with freshness indicators
+- **Review** — Section-by-section review of any context file: confirm, edit, remove, re-map (spawns a mapper agent to regenerate a section), or add new content. Sections are tracked with `AUTO_GENERATED` and `USER_MODIFIED` tags with dates.
+
 ---
 
 ## How It Works
 
+### The Brain
+
+The brain (`brain.md`) is a config-driven orchestrator that reads `pipeline.json` and drives the entire task lifecycle. Step workflows are pure execution — they do their work and return. The brain decides what comes next.
+
+```
+                        ┌─────────────────────┐
+                        │       BRAIN         │
+                        │  (config-driven     │
+                        │   orchestrator)     │
+                        └────────┬────────────┘
+                                 │
+                    ┌────────────┼────────────┐
+                    ▼            ▼            ▼
+              Read State   Load Pipeline   Check Mode
+                    │            │            │
+                    └────────────┼────────────┘
+                                 │
+                                 ▼
+                    ┌─────────────────────────┐
+                    │      Main Pipeline      │
+                    │                         │
+                    │  discuss → research →   │
+                    │  plan → phase-execution │
+                    └────────────┬────────────┘
+                                 │
+                         ┌───────┴───────┐
+                         ▼               │
+              ┌─────────────────────┐    │
+              │  Phase-Execution    │    │
+              │  Sub-Pipeline       │    │
+              │                     │    │
+              │  plan → execute →   │    │
+              │  review → revise   │    │
+              │      ──loop──┘     │    │
+              │                     │    │
+              │  Per phase, repeats │    │
+              │  until all phases   │    │
+              │  complete           │    │
+              └─────────────────────┘    │
+                         │               │
+                         └───────────────┘
+                                 │
+                                 ▼
+                          TASK COMPLETE
+```
+
+**The brain loop:**
+1. Read current state (`config.json`, `STATE.md`)
+2. Determine next step from pipeline config
+3. Execute pre-hooks → step workflow → post-hooks
+4. Update state → loop back
+
+**Execution modes:**
+
+| Mode | Behavior |
+|------|----------|
+| **Default** | Auto-runs steps, pauses where `pause: true`. Smart-skips unnecessary steps. |
+| **Interactive** (`--interactive`) | Prompts at each stage transition with skip/jump options |
+| **Auto** (`--auto`) | Runs everything, only stops on errors or task completion |
+
+### Pipeline Configuration
+
+The pipeline is defined in `pipeline.json` — nothing is hardcoded. The default pipeline ships with Specdacular and can be fully replaced by placing a `.specd/pipeline.json` in your project (full replace, not merge).
+
+**Default pipeline structure:**
+
+```json
+{
+  "schema_version": "1.0",
+  "pipelines": {
+    "main": [
+      { "name": "discuss",  "workflow": "discuss.md" },
+      { "name": "research", "workflow": "research.md" },
+      { "name": "plan",     "workflow": "plan.md" },
+      { "name": "phase-execution", "pipeline": "phase-execution" }
+    ],
+    "phase-execution": [
+      { "name": "plan",    "workflow": "phase-plan.md" },
+      { "name": "execute", "workflow": "execute.md", "pause": true },
+      { "name": "review",  "workflow": "review.md",  "pause": true },
+      { "name": "revise",  "workflow": "revise.md",  "pause": true }
+    ]
+  },
+  "hooks": { "pre-step": null, "post-step": null }
+}
+```
+
+**Customization options:**
+- **Swap workflows:** Point any step's `workflow` to your own `.md` file
+- **Add hooks:** Configure pre/post hooks per step or globally
+- **Full replace:** Drop `.specd/pipeline.json` to replace the entire pipeline
+
+### Hooks
+
+Hooks are markdown workflow files (`.md`) that run before and after pipeline steps. They can read and modify task files just like any other workflow.
+
+```
+  Global pre-step hook
+         │
+         ▼
+  Step pre-hook
+         │
+         ▼
+  ┌─────────────┐
+  │  Step runs   │
+  │  (discuss,   │
+  │   execute,   │
+  │   etc.)      │
+  └──────┬──────┘
+         │
+         ▼
+  Step post-hook
+         │
+         ▼
+  Global post-step hook
+```
+
+**Configuration in pipeline.json:**
+
+```json
+{
+  "name": "execute",
+  "workflow": "execute.md",
+  "hooks": {
+    "pre": { "workflow": ".specd/hooks/pre-execute.md", "mode": "inline", "optional": false },
+    "post": { "workflow": ".specd/hooks/post-execute.md", "mode": "subagent", "optional": true }
+  }
+}
+```
+
+**Hook modes:**
+- **`inline`** — Runs in the brain's context (can see all state)
+- **`subagent`** — Spawns a separate agent (fresh context, isolated)
+
+**Convention fallback:** If no hooks are configured explicitly, the brain checks for `.specd/hooks/pre-{step}.md` and `.specd/hooks/post-{step}.md` automatically.
+
+**Error handling:** Required hooks (`optional: false`) stop the pipeline on failure. Optional hooks log a warning and continue.
+
 ### Parallel Agents
 
 Specdacular spawns specialized agents that run simultaneously:
@@ -240,46 +387,6 @@ Specdacular spawns specialized agents that run simultaneously:
 - Faster execution (parallel, not sequential)
 - Agents write directly to files
 
-### Task Flow
-
-```
-/specd:new              /specd:continue
-      │                           │
-      ▼                           ▼
- Create task             ┌─── Read state ◀──────────────┐
- First discussion        │    Show status                │
- Offer to continue       │    Offer next step            │
-      │                  │         │                     │
-      ▼                  │         ▼                     │
- "Keep discussing?"      │   ┌──────────────┐           │
-  Yes → discuss loop     │   │  Execute the │           │
-  No  → continue         │   │  next action │           │
-                         │   └──────────────┘           │
-                         │         │                     │
-                         │    ┌────┴────┐                │
-                         │    │ Discuss │ Research       │
-                         │    │ Plan    │ Execute        │
-                         │    │ Review  │                │
-                         │    └────┬────┘                │
-                         │         │                     │
-                         │         ▼                     │
-                         │   "Continue or stop?"         │
-                         │    Continue ──────────────────┘
-                         │    Stop → clean exit
-                         │
-                         └─── No tasks? → /specd:new
-```
-
-**Under the hood,** `continue` delegates to specialized workflows:
-
-```
-discussion  → discuss workflow
-research    → research workflow (3 parallel agents)
-planning    → plan workflow
-execution   → execute workflow
-review      → review workflow (code review agent)
-```
-
 ---
 
 ## Multi-Project Support
@@ -329,6 +436,11 @@ Planning creates per-project roadmaps plus a cross-project dependency graph (`DE
 ```
 your-project/
 ├── .specd/
+│   ├── pipeline.json          # Optional — custom pipeline (full replace)
+│   ├── hooks/                 # Optional — convention-based hooks
+│   │   ├── pre-execute.md
+│   │   └── post-review.md
+│   │
 │   ├── codebase/              # From /specd:map-codebase
 │   │   ├── MAP.md
 │   │   ├── PATTERNS.md

package/commands/specd/continue.md

@@ -1,7 +1,7 @@
 ---
 name: specd:continue
 description: Continue task lifecycle — picks up where you left off
-argument-hint: "[task-name] [--semi-auto|--auto]"
+argument-hint: "[task-name] [--interactive|--auto]"
 allowed-tools:
   - Read
   - Write
@@ -14,22 +14,24 @@ allowed-tools:
 ---
 
 <objective>
-Smart state machine that reads current task state and drives the entire lifecycle. One command from discussion through execution and review.
+Config-driven orchestrator that reads pipeline.json and drives the entire task lifecycle. One command from discussion through execution and review.
 
 **Modes:**
-- **Default (interactive):** Prompts at each stage transition
-- **--semi-auto:** Auto-runs discuss→research→plan, pauses after each phase execution + review
-- **--auto:** Runs everything, only stops on review issues or task completion
+- **Default:** Auto-runs steps, pauses where `pause: true`. Smart-skips unnecessary steps.
+- **--interactive:** Prompts at every stage transition with skip/jump options
+- **--auto:** Runs everything, only stops on errors or task completion
 
 **How it works:**
 1. Select task (from argument or picker)
-2. Read current state
-3. Determine natural next step
-4. Execute it (delegating to workflows)
-5. Loop back — offer the next step or stop
+2. Load pipeline.json (user override or default)
+3. Read current state → determine next step
+4. Execute pre-hooks → step → post-hooks
+5. Update state → loop back or stop
 
-**Covers the full lifecycle:**
-- Discussion → Research → Planning → Execution → Review → Next phase
+**Pipeline customization:**
+- Place `.specd/pipeline.json` to fully replace the default pipeline
+- Swap any step's workflow to a custom `.md` file
+- Add pre/post hooks (markdown workflow files)
 </objective>
 
 <execution_context>
@@ -39,21 +41,27 @@ Smart state machine that reads current task state and drives the entire lifecycl
 <context>
 Task name and flags: $ARGUMENTS
 
+**Pipeline config:**
+@.specd/pipeline.json (user override, if exists)
+@~/.claude/specdacular/pipeline.json (default)
+
 **Scans for tasks:**
 @.specd/tasks/*/config.json
 
-**Delegates to workflows:**
+**Delegates to brain which dispatches:**
 @~/.claude/specdacular/workflows/discuss.md
 @~/.claude/specdacular/workflows/research.md
 @~/.claude/specdacular/workflows/plan.md
 @~/.claude/specdacular/workflows/execute.md
 @~/.claude/specdacular/workflows/review.md
+@~/.claude/specdacular/workflows/revise.md
 </context>
 
 <success_criteria>
 - [ ] Task selected (from argument or picker)
+- [ ] Pipeline loaded and validated
 - [ ] Current state accurately assessed
-- [ ] Correct next action offered/executed
-- [ ] Mode flags (--semi-auto, --auto) respected
+- [ ] Correct next step dispatched with hooks
+- [ ] Mode flags (--interactive, --auto) respected
 - [ ] User can stop at any natural boundary
 </success_criteria>

package/commands/specd/toolbox.md

@@ -1,7 +1,7 @@
 ---
 name: specd:toolbox
-description: "Advanced task operations — discuss, research, plan, execute, review"
-argument-hint: "[task-name]"
+description: "Advanced task operations and context management"
+argument-hint: "[tasks <task-name>|context]"
 allowed-tools:
   - Read
   - Write
@@ -16,18 +16,35 @@ allowed-tools:
 ---
 
 <objective>
-Menu of advanced task operations. Presents options and dispatches to the appropriate workflow.
-
-**Operations:**
-- **Discuss** — Explore open questions, record decisions
-- **Research** — Spawn parallel research agents
-- **Plan** — Create execution phases from task context
-- **Execute** — Execute the next phase's plan
-- **Review** — Review executed phase, approve or request fixes
+Toolbox with two subdomains:
+
+1. **tasks** — Task lifecycle operations (requires task name): discuss, research, plan, execute, review
+2. **context** — Codebase context management (no task name): review, add
 </objective>
 
 <execution_context>
-First, select the task using:
+**Parse $ARGUMENTS to determine subdomain:**
+
+- If starts with "tasks" → extract remaining words as task name, go to Tasks flow
+- If starts with "context" → go to Context flow
+- If a bare word that matches a directory in `.specd/tasks/` or `.specd/features/` → treat as `tasks {name}`
+- If empty or unrecognized → ask user which subdomain
+
+**If subdomain unclear, ask:**
+Use AskUserQuestion:
+- header: "Toolbox"
+- question: "Which toolbox?"
+- options:
+  - "Tasks" — Discuss, research, plan, execute, or review a task
+  - "Context" — Review or add to codebase context
+
+---
+
+## Tasks Flow
+
+Requires a task name. If not provided after "tasks", check `.specd/tasks/` for available tasks. If only one task exists, use it automatically. If multiple, ask.
+
+Validate using:
 @~/.claude/specdacular/references/validate-task.md
 
 Then present the menu using AskUserQuestion:
@@ -46,14 +63,41 @@ Based on selection, delegate to the appropriate workflow:
 - Plan → @~/.claude/specdacular/workflows/plan.md
 - Execute → @~/.claude/specdacular/workflows/execute.md
 - Review → @~/.claude/specdacular/workflows/review.md
+
+---
+
+## Context Flow
+
+No task name needed. Present the menu using AskUserQuestion:
+- header: "Context"
+- question: "What would you like to do with codebase context?"
+- options:
+  - "Review" — Walk through and review a context file section by section
+  - "Add" — Add new content to a context file
+
+Based on selection, delegate to the appropriate workflow:
+- Review → follow the context-manual-review.md workflow
+- Add → follow the context-add.md workflow
 </execution_context>
 
 <context>
-Task name: $ARGUMENTS
+Arguments: $ARGUMENTS
+
+**Task workflows:**
+@~/.claude/specdacular/workflows/discuss.md
+@~/.claude/specdacular/workflows/research.md
+@~/.claude/specdacular/workflows/plan.md
+@~/.claude/specdacular/workflows/execute.md
+@~/.claude/specdacular/workflows/review.md
+
+**Context workflows:**
+@~/.claude/specdacular/workflows/context-manual-review.md
+@~/.claude/specdacular/workflows/context-add.md
 </context>
 
 <success_criteria>
-- [ ] Task selected (from argument or picker)
-- [ ] Menu presented with operations
+- [ ] Subdomain selected (tasks or context) — from argument or prompt
+- [ ] For tasks: task validated and operation menu shown
+- [ ] For context: context operation menu shown
 - [ ] Selected operation executed via correct workflow
 </success_criteria>

package/package.json

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

package/specdacular/HELP.md

@@ -9,9 +9,9 @@
 | Command | Description |
 |---------|-------------|
 | `/specd:new [name]` | Initialize a task, start first discussion |
-| `/specd:continue [name] [--semi-auto\|--auto]` | Continue task lifecycle — picks up where you left off |
+| `/specd:continue [name] [--interactive\|--auto]` | Continue task lifecycle — picks up where you left off |
 
-| `/specd:toolbox [name]` | Advanced operations: discuss, research, plan, execute, review |
+| `/specd:toolbox [tasks <name>\|context]` | Task operations or context management |
 
 ### Utilities
 
@@ -38,13 +38,12 @@
    - 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
-   - Modes: interactive (default), `--semi-auto` (auto through planning, pause after review), `--auto` (run everything)
-3. **`/specd:toolbox [name]`** — Advanced operations menu:
-   - **Discuss** — Explore open questions, record decisions
-   - **Research** — Spawn parallel agents for patterns/pitfalls
-   - **Plan** — Create execution phases
-   - **Execute** — Execute the next phase
-   - **Review** — Review executed phase, approve or request fixes
+   - Modes: default (auto-runs, pauses at phase steps), `--interactive` (prompt at each step), `--auto` (run everything)
+3. **`/specd:toolbox`** — Two subdomains:
+   - **`/specd:toolbox tasks <name>`** — Task operations:
+     - Discuss, Research, Plan, Execute, Review
+   - **`/specd:toolbox context`** — Context management:
+     - Status, Review, Add
 
 ### Quick Start
 
@@ -57,6 +56,68 @@ After initialization, just keep running `continue`. It figures out what's next.
 
 ---
 
+## The Brain
+
+The `continue` command is powered by the **brain** — a config-driven orchestrator that reads `pipeline.json` and drives the entire task lifecycle. Step workflows are pure execution; the brain decides what comes next.
+
+**The brain loop:**
+1. Read current state (`config.json`, `STATE.md`)
+2. Determine next step from pipeline config
+3. Execute pre-hooks → step workflow → post-hooks
+4. Update state → loop back
+
+**Execution modes:**
+
+| Mode | Behavior |
+|------|----------|
+| **Default** | Auto-runs steps, pauses where `pause: true`. Smart-skips unnecessary steps. |
+| **Interactive** (`--interactive`) | Prompts at each stage transition with skip/jump options |
+| **Auto** (`--auto`) | Runs everything, only stops on errors or task completion |
+
+---
+
+## Pipeline Configuration
+
+The pipeline is defined in `pipeline.json` — nothing is hardcoded. The default pipeline ships with Specdacular and can be fully replaced by placing a `.specd/pipeline.json` in your project.
+
+**Default pipeline:** `discuss → research → plan → phase-execution (execute → review → revise loop)`
+
+**Customization options:**
+- **Swap workflows:** Point any step's `workflow` to your own `.md` file
+- **Add hooks:** Configure pre/post hooks per step or globally
+- **Full replace:** Drop `.specd/pipeline.json` to replace the entire pipeline
+
+---
+
+## Hooks
+
+Hooks are markdown workflow files that run before and after pipeline steps. They can read and modify task files just like any other workflow.
+
+**Execution order:** Global pre-step → Step pre-hook → **Step runs** → Step post-hook → Global post-step
+
+**Configuration in pipeline.json:**
+
+```json
+{
+  "name": "execute",
+  "workflow": "execute.md",
+  "hooks": {
+    "pre": { "workflow": ".specd/hooks/pre-execute.md", "mode": "inline" },
+    "post": { "workflow": ".specd/hooks/post-execute.md", "mode": "subagent", "optional": true }
+  }
+}
+```
+
+**Hook modes:**
+- **`inline`** — Runs in the brain's context (can see all state)
+- **`subagent`** — Spawns a separate agent (fresh context, isolated)
+
+**Convention fallback:** If no hooks are configured, the brain auto-discovers `.specd/hooks/pre-{step}.md` and `.specd/hooks/post-{step}.md`.
+
+**Error handling:** Required hooks (`optional: false`, default) stop the pipeline on failure. Optional hooks log a warning and continue.
+
+---
+
 ## Codebase Documentation
 
 ```