specdacular 0.8.0 → 0.9.2

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/new.md

@@ -52,10 +52,10 @@ Ask: "What's the name of this task?"
 
 **Validate:**
 - Task name should be kebab-case
-- Check if `.specd/tasks/{name}/` already exists
+- Check if task already exists (in either `.specd/tasks/` or `.specd/features/`)
 
 ```bash
-[ -d ".specd/tasks/$TASK_NAME" ] && echo "exists"
+{ [ -d ".specd/tasks/$TASK_NAME" ] || [ -d ".specd/features/$TASK_NAME" ]; } && echo "exists"
 ```
 
 **If task exists:**

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>

package/specdacular/workflows/research.md

@@ -42,9 +42,22 @@ Load all task context. Extract:
 - Technology stack (from codebase docs if available)
 - Files to create/modify (from FEATURE.md)
 
+**Detect phase-level research:**
+Read `.specd/tasks/$TASK_NAME/config.json`. If `stage` is `"execution"`, this is phase-level research:
+- Read `phases.current` to determine the current phase number
+- Set `$PHASE_NUM` to the zero-padded phase number (e.g., `01`)
+- Read the phase plan: `.specd/tasks/$TASK_NAME/phases/phase-$PHASE_NUM/PLAN.md`
+- Append the phase plan contents to `$TASK_CONTEXT` so research agents have phase-specific context
+- Set `$RESEARCH_OUTPUT` to `.specd/tasks/$TASK_NAME/phases/phase-$PHASE_NUM/RESEARCH.md`
+- Set `$PHASE_LEVEL = true`
+
+**If not in execution stage (task-level research):**
+- Set `$RESEARCH_OUTPUT` to `.specd/tasks/$TASK_NAME/RESEARCH.md`
+- Set `$PHASE_LEVEL = false`
+
 **Check if RESEARCH.md already exists:**
 ```bash
-[ -f ".specd/tasks/$TASK_NAME/RESEARCH.md" ] && echo "existing"
+[ -f "$RESEARCH_OUTPUT" ] && echo "existing"
 ```
 
 **If exists:**
@@ -93,7 +106,7 @@ Continue to synthesize.
 <step name="synthesize">
 @~/.claude/specdacular/references/synthesize-research.md
 
-Combine agent outputs into `.specd/tasks/$TASK_NAME/RESEARCH.md`.
+Combine agent outputs into `$RESEARCH_OUTPUT`.
 
 Continue to record_decisions.
 </step>
@@ -109,10 +122,15 @@ Continue to update_state.
 <step name="update_state">
 Update STATE.md and config.json.
 
-**STATE.md:**
-- Mark research as conducted
+**If phase-level research (`$PHASE_LEVEL = true`):**
+- Update STATE.md to note phase research was conducted
+- Do NOT change `stage` in config.json (stay in "execution")
+- Continue to commit
+
+**If task-level research (`$PHASE_LEVEL = false`):**
+- Mark research as conducted in STATE.md
 - Mark RESEARCH.md as created
-- Update decisions count
+- Update decisions count in STATE.md and config.json
 
 **config.json:**
 - Update `decisions_count`
@@ -123,8 +141,8 @@ Continue to commit.
 <step name="commit">
 @~/.claude/specdacular/references/commit-docs.md
 
-- **$FILES:** `.specd/tasks/{task-name}/RESEARCH.md .specd/tasks/{task-name}/DECISIONS.md .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
-- **$MESSAGE:** `docs({task-name}): research complete` with key findings summary
+- **$FILES:** `$RESEARCH_OUTPUT .specd/tasks/{task-name}/DECISIONS.md .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
+- **$MESSAGE:** `docs({task-name}): research complete` (or `docs({task-name}): phase {NN} research complete` for phase-level) with key findings summary
 - **$LABEL:** `research findings`
 
 Continue to completion.

package/specdacular/workflows/review.md

@@ -3,7 +3,7 @@ Review executed phase by comparing plan intent against actual code. Combines sem
 
 **Core principle:** Claude inspects first, then shows findings to user. User decides.
 
-**Output:** Phase approved (advance to next) or fix plans in decimal phases (e.g., phase-01.1/)
+**Output:** Review findings presented, user choice recorded for brain routing (approve, revise, or stop).
 </purpose>
 
 <philosophy>
@@ -16,10 +16,6 @@ Plans describe intent. Code implements intent. Check whether intent was fulfille
 
 Claude reads the code and compares against the plan first. Then presents findings with the git diff. The user gets a curated view, not a raw dump.
 
-## Fix Plans, Not Inline Fixes
-
-When the user reports issues, create proper PLAN.md files in decimal phases. These get executed through the same execute workflow.
-
 ## Deviations Are Neutral
 
 A deviation means code differs from plan. It might be an improvement. The review surfaces it; the user decides.
@@ -32,17 +28,8 @@ A deviation means code differs from plan. It might be an improvement. The review
 @~/.claude/specdacular/references/validate-task.md
 
 Use extended validation. Also check:
-- `config.json` → `phases.current_status` must be "executed"
 - `config.json` → `phases.phase_start_commit` must exist
 
-**If status is not "executed":**
-```
-Phase {N} is not ready for review (status: {status}).
-
-Run /specd:continue {task-name} to get to the right step.
-```
-End workflow.
-
 Continue to load_context.
 </step>
 
