specdacular 0.7.2 → 0.8.0

package/specdacular/references/load-context.md

@@ -0,0 +1,83 @@
+<shared name="load_context">
+
+## Load Task Context
+
+Load all context files for a task. Use after validation.
+
+**Before using this reference, you must have ready:**
+- `$TASK_NAME` — the task name
+- `$PHASE` (optional) — phase number, if loading phase-specific context
+
+### Always Load
+
+| File | Provides |
+|------|----------|
+| `FEATURE.md` | Technical requirements, files to create, integration points, constraints |
+| `CONTEXT.md` | Discussion history, resolved questions, gray areas remaining |
+| `DECISIONS.md` | Active decisions that constrain implementation |
+| `STATE.md` | Current stage, progress, completed phases |
+| `config.json` | Task settings, stage, decision count |
+
+```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
+```
+
+### Load If Exists
+
+| File | Provides | When Useful |
+|------|----------|-------------|
+| `RESEARCH.md` | Implementation patterns, library decisions, pitfalls | Planning, execution |
+| `ROADMAP.md` | Phase overview, success criteria, dependencies | Planning, execution, review |
+| `CHANGELOG.md` | Implementation deviations, execution-time decisions | Review, continued execution |
+
+```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
+```
+
+### Phase-Specific Context (when $PHASE is set)
+
+```bash
+PHASE_DIR=".specd/tasks/$TASK_NAME/phases/phase-$(printf '%02d' $PHASE)"
+
+# Read phase plan
+[ -f "$PHASE_DIR/PLAN.md" ] && cat "$PHASE_DIR/PLAN.md"
+```
+
+### Codebase Context (if available)
+
+```bash
+# Check for codebase docs
+[ -d ".specd/codebase" ] && {
+  [ -f ".specd/codebase/MAP.md" ] && cat .specd/codebase/MAP.md
+  [ -f ".specd/codebase/PATTERNS.md" ] && cat .specd/codebase/PATTERNS.md
+  [ -f ".specd/codebase/STRUCTURE.md" ] && cat .specd/codebase/STRUCTURE.md
+  [ -f ".specd/codebase/CONCERNS.md" ] && cat .specd/codebase/CONCERNS.md
+}
+```
+
+### Global Config
+
+```bash
+# Check for global specd config (auto-commit settings)
+cat .specd/config.json 2>/dev/null || echo '{}'
+```
+
+### What to Extract After Loading
+
+- **From FEATURE.md:** Files to create, integration points, constraints, success criteria
+- **From CONTEXT.md:** Resolved questions, gray areas, discussion history
+- **From DECISIONS.md:** Active decisions (filter out superseded/revoked)
+- **From RESEARCH.md:** Patterns to follow, libraries to use, pitfalls to avoid
+- **From ROADMAP.md:** Phase order, current phase, success criteria per phase
+- **From STATE.md:** Current stage, completed phases, discussion session count
+- **From codebase docs:** Code patterns, file locations, system architecture
+
+</shared>

package/specdacular/references/record-decision.md

@@ -0,0 +1,61 @@
+<shared name="record_decision">
+
+## Record Decision
+
+Add a new decision to DECISIONS.md with proper numbering and format.
+
+**Before using this reference, you must have ready:**
+- `$TASK_NAME` — the task name
+- The decision details (from discussion, research, or review)
+
+### When to Record
+
+Record a decision when:
+- Technology or library choice is made
+- Architecture pattern is chosen
+- Scope inclusion/exclusion is decided
+- Multiple valid approaches exist and one is picked
+- A constraint is discovered during discussion/research/review
+
+### Determine Next Decision Number
+
+Read `.specd/tasks/$TASK_NAME/DECISIONS.md` and find the highest existing DEC-{NNN} number. Increment by 1. Zero-pad to 3 digits.
+
+### Add Decision Entry
+
+Append to the **Active Decisions** section of DECISIONS.md:
+
+```markdown
+### DEC-{NNN}: {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Active
+**Context:** {What situation required this decision}
+**Decision:** {What was decided}
+**Rationale:**
+- {Why this choice was made}
+- {Additional reasoning}
+**Implications:**
+- {What this means for implementation}
+- {Files or patterns affected}
+**References:**
+- `@{path/to/relevant/code}` (if applicable)
+```
+
+### Update Decision Log Table
+
+Add a row to the Decision Log table at the bottom of DECISIONS.md:
+
+```markdown
+| DEC-{NNN} | {YYYY-MM-DD} | {Decision Title} | Active |
+```
+
+### Update Config
+
+Increment `decisions_count` in `.specd/tasks/$TASK_NAME/config.json`.
+
+### Multiple Decisions
+
+When recording multiple decisions in one session, number them sequentially and add all to the log table.
+
+</shared>

