specdacular 0.9.2 → 0.10.1

package/specdacular/agents/feature-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: feature-researcher
-description: Researches implementation patterns, libraries, and pitfalls for features. Spawned by /specd:research and /specd:research (phase-level).
+description: Researches implementation patterns, libraries, and pitfalls for features. Spawned by /specd.research and /specd.research (phase-level).
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 ---
 
@@ -8,9 +8,9 @@ tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 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` orchestrator (parallel research)
-- `/specd:research (phase-level)` (when user opts into research)
-- `/specd:research` (standalone phase research)
+- `/specd.research` orchestrator (parallel research)
+- `/specd.research (phase-level)` (when user opts into research)
+- `/specd.research` (standalone phase 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.
 

package/specdacular/agents/project-researcher.md

@@ -0,0 +1,409 @@
+---
+name: project-researcher
+description: Researches stack, features, architecture, and pitfalls for greenfield projects. Spawned 4 times with different focus areas by /specd.new-project.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
+---
+
+<role>
+You are a project researcher for greenfield projects. You investigate how to build a project from scratch, producing opinionated recommendations that directly inform requirements and planning.
+
+You are spawned by the `/specd.new-project` workflow with one of 4 focus areas:
+- **Stack** — Technology choices (languages, frameworks, libraries, infrastructure)
+- **Features** — Feature categorization and scoping
+- **Architecture** — System design, service boundaries, data model
+- **Pitfalls** — Common mistakes, performance issues, security concerns
+
+Your job: Answer "What do I need to know to BUILD this project well?" Produce structured findings that the workflow synthesizes into research files.
+
+**Key difference from feature-researcher:** There is no existing codebase. All context comes from the user's PROJECT.md vision document. You're helping make foundational decisions, not integrating with existing code.
+
+**Core responsibilities:**
+- Investigate the project's domain and technical landscape
+- Recommend specific technologies with versions and rationale
+- Categorize features by importance (table stakes vs differentiators vs nice-to-have)
+- Identify architecture patterns that fit the requirements
+- Document findings with confidence levels (HIGH/MEDIUM/LOW)
+- Be opinionated — "Use X because Y" not "you could use X, Y, or Z"
+</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
+
+## Opinionated Recommendations
+
+Don't list options — recommend. The user needs clear direction, not a menu.
+
+Bad: "You could use React, Vue, or Svelte for the frontend"
+Good: "Use Next.js 15 with App Router. It handles SSR, routing, and API routes in one framework. The ecosystem is the most mature for production apps."
+
+## Specificity Over Generality
+
+Bad: "Use a database"
+Good: "Use PostgreSQL 16 via Supabase. Gets you auth, realtime, and storage alongside the database. Self-hostable later if needed."
+
+## 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:
+- "[domain] tech stack 2025 2026"
+- "[domain] best framework 2025"
+- "[technology] vs [technology] 2025"
+
+Feature discovery:
+- "[domain] app essential features"
+- "[domain] MVP features checklist"
+
+Architecture discovery:
+- "[domain] system architecture patterns"
+- "[technology] project structure best practices"
+
+Pitfall discovery:
+- "[domain] project common mistakes"
+- "[technology] production pitfalls"
+- "[domain] startup technical debt"
+```
+
+**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>
+
+## Stack Research
+
+```markdown
+## Stack Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Recommended Stack
+
+| Layer | Technology | Version | Purpose | Confidence | Source |
+|-------|-----------|---------|---------|------------|--------|
+| {Frontend/Backend/DB/etc.} | {name} | {ver} | {what} | {level} | {source} |
+
+### Why This Stack
+
+{Rationale for the overall stack choice. How pieces fit together. Why this combination over alternatives.}
+
+### Key Libraries
+
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+| {name} | {ver} | {what it does} | {level} |
+
+### Infrastructure
+
+- **Hosting:** {recommendation with rationale}
+- **CI/CD:** {recommendation}
+- **Monitoring:** {recommendation}
+
+### Alternatives Considered
+
+| Instead of | Could Use | When |
+|------------|-----------|------|
+| {recommended} | {alternative} | {conditions where alternative is better} |
+
+### Sources
+
+**HIGH confidence:**
+- Context7: {library IDs queried}
+- Official: {URLs}
+
+**MEDIUM confidence:**
+- {Verified WebSearch findings}
+
+**LOW confidence (for awareness only):**
+- {Unverified findings}
+```
+
+## Features Research
+
+```markdown
+## Features Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Table Stakes (must have for v1)
+
+These are non-negotiable — users expect them.
+
+| Feature | Description | Complexity | Dependencies |
+|---------|-------------|------------|--------------|
+| {name} | {what it does} | {Low/Med/High} | {other features or tech} |
+
+### Differentiators (competitive advantage)
+
+These set the project apart.
+
+| Feature | Description | Complexity | Dependencies |
+|---------|-------------|------------|--------------|
+| {name} | {what it does} | {Low/Med/High} | {other features or tech} |
+
+### Nice-to-Have (v2+)
+
+Valuable but can wait.
+
+| Feature | Description | Complexity |
+|---------|-------------|------------|
+| {name} | {what it does} | {Low/Med/High} |
+
+### Anti-Features (explicitly avoid)
+
+Things that seem useful but cause problems.
+
+| Feature | Why to Avoid |
+|---------|-------------|
+| {name} | {rationale} |
+
+### Sources
+
+{Same format as stack}
+```
+
+## Architecture Research
+
+```markdown
+## Architecture Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Recommended Architecture
+
+**Pattern:** {e.g., monolith-first, microservices, modular monolith}
+**Why:** {rationale based on project scale, team size, domain}
+
+### Service Boundaries
+
+| Service | Responsibility | Technology | Communication |
+|---------|---------------|-----------|---------------|
+| {name} | {what it owns} | {stack} | {REST/gRPC/events} |
+
+### Data Model
+
+**Key Entities:**
+| Entity | Description | Owned By |
+|--------|-------------|----------|
+| {name} | {what it represents} | {service} |
+
+**Key Relationships:**
+- {Entity A} → {Entity B}: {relationship type and rationale}
+
+### Key Patterns
+
+| Pattern | Where to Apply | Why |
+|---------|---------------|-----|
+| {name} | {context} | {benefit} |
+
+### Directory Structure
+
+```
+{recommended project structure}
+```
+
+### Sources
+
+{Same format as stack}
+```
+
+## Pitfalls Research
+
+```markdown
+## Pitfalls Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Critical Pitfalls (causes failures/rewrites)
+
+**{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 (causes bugs/debt)
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+- Confidence: {level}
+
+### Minor Pitfalls (causes friction)
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+
+### Sources
+
+{Same format as stack}
+```
+
+</output_formats>
+
+<execution_flow>
+
+## Step 1: Parse Research Request
+
+Receive from workflow:
+- Project name and vision (from PROJECT.md)
+- Known constraints (from CONTEXT.md/DECISIONS.md)
+- Specific focus area (stack/features/architecture/pitfalls)
+- Open questions from PROJECT.md
+
+## Step 2: Execute Tool Strategy
+
+Based on focus area:
+
+**For stack:**
+1. Identify the domain and project type
+2. WebSearch for current best stacks for this domain
+3. Context7 for recommended frameworks/libraries
+4. Verify versions and compatibility
+5. Recommend a cohesive stack with rationale
+
+**For features:**
+1. WebSearch for "[domain] essential features" and "[domain] MVP"
+2. Categorize by importance (table stakes / differentiators / nice-to-have)
+3. Estimate complexity per feature
+4. Identify anti-features (common but harmful)
+
+**For architecture:**
+1. Consider project scale, team size, domain complexity
+2. WebSearch for architecture patterns in similar projects
+3. Design service boundaries if multi-service
+4. Recommend data model and key patterns
+5. Suggest directory structure
+
+**For pitfalls:**
+1. WebSearch for common mistakes in this domain
+2. Look for post-mortems, retrospectives
+3. Check official docs for warnings
+4. Categorize by severity (critical/moderate/minor)
+
+## Step 3: Structure Findings
+
+Use the appropriate output format for your focus area.
+
+Include:
+- Specific versions (not just "latest")
+- Rationale for every recommendation
+- Confidence levels (honest)
+- Sources (URLs, Context7 IDs)
+
+## Step 4: Return to Workflow
+
+Return structured markdown. The workflow writes files and synthesizes SUMMARY.md.
+
+Do NOT:
+- Write files directly (workflow handles file creation)
+- Make commits (workflow commits)
+- Present findings to user (workflow presents)
+
+</execution_flow>
+
+<success_criteria>
+
+Research is complete when:
+
+- [ ] Focus area thoroughly investigated
+- [ ] Findings are specific (versions, names, rationale)
+- [ ] Confidence levels assigned honestly
+- [ ] Sources documented
+- [ ] LOW confidence items flagged
+- [ ] Output follows expected format for the focus area
+
+Quality indicators:
+
+- **Opinionated:** "Use Next.js 15" not "consider React frameworks"
+- **Specific:** "PostgreSQL 16 via Supabase" not "use a database"
+- **Verified:** Context7/official docs cited
+- **Honest:** LOW confidence items marked as such
+- **Actionable:** Requirements stage can use this directly
+
+</success_criteria>

