specflow-cc 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.2.0] - 2026-01-20
+
+### Fixed
+
+- Command format: `/sf run` → `/sf:run` (matches Claude Code syntax)
+
+### Changed
+
+- `/sf:audit` now shows alternative next steps when APPROVED with recommendations
+- `/sf:review` now shows alternative next steps when APPROVED with minor suggestions
+- User can choose to proceed or apply optional feedback first
+
+---
+
+## [1.1.0] - 2026-01-20
+
+### Added
+
+#### Analysis Commands
+- `/sf:scan [--focus]` - Deep codebase analysis for tech debt, concerns, and improvement opportunities
+
+#### Agents
+- `codebase-scanner` - Analyzes codebase and writes structured SCAN.md report
+
+#### Templates
+- `scan.md` - Codebase scan report template
+
+---
+
 ## [1.0.0] - 2026-01-20
 
 ### Added

package/README.md

@@ -41,28 +41,28 @@ npx specflow-cc --local
 
 ```bash
 # 1. Initialize project (once per project)
-/sf init
+/sf:init
 
 # 2. Create a specification
-/sf new "Add user authentication with JWT"
+/sf:new "Add user authentication with JWT"
 
 # 3. Audit the specification (fresh context)
-/sf audit
+/sf:audit
 
 # 4. Revise if needed
-/sf revise
+/sf:revise
 
 # 5. Execute when approved
-/sf run
+/sf:run
 
 # 6. Review implementation (fresh context)
-/sf review
+/sf:review
 
 # 7. Fix if needed
-/sf fix
+/sf:fix
 
 # 8. Complete and archive
-/sf done
+/sf:done
 ```
 
 ## Commands
@@ -71,54 +71,60 @@ npx specflow-cc --local
 
 | 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: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 |
 
 ### Navigation
 
 | Command | Description |
 |---------|-------------|
-| `/sf list` | List all specifications |
-| `/sf show [ID]` | Show specification details |
-| `/sf next` | Switch to next priority task |
+| `/sf:list` | List all specifications |
+| `/sf:show [ID]` | Show specification details |
+| `/sf:next` | Switch to next priority task |
 
 ### To-Do Management
 
 | 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: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 |
 
 ### Decomposition
 
 | Command | Description |
 |---------|-------------|
-| `/sf split [ID]` | Split large spec into smaller parts |
-| `/sf deps` | Show dependency graph |
+| `/sf:split [ID]` | Split large spec into smaller parts |
+| `/sf:deps` | Show dependency graph |
 
 ### Session Management
 
 | Command | Description |
 |---------|-------------|
-| `/sf pause` | Save context for later |
-| `/sf resume` | Restore saved context |
+| `/sf:pause` | Save context for later |
+| `/sf:resume` | Restore saved context |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `/sf:scan [--focus]` | Deep codebase analysis for concerns and tech debt |
 
 ### Utilities
 
 | Command | Description |
 |---------|-------------|
-| `/sf help [command]` | Show help for commands |
-| `/sf history [ID]` | View completed specifications |
-| `/sf metrics` | Project statistics |
+| `/sf:help [command]` | Show help for commands |
+| `/sf:history [ID]` | View completed specifications |
+| `/sf:metrics` | Project statistics |
 
 ## Workflow Diagram
 
@@ -127,43 +133,44 @@ npx specflow-cc --local
 │                    SPECFLOW WORKFLOW                         │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
-│  /sf init    ──→  Initialize project (once)                  │
+│  /sf:init    ──→  Initialize project (once)                  │
 │       ↓                                                      │
-│  /sf new     ──→  Create specification                       │
+│  /sf:new     ──→  Create specification                       │
 │       ↓                                                      │
 │  ┌─────────────────────────────────────┐                     │
 │  │  SPEC AUDIT LOOP                    │                     │
-│  │  /sf audit ──→ APPROVED? ──yes──→ ──┼──→                  │
+│  │  /sf:audit ──→ APPROVED? ──yes──→ ──┼──→                  │
 │  │       │                             │    ↓                │
 │  │       no                            │                     │
 │  │       ↓                             │                     │
-│  │  /sf revise ────────→ loop back     │                     │
+│  │  /sf:revise ────────→ loop back     │                     │
 │  └─────────────────────────────────────┘                     │
 │       ↓                                                      │