package/specdacular/references/select-feature.md

@@ -1,25 +1,25 @@
-<shared name="select_feature">
+<shared name="select_task">
 
-## Feature Selection
+## Task Selection
 
-Determine which feature to work on.
+Determine which task to work on.
 
 **If $ARGUMENTS provided:**
-Use as feature name. Normalize to kebab-case (lowercase, hyphens).
+Use as task name. Normalize to kebab-case (lowercase, hyphens).
 
 ```bash
-[ -d ".specd/features/$ARGUMENTS" ] || { echo "not found"; exit 1; }
+[ -d ".specd/tasks/$ARGUMENTS" ] || { echo "not found"; exit 1; }
 ```
 
-**If feature not found:**
+**If task not found:**
 ```
-Feature '{name}' not found.
+Task '{name}' not found.
 
-Available features:
+Available tasks:
 ```
 
 ```bash
-ls -d .specd/features/*/ 2>/dev/null | while read dir; do
+ls -d .specd/tasks/*/ 2>/dev/null | while read dir; do
   basename "$dir"
 done
 ```
@@ -27,31 +27,31 @@ done
 End workflow.
 
 **If no arguments:**
-Scan for in-progress features:
+Scan for in-progress tasks:
 
 ```bash
-# List feature directories with config.json
-for dir in .specd/features/*/config.json; do
+# List task directories with config.json
+for dir in .specd/tasks/*/config.json; do
   [ -f "$dir" ] && echo "$dir"
 done
 ```
 
 Read each `config.json` and filter where `stage != "complete"`.
 
-**If no features found:**
+**If no tasks found:**
 ```
-No features in progress.
+No tasks in progress.
 
-Start one with /specd:feature:new
+Start one with /specd:new
 ```
 End workflow.
 
-**If features found:**
+**If tasks found:**
 Use AskUserQuestion:
-- header: "Feature"
-- question: "Which feature would you like to work on?"
-- options: List each feature with its current stage (e.g., "my-feature (discussion)", "other-feature (execution)")
+- header: "Task"
+- question: "Which task would you like to work on?"
+- options: List each task with its current stage (e.g., "my-task (discussion)", "other-task (execution)")
 
-Use the selected feature name.
+Use the selected task name.
 
 </shared>

package/specdacular/references/select-phase.md

@@ -2,13 +2,13 @@
 
 ## Phase Selection
 
-Determine which phase to work on. Requires a feature name to be already selected.
+Determine which phase to work on. Requires a task name to be already selected.
 
 **Read available phases:**
-Read `.specd/features/{feature-name}/ROADMAP.md` and extract the phase list with status.
+Read `.specd/tasks/{task-name}/ROADMAP.md` and extract the phase list with status.
 
 ```bash
-[ -f ".specd/features/{feature-name}/ROADMAP.md" ] || { echo "No roadmap found. Run /specd:feature:continue to create one."; exit 1; }
+[ -f ".specd/tasks/{task-name}/ROADMAP.md" ] || { echo "No roadmap found. Run /specd:continue to create one."; exit 1; }
 ```
 
 Parse the ROADMAP.md "Phases" section to get:

package/specdacular/references/spawn-research-agents.md

@@ -0,0 +1,180 @@
+<shared name="spawn_research_agents">
+
+## Spawn Research Agents
+
+Spawn three parallel research agents. Use `run_in_background: true` for all.
+
+**Before using this reference, you must have ready:**
+- `$TASK_NAME` — the task name
+- `$TASK_CONTEXT` — summary of what's being built (from FEATURE.md)
+- `$CONSTRAINTS` — active decisions and constraints (from DECISIONS.md)
+- `$TECH_STACK` — technology stack (from codebase docs if available)
+- `$FILES_TO_CREATE` — list of files to create (from FEATURE.md or PLAN.md)
+- `$FILES_TO_MODIFY` — list of files to modify (from FEATURE.md or PLAN.md)
+
+### Agent 1: Codebase Integration
+
+Uses the Explore agent to analyze how the task integrates with existing code.
+
+```
+Task(
+  subagent_type: "Explore"
+  description: "Codebase integration research"
+  run_in_background: true
+  prompt: "Research how {task-name} should integrate with the existing codebase.
+
+<task_context>
+$TASK_CONTEXT
+</task_context>
+
+<constraints>
+$CONSTRAINTS
+</constraints>
+
+<files_to_create>
+$FILES_TO_CREATE
+</files_to_create>
+
+<files_to_modify>
+$FILES_TO_MODIFY
+</files_to_modify>
+
+<research_questions>
+1. What existing files/modules will new files need to import from?
+2. What patterns do similar files in this codebase follow?
+3. Where exactly should new files be created?
+4. What types/interfaces already exist that should be reused?
+5. What utility functions or hooks can be leveraged?
+</research_questions>
+
+<output_format>
+## Codebase Integration
+
+### Import Dependencies
+- `path/to/file` — what it provides, why needed
+
+### Patterns to Follow
+- Pattern name: description, example file reference
+
+### File Locations
+- Where each new file should go
+
+### Reusable Code
+- Types: list with paths
+- Utilities: list with paths
+
+### Integration Points
+- Where new code connects to existing code
+</output_format>"
+)
+```
+
+### Agent 2: Implementation Patterns
+
+Uses a general-purpose agent with the feature-researcher role.
+
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Implementation patterns research"
+  run_in_background: true
+  prompt: "First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
+
+<research_type>
+Implementation patterns for {task-name}.
+</research_type>
+
+<task_context>
+$TASK_CONTEXT
+</task_context>
+
+<tech_stack>
+$TECH_STACK
+</tech_stack>
+
+<research_questions>
+1. What's the standard approach for this type of work in this stack?
+2. What libraries are commonly used?
+3. What code patterns work well?
+4. What should NOT be hand-rolled?
+</research_questions>
+
+<tool_strategy>
+1. Context7 first for any library questions
+2. Official docs via WebFetch for gaps
+3. WebSearch for patterns (include current year)
+4. Verify all findings
+</tool_strategy>
+
+<output_format>
+## Implementation Patterns
+
+### Standard Approach
+{Recommended approach with rationale}
+
+### Libraries
+| Library | Version | Purpose | Confidence |
+
+### Code Patterns
+{Code examples with sources}
+
+### Don't Hand-Roll
+| Problem | Use Instead | Why |
+</output_format>"
+)
+```
+
+### Agent 3: Pitfalls
+
+Uses a general-purpose agent with the feature-researcher role.
+
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Pitfalls research"
+  run_in_background: true
+  prompt: "First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
+
+<research_type>
+Pitfalls research for {task-name}.
+</research_type>
+
+<task_context>
+$TASK_CONTEXT
+</task_context>
+
+<research_questions>
+1. What do developers commonly get wrong with this type of work?
+2. What are the performance pitfalls?
+3. What security issues should be avoided?
+4. What integration mistakes happen?
+</research_questions>
+
+<tool_strategy>
+1. WebSearch for common mistakes (include current year)
+2. Look for post-mortems, issue discussions
+3. Check official docs for warnings/caveats
+</tool_strategy>
+
+<output_format>
+## Pitfalls
+
+### Critical (causes failures/rewrites)
+- Pitfall: description, prevention, detection
+
+### Moderate (causes bugs/debt)
+- Pitfall: description, prevention
+
+### Minor (causes friction)
+- Pitfall: description, prevention
+</output_format>"
+)
+```
+
+### After Spawning
+
+Wait for all three agents to complete. Read their output files. Continue to synthesis using `@synthesize-research.md`.
+
+</shared>

