specflow-cc 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.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/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/help.md

@@ -93,10 +93,22 @@ 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:audit`:**
 ```
 ## Examples
@@ -212,6 +224,13 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | /sf:pause    | Save session context for later          |
 | /sf:resume   | Restore previous session context        |
 
+## Research & Analysis
+
+| Command      | Description                             |
+|--------------|-----------------------------------------|
+| /sf:research | Research topic for spec context         |
+| /sf:scan     | Deep codebase analysis                  |
+
 ## Utilities
 
 | Command      | Description                             |
@@ -225,11 +244,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
 ```
 
 ## 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,7 @@ Create `.specflow/config.json`:
 - [ ] .specflow/specs/ subdirectory created
 - [ ] .specflow/audits/ subdirectory created
 - [ ] .specflow/archive/ subdirectory created
+- [ ] .specflow/research/ 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")
 ```
 

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.4.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]