-│  /sf run     ──→  Execute specification                      │
+│  /sf:run     ──→  Execute specification                      │
 │       ↓                                                      │
 │  ┌─────────────────────────────────────┐                     │
 │  │  IMPL REVIEW LOOP                   │                     │
-│  │  /sf review ──→ APPROVED? ──yes──→ ─┼──→                  │
+│  │  /sf:review ──→ APPROVED? ──yes──→ ─┼──→                  │
 │  │       │                             │    ↓                │
 │  │       no                            │                     │
 │  │       ↓                             │                     │
-│  │  /sf fix ───────────→ loop back     │                     │
+│  │  /sf:fix ───────────→ loop back     │                     │
 │  └─────────────────────────────────────┘                     │
 │       ↓                                                      │
-│  /sf done    ──→  Complete and archive                       │
+│  /sf:done    ──→  Complete and archive                       │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ## Project Structure
 
-After `/sf init`, SpecFlow creates:
+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
@@ -215,7 +222,7 @@ created: 2026-01-20
 |------|--------|--------|
 | Small | ≤50k | Execute directly |
 | Medium | 50-150k | Warning, proceed |
-| Large | >150k | Requires `/sf split` |
+| Large | >150k | Requires `/sf:split` |
 
 ## Statusline
 
@@ -228,8 +235,8 @@ SpecFlow includes a statusline hook showing:
 
 | Aspect | GSD | SpecFlow |
 |--------|-----|----------|
-| Commands | 25 | 22 |
-| Agents | 11 | 6 |
+| Commands | 25 | 23 |
+| Agents | 11 | 7 |
 | Phases per task | 5+ | 3-4 |
 | Quality audit | No | Yes (explicit) |
 | Revision loop | No | Yes |

package/agents/codebase-scanner.md

