specdacular 0.7.2 → 0.8.0

package/specdacular/templates/tasks/DECISIONS.md

@@ -0,0 +1,46 @@
+# Decisions: {task-name}
+
+**Task:** {task-name}
+**Created:** {YYYY-MM-DD}
+**Last Updated:** {YYYY-MM-DD}
+
+---
+
+## Active Decisions
+
+{Decisions currently in effect. These guide implementation.}
+
+### DEC-001: {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Active
+**Context:** {What situation required this decision}
+**Decision:** {What was decided}
+**Rationale:**
+- {Reason 1}
+- {Reason 2}
+**Implications:**
+- {What this means for implementation}
+- {Files or patterns affected}
+**References:**
+- `@{path/to/relevant/code}` (if applicable)
+
+---
+
+## Superseded Decisions
+
+{Decisions that were replaced by newer decisions. Kept for history.}
+
+---
+
+## Revoked Decisions
+
+{Decisions that were explicitly cancelled without replacement.}
+
+---
+
+## Decision Log
+
+| ID | Date | Title | Status |
+|----|------|-------|--------|
+| DEC-001 | {date} | {title} | Active |

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

@@ -1,4 +1,4 @@
-# Feature: {feature-name}
+# Task: {task-name}
 
 ## What This Is
 
@@ -8,7 +8,7 @@
 
 ### Must Create
 
-{Files and components that must be created for this feature to work.}
+{Files and components that must be created for this task to work.}
 
 - [ ] `{path/to/file.ts}` — {What it does}
 - [ ] `{path/to/file.tsx}` — {What it does}
@@ -16,7 +16,7 @@
 
 ### Must Integrate With
 
-{Existing code this feature connects to. Include paths.}
+{Existing code this task connects to. Include paths.}
 
 - `{path/to/existing.ts}` — {How it integrates}
 - `{path/to/existing.ts}` — {How it integrates}

package/specdacular/templates/tasks/PLAN.md

