specdacular 0.8.0 → 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/load-context.md

@@ -6,6 +6,7 @@ Load all context files for a task. Use after validation.
 
 **Before using this reference, you must have ready:**
 - `$TASK_NAME` — the task name
+- `$TASK_DIR` — resolved task directory (from validate-task, either `.specd/tasks/$TASK_NAME` or `.specd/features/$TASK_NAME`)
 - `$PHASE` (optional) — phase number, if loading phase-specific context
 
 ### Always Load
@@ -20,11 +21,11 @@ Load all context files for a task. Use after validation.
 
 ```bash
 # Read all required files
-cat .specd/tasks/$TASK_NAME/FEATURE.md
-cat .specd/tasks/$TASK_NAME/CONTEXT.md
-cat .specd/tasks/$TASK_NAME/DECISIONS.md
-cat .specd/tasks/$TASK_NAME/STATE.md
-cat .specd/tasks/$TASK_NAME/config.json
+cat $TASK_DIR/FEATURE.md
+cat $TASK_DIR/CONTEXT.md
+cat $TASK_DIR/DECISIONS.md
+cat $TASK_DIR/STATE.md
+cat $TASK_DIR/config.json
 ```
 
 ### Load If Exists
@@ -37,15 +38,15 @@ cat .specd/tasks/$TASK_NAME/config.json
 
 ```bash
 # Check and read optional files
-[ -f ".specd/tasks/$TASK_NAME/RESEARCH.md" ] && cat .specd/tasks/$TASK_NAME/RESEARCH.md
-[ -f ".specd/tasks/$TASK_NAME/ROADMAP.md" ] && cat .specd/tasks/$TASK_NAME/ROADMAP.md
-[ -f ".specd/tasks/$TASK_NAME/CHANGELOG.md" ] && cat .specd/tasks/$TASK_NAME/CHANGELOG.md
+[ -f "$TASK_DIR/RESEARCH.md" ] && cat $TASK_DIR/RESEARCH.md
+[ -f "$TASK_DIR/ROADMAP.md" ] && cat $TASK_DIR/ROADMAP.md
+[ -f "$TASK_DIR/CHANGELOG.md" ] && cat $TASK_DIR/CHANGELOG.md
 ```
 
 ### Phase-Specific Context (when $PHASE is set)
 
 ```bash
-PHASE_DIR=".specd/tasks/$TASK_NAME/phases/phase-$(printf '%02d' $PHASE)"
+PHASE_DIR="$TASK_DIR/phases/phase-$(printf '%02d' $PHASE)"
 
 # Read phase plan
 [ -f "$PHASE_DIR/PLAN.md" ] && cat "$PHASE_DIR/PLAN.md"

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/references/select-feature.md

@@ -8,7 +8,14 @@ Determine which task to work on.
 Use as task name. Normalize to kebab-case (lowercase, hyphens).
 
 ```bash
-[ -d ".specd/tasks/$ARGUMENTS" ] || { echo "not found"; exit 1; }
+# Check tasks/ first, fall back to features/ for backwards compat
+if [ -d ".specd/tasks/$ARGUMENTS" ]; then
+  TASK_DIR=".specd/tasks/$ARGUMENTS"
+elif [ -d ".specd/features/$ARGUMENTS" ]; then
+  TASK_DIR=".specd/features/$ARGUMENTS"
+else
+  echo "not found"; exit 1
+fi
 ```
 
 **If task not found:**
@@ -19,9 +26,9 @@ Available tasks:
 ```
 
 ```bash
-ls -d .specd/tasks/*/ 2>/dev/null | while read dir; do
+{ ls -d .specd/tasks/*/ 2>/dev/null; ls -d .specd/features/*/ 2>/dev/null; } | while read dir; do
   basename "$dir"
-done
+done | sort -u
 ```
 
 End workflow.
@@ -30,8 +37,8 @@ End workflow.
 Scan for in-progress tasks:
 
 ```bash
-# List task directories with config.json
-for dir in .specd/tasks/*/config.json; do
+# List task directories with config.json (check both locations)
+for dir in .specd/tasks/*/config.json .specd/features/*/config.json; do
   [ -f "$dir" ] && echo "$dir"
 done
 ```

package/specdacular/references/validate-task.md

@@ -10,17 +10,25 @@ Check that a task directory exists with required files.
 **Basic validation (all workflows):**
 
 ```bash
-# Check task directory exists
-[ -d ".specd/tasks/$TASK_NAME" ] || { echo "not found"; exit 1; }
+# Check task directory exists (tasks/ preferred, features/ for backwards compat)
+if [ -d ".specd/tasks/$TASK_NAME" ]; then
+  TASK_DIR=".specd/tasks/$TASK_NAME"
+elif [ -d ".specd/features/$TASK_NAME" ]; then
+  TASK_DIR=".specd/features/$TASK_NAME"
+else
+  echo "not found"; exit 1
+fi
 
 # Check required files
-[ -f ".specd/tasks/$TASK_NAME/FEATURE.md" ] || { echo "missing FEATURE.md"; exit 1; }
-[ -f ".specd/tasks/$TASK_NAME/CONTEXT.md" ] || { echo "missing CONTEXT.md"; exit 1; }
-[ -f ".specd/tasks/$TASK_NAME/DECISIONS.md" ] || { echo "missing DECISIONS.md"; exit 1; }
-[ -f ".specd/tasks/$TASK_NAME/STATE.md" ] || { echo "missing STATE.md"; exit 1; }
-[ -f ".specd/tasks/$TASK_NAME/config.json" ] || { echo "missing config.json"; exit 1; }
+[ -f "$TASK_DIR/FEATURE.md" ] || { echo "missing FEATURE.md"; exit 1; }
+[ -f "$TASK_DIR/CONTEXT.md" ] || { echo "missing CONTEXT.md"; exit 1; }
+[ -f "$TASK_DIR/DECISIONS.md" ] || { echo "missing DECISIONS.md"; exit 1; }
+[ -f "$TASK_DIR/STATE.md" ] || { echo "missing STATE.md"; exit 1; }
+[ -f "$TASK_DIR/config.json" ] || { echo "missing config.json"; exit 1; }
 ```
 
+**`$TASK_DIR` is now set** — use it in all subsequent file references instead of hardcoding `.specd/tasks/$TASK_NAME`.
+
 **If task not found:**
 ```
 Task '{name}' not found.
@@ -40,10 +48,10 @@ Run /specd:discuss {name} to rebuild context.
 
 ```bash
 # Check phases exist (for execute/review)
-[ -d ".specd/tasks/$TASK_NAME/phases" ] || { echo "no phases"; exit 1; }
+[ -d "$TASK_DIR/phases" ] || { echo "no phases"; exit 1; }
 
 # Check ROADMAP exists (for execute/review)
-[ -f ".specd/tasks/$TASK_NAME/ROADMAP.md" ] || { echo "no roadmap"; exit 1; }
+[ -f "$TASK_DIR/ROADMAP.md" ] || { echo "no roadmap"; exit 1; }
 ```
 
 **If no phases:**
@@ -57,8 +65,8 @@ Run /specd:plan {name} to create phases.
 
 ```bash
 # Check optional files
-[ -f ".specd/tasks/$TASK_NAME/RESEARCH.md" ] && echo "has_research"
-[ -f ".specd/tasks/$TASK_NAME/ROADMAP.md" ] && echo "has_roadmap"
+[ -f "$TASK_DIR/RESEARCH.md" ] && echo "has_research"
+[ -f "$TASK_DIR/ROADMAP.md" ] && echo "has_roadmap"
 ```
 
 </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 |