@@ -0,0 +1,243 @@
+---
+name: sf-codebase-scanner
+description: Analyzes codebase for concerns, quality issues, and improvement opportunities. Writes SCAN.md directly.
+tools: Read, Bash, Grep, Glob, Write
+---
+
+<role>
+You are a SpecFlow codebase scanner. You analyze a codebase to identify technical debt, code quality issues, security concerns, and improvement opportunities.
+
+You are spawned by `/sf:scan` with a focus area:
+- **concerns** — Technical debt, bugs, security issues
+- **quality** — Code quality, conventions, test coverage gaps
+- **arch** — Architecture problems, structure issues
+- **all** — Complete analysis (default)
+
+Your job: Explore thoroughly, analyze deeply, write `.specflow/SCAN.md` directly. Return only confirmation.
+</role>
+
+<philosophy>
+**Actionable findings only:**
+Every issue should have enough context to create a specification. Include file paths, line numbers when relevant, and suggested fixes.
+
+**Prioritize by impact:**
+Order findings by severity. A security vulnerability matters more than a missing comment.
+
+**Be specific, not vague:**
+"UserService.ts:45 has SQL injection risk" not "there might be security issues"
+
+**Include file paths:**
+Every finding needs a file path in backticks. This enables direct navigation.
+</philosophy>
+
+<process>
+
+## 1. Parse Focus Area
+
+Read focus from prompt. Default to "all" if not specified.
+
+## 2. Explore Codebase
+
+**For concerns focus:**
+```bash
+# TODO/FIXME/HACK comments
+grep -rn "TODO\|FIXME\|HACK\|XXX\|BUG" src/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" 2>/dev/null | head -50
+
+# Large files (complexity indicators)
+find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" | xargs wc -l 2>/dev/null | sort -rn | head -20
+
+# Empty catches / swallowed errors
+grep -rn "catch.*{}" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -20
+
+# Hardcoded secrets patterns
+grep -rn "password\|secret\|api_key\|apikey" src/ --include="*.ts" --include="*.tsx" --include="*.env*" 2>/dev/null | head -20
+
+# console.log in production code
+grep -rn "console.log\|console.error" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30
+```
+
+**For quality focus:**
+```bash
+# Check for linting/formatting config
+ls .eslintrc* .prettierrc* eslint.config.* biome.json tsconfig.json 2>/dev/null
+
+# Test file coverage
+find . -name "*.test.*" -o -name "*.spec.*" | wc -l
+find . -name "*.ts" -o -name "*.tsx" | grep -v test | grep -v spec | wc -l
+
+# Type safety issues (any usage)
+grep -rn ": any\|as any" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30
+
+# Duplicate code patterns (similar function names)
+grep -rn "function\|const.*=" src/ --include="*.ts" | cut -d: -f3 | sort | uniq -d | head -20
+```
+
+**For arch focus:**
+```bash
+# Directory structure
+find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | head -40
+
+# Circular dependency indicators
+grep -rn "import.*from" src/ --include="*.ts" | head -100
+
+# Entry points
+ls src/index.* src/main.* src/app.* app/page.* pages/index.* 2>/dev/null
+
+# Large directories (potential god modules)
+find src/ -type f | cut -d/ -f1-3 | sort | uniq -c | sort -rn | head -10
+```
+
+## 3. Deep Analysis
+
+Read key files identified during exploration:
+- Largest files (complexity hotspots)
+- Files with most TODO comments
+- Entry points and core modules
+- Test files (or lack thereof)
+
+## 4. Write SCAN.md
+
+Use the Write tool to create `.specflow/SCAN.md`:
+
+```markdown
+# Codebase Scan Report
+
+**Date:** [YYYY-MM-DD]
+**Focus:** [focus area]
+
+## Executive Summary
+
+[2-3 sentence overview of codebase health]
+
+**Health Score:** [Good | Moderate | Needs Attention | Critical]
+
+---
+
+## Tech Debt
+
+### High Priority
+
+**[Issue Title]**
+- Files: `[file paths]`
+- Problem: [What's wrong]
+- Impact: [Why it matters]
+- Fix: [How to address]
+
+### Medium Priority
+
+...
+
+### Low Priority
+
+...
+
+---
+
+## Code Quality Issues
+
+### Type Safety
+
+**[Issue]**
+- Files: `[paths]`
+- Count: [N occurrences]
+- Fix: [Approach]
+
+### Error Handling
+
+...
+
+### Code Duplication
+
+...
+
+---
+
+## Security Considerations
+
+**[Risk Area]**
+- Files: `[paths]`
+- Risk: [What could happen]
+- Severity: [Critical | High | Medium | Low]
+- Mitigation: [What to do]
+
+---
+
+## Test Coverage Gaps
+
+**[Untested Area]**
+- Files: `[paths]`
+- What's missing: [Description]
+- Priority: [High | Medium | Low]
+
+---
+
+## Architecture Observations
+
+**[Observation]**
+- Current: [How it is]
+- Concern: [Why it's problematic]
+- Suggestion: [Improvement]
+
+---
+
+## Suggested Specifications
+
+Based on this scan, consider creating specs for:
+
+1. **[Spec title]** — [brief description]
+   - Priority: [High | Medium | Low]
+   - Complexity: [small | medium | large]
+
+2. **[Spec title]** — [brief description]
+   ...
+
+---
+
+*Scan completed: [timestamp]*
+```
+
+## 5. Return Confirmation
+
+Return ONLY a brief confirmation:
+
+```
+## Scan Complete
+
+**Focus:** {focus}
+**Document:** `.specflow/SCAN.md` ({N} lines)
+
+**Findings:**
+- Tech Debt: {N} issues
+- Quality: {N} issues
+- Security: {N} considerations
+- Test Gaps: {N} areas
+
+Ready for review.
+```
+
+</process>
+
+<critical_rules>
+
+**WRITE SCAN.MD DIRECTLY.** Do not return findings to orchestrator.
+
+**ALWAYS INCLUDE FILE PATHS.** Every finding needs a file path in backticks.
+
+**PRIORITIZE FINDINGS.** Most impactful issues first.
+
+**BE SPECIFIC.** Line numbers, function names, concrete examples.
+
+**SUGGEST SPECS.** End with actionable specification ideas.
+
+**RETURN ONLY CONFIRMATION.** Your response should be ~15 lines max.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] Focus area understood
+- [ ] Codebase explored thoroughly
+- [ ] `.specflow/SCAN.md` written with structured findings
+- [ ] File paths included throughout
+- [ ] Suggested specifications provided
+- [ ] Confirmation returned (not full document)
+</success_criteria>

package/agents/impl-reviewer.md

@@ -196,8 +196,8 @@ Append to specification's Review History:
 
 ## Step 8: Update STATE.md
 
-- If APPROVED: Status → "done", Next Step → "/sf done"
-- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf fix"
+- If APPROVED: Status → "done", Next Step → "/sf:done"
+- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
 
 </process>
 
@@ -246,13 +246,13 @@ Return review result:
 
 ## Next Step
 
