specdacular 0.8.1 → 0.9.2

package/specdacular/workflows/continue.md

@@ -1,263 +1,26 @@
 <purpose>
-Continue a task's lifecycle. Reads state, determines the next action, and either prompts (interactive), auto-advances (semi-auto), or runs everything (auto).
+Continue a task's lifecycle. Delegates to brain.md for all flow control, state routing, mode handling, and step dispatch.
 
-This is the main driver — it dispatches to discuss, research, plan, execute, and review workflows based on current state.
-
-**Modes:**
-- **Interactive (default):** 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
+This is a thin entry point — the brain does all the work.
 </purpose>
 
 <process>
 
-<step name="parse_args">
-Parse arguments to extract task name and mode.
-
-**Parse $ARGUMENTS:**
-- Extract task name (first argument, or only argument without --)
-- Check for `--semi-auto` flag
-- Check for `--auto` flag
-- Default mode: interactive
-
-```
-Mode: {interactive | semi-auto | auto}
-Task: {task-name}
-```
-
-Continue to validate.
-</step>
-
-<step name="validate">
-@~/.claude/specdacular/references/validate-task.md
-
-Use basic validation with $TASK_NAME.
-
-Continue to load_state.
-</step>
-
-<step name="load_state">
-Read current state to determine next action.
-
-**Read:**
-- `config.json` — stage, phases info
-- `STATE.md` — progress checkboxes
-- `CONTEXT.md` — gray areas remaining
-
-**Determine current position:**
-- stage from config.json: discussion, research, planning, execution
-- phases.current_status: pending, executing, executed, completed
-- Gray areas count from CONTEXT.md
-
-Continue to determine_action.
-</step>
-
-<step name="determine_action">
-Route to the appropriate action based on state.
-
-**Routing logic:**
-
-1. **Stage = discussion, gray areas remain:**
-   → action_discuss
-
-2. **Stage = discussion, no gray areas:**
-   → action_research_or_plan
-
-3. **Stage = research (RESEARCH.md missing):**
-   → action_research
-
-4. **Stage = planning (no phases exist):**
-   → action_plan
-
-5. **Stage = planning or execution, phases.current_status = "pending":**
-   → action_execute
-
-6. **Stage = execution, phases.current_status = "executing":**
-   → action_resume_execute
-
-7. **Stage = execution, phases.current_status = "executed":**
-   → action_review
-
-8. **Stage = execution, phases.current_status = "completed":**
-   Check if more phases remain:
-   - Yes → advance to next phase, → action_execute
-   - No → action_complete
-
-Continue to the determined action step.
-</step>
-
-<step name="action_discuss">
-Offer or auto-run discussion.
-
-**Interactive mode:**
-```
-**Current state:** Discussion in progress
-**Gray areas remaining:** {count}
-
-{list gray areas}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Want to discuss the remaining gray areas?"
-- options:
-  - "Discuss" — Dive into gray areas (Recommended)
-  - "Skip to research" — Move on without resolving
-  - "Skip to planning" — Jump straight to planning
-
-**Semi-auto / Auto mode:**
-Auto-run discuss workflow.
-
-Dispatch to: @~/.claude/specdacular/workflows/discuss.md
-
-After completion, return to load_state (re-evaluate).
-</step>
-
-<step name="action_research_or_plan">
-Offer or auto-run research (when discussion is complete but no research yet).
-
-**Interactive mode:**
-```
-**Current state:** Discussion complete, no research yet
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Discussion looks solid. What's next?"
-- options:
-  - "Research" — Investigate implementation patterns (Recommended)
-  - "Skip to planning" — Plan without research
-  - "Discuss more" — Continue discussion
-
-**Semi-auto / Auto mode:**
-Auto-run research workflow.
-
-Dispatch to chosen workflow. After completion, return to load_state.
-</step>
-
-<step name="action_research">
-Run research.
-
-**Interactive mode:**
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to research implementation patterns?"
-- options:
-  - "Research" — Run research agents (Recommended)
-  - "Skip" — Proceed without research
-  - "Discuss first" — Go back to discussion
-
-**Semi-auto / Auto mode:**
-Auto-run research.
-
-Dispatch to: @~/.claude/specdacular/workflows/research.md
-
-After completion, return to load_state.
-</step>
-
-<step name="action_plan">
-Run planning.
-
-**Interactive mode:**
-```
-**Current state:** Ready to plan
-{If RESEARCH.md exists: "Research available — will inform planning"}
-{If no RESEARCH.md: "Note: No research. Consider running /specd:research first"}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to create execution phases?"
-- options:
-  - "Plan" — Create phases and PLAN.md files (Recommended)
-  - "Research first" — Run research before planning
-  - "Discuss more" — Continue discussion
-
-**Semi-auto / Auto mode:**
-Auto-run planning.
-
-Dispatch to: @~/.claude/specdacular/workflows/plan.md
-
-After completion, return to load_state.
-</step>
-
-<step name="action_execute">
-Execute next phase.
-
-**Interactive mode:**
-```
-**Current state:** Phase {N} ready for execution
-**Phase:** {name} — {goal}
-**Tasks:** {count}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to execute Phase {N}?"
-- options:
-  - "Execute" — Start phase execution (Recommended)
-  - "Review plan" — Read the PLAN.md first
-  - "Stop for now" — Come back later
-
-**Semi-auto mode:**
-Auto-execute. Review will pause for user after execution.
-
-**Auto mode:**
-Auto-execute. Review auto-approves if clean, stops only on issues.
-
-Dispatch to: @~/.claude/specdacular/workflows/execute.md
-
-Execute workflow chains to review automatically. After review completes (phase approved or stopped), return to load_state.
-</step>
-
-<step name="action_resume_execute">
-Resume interrupted execution.
-
-```
-**Resuming:** Phase {N} execution was interrupted
-**Phase:** {name}
-```
-
-Dispatch to: @~/.claude/specdacular/workflows/execute.md
-
-The execute workflow handles finding incomplete tasks within the phase.
-
-After completion, return to load_state.
-</step>
-
-<step name="action_review">
-Phase executed, needs review.
-
-**Interactive mode:**
-```
-**Current state:** Phase {N} executed, pending review
-```
-
-Dispatch to: @~/.claude/specdacular/workflows/review.md
-
-After review completes, return to load_state.
-
-**Semi-auto mode:**
-Auto-trigger review. Review will prompt user for approval.
-
-**Auto mode:**
-Auto-trigger review. If clean, auto-approve. If issues found, stop for user.
-</step>
-
-<step name="action_complete">
-All phases complete.
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- TASK COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+<step name="delegate">
+Pass all arguments through to the brain.
 