@@ -0,0 +1,91 @@
+---
+task: {task-name}
+phase: {N}
+depends_on: []
+creates:
+  - {path/to/new/file.ts}
+modifies:
+  - {path/to/existing/file.ts}
+---
+
+# Phase {N}: {Phase Title}
+
+## Objective
+
+{What this phase accomplishes and why. 1-2 sentences max.}
+
+## Context
+
+**Reference these files:**
+- `@.specd/codebase/PATTERNS.md` — Code patterns to follow
+- `@.specd/codebase/STRUCTURE.md` — Where files go
+- `@{path/to/pattern/file}` — Pattern to follow for this task
+
+**Relevant Decisions:**
+- DEC-XXX: {Decision that affects this phase}
+
+**From Research:** (if RESEARCH.md exists)
+- {Key finding that affects implementation}
+- {Pitfall to avoid}
+
+---
+
+## Tasks
+
+### Task 1: {Task Title}
+
+**Files:** `{path/to/file}`
+
+**Action:**
+{Clear description of what to create or modify. Include enough detail that the implementing agent doesn't need to ask questions.}
+
+**Verify:**
+```bash
+{command to verify task is complete}
+```
+
+**Done when:**
+- [ ] {Specific, observable completion criterion}
+
+---
+
+### Task 2: {Task Title}
+
+**Files:** `{path/to/file}`
+
+**Action:**
+{Clear description}
+
+**Verify:**
+```bash
+{verification command}
+```
+
+**Done when:**
+- [ ] {Completion criterion}
+
+---
+
+## Verification
+
+After all tasks complete:
+
+```bash
+{commands to verify the phase is done}
+```
+
+**Phase is complete when:**
+- [ ] All tasks marked done
+- [ ] All verification commands pass
+
+---
+
+## Implementation Log
+
+During implementation, capture decisions and deviations to `.specd/tasks/{task-name}/CHANGELOG.md`.
+
+**When to log:**
+- Choosing a different approach than specified
+- Adding functionality not in the plan
+- Skipping or modifying a task
+- Discovering issues that change the approach

package/specdacular/templates/tasks/RESEARCH.md

@@ -0,0 +1,121 @@
+# Research: {task-name}
+
+**Researched:** {YYYY-MM-DD}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Summary
+
+{2-3 paragraphs synthesizing all research findings}
+
+**Key recommendation:** {One-liner actionable guidance for the planner}
+
+---
+
+## Codebase Integration
+
+### Import Dependencies
+
+| Module | Provides | Path |
+|--------|----------|------|
+| {module} | {what it provides} | `{path}` |
+
+### Patterns to Follow
+
+**{Pattern name}**
+Follow pattern in `{existing file path}`:
+- {Key aspect 1}
+- {Key aspect 2}
+
+### File Structure
+
+Where new files should go:
+
+```
+src/
+├── {path}/           # {purpose}
+│   ├── {file}.ts     # {what it does}
+│   └── {file}.tsx    # {what it does}
+```
+
+### Reusable Code
+
+- **Types:** `@{path}` — {what types}
+- **Utilities:** `@{path}` — {what utilities}
+
+### Integration Points
+
+| Connect To | Via | Purpose |
+|------------|-----|---------|
+| {system} | {how} | {why} |
+
+---
+
+## Implementation Patterns
+
+### Standard Approach
+{Recommended approach with rationale}
+
+### Libraries
+
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+| {lib} | {ver}+ | {purpose} | {HIGH/MEDIUM} |
+
+### Code Patterns
+
+```{language}
+// Source: {Context7 / docs URL}
+{verified code example}
+```
+
+### Don't Hand-Roll
+
+| Problem | Use Instead | Why |
+|---------|-------------|-----|
+| {problem} | {library/utility} | {edge cases it handles} |
+
+---
+
+## Pitfalls
+
+### Critical
+- **{Pitfall}** — {description}, Prevention: {steps}
+
+### Moderate
+- **{Pitfall}** — {description}, Prevention: {steps}
+
+### Warnings
+
+| When Implementing | Watch Out For | Prevention |
+|-------------------|---------------|------------|
+| {task/file} | {pitfall} | {how to avoid} |
+
+---
+
+## Confidence Assessment
+
+| Area | Level | Reason |
+|------|-------|--------|
+| Codebase integration | {level} | {reason} |
+| Implementation approach | {level} | {reason} |
+| Pitfalls | {level} | {reason} |
+
+## Open Questions
+
+1. **{Question}** — {what's unclear}, Recommendation: {how to handle}
+
+## Sources
+
+### Codebase
+- `{path}` — {what was learned}
+
+### External
+- {Context7 queries, docs URLs}
+
+---
+
+## Decisions Made
+
+| Decision | Rationale |
+|----------|-----------|
+| DEC-XXX: {title} | {brief rationale} |

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

@@ -1,11 +1,10 @@
-# Roadmap: {feature-name}
+# Roadmap: {task-name}
 
 ## Overview
 
 | Metric | Value |
 |--------|-------|
 | Total Phases | {N} |
-| Total Plans | {N} |
 | Current Phase | 1 |
 | Status | Not Started |
 
@@ -27,19 +26,15 @@
 
 **Creates:**
 - `{path/to/file}` — {Purpose}
-- `{path/to/file}` — {Purpose}
 
 **Modifies:**
 - `{path/to/file}` — {What change}
 
-**Plans:**
-1. `plans/phase-01/01-PLAN.md` — {Plan summary}
-2. `plans/phase-01/02-PLAN.md` — {Plan summary}
+**Plan:** `phases/phase-01/PLAN.md`
 
 **Success Criteria:**
 1. {Observable behavior that proves the phase is complete}
 2. {Observable behavior}
-3. {Observable behavior}
 
 **Dependencies:** None (first phase)
 
@@ -52,52 +47,26 @@
 **Creates:**
 - `{path/to/file}` — {Purpose}
 
-**Modifies:**
-- `{path/to/file}` — {What change}
-
-**Plans:**
-1. `plans/phase-02/01-PLAN.md` — {Plan summary}
+**Plan:** `phases/phase-02/PLAN.md`
 
 **Success Criteria:**
 1. {Observable behavior}
-2. {Observable behavior}
 
 **Dependencies:** Phase 1 complete
 
 ---
 
-### Phase 3: {Name}
-
-**Goal:** {What this phase achieves}
-
-**Creates:**
-- `{path/to/file}` — {Purpose}
-
-**Plans:**
-1. `plans/phase-03/01-PLAN.md` — {Plan summary}
-
-**Success Criteria:**
-1. {Observable behavior}
-2. {Observable behavior}
-
-**Dependencies:** Phase 2 complete
-
----
-
 ## Execution Order
 
-The recommended execution order respects dependencies:
-
 ```
 Phase 1: {Name}
-├── 01-PLAN.md: {summary}
-└── 02-PLAN.md: {summary}
+└── PLAN.md
     ↓
 Phase 2: {Name}
-└── 01-PLAN.md: {summary}
+└── PLAN.md
     ↓
 Phase 3: {Name}
-└── 01-PLAN.md: {summary}
+└── PLAN.md
 ```
 
 ---
@@ -107,9 +76,3 @@ Phase 3: {Name}
 | Decision | Impact on Phases |
 |----------|------------------|
 | DEC-XXX: {title} | {How it affects phase ordering or content} |
-
----
-
-## Notes
-
-{Space for notes about the roadmap — why phases are ordered this way, alternatives considered, etc.}

package/specdacular/templates/tasks/STATE.md

@@ -0,0 +1,93 @@
+# State: {task-name}
+
+## Current Position
+
+**Stage:** {discussion | research | planning | execution}
+**Last Updated:** {YYYY-MM-DD}
+
+---
+
+## Stage Progress
+
+### Discussion
+- [x] Initial discussion complete
+- [ ] Gray areas identified
+- [ ] All gray areas resolved
+
+### Research
+- [ ] Research conducted
+- [ ] Findings documented in RESEARCH.md
+
+### Planning
+- [ ] Phases derived
+- [ ] Plans created
+
+### Execution
+- [ ] Phase 1 complete
+- [ ] Phase 2 complete
+
+---
+
+## Execution Progress
+
+### Current Phase
+- Phase: none
+- Started: —
+
+### Completed Phases
+| Phase | Completed | Tasks | Deviations |
+|-------|-----------|-------|------------|
+
+---
+
+## Review Cycles
+
+| Phase | Cycle | Date | Findings | Fix Plans | Status |
+|-------|-------|------|----------|-----------|--------|
+
+---
+
+## Discussion Sessions
+
+| Date | Focus | Outcome |
+|------|-------|---------|
+| {YYYY-MM-DD} | Initial discussion | FEATURE.md created |
+
+---
+
+## Documents Status
+
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| FEATURE.md | Created | {date} |
+| CONTEXT.md | Created | {date} |
+| DECISIONS.md | {N} decisions | {date} |
+| RESEARCH.md | Not started | — |
+| ROADMAP.md | Not started | — |
+| phases/ | Not started | — |
+
+---
+
+## Decision Count
+
+- **Active:** {N}
+- **Superseded:** {N}
+- **Total:** {N}
+
+---
+
+## Next Steps
+
+{What the user should do next based on current state.}
+
+**Resume:** `/specd:continue {task-name}` — Picks up where you left off.
+
+---
+
+## Quick Reference
+
+- **Task:** `.specd/tasks/{task-name}/FEATURE.md`
+- **Context:** `.specd/tasks/{task-name}/CONTEXT.md`
+- **Decisions:** `.specd/tasks/{task-name}/DECISIONS.md`
+- **Research:** `.specd/tasks/{task-name}/RESEARCH.md`
+- **Roadmap:** `.specd/tasks/{task-name}/ROADMAP.md`

package/specdacular/templates/tasks/config.json

@@ -0,0 +1,15 @@
+{
+  "task_name": "{name}",
+  "created": "{date}",
+  "stage": "discussion",
+  "discussion_sessions": 1,
+  "decisions_count": 0,
+  "phases": {
+    "total": 0,
+    "completed": 0,
+    "current": 1
+  },
+  "execution": {
+    "auto_commit": false
+  }
+}