specdacular 0.8.1 → 0.9.2

package/specdacular/references/execute-hooks.md

@@ -0,0 +1,127 @@
+<shared name="execute_hooks">
+
+## Execute Hooks
+
+Resolve and execute a hook. Called by brain.md for pre/post hooks around each step.
+
+**Before using this reference, you must have ready:**
+- `$HOOK_CONFIG` — the hook configuration (from pipeline.json step or global hooks)
+- `$STEP_NAME` — the current step name (for convention discovery and logging)
+- `$TASK_NAME` — the task name
+- `$TASK_DIR` — path to task directory
+
+### Resolve Hook
+
+**If hook config is explicitly set (not null):**
+
+Hook config shape:
+```json
+{
+  "workflow": "path/to/hook.md",
+  "mode": "inline",
+  "optional": false
+}
+```
+
+Defaults if fields are missing:
+- `mode`: `"inline"`
+- `optional`: `false`
+
+**If hook config is null — convention fallback:**
+
+Check for convention-named hook file:
+```bash
+[ -f ".specd/hooks/{pre|post}-{step-name}.md" ] && echo "found"
+```
+
+If found, use it with defaults: `mode: "inline"`, `optional: false`.
+
+If not found, skip — no hook to execute.
+
+### Execute Hook — Inline Mode
+
+When `mode` is `"inline"` (default):
+
+1. Read the hook markdown file
+2. Execute the hook's instructions in the brain's current context
+3. The hook has full access to task files (FEATURE.md, CONTEXT.md, DECISIONS.md, etc.)
+4. The hook can read and modify any task file — this is how it communicates with subsequent steps
+5. After hook completes, continue to next item in execution sequence
+
+**Convention for hooks modifying shared files:**
+Hooks should append to designated sections rather than overwriting. If adding context, append under a `## Hook Context` section or similar.
+
+### Execute Hook — Subagent Mode
+
+When `mode` is `"subagent"`:
+
+1. **Flush state to disk first:** Ensure all pending config.json and STATE.md writes are committed. The subagent reads from disk and must see current state.
+
+2. **Spawn hook as Task agent:**
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  run_in_background: false
+  description: "Hook: {hook-file-name}"
+  prompt: "You are executing a hook for the specdacular workflow system.
+
+Read and follow the instructions in: {path/to/hook.md}
+
+Task context:
+- Task name: {task-name}
+- Task directory: {task-dir}
+- Current step: {step-name}
+
+You have full access to read and modify task files in the task directory.
+After completing the hook instructions, return a brief summary of what you did."
+)
+```
+
+3. After subagent returns, brain continues. Subagent's file modifications are already on disk.
+
+### Error Handling
+
+**If hook succeeds:** Continue to next item in execution sequence.
+
+**If hook fails and `optional: false` (default):**
+- Stop the pipeline immediately
+- Save current state (config.json, STATE.md)
+- Surface the error to the user:
+```
+Hook failed: {hook-file-name}
+Error: {description of what went wrong}
+
+Pipeline stopped. Resume with /specd:continue {task-name}
+```
+- End workflow
+
+**If hook fails and `optional: true`:**
+- Print visible warning:
+```
+[HOOK SKIPPED] {hook-file-name} failed: {reason}
+```
+- Append to CHANGELOG.md:
+```markdown
+### {date} - Hook Failure
+
+**{hook-file-name} (optional, skipped)**
+- **Step:** {step-name}
+- **Error:** {reason}
+- **Impact:** Hook skipped, pipeline continued
+```
+- Continue to next item in execution sequence
+
+### Execution Order
+
+The full hook execution sequence around a step:
+
+```
+1. Global hooks.pre-step    (if configured)
+2. Step hooks.pre           (if configured, else convention fallback)
+3. ── STEP WORKFLOW ──
+4. Step hooks.post          (if configured, else convention fallback)
+5. Global hooks.post-step   (if configured)
+```
+
+</shared>

package/specdacular/references/resolve-pipeline.md

@@ -0,0 +1,74 @@
+<shared name="resolve_pipeline">
+
+## Resolve Pipeline
+
+Load and validate the pipeline configuration.
+
+**Before using this reference, you must have ready:**
+- Working directory is the project root
+
+### Load Pipeline
+
+**Resolution order:**
+1. Check for user override: `.specd/pipeline.json`
+2. Fall back to installed default: `~/.claude/specdacular/pipeline.json`
+
+```bash
+if [ -f ".specd/pipeline.json" ]; then
+  echo "user-override"
+elif [ -f "~/.claude/specdacular/pipeline.json" ]; then
+  echo "default"
+else
+  echo "not-found"
+fi
+```
+
+**If user override found:**
+```
+Using custom pipeline from .specd/pipeline.json
+```
+Read `.specd/pipeline.json`.
+
+**If default found:**
+Read the installed `specdacular/pipeline.json` (use the path prefix from install — `~/.claude/specdacular/pipeline.json` for global, `.claude/specdacular/pipeline.json` for local).
+
+**If not found:**
+```
+No pipeline.json found. This shouldn't happen — try reinstalling with npx specdacular.
+```
+End workflow.
+
+### Validate Pipeline
+
+After loading, validate the pipeline config:
+
+**1. Check schema_version:**
+```
+Read "schema_version" field. If missing, warn:
+"Warning: pipeline.json has no schema_version. Expected 1.0."
+```
+
+**2. Check pipeline references:**
+For each step in all pipelines, if a step has `"pipeline": "{name}"`:
+- Check that `pipelines.{name}` exists
+- If not: error with `"Pipeline step '{step.name}' references pipeline '{name}' which doesn't exist in pipelines object."`
+
+**3. Check workflow references:**
+For each step with a `"workflow"` field:
+- Check the value is a non-empty string
+- If empty: error with `"Step '{step.name}' has no workflow specified."`
+
+**4. Warn on missing standard steps (non-blocking):**
+Check if these step names exist in any pipeline: discuss, plan, execute, review.
+For each missing, warn:
+```
+Note: Standard step '{name}' not found in pipeline. This is OK if intentional.
+```
+
+### Set Pipeline Variable
+
+After validation, the pipeline config is available as `$PIPELINE` for the brain to use.
+
+`$PIPELINE_SOURCE` is set to `"user-override"` or `"default"`.
+
+</shared>

package/specdacular/templates/context/review-diff.md

@@ -0,0 +1,60 @@
+# Context Review Diff Template
+
+Template for displaying re-mapping results when comparing current vs re-mapped section content. Referenced by `specdacular/workflows/context-review.md`.
+
+---
+
+## Re-map Diff Display
+
+Shown after a `specd-codebase-mapper` agent returns re-mapped content for a section.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RE-MAP RESULTS: {section title}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Note: AI regeneration may rephrase content even when
+facts are unchanged. Focus on factual differences.
+
+───── CURRENT ─────────────────────────────────────────
+
+{current section content}
+
+───── RE-MAPPED ───────────────────────────────────────
+
+{agent's returned content}
+
+───── KEY DIFFERENCES ─────────────────────────────────
+
+- {factual difference 1: added/removed/changed item}
+- {factual difference 2}
+...
+
+{If no factual differences: "No factual changes detected — only phrasing differences."}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Key Differences Guidelines
+
+When summarizing differences, focus on **factual changes only**:
+- New file paths, functions, or integrations added
+- Removed items that no longer exist in the codebase
+- Changed descriptions that reflect actual behavior differences
+- Updated version numbers or configuration values
+
+**Ignore:**
+- Rephrased descriptions with the same meaning
+- Reordered items within a list
+- Formatting differences (bullet style, heading level)
+- Synonymous wording ("utilizes" vs "uses")
+
+---
+
+## Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{section title}` | The heading text of the section being re-mapped |
+| `{current section content}` | Existing section body for comparison |
+| `{agent's returned content}` | New content from the `specd-codebase-mapper` agent |