-**Task:** {task-name}
-**Phases completed:** {N}
-**Decisions made:** {N}
+The brain handles:
+- Argument parsing (task name, --interactive/--auto flags)
+- Task validation
+- Pipeline resolution (pipeline.json)
+- State-based routing
+- Mode handling (default/interactive/auto)
+- Hook execution
+- Step dispatch
+- State transitions
+- Phase loop management
 
-All phases executed and reviewed. Task is done!
-```
+@~/.claude/specdacular/workflows/brain.md
 
 End workflow.
 </step>
@@ -265,11 +28,6 @@ End workflow.
 </process>
 
 <success_criteria>
-- Correctly reads state and determines next action
-- Interactive mode prompts at each transition
-- Semi-auto mode auto-advances through discuss→research→plan, pauses after phase execution + review
-- Auto mode runs everything, stops only on review issues or completion
-- Dispatches to correct workflow at each stage
-- Loops back to state check after each workflow completes
-- Handles all edge cases (interrupted execution, missing research, etc.)
+- All arguments forwarded to brain.md
+- Brain handles all orchestration
 </success_criteria>

package/specdacular/workflows/execute.md

@@ -1,14 +1,14 @@
 <purpose>
-Execute the next phase's PLAN.md. Runs tasks with verification, handles deviations, commits after each task, and automatically triggers review when the phase is complete.
+Execute the current phase's PLAN.md. Runs tasks with verification, handles deviations, commits after each task. Does NOT trigger review — the brain handles that.
 
-**Output:** Implemented code, CHANGELOG.md entries, automatic review trigger
+**Output:** Implemented code, CHANGELOG.md entries
 </purpose>
 
 <philosophy>
 
 ## One Phase at a Time
 
-Execute one phase's PLAN.md, then review before moving on. Never skip review.
+Execute one phase's PLAN.md. The brain decides what happens after.
 
 ## Verify Each Task
 
@@ -49,31 +49,21 @@ Continue to find_phase.
 </step>
 
 <step name="find_phase">
-Find the next phase to execute.
+Find the phase to execute.
 
 **Read config.json:**
 - `phases.current` — current phase number
-- `phases.current_status` — pending, executing, executed, completed
-
-**If current_status is "executed":**
-Phase is done but not reviewed. Trigger review:
-@~/.claude/specdacular/workflows/review.md
-End this workflow.
-
-**If current_status is "completed":**
-Advance to next phase:
-- Increment `phases.current`
-- Set `phases.current_status` to "pending"
+- `phases.current_status` — should be "pending" or "executing"
 
 **Find PLAN.md:**
 ```bash
