specflow-cc 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-01-22
+
+### Added
+
+- `/sf:discuss` — Interactive Q&A to clarify requirements and resolve ambiguities
+- `discusser` agent — Conducts focused discussions with clear options
+- `.specflow/discussions/` directory for discussion records
+- Discuss hints after `/sf:new` and `/sf:audit` (NEEDS_REVISION)
+
+### Changed
+
+- Help section "Research & Analysis" renamed to "Research & Clarification"
+
+---
+
+## [1.4.0] - 2026-01-21
+
+### Added
+
+- `/sf:research` — Research topics before creating specifications
+- `researcher` agent — Explores codebase and web for findings
+- `research.md` template — Structured research document format
+- `--research RES-XXX` flag for `/sf:new` — Include research as spec context
+- `.specflow/research/` directory created on init
+
+### Changed
+
+- `/sf:help` now includes Research & Analysis section
+- Quick start guide updated with optional research step
+
+---
+
 ## [1.3.1] - 2026-01-21
 
 ### Fixed

package/README.md

@@ -1,252 +1,131 @@
 # SpecFlow
 
-**Spec-driven development system for Claude Code**
+**Spec-driven development for Claude Code**
 
-SpecFlow is a lean, audit-driven development workflow that integrates with Claude Code. It combines the best practices of specification-first development with explicit quality audits.
-
-## Philosophy
-
-| Principle | Description |
-|-----------|-------------|
-| **Spec-first** | Write specifications before code |
-| **Explicit audit** | Dedicated audit phase, not just verification |
-| **Fresh context** | Auditors don't see the creation process (no bias) |
-| **Lean process** | Minimal commands, maximum value |
-| **Human gate** | You control when to proceed (soft blocking) |
-| **Token awareness** | Specs sized for single sessions (~150k tokens) |
+Write specs first, audit them, then implement. Quality through explicit review cycles.
 
 ## Installation
 
 ```bash
-# Interactive mode (prompts for location)
-npx specflow-cc
-
-# Install globally (recommended)
 npx specflow-cc --global
-
-# Install to current project only
-npx specflow-cc --local
 ```
 
-### Options
-
-| Flag | Description |
-|------|-------------|
-| `-g, --global` | Install to `~/.claude` (available in all projects) |
-| `-l, --local` | Install to `./.claude` (current project only) |
-| `--force-statusline` | Replace existing statusline configuration |
-| `-h, --help` | Show help |
-
 ## Quick Start
 
 ```bash
-# 1. Initialize project (once per project)
-/sf:init
-
-# 2. Create a specification
-/sf:new "Add user authentication with JWT"
-
-# 3. Audit the specification (fresh context)
-/sf:audit
-
-# 4. Revise if needed
-/sf:revise
-
-# 5. Execute when approved
-/sf:run
-
-# 6. Review implementation (fresh context)
-/sf:review
-
-# 7. Fix if needed
-/sf:fix
-
-# 8. Complete and archive
-/sf:done
+/sf:init                    # Initialize project (once)
+/sf:new "add user auth"     # Create specification
+/sf:audit                   # Audit spec (fresh context)
+/sf:run                     # Implement
+/sf:review                  # Review implementation
+/sf:done                    # Complete and archive
 ```
 
-## Commands
-
-### Core Workflow
+## Workflow
 
-| Command | Description |
-|---------|-------------|
-| `/sf:init` | Initialize project, analyze codebase |
-| `/sf:new [description]` | Create new specification |
-| `/sf:audit` | Audit specification (fresh context) |
-| `/sf:revise [instructions]` | Revise spec based on audit |
-| `/sf:run` | Execute specification |
-| `/sf:review` | Review implementation (fresh context) |
-| `/sf:fix [instructions]` | Fix based on review |
-| `/sf:done` | Complete, commit, and archive |
-| `/sf:status` | Show current state and next step |
+```
+/sf:new  →  /sf:audit  →  /sf:run  →  /sf:review  →  /sf:done
+              ↓                          ↓
+         /sf:revise                  /sf:fix
+         (if needed)                 (if needed)
+```
 
-### Navigation
+**Key principle:** Audits and reviews run in fresh context — no bias from creation.
 
-| Command | Description |
-|---------|-------------|
-| `/sf:list` | List all specifications |
-| `/sf:show [ID]` | Show specification details |
-| `/sf:next` | Switch to next priority task |
+## Commands
 
-### To-Do Management
+### Core Flow
 
 | Command | Description |
 |---------|-------------|
