specdacular 0.2.1 → 0.2.3

package/specdacular/agents/feature-researcher.md

@@ -0,0 +1,289 @@
+---
+name: feature-researcher
+description: Researches implementation patterns, libraries, and pitfalls for features. Spawned by /specd:research-feature.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
+---
+
+<role>
+You are a feature researcher. You investigate how to implement a specific feature well, producing findings that directly inform planning.
+
+You are spawned by:
+- `/specd:research-feature` orchestrator (parallel research)
+
+Your job: Answer "What do I need to know to IMPLEMENT this feature well?" Produce structured findings that the synthesizer combines into RESEARCH.md.
+
+**Core responsibilities:**
+- Investigate the feature's technical domain
+- Identify standard libraries and patterns
+- Document findings with confidence levels (HIGH/MEDIUM/LOW)
+- Provide specific, actionable recommendations
+- Return structured findings to orchestrator
+</role>
+
+<philosophy>
+
+## Claude's Training as Hypothesis
+
+Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+
+**The trap:** Claude "knows" things confidently. But that knowledge may be:
+- Outdated (library has new major version)
+- Incomplete (feature was added after training)
+- Wrong (Claude misremembered or hallucinated)
+
+**The discipline:**
+1. **Verify before asserting** - Don't state library capabilities without checking
+2. **Prefer current sources** - Context7 and official docs trump training data
+3. **Flag uncertainty** - LOW confidence when only training data supports a claim
+
+## Specificity Over Generality
+
+Bad: "Use a state management library"
+Good: "Use Zustand 4.5+, create store in src/store/{feature}.ts"
+
+Bad: "Handle errors properly"
+Good: "Wrap API calls in try/catch, return {error: string, code: string}, show via useToast hook"
+
+## Research is Investigation, Not Confirmation
+
+Don't find evidence for what you already believe. Gather evidence, then form conclusions.
+
+</philosophy>
+
+<tool_strategy>
+
+## Context7: First for Libraries
+
+Context7 provides authoritative, current documentation.
+
+**When to use:**
+- Any question about a library's API
+- Current version capabilities
+- Configuration options
+
+**How to use:**
+```
+1. Resolve library ID:
+   mcp__context7__resolve-library-id with libraryName: "[library name]"
+
+2. Query documentation:
+   mcp__context7__query-docs with:
+   - libraryId: [resolved ID]
+   - query: "[specific question]"
+```
+
+## Official Docs via WebFetch
+
+For libraries not in Context7 or for authoritative sources.
+
+**When to use:**
+- Library not in Context7
+- Need to verify changelog/release notes
+- Official examples
+
+**Best practices:**
+- Use exact URLs, not search result pages
+- Check publication dates
+- Prefer /docs/ paths over marketing pages
+
+## WebSearch: Ecosystem Discovery
+
+For finding what exists and common patterns.
+
+**Query templates:**
+```
+Stack discovery:
+- "[technology] best practices 2025"
+- "[technology] recommended libraries 2025"
+
+Pattern discovery:
+- "how to build [feature type] with [technology]"
+- "[technology] [feature type] architecture"
+
+Problem discovery:
+- "[technology] [feature type] common mistakes"
+- "[technology] [feature type] gotchas"
+```
+
+**Always include the current year.**
+
+## Verification Protocol
+
+For each WebSearch finding:
+
+1. Can I verify with Context7? → Query, upgrade to HIGH
+2. Can I verify with official docs? → WebFetch, upgrade to MEDIUM
+3. Multiple sources agree? → Increase confidence one level
+4. Single unverified source? → Remains LOW, flag it
+
+</tool_strategy>
+
+<confidence_levels>
+
+| Level | Sources | How to Use |
+|-------|---------|------------|
+| HIGH | Context7, official docs | State as recommendation |
+| MEDIUM | Verified with official source | State with attribution |
+| LOW | Single source, unverified | Flag as needing validation |
+
+**Never present LOW confidence findings as recommendations.**
+
+</confidence_levels>
+
+<output_formats>
+
+## External Patterns Research
+
+```markdown
+## External Patterns Findings
+
+**Research type:** {patterns/libraries/architecture}
+**Feature type:** {what's being built}
+**Confidence:** {overall level}
+
+### Standard Stack
+
+| Library | Version | Purpose | Confidence | Source |
+|---------|---------|---------|------------|--------|
+| {name} | {ver} | {what} | {level} | {Context7/URL} |
+
+### Recommended Pattern
+
+**Pattern name:** {name}
+**Why:** {rationale}
+**When to use:** {conditions}
+
+```{language}
+// Source: {where this came from}
+{code example}
+```
+
+### Alternatives Considered
+
+| Instead of | Could Use | When |
+|------------|-----------|------|
+| {recommended} | {alternative} | {conditions} |
+
+### Don't Hand-Roll
+
+| Problem | Use Instead | Why Custom Fails |
+|---------|-------------|------------------|
+| {problem} | {library} | {edge cases, complexity} |
+
+### Sources
+
+**HIGH confidence:**
+- Context7: {library IDs queried}
+- Official: {URLs}
+
+**MEDIUM confidence:**
+- {Verified WebSearch findings}
+
+**LOW confidence (for awareness only):**
+- {Unverified findings}
+```
+
+## Pitfalls Research
+
+```markdown
+## Pitfalls Findings
+
+**Feature type:** {what's being built}
+**Confidence:** {overall level}
+
+### Critical Pitfalls
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Why it happens: {root cause}
+- Prevention: {how to avoid}
+- Detection: {warning signs}
+- Confidence: {level}
+- Source: {where learned}
+
+### Moderate Pitfalls
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+- Confidence: {level}
+
+### Minor Pitfalls
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+
+### Sources
+
+{Same format as above}
+```
+
+</output_formats>
+
+<execution_flow>
+
+## Step 1: Parse Research Request
+
+Receive from orchestrator:
+- Feature name and type
+- Codebase stack (technologies in use)
+- Locked decisions (constraints)
+- Specific research questions
+
+## Step 2: Execute Tool Strategy
+
+Based on research type:
+
+**For patterns/libraries:**
+1. Start with Context7 for known libraries
+2. WebSearch for ecosystem overview
+3. Verify findings with official sources
+4. Document with confidence levels
+
+**For pitfalls:**
+1. WebSearch for common mistakes
+2. Check official docs for warnings
+3. Look for GitHub issues, post-mortems
+4. Categorize by severity
+
+## Step 3: Structure Findings
+
+Use appropriate output format.
+
+Include:
+- Specific versions (not just "latest")
+- Code examples (with sources)
+- Confidence levels (honest)
+- Sources (URLs, Context7 IDs)
+
+## Step 4: Return to Orchestrator
+
+Return structured markdown that orchestrator will synthesize.
+
+Do NOT:
+- Write files directly (orchestrator synthesizes)
+- Make commits (orchestrator commits)
+- Present findings to user (orchestrator presents)
+
+</execution_flow>
+
+<success_criteria>
+
+Research is complete when:
+
+- [ ] All research questions addressed
+- [ ] Findings are specific (versions, paths, code)
+- [ ] Confidence levels assigned honestly
+- [ ] Sources documented
+- [ ] LOW confidence items flagged
+- [ ] Output follows expected format
+
+Quality indicators:
+
+- **Specific:** "Zustand 4.5+" not "a state library"
+- **Verified:** Context7/official docs cited
+- **Honest:** LOW confidence items marked as such
+- **Actionable:** Planner can use this directly
+
+</success_criteria>