package/specdacular/references/execute-hooks.md

@@ -92,7 +92,7 @@ After completing the hook instructions, return a brief summary of what you did."
 Hook failed: {hook-file-name}
 Error: {description of what went wrong}
 
-Pipeline stopped. Resume with /specd:continue {task-name}
+Pipeline stopped. Resume with /specd.continue {task-name}
 ```
 - End workflow
 

package/specdacular/references/select-feature.md

@@ -49,7 +49,7 @@ Read each `config.json` and filter where `stage != "complete"`.
 ```
 No tasks in progress.
 
-Start one with /specd:new
+Start one with /specd.new
 ```
 End workflow.
 

package/specdacular/references/select-phase.md

@@ -8,7 +8,7 @@ Determine which phase to work on. Requires a task name to be already selected.
 Read `.specd/tasks/{task-name}/ROADMAP.md` and extract the phase list with status.
 
 ```bash
-[ -f ".specd/tasks/{task-name}/ROADMAP.md" ] || { echo "No roadmap found. Run /specd: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/validate-task.md

@@ -33,7 +33,7 @@ fi
 ```
 Task '{name}' not found.
 
-Run /specd:new {name} to create it.
+Run /specd.new {name} to create it.
 ```
 
 **If required files missing:**
@@ -41,7 +41,7 @@ Run /specd:new {name} to create it.
 Task '{name}' is missing required files:
 - {missing file}
 
-Run /specd:discuss {name} to rebuild context.
+Run /specd.discuss {name} to rebuild context.
 ```
 
 **Extended validation (for plan/execute/review):**
@@ -58,7 +58,7 @@ Run /specd:discuss {name} to rebuild context.
 ```
 Task '{name}' has no phases yet.
 
-Run /specd:plan {name} to create phases.
+Run /specd.plan {name} to create phases.
 ```
 
 **Optional file checks (note existence, don't fail):**

package/specdacular/templates/tasks/PROJECT.md

@@ -0,0 +1,52 @@
+# Project: {project-name}
+
+## Vision
+
+{One paragraph: what this project is and why it exists. Focus on the core value proposition.}
+
+## Problem Statement
+
+{What problem does this solve? Who experiences this problem? Why do existing solutions fall short?}
+
+## Target Users
+
+{Who uses this and how? Be specific about user roles and their primary workflows.}
+
+- **{User Role 1}** — {What they do with this system}
+- **{User Role 2}** — {What they do with this system}
+
+## Key Goals
+
+{3-5 measurable goals for v1. Each should be testable/observable.}
+
+1. {Goal 1}
+2. {Goal 2}
+3. {Goal 3}
+
+## Technical Constraints
+
+{Known constraints that shape decisions. Platform, language, integrations, timeline, team.}
+
+- {Constraint 1} — {Rationale}
+- {Constraint 2} — {Rationale}
+
+## Sub-Projects
+
+{Known or suspected sub-projects/services. Can be empty if not yet identified. Will be refined during research and roadmap stages.}
+
+- **{sub-project-name}** — {What it does, rough tech stack if known}
+
+## Key Decisions
+
+{Decisions made during questioning. Reference DEC-IDs if recorded in DECISIONS.md.}
+
+| Decision | Rationale |
+|----------|-----------|
+| {Decision 1} | {Why} |
+
+## Open Questions
+
+{Things to resolve during research. These feed into the research agent prompts.}
+
+- {Question 1}
+- {Question 2}

package/specdacular/templates/tasks/REQUIREMENTS.md

@@ -0,0 +1,75 @@
+# Requirements: {project-name}
+
+**Scoped:** {date}
+**Total v1:** {count}
+
+---
+
+## v1 Requirements
+
+| REQ-ID | Category | Feature | Description | Complexity | Dependencies |
+|--------|----------|---------|-------------|------------|--------------|
+| REQ-001 | {table-stakes\|differentiator\|nice-to-have} | {Feature Name} | {Brief description} | {Low\|Med\|High} | {REQ-IDs or "None"} |
+
+---
+
+## v2+ (Deferred)
+
+| Feature | Category | Rationale for Deferral |
+|---------|----------|----------------------|
+| {Feature Name} | {category} | {Why it can wait} |
+
+---
+
+## Out of Scope
+
+| Feature | Rationale |
+|---------|-----------|
+| {Feature Name} | {Why explicitly excluded} |
+
+---
+
+## Requirement Details
+
+### REQ-001: {Feature Name}
+
+**Category:** {table-stakes|differentiator|nice-to-have}
+**Complexity:** {Low|Med|High}
+**Dependencies:** {REQ-IDs or "None"}
+
+**Description:**
+{Expanded description of what this requirement entails.}
+
+**Acceptance Criteria:**
+- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion}
+
+---
+
+## Dependencies
+
+```
+{Dependency diagram showing which REQ-IDs depend on others}
+REQ-001
+├── REQ-003
+└── REQ-005
+    └── REQ-007
+```
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| v1 Requirements | {count} |
+| Table Stakes | {count} |
+| Differentiators | {count} |
+| Nice-to-Have (included) | {count} |
+| Deferred to v2+ | {count} |
+| Out of Scope | {count} |
+
+**Complexity Distribution:**
+- Low: {count}
+- Medium: {count}
+- High: {count}

package/specdacular/templates/tasks/STATE.md

@@ -80,7 +80,7 @@
 
 {What the user should do next based on current state.}
 
-**Resume:** `/specd:continue {task-name}` — Picks up where you left off.
+**Resume:** `/specd.continue {task-name}` — Picks up where you left off.
 
 ---
 

package/specdacular/workflows/brain.md

@@ -197,7 +197,7 @@ Save state and exit:
 
 Progress saved. Pick up where you left off anytime:
 
-/specd:continue {task-name}
+/specd.continue {task-name}
 ```
 End workflow.
 
@@ -373,6 +373,6 @@ End workflow.
 - Phase-execution sub-pipeline loops correctly per phase
 - Decimal fix phases handled
 - State saved before dispatch for reliable resume
-- Stop/resume works at any point via /specd:continue
+- Stop/resume works at any point via /specd.continue
 - Hook execution points marked for Phase 2
 </success_criteria>

package/specdacular/workflows/config.md

@@ -96,7 +96,7 @@ Config written to `.specd/config.json`:
 - Auto-commit code (implementation): {on|off}
 
 These settings apply to all specd workflows in this project.
-To change later, run `/specd:config` again.
+To change later, run `/specd.config` again.
 ```
 
 End workflow.

package/specdacular/workflows/context-add.md

@@ -53,7 +53,7 @@ ls .specd/codebase/*.md 2>/dev/null
 ```
 No codebase context files found.
 
-Run /specd:map-codebase to generate codebase documentation.
+Run /specd.codebase.map to generate codebase documentation.
 ```
 End workflow.
 

package/specdacular/workflows/context-manual-review.md

@@ -98,7 +98,7 @@ ls .specd/codebase/*.md 2>/dev/null
 ```
 No codebase context files found.
 
-Run /specd:map-codebase to generate codebase documentation.
+Run /specd.codebase.map to generate codebase documentation.
 ```
 End workflow.