-{If APPROVED:} `/sf done` — finalize and archive
+{If APPROVED:} `/sf:done` — finalize and archive
 
-{If CHANGES_REQUESTED:} `/sf fix` — address issues
+{If CHANGES_REQUESTED:} `/sf:fix` — address issues
 
 Options:
-- `/sf fix all` — apply all fixes
-- `/sf fix 1,2` — fix specific issues
+- `/sf:fix all` — apply all fixes
+- `/sf:fix 1,2` — fix specific issues
 ```
 
 </output>

package/agents/spec-auditor.md

@@ -100,7 +100,7 @@ Separate findings into:
 
 **Critical (blocks implementation):**
 - Numbered list: 1, 2, 3...
-- Must be fixed before `/sf run`
+- Must be fixed before `/sf:run`
 
 **Recommendations (improvements):**
 - Numbered list continuing from critical
@@ -138,8 +138,8 @@ N+1. [recommendation]
 ## Step 7: Update STATE.md
 
 Update status:
-- If APPROVED: Status → "audited", Next Step → "/sf run"
-- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf revise"
+- If APPROVED: Status → "audited", Next Step → "/sf:run"
+- If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf:revise"
 
 </process>
 
@@ -168,7 +168,7 @@ Return formatted audit result:
 
 ### Next Step
 
-`/sf revise` — address critical issues
+`/sf:revise` — address critical issues
 
 ---
 
@@ -180,7 +180,7 @@ Return formatted audit result:
 
 ### Next Step
 
-`/sf run` — implement specification
+`/sf:run` — implement specification
 ```
 
 </output>

package/agents/spec-creator.md

@@ -24,7 +24,7 @@ Ask ONLY questions that:
 - Cannot be reasonably assumed from PROJECT.md context
 - Have mutually exclusive answers (not "yes/no/maybe")
 
-Everything else becomes an assumption that can be corrected during `/sf revise`.
+Everything else becomes an assumption that can be corrected during `/sf:revise`.
 
 ## Spec Quality
 
@@ -40,7 +40,7 @@ Good specifications are:
 |------|--------|---------------|
 | small | ≤50k | Single file, simple feature |
 | medium | 50-150k | Multiple files, moderate feature |
-| large | >150k | Many files, complex feature — needs /sf split |
+| large | >150k | Many files, complex feature — needs /sf:split |
 
 </philosophy>
 
@@ -111,7 +111,7 @@ Mark as small/medium/large in frontmatter.
 Update `.specflow/STATE.md`:
 - Set Active Specification to new spec
 - Set Status to "drafting"
-- Set Next Step to "/sf audit"
+- Set Next Step to "/sf:audit"
 - Add spec to Queue
 
 </process>
@@ -136,11 +136,11 @@ Return structured result:
 - .specflow/specs/SPEC-XXX.md
 
 ### Next Step
-`/sf audit` — audit specification before implementation
+`/sf:audit` — audit specification before implementation
 
 {If complexity is large:}
 ### Warning
-Specification is large (>150k tokens estimated). Consider `/sf split SPEC-XXX` to decompose.
+Specification is large (>150k tokens estimated). Consider `/sf:split SPEC-XXX` to decompose.
 ```
 
 </output>

package/agents/spec-executor.md

@@ -182,7 +182,7 @@ Append to specification:
 ## Step 8: Update STATE.md
 
 - Status → "review"
-- Next Step → "/sf review"
+- Next Step → "/sf:review"
 
 </process>
 
@@ -216,7 +216,7 @@ Return execution result:
 
 ### Next Step
 
-`/sf review` — audit implementation
+`/sf:review` — audit implementation
 ```
 
 </output>

package/agents/spec-reviser.md

@@ -137,7 +137,7 @@ Set status to "auditing" (ready for re-audit).
 ## Step 7: Update STATE.md
 
 - Status → "auditing"
-- Next Step → "/sf audit"
+- Next Step → "/sf:audit"
 
 </process>
 
@@ -167,7 +167,7 @@ Return formatted revision result:
 
 ### Next Step
 
-`/sf audit` — re-audit revised specification
+`/sf:audit` — re-audit revised specification
 ```
 
 </output>

package/agents/spec-splitter.md

@@ -179,7 +179,7 @@ SPEC-XXXc
 
 ### Next Step
 
-`/sf audit SPEC-XXXa` — start with first sub-specification
+`/sf:audit SPEC-XXXa` — start with first sub-specification
 ```
 
 </output>