-PHASE_DIR=".specd/tasks/$TASK_NAME/phases/phase-$(printf '%02d' $CURRENT_PHASE)"
+PHASE_DIR="$TASK_DIR/phases/phase-$(printf '%02d' $CURRENT_PHASE)"
 [ -f "$PHASE_DIR/PLAN.md" ] || { echo "no plan"; exit 1; }
 ```
 
 **Also check for fix plans (decimal phases):**
 ```bash
-ls -d .specd/tasks/$TASK_NAME/phases/phase-$CURRENT_PHASE.* 2>/dev/null
+ls -d $TASK_DIR/phases/phase-$(printf '%02d' $CURRENT_PHASE).* 2>/dev/null
 ```
 If fix plans exist and are incomplete, execute those first.
 
@@ -85,21 +75,11 @@ Continue to record_start.
 <step name="record_start">
 Record phase execution start.
 
-**If status is "pending" (first time executing this phase):**
+**If this is a fresh start (not resuming):**
 ```bash
 git rev-parse HEAD
 ```
-Store as `phases.phase_start_commit` in config.json.
-Set `phases.current_status` to "executing".
-
-Commit config update:
-```bash
-git add .specd/tasks/{task-name}/config.json
-git commit -m "docs({task-name}): start phase {N} execution"
-```
-
-**If status is already "executing":**
-Resuming — phase_start_commit already recorded.
+Store as `phases.phase_start_commit` in config.json if not already set.
 
 Continue to execute_tasks.
 </step>
@@ -137,29 +117,23 @@ Continue to phase_complete.
 </step>
 
 <step name="phase_complete">
-Mark phase as executed and trigger review.
-
-**Update config.json:**
-- Set `phases.current_status` to "executed"
+Mark phase execution as done.
 
 **Update STATE.md:**
-- Add phase to Completed Phases table
+- Add phase to Completed Phases table (or update if fix phase)
 - Update current phase info
 
 **Commit state:**
 @~/.claude/specdacular/references/commit-docs.md
-- **$FILES:** `.specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json .specd/tasks/{task-name}/CHANGELOG.md`
+- **$FILES:** `$TASK_DIR/STATE.md $TASK_DIR/CHANGELOG.md`
 - **$MESSAGE:** `docs({task-name}): phase {N} executed`
 - **$LABEL:** `phase execution complete`
 
-**Automatically trigger review:**
 ```
