specdacular 0.2.0 → 0.2.2

package/commands/specd/discuss-feature.md

@@ -0,0 +1,64 @@
+---
+name: specd:discuss-feature
+description: Continue or deepen feature discussion - can be called multiple times
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Continue or deepen understanding of a feature through targeted discussion. Can be called **many times** — context accumulates.
+
+**Updates:**
+- `.specd/features/{name}/CONTEXT.md` — Accumulates resolved questions
+- `.specd/features/{name}/DECISIONS.md` — Accumulates decisions with dates/rationale
+- `.specd/features/{name}/STATE.md` — Tracks discussion progress
+
+**Idempotent:** Calling multiple times builds on previous discussions, doesn't reset.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/discuss-feature.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS
+
+**Load feature context:**
+@.specd/features/{name}/FEATURE.md
+@.specd/features/{name}/CONTEXT.md
+@.specd/features/{name}/DECISIONS.md
+@.specd/features/{name}/STATE.md
+
+**Load codebase context (if available):**
+@.specd/codebase/PATTERNS.md
+@.specd/codebase/STRUCTURE.md
+@.specd/codebase/MAP.md
+</context>
+
+<process>
+1. **Validate** — Check feature exists, has required files
+2. **Load Context** — Read FEATURE.md, CONTEXT.md, DECISIONS.md
+3. **Show Current State** — "Here's what we've discussed so far..."
+4. **Identify Gray Areas** — Based on feature type and existing context
+5. **Let User Select** — Which areas to discuss this session
+6. **Probe Each Area** — Until clear (4 questions, then check)
+7. **Record Decisions** — NEW decisions to DECISIONS.md with date + rationale
+8. **Update CONTEXT.md** — With newly resolved questions
+9. **Present Summary** — Offer next steps
+</process>
+
+<success_criteria>
+- [ ] Feature validated (exists, has required files)
+- [ ] Existing context loaded and summarized
+- [ ] Gray areas identified and presented
+- [ ] User-selected areas discussed
+- [ ] Decisions recorded with date, context, rationale
+- [ ] CONTEXT.md updated with resolved questions
+- [ ] User knows options: discuss more, research, or plan
+</success_criteria>

package/commands/specd/help.md

@@ -12,24 +12,77 @@ Display available specdacular commands and usage guidance.
 <output>
 # Specdacular
 
-**AI-optimized codebase documentation for Claude.**
+**AI-optimized codebase documentation and feature planning for Claude.**
 
 ## Commands
 
+### Codebase Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/specd:map-codebase` | Analyze codebase with parallel agents → produce AI-optimized docs |
+
+### Feature Flow
+
+| Command | Description |
+|---------|-------------|
+| `/specd:new-feature [name]` | Initialize a feature, start first discussion |
+| `/specd:discuss-feature [name]` | Continue/deepen feature discussion (can call many times) |
+| `/specd:research-feature [name]` | Research implementation with parallel agents |
+| `/specd:plan-feature [name]` | Create executable task plans for agents |
+
+### Utilities
+
 | Command | Description |
 |---------|-------------|
-| `/specd:map-codebase` | Analyze codebase → produce 4 AI-optimized docs |
-| `/specd:new-feature` | Initialize a feature with requirements and roadmap |
 | `/specd:update` | Update Specdacular to the latest version |
 | `/specd:help` | Show this help |
 
-## Quick Start
+---
+
+## Feature Flow
+
+The feature flow helps you plan features specific enough that an agent can implement without asking questions.
+
+```
+new-feature → (discuss ↔ research)* → plan-feature
+```
+
+**You control the rhythm:**
+- `new-feature` — Creates structure, asks initial questions, starts first discussion
+- `discuss-feature` — Can be called **many times** to refine understanding
+- `research-feature` — Can be called **many times** to investigate
+- `plan-feature` — When satisfied, creates executable plans for an agent
+
+### Quick Start
+
+```
+/specd:new-feature user-dashboard
+```
+
+This creates `.specd/features/user-dashboard/` with:
+- `FEATURE.md` — Technical requirements
+- `CONTEXT.md` — Discussion context (accumulates)
+- `DECISIONS.md` — Decisions with dates and rationale
+- `STATE.md` — Progress tracking
+
+After initialization, refine with discussion and research, then create plans:
+
+```
+/specd:discuss-feature user-dashboard    # Clarify gray areas
+/specd:research-feature user-dashboard   # Research implementation
+/specd:plan-feature user-dashboard       # Create executable plans
+```
+
+---
+
+## Codebase Documentation
 
 ```
 /specd:map-codebase
 ```
 
-This spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
+Spawns 4 parallel agents to analyze your codebase and creates `.specd/codebase/`:
 
 | Document | What it contains |
 |----------|------------------|