package/specdacular/references/synthesize-research.md

@@ -0,0 +1,127 @@
+<shared name="synthesize_research">
+
+## Synthesize Research
+
+Combine findings from three research agents into a single RESEARCH.md.
+
+**Before using this reference, you must have ready:**
+- `$TASK_NAME` — the task name
+- Agent 1 output (Codebase Integration findings)
+- Agent 2 output (Implementation Patterns findings)
+- Agent 3 output (Pitfalls findings)
+
+### Collect Agent Outputs
+
+Read the output from each background agent. If an agent failed or returned empty results, note it in the confidence assessment but continue with available data.
+
+### Write RESEARCH.md
+
+Write to `.specd/tasks/$TASK_NAME/RESEARCH.md`:
+
+```markdown
+# Research: {task-name}
+
+**Researched:** {YYYY-MM-DD}
+
+## Summary
+
+{2-3 paragraphs synthesizing all findings}
+
+**Key recommendation:** {One-liner actionable guidance}
+
+---
+
+## Codebase Integration
+
+{From Agent 1 — Explore findings}
+
+### Import From
+| Module | Provides | Path |
+|--------|----------|------|
+
+### Patterns to Follow
+{Patterns with file references}
+
+### File Locations
+{Exact paths for new files}
+
+### Reusable Code
+- **Types:** {list with @paths}
+- **Utilities:** {list with @paths}
+
+### Integration Points
+{Where new code connects to existing code}
+
+---
+
+## Implementation Patterns
+
+{From Agent 2 — Pattern findings}
+
+### Standard Approach
+{Recommended approach with rationale}
+
+### Libraries
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+
+### Code Patterns
+{Code examples with sources}
+
+### Don't Hand-Roll
+| Problem | Use Instead | Why |
+|---------|-------------|-----|
+
+---
+
+## Pitfalls
+
+{From Agent 3 — Pitfalls findings}
+
+### Critical
+{List with prevention strategies}
+
+### Moderate
+{List with prevention strategies}
+
+### Warnings
+| When Implementing | Watch Out For | Prevention |
+|-------------------|---------------|------------|
+
+---
+
+## Confidence Assessment
+
+| Area | Level | Reason |
+|------|-------|--------|
+| Codebase integration | {HIGH/MEDIUM/LOW} | {reason} |
+| Implementation patterns | {HIGH/MEDIUM/LOW} | {reason} |
+| Pitfalls | {HIGH/MEDIUM/LOW} | {reason} |
+
+## Open Questions
+
+{Anything that couldn't be resolved — may need discussion}
+
+## Sources
+
+### Codebase
+- {file references explored}
+
+### External
+- {Context7 queries, docs URLs}
+```
+
+### Confidence Levels
+
+- **HIGH** — From Context7, official docs, or verified against codebase
+- **MEDIUM** — From reputable sources, verified but not tested
+- **LOW** — From general search, unverified, or conflicting sources
+
+### Extract Decisions
+
+If research reveals clear technology/library/pattern choices, record them using `@record-decision.md`. Common research-driven decisions:
+- Library selections (with version)
+- Pattern choices (e.g., "use X pattern, not Y")
+- Scope constraints discovered from pitfalls
+
+</shared>

package/specdacular/references/validate-task.md