@@ -53,14 +40,14 @@ Load all context including the current phase's PLAN.md.
 
 **Read phase plan:**
 ```bash
-PHASE_NUM=$(cat .specd/tasks/$TASK_NAME/config.json | grep -o '"current": [0-9]*' | grep -o '[0-9]*')
-PHASE_DIR=".specd/tasks/$TASK_NAME/phases/phase-$(printf '%02d' $PHASE_NUM)"
+PHASE_NUM=$(cat $TASK_DIR/config.json | grep -o '"current": [0-9]*' | grep -o '[0-9]*')
+PHASE_DIR="$TASK_DIR/phases/phase-$(printf '%02d' $PHASE_NUM)"
 cat "$PHASE_DIR/PLAN.md"
 ```
 
 **Get phase start commit:**
 ```bash
-cat .specd/tasks/$TASK_NAME/config.json | grep phase_start_commit
+cat $TASK_DIR/config.json | grep phase_start_commit
 ```
 
 Continue to inspect_code.
@@ -156,121 +143,11 @@ Use AskUserQuestion:
   - "I have concerns" — Describe issues
   - "Stop for now" — Come back later
 
-**If "Looks good":**
-Continue to approve_phase.
-
-**If "I want to revise" or "I have concerns":**
-Continue to collect_feedback.
-
-**If "Stop for now":**
-```
-Progress saved. Phase stays in "executed" state.
-Resume review with /specd:continue {task-name}
-```
-End workflow.
-</step>
-
-<step name="collect_feedback">
-Gather specific feedback from user.
-
-```
-Tell me what needs fixing. You can describe:
-- Bugs or incorrect behavior
-- Approach you'd prefer changed
-- Missing functionality
-- Code quality issues
-
-Describe as many issues as you want — I'll create a fix plan for all of them.
-```
-
-Wait for user response. Follow up to understand each issue clearly.
-
-Continue to create_fix_plan.
-</step>
-
-<step name="create_fix_plan">
-Create a fix plan in a decimal phase.
-
-**Determine fix phase number:**
-```bash
-ls -d .specd/tasks/$TASK_NAME/phases/phase-$CURRENT.* 2>/dev/null | sort -V | tail -1
-```
-- If no decimal phases → create `phase-{N}.1/`
-- If `phase-{N}.1/` exists → create `phase-{N}.2/`, etc.
-
-**Create fix phase directory and PLAN.md:**
-```bash
-mkdir -p .specd/tasks/$TASK_NAME/phases/phase-{N.M}/
-```
-
-Write `PLAN.md` using standard plan format:
-- Objective: Address review feedback for Phase {N}
-- Tasks: One per issue reported, with clear fix description and verification
-
-**Update ROADMAP.md:**
-Add fix phase entry after the parent phase.
-
-**Commit:**
-@~/.claude/specdacular/references/commit-docs.md
-- **$FILES:** fix plan directory + ROADMAP.md
-- **$MESSAGE:** `docs({task-name}): create fix plan phase-{N.M}`
-- **$LABEL:** `fix plan`
-
-**Offer execution:**
-Use AskUserQuestion:
-- header: "Fix Plan"
-- question: "Execute the fix plan now?"
-- options:
-  - "Execute" — Run the fix plan
-  - "Stop for now" — Come back later
-
-**If "Execute":**
-Execute fix plan via:
-@~/.claude/specdacular/workflows/execute.md
-
-After fix execution, loop back to the validate step of this review workflow (re-review with updated diff).
-
-**If "Stop for now":**
-```
-Fix plan saved. Resume with /specd:continue {task-name}
-```
-End workflow.
-</step>
-
-<step name="approve_phase">
-Mark phase as completed and advance.
-
-**Update config.json:**
-- Set `phases.current_status` to "completed"
-- Increment `phases.completed`
-- Advance `phases.current` to next phase
-- Reset `phases.phase_start_commit` to null
-- Set new phase status to "pending"
-
-**Update STATE.md:**
-- Mark phase as complete in execution progress
-
-**Add review cycle to STATE.md:**
-```markdown
-| {N} | 1 | {date} | {summary} | {fix plans or "—"} | clean |
-```
-
-**Commit:**
-@~/.claude/specdacular/references/commit-docs.md
-- **$FILES:** config.json + STATE.md
-- **$MESSAGE:** `docs({task-name}): phase {N} approved`
-- **$LABEL:** `phase approved`
-
-**Present:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PHASE {N} COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Phase {N}: {phase-name} approved.
-{If more phases: "Next: Phase {N+1}: {next-phase-name}"}
-{If all phases done: "All phases complete! Task '{task-name}' is done."}
-```
+**Record the user's choice** so the brain can route accordingly.
+The brain reads this choice and handles:
+- "Looks good" → brain approves phase (updates config.json, advances)
+- "I want to revise" / "I have concerns" → brain dispatches revise.md
+- "Stop for now" → brain saves state, exits
 
 End workflow (caller handles continuation).
 </step>
@@ -282,8 +159,6 @@ End workflow (caller handles continuation).
 - Git diff presented to user
 - Per-task status with icons (✅ ⚠️ ❌)
 - User can approve, revise, or stop
-- Fix plans created in decimal phases when needed
-- Fix plans execute through same execute workflow
-- Review loops after fix execution
-- Phase advances only after explicit user approval
+- User's choice recorded for brain routing
+- Phase advances only through brain (not in this workflow)
 </success_criteria>