specdacular 0.7.0 → 0.7.1

package/commands/specd/feature/research.md

@@ -1,459 +0,0 @@
----
-name: specd:feature:research
-description: Research how to implement a feature - spawns parallel agents for codebase, external, and pitfalls research
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-> **Note:** Consider using `/specd:feature:next` instead — it guides you through the entire feature lifecycle automatically, including research.
-
-Research how to implement a feature before planning. Spawns parallel research agents to investigate:
-
-1. **Codebase Integration** - How does this fit with existing code? (uses Claude Code Explore agent)
-2. **External Patterns** - What libraries/patterns are standard for this?
-3. **Pitfalls** - What commonly goes wrong?
-
-**Output:** `.specd/features/{name}/RESEARCH.md` with prescriptive guidance for the planner.
-
-**Why parallel agents:** Research burns context fast. Fresh context per dimension = thorough investigation. Synthesize results into single RESEARCH.md.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/research-feature.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS
-
-**Load feature context:**
-@.specd/features/{name}/FEATURE.md
-@.specd/features/{name}/DECISIONS.md
-@.specd/features/{name}/CONTEXT.md (if exists)
-
-**Load codebase context:**
-@.specd/codebase/ARCHITECTURE.md
-@.specd/codebase/CONVENTIONS.md
-@.specd/codebase/STACK.md
-</context>
-
-<process>
-
-## Phase 1: Validate Feature
-
-```bash
-# Check feature exists
-[ -d ".specd/features/$ARGUMENTS" ] || { echo "Feature not found. Run /specd:feature:new first."; exit 1; }
-
-# Check if RESEARCH.md exists
-[ -f ".specd/features/$ARGUMENTS/RESEARCH.md" ] && echo "existing"
-```
-
-**If RESEARCH.md exists:**
-Use AskUserQuestion:
-- header: "Research Exists"
-- question: "Research already exists for this feature. What would you like to do?"
-- options:
-  - "Update research" — Re-run research, incorporate new findings
-  - "View existing" — Show current RESEARCH.md
-  - "Continue anyway" — Skip research, use existing
-
-## Phase 2: Load Feature Context
-
-Read and parse:
-- `FEATURE.md` - What needs to be built
-- `DECISIONS.md` - Constraints already decided
-- `CONTEXT.md` - Gray areas already resolved (if exists)
-
-Extract:
-- Technical requirements (files to create, integrations needed)
-- Locked decisions (don't research alternatives)
-- Open questions (areas to investigate)
-
-## Phase 3: Identify Research Dimensions
-
-Based on feature requirements, determine what needs research:
-
-**Always research:**
-- Codebase integration patterns
-- Pitfalls for this type of feature
-
-**Conditionally research:**
-- External libraries (if new dependencies needed)
-- API patterns (if building APIs)
-- UI patterns (if building UI components)
-- Data modeling (if new models needed)
-
-Present research plan:
-```
-I'll research these dimensions for {feature-name}:
-
-1. **Codebase Integration** — How this fits with existing code
-   - Integration points in current architecture
-   - Patterns to follow from existing code
-   - Files that will need modification
-
-2. **External Patterns** — Standard approaches for {feature-type}
-   - Libraries commonly used
-   - Architecture patterns
-   - Code examples
-
-3. **Pitfalls** — What commonly goes wrong
-   - Implementation mistakes
-   - Integration gotchas
-   - Performance traps
-
-Estimated: 3 parallel research agents
-
-[Start research] / [Adjust scope]
-```
-
-## Phase 4: Spawn Parallel Research Agents
-
-### Agent 1: Codebase Integration (using Explore agent)
-
-```
-Task(
-  prompt="Research how {feature-name} should integrate with the existing codebase.
-
-<feature_context>
-{FEATURE.md content}
-</feature_context>
-
-<locked_decisions>
-{Relevant decisions from DECISIONS.md}
-</locked_decisions>
-
-<research_questions>
-1. What existing files/modules will this feature need to import from?
-2. What patterns do similar features in this codebase follow?
-3. Where should new files be created based on project structure?
-4. What types/interfaces already exist that this feature should use?
-5. What utility functions or hooks can be reused?
-</research_questions>
-
-<output_format>
-Return findings as structured markdown:
-
-## Codebase Integration Findings
-
-### Import Dependencies
-- `path/to/file` — what it provides, why needed
-
-### Patterns to Follow
-- Pattern name: description, example file reference
-
-### File Locations
-- New files should go in: path/reason
-- Existing files to modify: path/what change
-
-### Reusable Code
-- Types: list with paths
-- Utilities: list with paths
-- Components: list with paths
-
-### Integration Points
-- Where this connects to existing code
-- What interfaces to implement
-</output_format>
-",
-  subagent_type="Explore",
-  description="Codebase integration research"
-)
-```
-
-### Agent 2: External Patterns Research
-
-```
-Task(
-  prompt="First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
-
-<research_type>
-External patterns research for {feature-type}.
-</research_type>
-
-<feature_context>
-{FEATURE.md content}
-</feature_context>
-
-<codebase_stack>
-{From .specd/codebase/STACK.md}
-</codebase_stack>
-
-<locked_decisions>
-{Decisions that constrain library/pattern choices}
-</locked_decisions>
-
-<research_questions>
-1. What's the standard approach for {feature-type} in {stack}?
-2. What libraries are commonly used? (verify versions with Context7)
-3. What architecture patterns work well?
-4. What code patterns are recommended?
-5. 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 ecosystem patterns (include current year)
-4. Verify all findings - no LOW confidence recommendations
-</tool_strategy>
-
-<output_format>
-Return findings as structured markdown with confidence levels.
-</output_format>
-",
-  subagent_type="general-purpose",
-  model="sonnet",
-  description="External patterns research"
-)
-```
-
-### Agent 3: Pitfalls Research
-
-```
-Task(
-  prompt="First, read ~/.claude/specdacular/agents/feature-researcher.md for your role.
-
-<research_type>
-Pitfalls research for {feature-type}.
-</research_type>
-
-<feature_context>
-{FEATURE.md content}
-</feature_context>
-
-<codebase_context>
-{Relevant architecture/conventions}
-</codebase_context>
-
-<research_questions>
-1. What do developers commonly get wrong with {feature-type}?
-2. What are the performance pitfalls?
-3. What security issues should be avoided?
-4. What integration mistakes happen?
-5. What looks simple but is actually complex?
-</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
-4. Consider edge cases specific to this stack
-</tool_strategy>
-
-<output_format>
-Return pitfalls as structured markdown:
-
-## Pitfalls for {feature-type}
-
-### Critical (causes failures/rewrites)
-- Pitfall: description
-  - Why it happens: reason
-  - Prevention: how to avoid
-  - Detection: warning signs
-
-### Moderate (causes bugs/debt)
-- Pitfall: description
-  - Prevention: how to avoid
-
-### Minor (causes friction)
-- Pitfall: description
-  - Prevention: how to avoid
-</output_format>
-",
-  subagent_type="general-purpose",
-  model="sonnet",
-  description="Pitfalls research"
-)
-```
-
-## Phase 5: Synthesize Results
-
-After all agents complete, synthesize into single RESEARCH.md:
-
-```markdown
-# Research: {feature-name}
-
-**Researched:** {date}
-**Feature:** {feature-type}
-**Confidence:** {overall level}
-
-## 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 Structure
-```
-src/
-├── {where new files go}
-└── {existing files to modify}
-```
-
-### Reusable Code
-- **Types:** {list with @paths}
-- **Utilities:** {list with @paths}
-- **Components:** {list with @paths}
-
----
-
-## Implementation Approach
-
-{From Agent 2 - External patterns}
-
-### Standard Stack
-| Library | Version | Purpose | Confidence |
-|---------|---------|---------|------------|
-| ... | ... | ... | HIGH/MED |
-
-### Architecture Pattern
-{Recommended pattern with rationale}
-
-### Code Patterns
-```typescript
-// Pattern name - source: {Context7/docs URL}
-{code example}
-```
-
-### Don't Hand-Roll
-| Problem | Use Instead | Why |
-|---------|-------------|-----|
-| ... | ... | ... |
-
----
-
-## Pitfalls
-
-{From Agent 3 - Pitfalls research}
-
-### Critical
-{List with prevention strategies}
-
-### Moderate
-{List with prevention strategies}
-
-### Task-Specific Warnings
-| When Implementing | Watch Out For | Prevention |
-|-------------------|---------------|------------|
-| ... | ... | ... |
-
----
-
-## Confidence Assessment
-
-| Area | Level | Reason |
-|------|-------|--------|
-| Codebase integration | {level} | {reason} |
-| Implementation approach | {level} | {reason} |
-| Pitfalls | {level} | {reason} |
-
-## Open Questions
-
-{Anything that couldn't be resolved - planner should be aware}
-
-## Sources
-
-### Codebase (from Explore)
-- {file references used}
-
-### External (verified)
-- {Context7 queries}
-- {Official docs URLs}
-
-### Community (for awareness)
-- {WebSearch findings - lower confidence}
-```
-
-## Phase 6: Update DECISIONS.md
-
-Any technology choices or pattern decisions from research should be recorded:
-
-```markdown
-### DEC-XXX: {Decision from research}
-**Date:** {today}
-**Status:** Active
-**Context:** Identified during feature research
-**Decision:** {what was decided}
-**Rationale:** {from research findings}
-**Implications:** {what this means for implementation}
-**References:** {sources}
-```
-
-## Phase 7: Commit and Complete
-
-```bash
-git add .specd/features/{name}/RESEARCH.md .specd/features/{name}/DECISIONS.md
-git commit -m "docs({feature}): complete feature research
-
-Dimensions researched:
-- Codebase integration
-- External patterns
-- Pitfalls
-
-Key findings:
-- {one-liner from summary}"
-```
-
-Present completion:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Feature:** {name}
-**Confidence:** {level}
-
-## Key Findings
-
-{3-5 bullet points}
-
-## Files Created
-
-- `.specd/features/{name}/RESEARCH.md`
-- Updated `DECISIONS.md` with {N} new decisions
-
-───────────────────────────────────────────────────────
-
-## Next Steps
-
-/specd:feature:plan {name} — Create roadmap with phase overview
-
-<sub>/clear first — fresh context window</sub>
-```
-
-</process>
-
-<success_criteria>
-- [ ] Feature validated (exists, has FEATURE.md)
-- [ ] Feature context loaded (requirements, decisions)
-- [ ] Codebase research completed (Explore agent)
-- [ ] External patterns researched (with verification)
-- [ ] Pitfalls catalogued (with prevention strategies)
-- [ ] Results synthesized into RESEARCH.md
-- [ ] Decisions recorded in DECISIONS.md
-- [ ] Files committed
-- [ ] User knows next step is `/specd:feature:plan`
-</success_criteria>

package/commands/specd/phase/execute.md

@@ -1,68 +0,0 @@
----
-name: specd:phase:execute
-description: Execute a feature plan with progress tracking
-argument-hint: "[feature-name] [plan-path]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Execute a plan from a feature, tracking progress and logging deviations.
-
-**What it does:**
-1. Load context — STATE.md, DECISIONS.md, RESEARCH.md, codebase patterns
-2. Find next plan — First incomplete plan, or accept path as argument
-3. Execute tasks with:
-   - Auto-fix blockers/bugs -> log to CHANGELOG.md
-   - Ask about architectural changes -> wait for user
-   - Run verification after each task
-   - Stop on verification failure -> ask user (retry/skip/stop)
-   - Commit after each task
-4. Update progress — STATE.md with completed tasks
-5. Suggest next — Next plan to execute
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/execute-plan.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS (first argument)
-Plan path: $ARGUMENTS (optional second argument)
-
-**Load ALL feature context:**
-@.specd/features/{name}/STATE.md — Progress tracking
-@.specd/features/{name}/DECISIONS.md — Constraints to follow
-@.specd/features/{name}/RESEARCH.md — Implementation notes (if exists)
-@.specd/features/{name}/ROADMAP.md — Phase overview
-
-**Load codebase context:**
-@.specd/codebase/PATTERNS.md — Code patterns to follow
-@.specd/codebase/STRUCTURE.md — Where files go
-@.specd/codebase/MAP.md — System overview
-</context>
-
-<process>
-1. **Validate** — Check feature exists with plans
-2. **Load Context** — Read all feature and codebase docs
-3. **Find Plan** — Next incomplete or specified plan
-4. **Execute Tasks** — With verification and deviation handling
-5. **Complete Plan** — Update STATE.md, suggest next
-</process>
-
-<success_criteria>
-- [ ] Feature validated with plans
-- [ ] Context loaded (feature, codebase)
-- [ ] Tasks executed in order
-- [ ] Verification run after each task
-- [ ] Deviations logged to CHANGELOG.md
-- [ ] STATE.md updated with progress
-- [ ] Commits made after each task
-- [ ] Next plan suggested
-</success_criteria>

package/commands/specd/phase/insert.md

@@ -1,62 +0,0 @@
----
-name: specd:phase:insert
-description: Insert a new phase after an existing one (decimal numbering)
-argument-hint: "[feature-name] [after-phase] [description...]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
----
-
-<objective>
-Insert a new phase after an existing one using decimal numbering (e.g., Phase 03.1 after Phase 03).
-
-**What it does:**
-1. Parse arguments — feature name, target phase number, description
-2. Validate — Feature exists, ROADMAP.md exists, target phase exists
-3. Find next decimal — Scan existing decimals, calculate next (03.1, 03.2, etc.)
-4. Create phase directory — `plans/phase-{NN.M}/`
-5. Update ROADMAP.md — Insert new phase section with `(INSERTED)` marker
-6. Update STATE.md — Add roadmap evolution note, add unchecked phase checkbox
-7. Update config.json — Increment `phases_count`
-8. Show next steps
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/insert-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (expects: feature-name after-phase description...)
-
-**Load feature context:**
-@.specd/features/{name}/ROADMAP.md
-@.specd/features/{name}/STATE.md
-@.specd/features/{name}/config.json
-</context>
-
-<process>
-1. **Parse Arguments** — Extract feature-name, after-phase (integer), description
-2. **Validate** — Feature exists, ROADMAP.md exists, target phase exists
-3. **Find Next Decimal** — Scan for existing decimal directories, calculate next
-4. **Create Phase Directory** — `plans/phase-{NN.M}/`
-5. **Update ROADMAP.md** — Insert after target phase with `(INSERTED)` marker
-6. **Update STATE.md** — Add evolution note and unchecked checkbox
-7. **Update config.json** — Increment `phases_count`
-8. **Completion** — Show summary with next steps
-</process>
-
-<success_criteria>
-- [ ] Arguments parsed correctly (feature, phase number, description)
-- [ ] Feature and target phase validated
-- [ ] Decimal number calculated correctly (based on existing decimals)
-- [ ] Phase directory created: `plans/phase-{NN.M}/`
-- [ ] ROADMAP.md updated with new phase entry (includes `(INSERTED)` marker)
-- [ ] Phase inserted in correct position (after target phase, before next phase)
-- [ ] STATE.md updated with roadmap evolution note and unchecked checkbox
-- [ ] config.json `phases_count` incremented
-- [ ] User informed of next steps
-</success_criteria>

package/commands/specd/phase/plan.md

@@ -1,73 +0,0 @@
----
-name: specd:phase:plan
-description: Create detailed PLAN.md files for one phase
-argument-hint: "[feature-name] [phase-number]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Create detailed, executable PLAN.md files for a single phase. Each plan is a prompt for an implementing agent.
-
-**Creates:**
-- `.specd/features/{name}/plans/phase-{NN}/{NN}-PLAN.md` — Executable task plans
-
-**Each PLAN.md is a prompt** for an implementing agent with:
-- Files to create/modify with specific paths
-- Code patterns to follow (from codebase)
-- Verification commands
-- Clear completion criteria
-
-**Prerequisite:** Phase should exist in ROADMAP.md. Phase preparation (`/specd:phase:prepare`) recommended but optional.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/plan-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (expects: feature-name phase-number)
-
-**Load feature context:**
-@.specd/features/{name}/FEATURE.md — Technical requirements
-@.specd/features/{name}/CONTEXT.md — Resolved gray areas
-@.specd/features/{name}/DECISIONS.md — Implementation decisions
-@.specd/features/{name}/RESEARCH.md — Research findings (if exists)
-@.specd/features/{name}/ROADMAP.md — Phase overview
-
-**Load phase context:**
-@.specd/features/{name}/plans/phase-{NN}/CONTEXT.md (if exists, from phase:prepare)
-@.specd/features/{name}/plans/phase-{NN}/RESEARCH.md (if exists, from phase:research)
-
-**Load codebase context:**
-@.specd/codebase/PATTERNS.md — Code patterns to follow
-@.specd/codebase/STRUCTURE.md — Where files go
-@.specd/codebase/MAP.md — System overview
-</context>
-
-<process>
-1. **Validate** — Feature exists, phase exists, phase not already executed
-2. **Load Context** — Read ALL feature, phase, and codebase docs
-3. **Check Existing Plans** — If plans exist, show them and confirm replace
-4. **Break Into Tasks** — 2-3 tasks per plan, sized for agent execution
-5. **Write PLAN Files** — As prompts for implementing agent
-6. **Update ROADMAP** — Mark this phase as planned
-7. **Update STATE.md** — Record planning for this phase
-8. **Commit and Present** — Points to `/specd:phase:execute`
-</process>
-
-<success_criteria>
-- [ ] Feature and phase validated
-- [ ] Phase not already executed
-- [ ] All context loaded (feature, phase, codebase)
-- [ ] Tasks are specific (files, actions, verification)
-- [ ] PLAN.md files are self-contained prompts
-- [ ] ROADMAP.md updated for this phase
-- [ ] Committed to git
-- [ ] User knows next step: `/specd:phase:execute`
-</success_criteria>