@@ -38,7 +91,7 @@ This spawns 4 parallel agents to analyze your codebase and creates `.specd/codeb
 | **STRUCTURE.md** | Organization: where to put new code |
 | **CONCERNS.md** | Warnings: gotchas, anti-patterns, debt |
 
-## Philosophy
+### Philosophy
 
 These docs are **for Claude, not humans**.
 
@@ -50,6 +103,8 @@ Each document answers a question Claude can't get from reading code:
 
 **Principle:** Don't document what Claude can grep. Document tribal knowledge, gotchas, and patterns.
 
+---
+
 ## Updating
 
 When an update is available, you'll see `⬆ /specd:update` in your statusline. Run:

package/commands/specd/new-feature.md

@@ -1,6 +1,6 @@
 ---
 name: specd:new-feature
-description: Initialize a new feature with deep questioning, requirements, and roadmap
+description: Initialize a new feature with technical questioning and start the first discussion
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -12,14 +12,16 @@ allowed-tools:
 ---
 
 <objective>
-Initialize a feature folder with structured planning documents through a conversational workflow.
+Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements.
 
-Creates `.specd/features/{feature-name}/` with:
-- FEATURE.md - What this feature does, core value, constraints
-- REQUIREMENTS.md - Scoped requirements with REQ-IDs (v1/v2/out-of-scope)
-- ROADMAP.md - Phases with success criteria and requirement mapping
-- STATE.md - Project memory, current position, decisions
-- config.json - Mode (yolo/interactive), depth (quick/standard/comprehensive)
+**Creates:**
+- `.specd/features/{name}/FEATURE.md` — Technical requirements from discussion
+- `.specd/features/{name}/CONTEXT.md` — Discussion context (accumulates over time)
+- `.specd/features/{name}/DECISIONS.md` — Memory file for decisions with rationale
+- `.specd/features/{name}/STATE.md` — Progress tracking
+- `.specd/features/{name}/config.json` — Feature configuration
+
+**This is the entry point.** After this, user controls the loop with discuss/research/plan.
 </objective>
 
 <execution_context>
@@ -30,46 +32,36 @@ Creates `.specd/features/{feature-name}/` with:
 Feature name: $ARGUMENTS
 
 **Codebase context discovery:**
-1. Check for `.specd/config.json` - if exists, read `codebase_docs` path
+1. Check for `.specd/config.json` — if exists, read `codebase_docs` path
 2. If no config, check for `.specd/codebase/` (default location)
-3. If neither found, ask user for custom location or suggest `/specd:map-codebase`
+3. If neither found, offer `/specd:map-codebase`
 
 **Referenced docs (when available):**
-- `ARCHITECTURE.md` - Understand existing patterns for integration
-- `CONVENTIONS.md` - Ensure requirements follow coding standards
-- `STRUCTURE.md` - Know where new code should go
+- `ARCHITECTURE.md` or `MAP.md` — System structure
+- `CONVENTIONS.md` or `PATTERNS.md` — Code patterns
+- `STRUCTURE.md` — Directory layout
 </context>
 
-<when_to_use>
-**Use new-feature for:**
-- Starting a new feature or enhancement
-- When you need structured planning documents
-- Before implementing non-trivial functionality
-- When multiple people will work on a feature
-
-**Skip new-feature for:**
-- Bug fixes (just fix them)
-- Trivial changes (<1 hour of work)
-- Exploratory spikes
-</when_to_use>
-
 <process>
-1. Setup - Get feature name, check if exists
-2. Codebase Context - Look for codebase docs
-3. Complexity Assessment - Ask light/moderate/complicated
-4. Deep Questioning - Adaptive depth based on complexity
-5. Write FEATURE.md - Capture context from conversation
-6. Configuration - Ask mode/depth preferences
-7. Define Requirements - Scope v1/v2/out-of-scope
-8. Create Roadmap - Derive phases, map requirements
-9. Initialize State - Create STATE.md
-10. Completion - Summary and next steps
+1. **Validate** — Check name, check if exists
+2. **Codebase Context** — Look for codebase docs (offer map-codebase if missing)
+3. **First Discussion** — "What are you building?"
+4. **Follow the Thread** — Collaborative, not interrogative
+5. **Probe Until Clear** — What creates, what integrates with, constraints
+6. **Write FEATURE.md** — Technical requirements
+7. **Write CONTEXT.md** — Initial discussion state
+8. **Initialize DECISIONS.md** — With any decisions made so far
+9. **Initialize STATE.md** — Feature created, ready for more discussion
+10. **Commit and Present Options**
 </process>
 
 <success_criteria>
 - [ ] Feature folder created at `.specd/features/{name}/`
-- [ ] All 5 files created (FEATURE.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json)
-- [ ] Requirements have REQ-IDs in format `{FEAT}-{CAT}-{NUM}`
-- [ ] Roadmap phases map to requirements
-- [ ] Commits made at key milestones
+- [ ] FEATURE.md captures technical requirements
+- [ ] CONTEXT.md initialized with discussion context
+- [ ] DECISIONS.md initialized (possibly with initial decisions)
+- [ ] STATE.md tracks current position
+- [ ] config.json created
+- [ ] Committed to git
+- [ ] User knows next options: discuss-feature, research-feature, or continue talking
 </success_criteria>

package/commands/specd/plan-feature.md

@@ -0,0 +1,69 @@
+---
+name: specd:plan-feature
+description: Create executable task plans for implementing a feature
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Create executable task plans that an agent can implement without asking clarifying questions.
+
+**Creates:**
+- `.specd/features/{name}/ROADMAP.md` — Phase overview with dependencies
+- `.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:** Feature should have sufficient discussion context (FEATURE.md, CONTEXT.md, DECISIONS.md). Research (RESEARCH.md) recommended but optional.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/plan-feature.md
+</execution_context>
+
+<context>
+Feature name: $ARGUMENTS
+
+**Load ALL 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)
+
+**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, has required context
+2. **Load Context** — Read ALL feature and codebase docs
+3. **Assess Readiness** — Check if enough context to plan
+4. **Derive Phases** — Based on dependencies (types→API→UI pattern)
+5. **Break Into Tasks** — 2-3 tasks per plan, sized for agent execution
+6. **Write PLAN Files** — As prompts for implementing agent
+7. **Write ROADMAP.md** — Phase overview
+8. **Commit and Present**
+</process>
+
+<success_criteria>
+- [ ] Feature validated with sufficient context
+- [ ] All context loaded (feature, codebase, research)
+- [ ] Phases derived from dependency analysis
+- [ ] Tasks are specific (files, actions, verification)
+- [ ] PLAN.md files are self-contained prompts
+- [ ] ROADMAP.md provides clear overview
+- [ ] Committed to git
+- [ ] User knows how to execute plans
+</success_criteria>