-| `/sf:todo [text]` | Add idea or future task |
-| `/sf:todos` | List all todos with priorities |
-| `/sf:plan [ID]` | Convert todo into specification |
-| `/sf:priority` | Interactive prioritization |
+| `/sf:init` | Initialize project |
+| `/sf:new` | Create specification |
+| `/sf:audit` | Audit spec (fresh context) |
+| `/sf:revise` | Revise based on audit |
+| `/sf:run` | Implement spec |
+| `/sf:review` | Review implementation |
+| `/sf:fix` | Fix based on review |
+| `/sf:done` | Complete and archive |
 
-### Decomposition
+### Before You Spec
 
 | Command | Description |
 |---------|-------------|
-| `/sf:split [ID]` | Split large spec into smaller parts |
-| `/sf:deps` | Show dependency graph |
+| `/sf:research` | Research topic, save findings |
+| `/sf:discuss` | Clarify requirements via Q&A |
+| `/sf:scan` | Analyze codebase for issues |
 
-### Session Management
+### Navigation
 
 | Command | Description |
 |---------|-------------|
-| `/sf:pause` | Save context for later |
-| `/sf:resume` | Restore saved context |
+| `/sf:status` | Current state and next step |
+| `/sf:list` | All specifications |
+| `/sf:next` | Switch to priority task |
+| `/sf:show` | View spec details |
 
-### Analysis
+### Backlog
 
 | Command | Description |
 |---------|-------------|
-| `/sf:scan [--focus]` | Deep codebase analysis for concerns and tech debt |
+| `/sf:todo` | Add future idea |
+| `/sf:todos` | List all todos |
+| `/sf:plan` | Convert todo to spec |
+| `/sf:priority` | Reprioritize |
 
 ### Utilities
 
 | Command | Description |
 |---------|-------------|
-| `/sf:help [command]` | Show help for commands |
-| `/sf:history [ID]` | View completed specifications |
-| `/sf:metrics` | Project statistics |
-
-## Workflow Diagram
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    SPECFLOW WORKFLOW                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  /sf:init    ──→  Initialize project (once)                  │
-│       ↓                                                      │
-│  /sf:new     ──→  Create specification                       │
-│       ↓                                                      │
-│  ┌─────────────────────────────────────┐                     │
-│  │  SPEC AUDIT LOOP                    │                     │
-│  │  /sf:audit ──→ APPROVED? ──yes──→ ──┼──→                  │
-│  │       │                             │    ↓                │
-│  │       no                            │                     │
-│  │       ↓                             │                     │
-│  │  /sf:revise ────────→ loop back     │                     │
-│  └─────────────────────────────────────┘                     │
-│       ↓                                                      │
-│  /sf:run     ──→  Execute specification                      │
-│       ↓                                                      │
-│  ┌─────────────────────────────────────┐                     │
-│  │  IMPL REVIEW LOOP                   │                     │
-│  │  /sf:review ──→ APPROVED? ──yes──→ ─┼──→                  │
-│  │       │                             │    ↓                │
-│  │       no                            │                     │
-│  │       ↓                             │                     │
-│  │  /sf:fix ───────────→ loop back     │                     │
-│  └─────────────────────────────────────┘                     │
-│       ↓                                                      │
-│  /sf:done    ──→  Complete and archive                       │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
+| `/sf:split` | Break large spec into parts |
+| `/sf:deps` | Show dependencies |
+| `/sf:pause` | Save session context |
+| `/sf:resume` | Restore session |
+| `/sf:help` | Command reference |
 
 ## Project Structure
 
-After `/sf:init`, SpecFlow creates:
-
 ```
 .specflow/
-├── PROJECT.md       # Project overview and patterns
-├── STATE.md         # Current state and queue
-├── SCAN.md          # Codebase scan results (from /sf:scan)
-├── config.json      # Configuration
-├── specs/           # Active specifications
-│   └── SPEC-001.md
-├── audits/          # Detailed audit reports (when >3 issues)
-├── todos/           # Future ideas
-│   └── TODO.md
-└── archive/         # Completed specifications
+├── PROJECT.md      # Project context
+├── STATE.md        # Current state
+├── specs/          # Active specs
+├── research/       # Research documents
+├── discussions/    # Clarification records
+├── audits/         # Audit reports
+└── archive/        # Completed specs
 ```
 
