specdacular 0.8.1 → 0.9.2

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>

package/specdacular/workflows/revise.md

@@ -0,0 +1,126 @@
+<purpose>
+Collect user feedback on review findings and create fix plans in decimal phases. Extracted from review.md — revise handles the "what to fix" conversation while review handles pure inspection.
+
+**Output:** Fix plan in decimal phase directory (e.g., phase-01.1/PLAN.md), updated ROADMAP.md, config.json signaling for brain routing.
+</purpose>
+
+<philosophy>
+
+## 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.
+
+## Clear Signal to Brain
+
+After creating a fix plan, signal the brain by setting `phases.current_status: "pending"` so the brain routes back to execute for the current phase.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use extended validation. Check phases and ROADMAP exist.
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load all context including the current phase's PLAN.md and review findings.
+
+**Read phase info:**
+```bash
+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"
+```
+
+Continue to collect_feedback.
+</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
+CURRENT=$(printf '%02d' $PHASE_NUM)
+ls -d $TASK_DIR/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 $TASK_DIR/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.
+
+Continue to signal_outcome.
+</step>
+
+<step name="signal_outcome">
+Signal the brain that a fix plan was created and needs execution.
+
+**Update config.json:**
+- Set `phases.current_status` to `"pending"` — this tells the brain to route back to execute for the current phase (which will pick up the decimal fix phase)
+
+Continue to commit.
+</step>
+
+<step name="commit">
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** fix plan directory + ROADMAP.md + config.json
+- **$MESSAGE:** `docs({task-name}): create fix plan phase-{N.M}`
+- **$LABEL:** `fix plan`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present what was created.
+
+```
+Fix plan created: phase-{N.M}
+{count} tasks to address review feedback.
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- User feedback collected with clear understanding of issues
+- Fix plan created in decimal phase directory
+- ROADMAP.md updated with fix phase
+- config.json signals brain to route back to execute
+- Changes committed
+</success_criteria>