specdacular 0.7.1 → 0.8.0

package/specdacular/workflows/continue.md

@@ -0,0 +1,275 @@
+<purpose>
+Continue a task's lifecycle. Reads state, determines the next action, and either prompts (interactive), auto-advances (semi-auto), or runs everything (auto).
+
+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
+</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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+**Phases completed:** {N}
+**Decisions made:** {N}
+
+All phases executed and reviewed. Task is done!
+```
+
+End workflow.
+</step>
+
+</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.)
+</success_criteria>

package/specdacular/workflows/discuss.md

@@ -0,0 +1,184 @@
+<purpose>
+Continue/deepen task discussion. Targets gray areas, records decisions, and builds understanding.
+
+**Output:** Updated CONTEXT.md, DECISIONS.md, STATE.md
+</purpose>
+
+<philosophy>
+
+## Follow the Thread
+
+Don't march through gray areas like a checklist. Pick the most important one, explore it, and let the conversation branch naturally.
+
+## Four Questions Then Check
+
+For each gray area: ask 4 focused questions, then summarize what was resolved. If clear, mark resolved. If not, continue probing.
+
+## Decisions Get Recorded
+
+Any decision made gets a DEC-{NNN} entry immediately — not at the end.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use basic validation with $TASK_NAME from $ARGUMENTS.
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load required files + optional RESEARCH.md.
+
+**Parse:**
+- Extract gray areas remaining from CONTEXT.md
+- Extract active decisions from DECISIONS.md
+- Count discussion sessions from STATE.md
+
+Continue to show_state.
+</step>
+
+<step name="show_state">
+Display what's established and what needs discussion.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DISCUSSION: {task-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Session:** {N+1}
+**Decisions so far:** {count}
+
+**Gray areas to explore:**
+{numbered list of gray areas from CONTEXT.md}
+```
+
+Continue to identify_focus.
+</step>
+
+<step name="identify_focus">
+Pick the most impactful gray area to start with.
+
+Choose based on:
+1. Dependencies — does resolving this unblock other areas?
+2. Risk — is this the area most likely to cause problems later?
+3. User interest — did the user hint at wanting to discuss something specific?
+
+```
+Let's start with: {gray area}
+
+{Opening question that explores this area}
+```
+
+Continue to probe_area.
+</step>
+
+<step name="probe_area">
+Explore the gray area through conversation.
+
+**Question pattern (not rigid — follow the thread):**
+1. Open-ended question to understand the space
+2. Clarifying question based on response
+3. Edge case or constraint question
+4. Confirmation of understanding
+
+**After 4 questions, check:**
+```
+So for {gray area}, it sounds like:
+- {Summary point 1}
+- {Summary point 2}
+
+Is that right, or should we dig deeper?
+```
+
+**If resolved:** Record any decisions, mark gray area as resolved. Move to next gray area or wrap up.
+
+**If not resolved:** Continue probing, or defer with explicit reasoning.
+
+Continue to record_decisions.
+</step>
+
+<step name="record_decisions">
+Record any new decisions from this discussion.
+
+@~/.claude/specdacular/references/record-decision.md
+
+For each decision identified during the discussion, add to DECISIONS.md.
+
+Continue to update_context.
+</step>
+
+<step name="update_context">
+Update CONTEXT.md with session results.
+
+**Add resolved questions:**
+For each gray area that was resolved, add to the "Resolved Questions" section with question, resolution, and details.
+
+**Update gray areas:**
+Remove resolved items from "Gray Areas Remaining."
+
+**Add discussion history entry:**
+```markdown
+| {today} | {topics covered} | {what was resolved} |
+```
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update STATE.md and config.json.
+
+**STATE.md:**
+- Increment discussion session in table
+- Update gray areas checkboxes
+- Update documents status
+
+**config.json:**
+- Increment `discussion_sessions`
+- Update `decisions_count`
+
+Continue to commit.
+</step>
+
+<step name="commit">
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/{task-name}/CONTEXT.md .specd/tasks/{task-name}/DECISIONS.md .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
+- **$MESSAGE:** `docs({task-name}): discussion session {N}` with summary of resolved areas
+- **$LABEL:** `discussion updates`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present session summary.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DISCUSSION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Session {N}:** {summary of what was discussed}
+
+**Resolved:** {count} gray areas
+**New decisions:** {count}
+**Remaining gray areas:** {count}
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- Gray areas explored through conversation
+- New decisions recorded in DECISIONS.md
+- CONTEXT.md updated with resolutions
+- STATE.md reflects updated progress
+- Changes committed
+</success_criteria>

package/specdacular/workflows/execute.md

@@ -0,0 +1,174 @@
+<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.
+
+**Output:** Implemented code, CHANGELOG.md entries, automatic review trigger
+</purpose>
+
+<philosophy>
+
+## One Phase at a Time
+
+Execute one phase's PLAN.md, then review before moving on. Never skip review.
+
+## Verify Each Task
+
+After each task, run the verification command. If it fails, attempt to fix. If fix fails, stop and ask the user.
+
+## Log Deviations
+
+If implementation differs from plan, log it in CHANGELOG.md. Deviations are neutral — they might be improvements.
+
+## Commit Granularly
+
+Commit after each task (or logical group of closely related tasks). Small commits make review easier.
+
+</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 task context including phase-specific context.
+
+**Read global config:**
+```bash
+cat .specd/config.json 2>/dev/null || echo '{}'
+```
+Check `auto_commit_code` and `auto_commit_docs` settings.
+
+Continue to find_phase.
+</step>
+
+<step name="find_phase">
+Find the next 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"
+
+**Find PLAN.md:**
+```bash
+PHASE_DIR=".specd/tasks/$TASK_NAME/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
+```
+If fix plans exist and are incomplete, execute those first.
+
+Read the PLAN.md. Parse tasks.
+
+Continue to record_start.
+</step>
+
+<step name="record_start">
+Record phase execution start.
+
+**If status is "pending" (first time executing this phase):**
+```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.
+
+Continue to execute_tasks.
+</step>
+
+<step name="execute_tasks">
+Execute each task from the PLAN.md.
+
+**For each task:**
+
+1. **Announce:** `Starting Task {N}: {title}`
+
+2. **Implement:** Follow the action description. Reference codebase patterns from PATTERNS.md. Follow active decisions from DECISIONS.md.
+
+3. **Verify:** Run the verification command from the plan.
+   - If passes: mark done, continue
+   - If fails: attempt to fix (max 2 attempts)
+   - If still fails: stop and ask user (retry/skip/stop)
+
+4. **Log deviations:** If implementation differs from plan, add to CHANGELOG.md:
+   ```markdown
+   ### {date} - Phase {N} PLAN.md
+
+   **{Brief title}**
+   - **What:** {What was changed/decided}
+   - **Why:** {Reason for deviation}
+   - **Files:** `{affected files}`
+   ```
+
+5. **Commit:**
+   @~/.claude/specdacular/references/commit-code.md
+   - **$FILES:** files created/modified by this task
+   - **$MESSAGE:** `feat({task-name}): {task summary}`
+
+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"
+
+**Update STATE.md:**
+- Add phase to Completed Phases table
+- 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`
+- **$MESSAGE:** `docs({task-name}): phase {N} executed`
+- **$LABEL:** `phase execution complete`
+
+**Automatically trigger review:**
+```
+Phase {N} execution complete. Starting code review...
+```
+
+@~/.claude/specdacular/workflows/review.md
+
+End workflow (review takes over).
+</step>
+
+</process>
+
+<success_criteria>
+- Phase PLAN.md tasks executed in order
+- 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
+</success_criteria>