-Phase {N} execution complete. Starting code review...
+Phase {N} execution complete.
 ```
 
-@~/.claude/specdacular/workflows/review.md
-
-End workflow (review takes over).
+End workflow (caller handles continuation).
 </step>
 
 </process>
@@ -169,6 +143,5 @@ End workflow (review takes over).
 - Each task verified after implementation
 - Deviations logged in CHANGELOG.md
 - Code committed after each task
-- Phase marked as "executed" in config.json
-- Review automatically triggered after completion
+- Ends cleanly without dispatching review
 </success_criteria>

package/specdacular/workflows/map-codebase.md

@@ -609,6 +609,20 @@ Continue to commit_orchestrator_map.
 <step name="commit_orchestrator_map">
 Commit all mapping results (orchestrator + all sub-projects).
 
+**IMPORTANT — Check auto-commit setting first:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+**If `auto_commit_docs` is `false`:** Do NOT commit. Print:
+```
+Auto-commit disabled for docs — orchestrator codebase map not committed.
+```
+Skip to orchestrator_completion.
+
+**If `auto_commit_docs` is `true` or not set (default):**
+
 ```bash
 # Add orchestrator docs and config
 git add .specd/codebase/*.md .specd/config.json

package/specdacular/workflows/phase-plan.md

@@ -0,0 +1,142 @@
+<purpose>
+Create a detailed PLAN.md for the current phase. Reads the phase goal from ROADMAP.md, considers what happened in previous phases, and creates an actionable plan with tasks.
+
+This is the phase-level counterpart to plan.md (which creates the high-level ROADMAP.md). Each phase gets its own just-in-time planning, allowing later phases to adapt based on earlier execution.
+
+**Output:** `phases/phase-NN/PLAN.md`, updated STATE.md
+</purpose>
+
+<philosophy>
+
+## Just-In-Time Planning
+
+Plans are created when the phase starts, not upfront. This means the plan can account for deviations, discoveries, and changes from earlier phases.
+
+## Small and Focused
+
+One phase, one PLAN.md. 2-5 tasks. Each task creates or modifies 1-3 files.
+
+## Self-Contained Plans
+
+Each PLAN.md should have enough context that the executing agent doesn't need to ask questions. Reference decisions, research, and codebase patterns.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use basic validation with $TASK_NAME.
+
+Also check:
+- ROADMAP.md must exist (source of phase goals)
+- config.json must have phases.current set
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load all task context including RESEARCH.md if available.
+
+**Read phase info:**
+- `phases.current` from config.json → current phase number
+- Phase goal from ROADMAP.md → find the "Phase {N}" section
+
+**Read previous phase context (if not phase 1):**
+- Check completed phases for deviations in CHANGELOG.md
+- Read previous phase PLAN.md files to understand what was done
+- Note any decisions made during earlier execution
+
+**Read global config:**
+```bash
+cat .specd/config.json 2>/dev/null || echo '{}'
+```
+Check `auto_commit_docs` setting.
+
+Continue to create_plan.
+</step>
+
+<step name="create_plan">
+Create the phase directory and write PLAN.md.
+
+**Create phase directory:**
+```bash
+PHASE_NUM=$(printf '%02d' $CURRENT_PHASE)
+mkdir -p .specd/tasks/$TASK_NAME/phases/phase-$PHASE_NUM
+```
+
+**Write PLAN.md:**
+Use template from: `~/.claude/specdacular/templates/tasks/PLAN.md`
+
+Fill in based on ROADMAP.md goal and full task context:
+- Objective: what the phase accomplishes (from ROADMAP.md)
+- Context: reference codebase patterns, relevant decisions, research findings, previous phase outcomes
+- Tasks: 2-5 tasks with clear actions, verification, and done-when criteria
+
+**Each task should include:**
+- Files affected
+- Clear action description
+- Verification command
+- Done-when checklist
+
+**Adapt based on previous phases:**
+If earlier phases had deviations or discoveries, adjust this phase's plan accordingly. This is the key benefit of just-in-time planning.
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update STATE.md to note phase planning.
+
+**STATE.md:**
+- Note that phase {N} plan was created
+- Update documents status
+
+**Do NOT change config.json stage or phases.current_status.** The brain manages state transitions. Phase status stays "pending" — the brain will check for PLAN.md existence and route to execute next.
+
+Continue to commit.
+</step>
+
+<step name="commit">
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/{task-name}/phases/phase-{NN}/PLAN.md .specd/tasks/{task-name}/STATE.md`
+- **$MESSAGE:** `docs({task-name}): plan phase {N}` with brief plan summary
+- **$LABEL:** `phase planning`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present the phase plan.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE {N} PLANNED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+**Phase:** {N} — {phase title}
+**Tasks:** {count}
+
+{For each task:}
+Task {N}: {title}
+  Files: {file list}
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- Phase directory created
+- PLAN.md written with detailed tasks from ROADMAP.md goal
+- Previous phase outcomes considered in planning
+- STATE.md updated
+- Changes committed
+- config.json NOT modified (brain manages state)
+</success_criteria>

package/specdacular/workflows/plan.md

@@ -1,7 +1,7 @@
 <purpose>
-Create execution phases from task context. Derives phases based on dependencies, creates one PLAN.md per phase, and writes ROADMAP.md.
+Create a high-level execution roadmap from task context. Derives phases based on dependencies and writes ROADMAP.md with phase goals. Does NOT create PLAN.md files or phase directories — those are created just-in-time by phase-plan.md when each phase starts.
 
-**Output:** `phases/phase-NN/PLAN.md` files, ROADMAP.md, updated STATE.md
+**Output:** ROADMAP.md, updated STATE.md, config.json
 </purpose>
 
 <philosophy>
@@ -98,36 +98,7 @@ Break the task into ordered phases based on dependencies.
 - Each task creates or modifies 1-3 files
 - If a phase has >5 tasks, split it
 
-```bash
-mkdir -p .specd/tasks/{task-name}/phases
-```
-
-Continue to write_plans.
-</step>
-
-<step name="write_plans">
-Write one PLAN.md for each phase.
-
-For each phase:
-
-```bash
-mkdir -p .specd/tasks/{task-name}/phases/phase-$(printf '%02d' $N)
-```
-
-Write `phases/phase-NN/PLAN.md` using template from:
-`~/.claude/specdacular/templates/tasks/PLAN.md`
-
-Fill in:
-- YAML frontmatter: task name, phase number, dependencies, creates, modifies
-- Objective: what the phase accomplishes
-- Context: reference codebase patterns, relevant decisions, research findings
-- Tasks: 2-5 tasks with clear actions, verification, and done-when criteria
-
-**Each task should include:**
-- Files affected
-- Clear action description
-- Verification command
-- Done-when checklist
+**Do NOT create phase directories or PLAN.md files.** Those are created just-in-time by `phase-plan.md` when each phase starts execution. This allows later phases to adapt based on what happened in earlier phases.
 
 Continue to write_roadmap.
 </step>
@@ -151,9 +122,10 @@ Update STATE.md and config.json.
 - Update documents status
 
 **config.json:**
-- Set `stage` to `"planning"`
+- Set `stage` to `"execution"`
 - Set `phases.total` to phase count
 - Set `phases.current` to 1
+- Set `phases.current_status` to `"pending"`
 
 Continue to commit.
 </step>
@@ -161,7 +133,7 @@ Continue to commit.
 <step name="commit">
 @~/.claude/specdacular/references/commit-docs.md
 
-- **$FILES:** `.specd/tasks/{task-name}/ROADMAP.md .specd/tasks/{task-name}/phases/ .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
+- **$FILES:** `.specd/tasks/{task-name}/ROADMAP.md .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
 - **$MESSAGE:** `docs({task-name}): create roadmap and phase plans` with phase summary
 - **$LABEL:** `planning complete`
 
@@ -194,8 +166,9 @@ End workflow (caller handles continuation).
 
 <success_criteria>
 - Phases derived from task requirements and dependencies
-- One PLAN.md per phase with clear tasks
-- ROADMAP.md created with phase overview
-- STATE.md updated to planning stage
+- ROADMAP.md created with phase goals and scope (no PLAN.md files)
+- No phase directories created (just-in-time by phase-plan.md)
+- STATE.md updated
+- config.json set to execution stage with phases info
 - Changes committed
 </success_criteria>