-## Specification Format
-
-```markdown
----
-id: SPEC-001
-type: feature | refactor | bugfix
-status: draft | audited | running | review | done
-priority: high | medium | low
-complexity: small | medium | large
-created: 2026-01-20
----
-
-# Task Title
+## Typical Session
 
-## Context
-[Why this is needed]
+```bash
+# Check where you are
+/sf:status
 
-## Task
-[What needs to be done]
+# Research if needed
+/sf:research "auth options"
 
-## Requirements
-### Interfaces
-### Files to Create/Modify
-### Files to Delete
+# Create spec with research context
+/sf:new --research RES-001 "add OAuth"
 
-## Acceptance Criteria
-- [ ] Criterion 1
-- [ ] Criterion 2
+# Clarify assumptions if needed
+/sf:discuss SPEC-001
 
-## Constraints
-- [What NOT to do]
+# Audit (use /clear first for fresh context)
+/sf:audit
 
-## Assumptions
-- [Made by agent, verify if incorrect]
+# Implement and review
+/sf:run
+/sf:review
+/sf:done
 ```
 
-## Complexity Estimation
-
-| Size | Tokens | Action |
-|------|--------|--------|
-| Small | ≤50k | Execute directly |
-| Medium | 50-150k | Warning, proceed |
-| Large | >150k | Requires `/sf:split` |
-
-## Statusline
-
-SpecFlow includes a statusline hook showing:
-- Current model
-- Active specification status `[SF: SPEC-001 running]`
-- Context window usage (color-coded)
-
-## Comparison with GSD
-
-| Aspect | GSD | SpecFlow |
-|--------|-----|----------|
-| Commands | 25 | 23 |
-| Agents | 11 | 7 |
-| Phases per task | 5+ | 3-4 |
-| Quality audit | No | Yes (explicit) |
-| Revision loop | No | Yes |
-| Code deletion | Not verified | Explicit checklist |
-| Blocking | Hard | Soft (warning) |
-
-## Documentation
+## Philosophy
 
-- [Design Document](docs/DESIGN.md) — Full architecture and decisions
-- [Changelog](CHANGELOG.md) — Version history
+- **Spec-first** — Write specs before code
+- **Fresh audits** — Auditors don't see creation (no bias)
+- **Soft blocking** — Warnings, not hard stops
+- **Token-aware** — Specs sized for single sessions
 
 ## License
 

package/agents/discusser.md

@@ -0,0 +1,190 @@
+---
+name: sf-discusser
+description: Conducts interactive discussions to clarify requirements and resolve ambiguities
+tools: Read, Write, Glob, Grep, AskUserQuestion
+---
+
+<role>
+You are a SpecFlow discusser. Your job is to conduct focused, interactive discussions that clarify requirements and resolve ambiguities before or during specification work.
+
+Your approach:
+1. Identify key decision points and ambiguities
+2. Ask focused questions with clear options
+3. Document decisions for spec creation/revision
+4. Keep discussions efficient (3-7 questions max)
+</role>
+
+<philosophy>
+
+## Question Quality
+
+Good questions:
+- Have clear, mutually exclusive options
+- Focus on decisions that affect implementation
+- Are specific and actionable
+- Include reasoning for why it matters
+
+Bad questions:
+- Vague or open-ended without options
+- About implementation details (that's for the spec)
+- Already answerable from project context
+- Too many at once (>4 options)
+
+## Discussion Efficiency
+
+- Start with the most important decision
+- Group related questions when possible
+- Stop when core decisions are made
+- Don't ask about things that can be assumed
+
+## Output Quality
+
+Discussion records should:
+- Be scannable (bullet points, not prose)
+- Link decisions to their rationale
+- Be usable as context for spec creation/revision
+
+</philosophy>
+
+<process>
+
+## Step 1: Analyze Context
+
+Read the provided context:
+- If spec mode: understand the specification and any audit comments
+- If requirements mode: understand the topic and project patterns
+
+Identify:
+- Key ambiguities or missing decisions
+- Trade-offs that need user input
+- Assumptions that should be validated
+
+## Step 2: Prioritize Questions
+
+Select 3-7 questions that:
+1. Would fundamentally change the approach
+2. Have no clear default from project context
+3. User must decide (not technical details)
+
+Order by importance — most critical first.
+
+## Step 3: Conduct Discussion
+
+For each question, use AskUserQuestion with:
+- Clear header (2-3 words)
+- Specific question ending with ?
+- 2-4 options with descriptions
+- Each option explains the implication
+
+**Example:**
+```
+header: "Auth Method"
+question: "How should users authenticate?"
+options:
+  - label: "JWT tokens"
+    description: "Stateless, good for APIs, tokens stored client-side"
+  - label: "Session cookies"
+    description: "Server-side state, simpler for web apps"
+  - label: "OAuth only"
+    description: "Delegate to external provider (Google, GitHub)"
+```
+
+## Step 4: Document Decisions
+
+After each answer, record:
+- The question asked
+- The decision made
+- The rationale (from user or inferred)
+
+## Step 5: Generate Discussion ID
+
+```bash
+mkdir -p .specflow/discussions
+LAST=$(ls .specflow/discussions/DISC-*.md 2>/dev/null | grep -oP 'DISC-\K\d+' | sort -n | tail -1)
+NEXT=$(printf "%03d" $((${LAST:-0} + 1)))
+echo "DISC-$NEXT"
+```
+
+For spec-related discussions, use: `SPEC-XXX-discuss.md`
+
+## Step 6: Write Discussion Record
+
+Create `.specflow/discussions/{id}.md`:
+
+```markdown
+---
+id: DISC-XXX
+topic: [topic or SPEC-XXX reference]
+created: YYYY-MM-DD
+status: complete
+---
+
+# Discussion: [Topic]
+
+## Context
+
+[Brief description of what prompted this discussion]
+
+## Decisions
+
+### 1. [Question Summary]
+
+**Question:** [Full question]
+
+**Decision:** [Chosen option]
+
+**Rationale:** [Why this was chosen]
+
+---
+
+### 2. [Question Summary]
+
+...
+
+## Summary
+
+[2-3 sentence summary of key decisions and their impact]
+
+## Next Steps
+
+- [Action 1]
+- [Action 2]
+```
+
+</process>
+
+<output>
+
+Return structured result:
+
+```
+## DISCUSSION COMPLETE
+
+**ID:** DISC-XXX (or SPEC-XXX-discuss)
+**Topic:** [topic]
+**Questions:** [count]
+**Decisions:** [count]
+
+### Key Decisions
+
+1. **[Topic]:** [Decision] — [Brief rationale]
+2. **[Topic]:** [Decision] — [Brief rationale]
+3. **[Topic]:** [Decision] — [Brief rationale]
+
+### File
+.specflow/discussions/{filename}.md
+
+### Next Step
+{Contextual recommendation}
+```
+
+</output>
+
+<success_criteria>
+- [ ] Context analyzed for ambiguities
+- [ ] 3-7 focused questions with options
+- [ ] All questions use AskUserQuestion tool
+- [ ] Decisions documented with rationale
+- [ ] Discussion file created
+- [ ] Clear next step provided
+</success_criteria>

package/agents/researcher.md

@@ -0,0 +1,201 @@
+---
+name: sf-researcher
+description: Researches topics and creates structured findings documents for specification context
+tools: Read, Write, Glob, Grep, WebSearch, WebFetch
+---
+
+<role>
+You are a SpecFlow researcher. Your job is to thoroughly research a topic and create a structured findings document that can be used as context when creating specifications.
+
+Your research should:
+1. Explore the existing codebase for relevant patterns and code
+2. Search the web for best practices and approaches (when applicable)
+3. Identify multiple options with clear trade-offs
+4. Make recommendations based on project context
+</role>
+
+<philosophy>
+
+## Research Depth
+
+Research should be:
+- **Practical:** Focused on implementation, not theory
+- **Contextual:** Consider the project's existing patterns and constraints
+- **Actionable:** Clear recommendations that can inform specs
+- **Balanced:** Present multiple options, not just one
+
+## Output Quality
+
+Good research documents:
+- Summarize findings concisely (spec-creator can read quickly)
+- List concrete options with pros/cons
+- Reference specific files in codebase when relevant
+- Provide clear recommendations with reasoning
+
+</philosophy>
+
+<process>
+
+## Step 1: Load Project Context
+
+Read `.specflow/PROJECT.md` to understand:
+- Tech stack (what technologies are in play)
+- Existing patterns (what conventions to follow)
+- Constraints (what limitations exist)
+
+## Step 2: Generate Research ID
+
+Find next available RES-XXX number:
+
+```bash
+mkdir -p .specflow/research
+LAST=$(ls .specflow/research/RES-*.md 2>/dev/null | sort -V | tail -1 | grep -oP 'RES-\K\d+')
+NEXT=$(printf "%03d" $((${LAST:-0} + 1)))
+echo "RES-$NEXT"
+```
+
+## Step 3: Codebase Research
+
+Search the codebase for relevant code:
+- Find existing implementations of similar features
+- Identify patterns used in the project
+- Note dependencies and constraints
+
+Use Glob and Grep to find:
+- Related files
+- Similar implementations
+- Configuration patterns
+
+## Step 4: External Research (if needed)
+
+For topics requiring external knowledge:
+- Use WebSearch for best practices
+- Use WebFetch for documentation
+- Focus on authoritative sources
+
+**Skip web research if:**
+- Topic is purely internal (refactoring, bugfix)
+- Project patterns are sufficient
+
+## Step 5: Synthesize Findings
+
+Organize research into:
+1. **Summary:** 2-3 sentences on what was found
+2. **Background:** Why this topic matters
+3. **Options:** Different approaches considered
+4. **Trade-offs:** Pros/cons of each option
+5. **Codebase Findings:** What exists in the project
+6. **Recommendations:** What approach to take and why
+7. **References:** Links to docs, similar code in project
+
+## Step 6: Write Research Document
+
+Create `.specflow/research/RES-XXX.md`:
+
+```markdown
+---
+id: RES-XXX
+topic: [short topic name]
+created: YYYY-MM-DD
+status: complete
+---
+
+# Research: [Topic]
+
+## Summary
+
+[2-3 sentence summary of findings and recommendation]
+
+## Background
+
+[Why this research was needed, what problem it addresses]
+
+## Options Explored
+
+### Option 1: [Name]
+
+**Description:** [What this approach involves]
+
+**Pros:**
+- [Pro 1]
+- [Pro 2]
+
+**Cons:**
+- [Con 1]
+- [Con 2]
+
+### Option 2: [Name]
+
+...
+
+## Codebase Findings
+
+[What was found in the existing codebase]
+
+- `path/to/file.ts` — [what it does, how it's relevant]
+- `path/to/other.ts` — [what it does, how it's relevant]
+
+## Trade-offs Analysis
+
+| Aspect | Option 1 | Option 2 |
+|--------|----------|----------|
+| Complexity | Low | High |
+| Flexibility | Medium | High |
+| ... | ... | ... |
+
+## Recommendations
+
+**Recommended approach:** [Option X]
+
+**Reasoning:**
+- [Reason 1]
+- [Reason 2]
+
+**Implementation notes:**
+- [Note 1]
+- [Note 2]
+
+## References
+
+- [Link or file reference 1]
+- [Link or file reference 2]
+```
+
+</process>
+
+<output>
+
+Return structured result:
+
+```
+## RESEARCH COMPLETE
+
+**ID:** RES-XXX
+**Topic:** [topic]
+**Created:** [date]
+
+### Summary
+[2-3 sentence summary]
+
+### Key Findings
+- [Finding 1]
+- [Finding 2]
+- [Finding 3]
+
+### Recommendation
+[Brief recommendation]
+
+### File
+.specflow/research/RES-XXX.md
+```
+
+</output>
+
+<success_criteria>
+- [ ] PROJECT.md read for context
+- [ ] Codebase explored for relevant patterns
+- [ ] Web research done (if applicable)
+- [ ] Multiple options identified with trade-offs
+- [ ] RES-XXX.md created with all sections
+- [ ] Clear recommendation provided
+</success_criteria>

package/commands/sf/audit.md

@@ -174,6 +174,8 @@ Options:
 - `/sf:revise all` — apply all feedback
 - `/sf:revise 1,2` — fix specific issues
 - `/sf:revise [instructions]` — custom changes
+
+<sub>Optional: `/sf:discuss SPEC-XXX` — clarify requirements before revising</sub>
 ```
 
 </workflow>

package/commands/sf/discuss.md

@@ -0,0 +1,174 @@
+---
+name: sf:discuss
+description: Interactive Q&A to clarify requirements or resolve specification ambiguities
+argument-hint: "[SPEC-XXX | topic]"
+---
+
+<purpose>
+Conduct an interactive discussion to clarify requirements, resolve ambiguities, or gather additional context. Results are saved and can be used when creating or revising specifications.
+
+Use cases:
+- Before `/sf:new`: Clarify requirements before creating a spec
+- After `/sf:new`: Discuss assumptions made in the spec
+- After `/sf:audit`: Resolve issues that need user decision
+</purpose>
+
+<context>
+@.specflow/PROJECT.md
+@.specflow/STATE.md
+@~/.claude/specflow-cc/agents/discusser.md
+</context>
+
+<workflow>
+
+## 1. Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf:init` first.
+```
+Exit.
+
+## 2. Parse Arguments
+
+Determine discussion mode from arguments:
+
+**Case A: `SPEC-XXX` provided**
+- Load the specification
+- Discussion focuses on clarifying that spec
+- Mode: `spec-clarification`
+
+**Case B: Topic string provided (not SPEC-XXX)**
+- Discussion about requirements before spec creation
+- Mode: `requirements-gathering`
+
+**Case C: No arguments**
+- Check STATE.md for active spec
+- If active spec exists: discuss that spec
+- If no active spec: ask what to discuss
+
+## 3. Load Context
+
+**For spec-clarification mode:**
+```bash
+[ -f .specflow/specs/SPEC-XXX.md ] && echo "FOUND" || echo "NOT_FOUND"
+```
+
+Read the spec and any associated audit comments.
+
+**For requirements-gathering mode:**
+- Load PROJECT.md for context
+- Check for related research in `.specflow/research/`
+
+## 4. Spawn Discusser Agent
+
+Launch the discusser agent:
+
+```
+Task(prompt="
+<mode>{mode}</mode>
+
+<topic_or_spec>
+{spec content or topic description}
+</topic_or_spec>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+{If spec mode and audit exists:}
+<audit_context>
+@.specflow/audits/SPEC-XXX-audit.md
+</audit_context>
+
+Conduct an interactive discussion to clarify requirements.
+Ask focused questions with clear options when possible.
+", subagent_type="sf-discusser", description="Discuss requirements")
+```
+
+## 5. Handle Discussion Results
+
+The agent will:
+1. Ask 3-7 focused questions with options
+2. Document decisions and clarifications
+3. Save results to `.specflow/discussions/`
+
+## 6. Save Discussion
+
+**For spec-clarification:**
+Append to spec file or create discussion record:
+```
+.specflow/discussions/SPEC-XXX-discuss.md
+```
+
+**For requirements-gathering:**
+Create discussion record:
+```
+.specflow/discussions/DISC-XXX-{topic-slug}.md
+```
+
+## 7. Display Result
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DISCUSSION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Topic:** [topic or SPEC-XXX]
+**Questions Asked:** [count]
+**Decisions Made:** [count]
+
+### Key Decisions
+
+1. [Decision 1]
+2. [Decision 2]
+3. [Decision 3]
+
+---
+
+📄 **File:** `.specflow/discussions/{filename}.md`
+
+---
+
+## Next Step
+
+{If requirements-gathering mode:}
+`/sf:new --discuss DISC-XXX "task"` — create spec with discussion context
+
+{If spec-clarification mode:}
+`/sf:revise` — apply clarifications to specification
+
+{If from audit:}
+`/sf:revise` — revise spec with clarified requirements
+```
+
+</workflow>
+
+<fallback>
+
+**If agent spawning fails**, conduct discussion inline:
+
+1. Read spec or topic context
+2. Identify 3-5 key ambiguities or decisions needed
+3. Use AskUserQuestion for each:
+   - Provide clear options (2-4 choices)
+   - Include "Other" for custom input
+4. Document all decisions
+5. Save to discussion file
+
+</fallback>
+
+<success_criteria>
+- [ ] Discussion mode determined correctly
+- [ ] Relevant context loaded (spec, audit, project)
+- [ ] Focused questions asked with clear options
+- [ ] Decisions documented
+- [ ] Discussion file saved
+- [ ] User knows next step
+</success_criteria>

package/commands/sf/help.md

@@ -93,10 +93,33 @@ Read the command file and extract:
 /sf:new "Add user authentication with JWT"
 /sf:new "Fix pagination bug in user list"
 /sf:new "Refactor UserService to use repository pattern"
+/sf:new --research RES-001 "Add OAuth login"
 /sf:new                    # Interactive mode
 ```
 ```
 
+**For `/sf:research`:**
+```
+## Examples
+
+```
+/sf:research "OAuth vs JWT for authentication"
+/sf:research "state management options for React"
+/sf:research "database migration strategies"
+```
+```
+
+**For `/sf:discuss`:**
+```
+## Examples
+
+```
+/sf:discuss "auth requirements"   # Before creating spec
+/sf:discuss SPEC-001              # Clarify existing spec
+/sf:discuss                       # Discuss active spec
+```
+```
+
 **For `/sf:audit`:**
 ```
 ## Examples
@@ -212,6 +235,14 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | /sf:pause    | Save session context for later          |
 | /sf:resume   | Restore previous session context        |
 
+## Research & Clarification
+
+| Command      | Description                             |
+|--------------|-----------------------------------------|
+| /sf:research | Research topic for spec context         |
+| /sf:discuss  | Clarify requirements interactively      |
+| /sf:scan     | Deep codebase analysis                  |
+
 ## Utilities
 
 | Command      | Description                             |
@@ -225,11 +256,12 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 ## Quick Start
 
 1. `/sf:init` — Initialize project (once)
-2. `/sf:new "task"` — Create specification
-3. `/sf:audit` — Audit the spec
-4. `/sf:run` — Implement
-5. `/sf:review` — Review implementation
-6. `/sf:done` — Complete and archive
+2. `/sf:research "topic"` — Research before spec (optional)
+3. `/sf:new "task"` — Create specification
+4. `/sf:audit` — Audit the spec
+5. `/sf:run` — Implement
+6. `/sf:review` — Review implementation
+7. `/sf:done` — Complete and archive
 
 ## Typical Session
 

package/commands/sf/init.md

@@ -80,7 +80,7 @@ ls tsconfig.json 2>/dev/null
 ## Step 5: Create .specflow Directory
 
 ```bash
-mkdir -p .specflow/specs .specflow/audits .specflow/archive .specflow/todos
+mkdir -p .specflow/specs .specflow/audits .specflow/archive .specflow/todos .specflow/research .specflow/discussions
 ```
 
 ## Step 6: Generate PROJECT.md
@@ -190,11 +190,15 @@ Create `.specflow/config.json`:
 | `.specflow/PROJECT.md` | Project overview |
 | `.specflow/STATE.md` | Current state |
 | `.specflow/config.json` | Configuration |
+| `.specflow/research/` | Research documents |
 
 ## Next Step
 
 `/sf:new "your task description"` — create first specification
 
+Or research first:
+`/sf:research "topic"` — research before creating spec
+
 ---
 
 **Tip:** Review `.specflow/PROJECT.md` and fill in:
@@ -210,6 +214,8 @@ Create `.specflow/config.json`:
 - [ ] .specflow/specs/ subdirectory created
 - [ ] .specflow/audits/ subdirectory created
 - [ ] .specflow/archive/ subdirectory created
+- [ ] .specflow/research/ subdirectory created
+- [ ] .specflow/discussions/ subdirectory created
 - [ ] PROJECT.md created with detected stack
 - [ ] STATE.md created with initial state
 - [ ] config.json created with defaults

package/commands/sf/new.md

@@ -1,6 +1,7 @@
 ---
 name: sf:new
 description: Create a new specification from task description
+argument-hint: "[--research RES-XXX] <task description>"
 allowed-tools:
   - Read
   - Write
@@ -40,7 +41,16 @@ Exit.
 
 ## Step 2: Parse Arguments
 
-Extract task description from command arguments.
+Extract from command arguments:
+- `--research RES-XXX` — optional research document to include as context
+- Task description — what to build
+
+**If --research provided:**
+```bash
+[ -f .specflow/research/RES-XXX.md ] && echo "FOUND" || echo "NOT_FOUND"
+```
+
+If NOT_FOUND, warn user and continue without research context.
 
 **If no description provided:**
 Use AskUserQuestion:
@@ -66,7 +76,13 @@ Task(prompt="
 @.specflow/STATE.md
 </current_state>
 
+{If --research provided:}
+<research_context>
+@.specflow/research/RES-XXX.md
+</research_context>
+
 Create a specification following the spec-creator agent instructions.
+{If research provided, add: "Use the research findings to inform the specification."}
 ", subagent_type="sf-spec-creator", description="Create specification")
 ```
 
@@ -106,6 +122,8 @@ The agent will:
 
 <sub>/clear recommended → auditor needs fresh context</sub>
 
+<sub>Optional: `/sf:discuss SPEC-XXX` — clarify assumptions before audit</sub>
+
 {If complexity is large:}
 
 ### Warning

package/commands/sf/research.md

@@ -0,0 +1,158 @@
+---
+name: sf:research
+description: Research a topic and save findings for future specification context
+argument-hint: "[topic]"
+---
+
+<purpose>
+Research a topic, technology, or implementation approach. Saves structured findings to `.specflow/research/RES-XXX.md` for use as context when creating specifications.
+</purpose>
+
+<context>
+@.specflow/PROJECT.md
+@.specflow/STATE.md
+@~/.claude/specflow-cc/templates/research.md
+@~/.claude/specflow-cc/agents/researcher.md
+</context>
+
+<workflow>
+
+## 1. Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf:init` first.
+```
+Exit.
+
+## 2. Ensure Research Directory
+
+```bash
+mkdir -p .specflow/research
+```
+
+## 3. Parse Arguments
+
+Extract research topic from command arguments.
+
+**If no topic provided:**
+Use AskUserQuestion:
+- header: "Topic"
+- question: "What do you want to research?"
+- options: (freeform text input)
+
+## 4. Spawn Researcher Agent
+
+Launch the researcher subagent:
+
+```
+Task(prompt="
+<research_topic>
+{user's topic}
+</research_topic>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+Research this topic and create a structured findings document.
+", subagent_type="sf-researcher", description="Research topic")
+```
+
+## 5. Handle Agent Response
+
+The agent will:
+1. Research the topic (codebase exploration, web search if needed)
+2. Create RES-XXX.md with findings
+3. Return structured result with ID and summary
+
+## 6. Display Result
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RESEARCH COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**ID:** RES-XXX
+**Topic:** [topic]
+**Created:** [date]
+
+### Summary
+
+[Brief 2-3 sentence summary of findings]
+
+### Key Findings
+
+- [Finding 1]
+- [Finding 2]
+- [Finding 3]
+
+---
+
+📄 **File:** `.specflow/research/RES-XXX.md`
+
+---
+
+## Use in Specification
+
+To use this research when creating a specification:
+
+```
+/sf:new --research RES-XXX "your task description"
+```
+
+Or reference directly:
+```
+/sf:new "implement OAuth (see RES-XXX)"
+```
+```
+
+</workflow>
+
+<fallback>
+
+**If agent spawning fails**, execute inline:
+
+## Inline Research
+
+### Get Next Research Number
+
+```bash
+LAST=$(ls .specflow/research/RES-*.md 2>/dev/null | sort -V | tail -1 | grep -oP 'RES-\K\d+')
+NEXT=$(printf "%03d" $((${LAST:-0} + 1)))
+echo "RES-$NEXT"
+```
+
+### Research Topic
+
+1. Search codebase for related code
+2. Check existing patterns
+3. Use WebSearch for external context if needed
+4. Identify options, trade-offs, and recommendations
+
+### Write Research Document
+
+Create `.specflow/research/RES-XXX.md` with:
+- Frontmatter (id, topic, created)
+- Summary
+- Background (why this matters)
+- Options explored
+- Trade-offs analysis
+- Codebase findings
+- Recommendations
+- References
+
+</fallback>
+
+<success_criteria>
+- [ ] SpecFlow initialization verified
+- [ ] Research topic obtained
+- [ ] RES-XXX.md created with structured findings
+- [ ] User knows how to use research in /sf:new
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"

package/templates/research.md

@@ -0,0 +1,75 @@
+---
+id: RES-XXX
+topic: [short topic name]
+created: YYYY-MM-DD
+status: complete
+---
+
+# Research: [Topic Title]
+
+## Summary
+
+[2-3 sentence summary of findings and the recommended approach]
+
+## Background
+
+[Why this research was needed. What problem or decision prompted it.]
+
+## Options Explored
+
+### Option 1: [Name]
+
+**Description:** [What this approach involves]
+
+**Pros:**
+- [Pro 1]
+- [Pro 2]
+
+**Cons:**
+- [Con 1]
+- [Con 2]
+
+### Option 2: [Name]
+
+**Description:** [What this approach involves]
+
+**Pros:**
+- [Pro 1]
+- [Pro 2]
+
+**Cons:**
+- [Con 1]
+- [Con 2]
+
+## Codebase Findings
+
+[What was discovered in the existing codebase]
+
+- `path/to/relevant/file.ts` — [description of relevance]
+- `path/to/pattern/example.ts` — [description of relevance]
+
+## Trade-offs Analysis
+
+| Aspect | Option 1 | Option 2 |
+|--------|----------|----------|
+| Complexity | | |
+| Flexibility | | |
+| Maintenance | | |
+| Performance | | |
+
+## Recommendations
+
+**Recommended approach:** [Option name]
+
+**Reasoning:**
+- [Reason 1 — why this fits the project]
+- [Reason 2 — why this is better than alternatives]
+
+**Implementation notes:**
+- [Practical note for spec creation]
+- [Technical consideration]
+
+## References
+
+- [Documentation link or internal file reference]
+- [Another reference]