package/specdacular/templates/context/section-display.md

@@ -0,0 +1,51 @@
+# Context Section Display Template
+
+Template for displaying a single section of a codebase context file to the user during review. Referenced by `specdacular/workflows/context-review.md`.
+
+---
+
+## Section Display
+
+```
+================================================================
+{If ### subsection: "## {Parent Title} > "}{## or ###} {Section Title}  [{current}/{total}]{If tagged: "  · {USER_MODIFIED|AUTO_GENERATED}: YYYY-MM-DD"}
+================================================================
+
+{exact section content from the file — verbatim, no modifications, no strikethrough, no interpretation}
+
+────────────────────────────────────────
+{assessment icon} {assessment label} — {brief explanation}
+================================================================
+```
+
+**Header:** `=` separator, section heading with position counter, `=` separator. For `###` subsections, prefix with the parent `##` heading and ` > ` to show context.
+
+**Middle — Raw content:** The exact text from the file in a code fence. Do NOT interpret the content — no strikethrough on missing paths, no added formatting. Show it verbatim.
+
+**Bottom — Assessment:** The agent's analysis with icon, label, and brief explanation. Closed with `=` separator.
+
+**Empty parent sections** (## with no content, only ### children) are NOT displayed as reviewable sections. Their heading is shown as a prefix on child sections instead.
+
+---
+
+## Assessment Logic
+
+Based on the section's tag and its date:
+
+- **No tag** → ⚠️ Untagged — never reviewed or generated
+- **Tag date older than 14 days** → ⚠️ Potentially stale
+- **Tag date within 14 days** → ✅ Recently reviewed
+
+---
+
+## User Actions
+
+After displaying the section, prompt the user with:
+
+| Action | Description |
+|--------|-------------|
+| Confirm | Section is correct, move to next |
+| Edit | User describes what to change |
+| Remove | Delete this section (warns about children) |
+| Re-map | Spawn mapper agent, show diff |
+| Done for now | Skip remaining sections |

package/specdacular/workflows/brain.md

@@ -0,0 +1,378 @@
+<purpose>
+Config-driven orchestrator that replaces continue.md's hardcoded flow control. Reads pipeline.json, determines the next step based on task state, handles modes (default/interactive/auto), dispatches step workflows, executes hooks, and manages state transitions.
+
+The brain is the single source of truth for workflow orchestration. Step workflows just do their job and return — the brain decides what comes next.
+
+**Modes:**
+- **Default:** Auto-runs steps, pauses where `pause: true`. Smart about skipping unnecessary steps.
+- **Interactive (`--interactive`):** Prompts at each stage transition with skip/jump options
+- **Auto (`--auto`):** Runs everything, only stops on errors or task completion
+</purpose>
+
+<philosophy>
+
+## One Orchestrator
+
+All flow control lives here. Step workflows are pure execution — they do their work and return. They never dispatch the next step.
+
+## Config-Driven
+
+The pipeline comes from pipeline.json, not hardcoded logic. Users can swap steps, add hooks, or replace the entire pipeline.
+
+## State Machine
+
+The brain reads state → determines position → dispatches → updates state → loops. Every state transition is explicit and persisted before dispatch.
+
+## Hooks Are Workflow Steps
+
+Hooks are markdown files executed like any other workflow step. They can read and modify task files. No special output contract.
+
+</philosophy>
+
+<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 `--interactive` flag
+- Check for `--auto` flag
+- If `--interactive` → interactive mode
+- If `--auto` → auto mode
+- Otherwise → default mode
+
+```
+Mode: {default | interactive | 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 resolve_pipeline.
+</step>
+
+<step name="resolve_pipeline">
+@~/.claude/specdacular/references/resolve-pipeline.md
+
+Load and validate the pipeline configuration.
+
+After loading, apply mode:
+- If `--interactive` flag was set, use interactive mode
+- If `--auto` flag was set, use auto mode
+- Otherwise use default mode (auto-run, pause at `pause: true` steps)
+
+**Check for orchestrator mode:**
+Read `.specd/config.json` (project-level, not task-level). If it has `"type": "orchestrator"`:
+- Set `$ORCHESTRATOR_MODE = true`
+- Log: `Orchestrator mode: multi-project task management active.`
+
+**How orchestrator mode works with the brain:**
+
+The brain runs the same pipeline for orchestrator tasks. The difference is that step workflows detect orchestrator mode internally and hand off to specialized orchestrator workflows:
+- `new.md` → detects orchestrator → delegates to `orchestrator/new.md` (multi-project task creation)
+- `plan.md` → detects orchestrator → delegates to `orchestrator/plan.md` (cross-project phasing)
+- `discuss.md`, `research.md` → work at orchestrator level (system-wide discussion/research)
+- `execute.md` → for orchestrator tasks, reads DEPENDENCIES.md to determine cross-project phase order. Executes phases per-project respecting dependency graph.
+- `review.md`, `revise.md` → work per-project within the orchestrator's coordination
+
+The brain does NOT need different routing for orchestrator mode. The pipeline is the same — orchestrator awareness lives in the step workflows that need it. The brain's job is to drive the pipeline; the steps handle multi-project specifics.
+
+**Important:** When in orchestrator mode, the phase-execution loop may need to coordinate across projects. The brain reads the orchestrator task's DEPENDENCIES.md to understand cross-project phase ordering, and dispatches execute/review/revise per project in dependency order.
+
+Continue to main_loop.
+</step>
+
+<step name="main_loop">
+The core orchestration loop. Repeats until task is complete or user stops.
+
+**On each iteration:**
+
+1. **Load current state:**
+   Read config.json, STATE.md, CONTEXT.md from task directory.
+
+2. **Determine next step:**
+   @~/.claude/specdacular/references/brain-routing.md
+
+   This sets: `$NEXT_STEP`, `$NEXT_PIPELINE`, and optionally `$TASK_COMPLETE` or `$RESUME`.
+
+3. **If task complete:**
+   Continue to complete.
+
+4. **Find step config in pipeline:**
+   Look up `$NEXT_STEP` in `$PIPELINE.pipelines.$NEXT_PIPELINE`.
+
+5. **Prompt or proceed:**
+   Continue to prompt_or_proceed.
+
+6. **After step dispatch returns:**
+   Continue to update_state.
+
+7. **After state update:**
+   Loop back to step 1 (re-read state, determine next step).
+
+Continue to prompt_or_proceed.
+</step>
+
+<step name="prompt_or_proceed">
+Mode-based dispatch decision.
+
+**Default mode:**
+Check the step's `pause` field:
+- If `false` or absent: auto-proceed (no prompt). But first, evaluate if the step adds value — if not, skip it (see smart skipping below).
+- If `true`: prompt user before proceeding
+
+When pausing, present current state and ask what to do:
+
+```
+**Current state:** {stage description}
+{Additional context based on step — e.g., phase number}
+```
+
+Use AskUserQuestion with step-appropriate options:
+
+For plan step (phase-execution pipeline — phase-plan.md):
+- Auto-proceed (no pause). Plan has no pause field.
+
+For execute step:
+- "Execute" (Recommended) — Start/resume phase execution
+- "Review plan" — Read the PLAN.md first
+- "Stop for now" — Come back later
+
+For review step:
+- Dispatch directly (review has its own user interaction)
+
+For revise step:
+- Dispatch directly (revise has its own user interaction)
+
+**Interactive mode (`--interactive`):**
+Prompt at every stage transition, regardless of `pause` field.
+
+Use AskUserQuestion with step-appropriate options:
+
+For discuss step:
+- "Discuss" (Recommended) — Dive into gray areas
+- "Skip to research" — Move on without resolving
+- "Skip to planning" — Jump straight to planning
+
+For research step:
+- "Research" (Recommended) — Investigate implementation patterns
+- "Skip to planning" — Plan without research
+- "Discuss more" — Continue discussion
+
+For plan step (main pipeline — task-level):
+- "Plan" (Recommended) — Create roadmap with phase goals
+- "Research first" — Run research before planning
+- "Discuss more" — Continue discussion
+
+For plan step (phase-execution pipeline — phase-plan.md):
+- "Plan this phase" (Recommended) — Create detailed PLAN.md
+- "Skip to execute" — Execute without explicit planning
+- "Stop for now" — Come back later
+
+For execute step:
+- "Execute" (Recommended) — Start/resume phase execution
+- "Review plan" — Read the PLAN.md first
+- "Stop for now" — Come back later
+
+For review step:
+- Dispatch directly (review has its own user interaction)
+
+For revise step:
+- Dispatch directly (revise has its own user interaction)
+
+**Auto mode (`--auto`):**
+Proceed without prompting. Apply smart skipping (see below). Only stop on errors or task completion.
+
+**If user chooses "Stop for now":**
+Save state and exit:
+```
+───────────────────────────────────────────────────────
+
+Progress saved. Pick up where you left off anytime:
+
+/specd:continue {task-name}
+```
+End workflow.
+
+**If user chooses an alternative (e.g., "Skip to research"):**
+Update `$NEXT_STEP` accordingly and continue to dispatch.
+
+**Smart step skipping (default and auto modes):**
+Before dispatching a step, evaluate whether it adds value. Skip if:
+- **discuss:** No gray areas remaining in CONTEXT.md → skip, advance to research
+- **research (task-level):** Task is straightforward (few files, clear requirements, no external dependencies) → skip, advance to plan
+
+When skipping, log:
+```
+Skipping {step}: {reason}
+```
+
+In interactive mode, don't auto-skip — instead recommend skipping: mark the skip option as "(Recommended)" and the step as the alternative.
+
+Continue to execute_hooks_and_step.
+</step>
+
+<step name="execute_hooks_and_step">
+Execute pre-hooks, the step workflow, and post-hooks.
+
+**Save state before dispatch:**
+Update config.json to reflect the step is starting. For execute step, set `phases.current_status: "executing"` and record `phase_start_commit`.
+
+Commit state:
+@~/.claude/specdacular/references/commit-docs.md
+- **$FILES:** config.json, STATE.md
+- **$MESSAGE:** `docs({task-name}): starting {step-name}`
+- **$LABEL:** `state transition`
+
+**Execute pre-hooks:**
+@~/.claude/specdacular/references/execute-hooks.md
+
+Run pre-hooks in order:
+1. Global `hooks.pre-step` from pipeline.json (if configured)
+2. Step's `hooks.pre` from the step config (if configured)
+3. Convention fallback: check `.specd/hooks/pre-{step-name}.md` (if file exists and no explicit config)
+
+For each hook, use the execution logic from the reference.
+
+If a required pre-hook fails, stop pipeline and save state. Do NOT dispatch the step.
+
+**Dispatch step workflow:**
+Resolve the workflow path from the step's `workflow` field.
+Execute the workflow:
+@~/.claude/specdacular/workflows/{workflow}
+
+Pass $TASK_NAME as context.
+
+**After step returns:**
+
+**Execute post-hooks:**
+@~/.claude/specdacular/references/execute-hooks.md
+
+Run post-hooks in order:
+1. Step's `hooks.post` from the step config (if configured)
+2. Convention fallback: check `.specd/hooks/post-{step-name}.md` (if file exists and no explicit config)
+3. Global `hooks.post-step` from pipeline.json (if configured)
+
+For each hook, use the execution logic from the reference.
+
+If a required post-hook fails, stop pipeline and save state.
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update state based on which step just completed.
+
+**After discuss completes:**
+- Stage stays at "discussion"
+- Re-read CONTEXT.md to check if gray areas are resolved
+- If all resolved, advance stage to "research"
+
+**After research completes:**
+- Set stage to "planning" in config.json
+
+**After plan completes (task-level — main pipeline):**
+- plan.md sets stage to "execution" and phases info in config.json
+- Brain loops back, routing picks up phase-execution pipeline
+
+**After plan completes (phase-level — phase-execution pipeline, phase-plan.md):**
+- phase-plan.md creates PLAN.md but does NOT change config.json
+- Status stays "pending" but PLAN.md now exists
+- Brain loops back, routing sees pending + PLAN.md exists → routes to execute
+
+**After execute completes:**
+- Set `phases.current_status: "executed"` in config.json
+
+**After review completes:**
+- Read review outcome from config.json or STATE.md
+- If user approved ("Looks good"): set `phases.current_status: "completed"`, increment `phases.completed`, advance to next phase or mark task complete
+- If user wants revisions: set up for revise step
+- If user stopped: save state, exit
+
+**After revise completes:**
+- Read config.json — revise should have set `phases.current_status: "pending"` (fix plan created, needs execution)
+- Brain loops back to execute for the current phase (including decimal fix phases)
+
+**Commit state updates:**
+@~/.claude/specdacular/references/commit-docs.md
+- **$FILES:** config.json, STATE.md
+- **$MESSAGE:** `docs({task-name}): {step-name} complete`
+- **$LABEL:** `state transition`
+
+Return to main_loop.
+</step>
+
+<step name="phase_loop">
+Handle the phase-execution sub-pipeline loop.
+
+When the brain reaches the `phase-execution` pipeline reference in the main pipeline:
+
+1. Read ROADMAP.md and config.json to determine current phase
+2. Enter the phase-execution sub-pipeline (plan → execute → review → revise)
+3. After each iteration through the sub-pipeline:
+   - If review approved and more phases remain: advance `phases.current`, set status "pending", loop
+   - If review approved and no more phases: exit sub-pipeline, task complete
+   - If revise created fix plans: stay on current phase, loop back to execute
+   - If user stopped: save state, exit
+
+**Decimal phase handling:**
+After revise creates a fix plan (e.g., phase-01.1/):
+```bash
+ls -d $TASK_DIR/phases/phase-$(printf '%02d' $CURRENT).* 2>/dev/null | sort -V
+```
+If decimal phases exist and are incomplete, execute them before advancing to next integer phase.
+
+**Phase advancement:**
+```
+phases.current += 1
+phases.current_status = "pending"
+phases.phase_start_commit = null
+```
+
+Continue to main_loop (which will route to the next phase's execute step).
+</step>
+
+<step name="complete">
+All phases complete. Task is done.
+
+**Update state:**
+- Set stage to "complete" in config.json
+
+**Present:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ 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>
+- Pipeline loaded from .specd/pipeline.json or installed default
+- Pipeline validated (schema version, references, workflow paths)
+- State-based routing matches all 8 state combinations
+- Default mode auto-runs, pauses at `pause: true` steps, smart-skips unnecessary steps
+- Interactive mode prompts at each transition with skip/jump options
+- Auto mode proceeds without prompting, smart-skips, stops on errors
+- Phase-execution sub-pipeline loops correctly per phase
+- Decimal fix phases handled
+- State saved before dispatch for reliable resume
+- Stop/resume works at any point via /specd:continue
+- Hook execution points marked for Phase 2
+</success_criteria>