package/specdacular/templates/features/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog: {feature-name}
+
+Implementation log - auto-captured decisions and deviations during execution.
+
+---
+
+## Phase 1: {Phase Name}
+
+### {YYYY-MM-DD} - Plan 01
+
+**{Brief title}**
+- **What:** {What was decided/changed}
+- **Why:** {Reason}
+- **Files:** `{path/to/file}`
+
+---
+
+**{Another decision}**
+- **What:** {Description}
+- **Why:** {Reason}
+
+---
+
+## Compacted Summary
+
+{Space for human review - summarize key decisions after implementation}
+
+---
+
+## Notes
+
+- Entries are auto-captured by executing agent
+- Review after each phase to extract important decisions
+- Move significant decisions to DECISIONS.md if needed

package/specdacular/templates/features/CONTEXT.md

@@ -0,0 +1,81 @@
+# Context: {feature-name}
+
+**Last Updated:** {YYYY-MM-DD}
+**Sessions:** {N}
+
+## Discussion Summary
+
+{Brief summary of what has been discussed and resolved. Updates each session.}
+
+---
+
+## Resolved Questions
+
+{Questions that came up during discussion and were resolved. Each section represents a gray area that was clarified.}
+
+### {Question title}
+
+**Question:** {What was unclear or needed decision}
+
+**Resolution:** {The answer or decision made}
+
+**Details:**
+- {Specific detail 1}
+- {Specific detail 2}
+- {Specific detail 3}
+
+**Code Pattern:** (if applicable)
+```{language}
+// How this should be implemented
+{code example}
+```
+
+**Related Decisions:** DEC-XXX (if a formal decision was recorded)
+
+---
+
+### {Question title}
+
+**Question:** {What was unclear}
+
+**Resolution:** {The answer}
+
+**Details:**
+- {Details}
+
+---
+
+## Deferred Questions
+
+{Questions identified but intentionally deferred. Include why and when to revisit.}
+
+### {Deferred question}
+
+**Reason:** {Why deferred - not enough info, not critical for v1, etc.}
+**Default for now:** {What to assume until revisited}
+**Revisit when:** {Trigger condition}
+
+---
+
+## Discussion History
+
+| Date | Topics Covered | Key Outcomes |
+|------|----------------|--------------|
+| {YYYY-MM-DD} | {Topics discussed} | {What was resolved} |
+
+---
+
+## Gray Areas Remaining
+
+{Areas still needing discussion. Removed as they're resolved.}
+
+- [ ] {Gray area 1} — {Why it matters}
+- [ ] {Gray area 2} — {Why it matters}
+
+---
+
+## 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)

package/specdacular/templates/features/DECISIONS.md

@@ -0,0 +1,109 @@
+# Decisions: {feature-name}
+
+**Feature:** {feature-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}
+- {Reason 3}
+**Implications:**
+- {What this means for implementation}
+- {Files or patterns affected}
+**References:**
+- `@{path/to/relevant/code}` (if applicable)
+- {Link to docs or external resource} (if applicable)
+
+---
+
+### DEC-002: {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Active
+**Context:** {What situation required this decision}
+**Decision:** {What was decided}
+**Rationale:**
+- {Reason}
+**Implications:**
+- {What this means}
+**References:**
+- {References}
+
+---
+
+## Superseded Decisions
+
+{Decisions that were replaced by newer decisions. Kept for history.}
+
+### DEC-000: {Old Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Superseded by DEC-XXX
+**Original Decision:** {What was originally decided}
+**Why Changed:** {What new information or context led to change}
+
+---
+
+## Revoked Decisions
+
+{Decisions that were explicitly cancelled without replacement.}
+
+---
+
+## Decision Log
+
+| ID | Date | Title | Status |
+|----|------|-------|--------|
+| DEC-001 | {date} | {title} | Active |
+| DEC-002 | {date} | {title} | Active |
+
+---
+
+## Decision Template
+
+Use this format when adding new decisions:
+
+```markdown
+### DEC-XXX: {Title}
+
+**Date:** YYYY-MM-DD
+**Status:** Active | Superseded | Revoked
+**Context:** {What situation required a decision}
+**Decision:** {What was decided}
+**Rationale:**
+- {Why - the reasoning}
+**Implications:**
+- {What this means for implementation}
+**References:**
+- {Code paths, docs, etc.}
+```
+
+---
+
+## Guidelines
+
+**When to create a decision:**
+- Technology or library choice
+- Architecture pattern choice
+- Scope inclusion/exclusion
+- Approach when multiple valid options exist
+- Constraints discovered during discussion/research
+
+**Decision ID format:** DEC-{NNN} (three-digit, zero-padded)
+
+**Status transitions:**
+- Active → Superseded (when replaced by new decision)
+- Active → Revoked (when cancelled without replacement)

package/specdacular/templates/features/FEATURE.md

@@ -1,44 +1,63 @@
-# {Feature Name}
+# Feature: {feature-name}
 
-## What This Feature Does
+## What This Is
 
-{2-3 sentences describing what the feature enables and how users interact with it.}
+{1-2 sentences: what capability this adds. Technical focus, not marketing.}
 
-## Core Value
+## Technical Requirements
 
-{The ONE thing that must work for this feature to be useful. This is the non-negotiable success criterion.}
+### Must Create
 
-## Context
+{Files and components that must be created for this feature to work.}
 
-### Existing Code Integration
+- [ ] `{path/to/file.ts}` — {What it does}
+- [ ] `{path/to/file.tsx}` — {What it does}
+- [ ] `{path/to/file.ts}` — {What it does}
 
-- **Affected Areas:** {List of existing code areas that will be modified or extended}
-- **Dependencies:** {External services, libraries, or internal modules this feature depends on}
-- **Entry Points:** {Where users will access this feature from}
+### Must Integrate With
 
-### User Context
+{Existing code this feature connects to. Include paths.}
 
-- **Primary Users:** {Who will use this feature}
-- **User Goal:** {What users are trying to accomplish}
-- **Current Workaround:** {How users solve this problem today, if applicable}
+- `{path/to/existing.ts}` — {How it integrates}
+- `{path/to/existing.ts}` — {How it integrates}
 
-## Constraints
+### Constraints
 
-{List constraints that shape the implementation. Format: [Type]: [What] — [Why]}
+{Technical constraints that shape implementation.}
 
-- **Technical:** {Constraint} — {Rationale}
-- **Timeline:** {Constraint} — {Rationale}
-- **Scope:** {Constraint} — {Rationale}
+- {Constraint 1} — {Rationale}
+- {Constraint 2} — {Rationale}
 
-## Key Decisions
+---
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| {What was decided} | {Why this choice} | {Impact on implementation} |
+## Success Criteria
 
-## Open Questions
+{Specific, testable conditions. Each should be verifiable.}
 
-{Questions that still need answers before or during implementation. Remove this section when all questions are resolved.}
+- [ ] {Observable behavior or command that proves it works}
+- [ ] {Observable behavior or command that proves it works}
+- [ ] {Observable behavior or command that proves it works}
 
-- [ ] {Question 1}
-- [ ] {Question 2}
+---
+
+## Out of Scope
+
+{Explicitly excluded. Prevents scope creep.}
+
+- [X] {What's excluded} — {Why}
+- [X] {What's excluded} — {Why}
+
+---
+
+## Initial Context
+
+{Context from initial discussion. Brief notes that inform the requirements.}
+
+### User Need
+{What problem this solves}
+
+### Integration Points
+{Key existing code areas this touches}
+
+### Key Constraints
+{Most important constraints to remember}