@@ -0,0 +1,64 @@
+<shared name="validate_task">
+
+## Validate Task Exists
+
+Check that a task directory exists with required files.
+
+**Before using this reference, you must have ready:**
+- `$TASK_NAME` — the task name (from `$ARGUMENTS` or parsed)
+
+**Basic validation (all workflows):**
+
+```bash
+# Check task directory exists
+[ -d ".specd/tasks/$TASK_NAME" ] || { echo "not found"; exit 1; }
+
+# 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; }
+```
+
+**If task not found:**
+```
+Task '{name}' not found.
+
+Run /specd:new {name} to create it.
+```
+
+**If required files missing:**
+```
+Task '{name}' is missing required files:
+- {missing file}
+
+Run /specd:discuss {name} to rebuild context.
+```
+
+**Extended validation (for plan/execute/review):**
+
+```bash
+# Check phases exist (for execute/review)
+[ -d ".specd/tasks/$TASK_NAME/phases" ] || { echo "no phases"; exit 1; }
+
+# Check ROADMAP exists (for execute/review)
+[ -f ".specd/tasks/$TASK_NAME/ROADMAP.md" ] || { echo "no roadmap"; exit 1; }
+```
+
+**If no phases:**
+```
+Task '{name}' has no phases yet.
+
+Run /specd:plan {name} to create phases.
+```
+
+**Optional file checks (note existence, don't fail):**
+
+```bash
+# Check optional files
+[ -f ".specd/tasks/$TASK_NAME/RESEARCH.md" ] && echo "has_research"
+[ -f ".specd/tasks/$TASK_NAME/ROADMAP.md" ] && echo "has_roadmap"
+```
+
+</shared>

package/specdacular/templates/{features → tasks}/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog: {feature-name}
+# Changelog: {task-name}
 
 Implementation log - auto-captured decisions and deviations during execution.
 
@@ -6,7 +6,7 @@ Implementation log - auto-captured decisions and deviations during execution.
 
 ## Phase 1: {Phase Name}
 
-### {YYYY-MM-DD} - Plan 01
+### {YYYY-MM-DD} - PLAN.md
 
 **{Brief title}**
 - **What:** {What was decided/changed}
@@ -15,12 +15,6 @@ Implementation log - auto-captured decisions and deviations during execution.
 
 ---
 
-**{Another decision}**
-- **What:** {Description}
-- **Why:** {Reason}
-
----
-
 ## Compacted Summary
 
 {Space for human review - summarize key decisions after implementation}

package/specdacular/templates/{features → tasks}/CONTEXT.md

@@ -1,4 +1,4 @@
-# Context: {feature-name}
+# Context: {task-name}
 
 **Last Updated:** {YYYY-MM-DD}
 **Sessions:** {N}
@@ -11,7 +11,7 @@
 
 ## Resolved Questions
 
-{Questions that came up during discussion and were resolved. Each section represents a gray area that was clarified.}
+{Questions that came up during discussion and were resolved.}
 
 ### {Question title}
 
@@ -34,20 +34,9 @@
 
 ---
 
-### {Question title}
-
-**Question:** {What was unclear}
-
-**Resolution:** {The answer}
-
-**Details:**
-- {Details}
-
----
-
 ## Deferred Questions
 
-{Questions identified but intentionally deferred. Include why and when to revisit.}
+{Questions identified but intentionally deferred.}
 
 ### {Deferred question}
 
@@ -76,6 +65,6 @@
 
 ## Quick Reference
 
-- **Feature:** `.specd/features/{feature-name}/FEATURE.md`
-- **Decisions:** `.specd/features/{feature-name}/DECISIONS.md`
-- **Research:** `.specd/features/{feature-name}/RESEARCH.md` (if exists)
+- **Task:** `.specd/tasks/{task-name}/FEATURE.md`
+- **Decisions:** `.specd/tasks/{task-name}/DECISIONS.md`
+- **Research:** `.specd/tasks/{task-name}/RESEARCH.md` (if exists)