specflow-cc 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.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

@@ -112,6 +112,12 @@ npx specflow-cc --local
 | `/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 |
@@ -164,6 +170,7 @@ 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
@@ -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/commands/sf/scan.md

@@ -0,0 +1,164 @@
+---
+name: sf:scan
+description: Deep codebase analysis — identifies concerns, tech debt, and improvement opportunities
+argument-hint: "[--focus=concerns|quality|arch|all]"
+---
+
+<purpose>
+Perform deep analysis of the codebase to identify technical debt, code quality issues, architectural problems, and improvement opportunities. Results are saved to `.specflow/SCAN.md` for use in creating specifications.
+</purpose>
+
+<context>
+@.specflow/PROJECT.md
+@.specflow/STATE.md
+@~/.claude/specflow-cc/templates/scan.md
+@~/.claude/specflow-cc/agents/codebase-scanner.md
+</context>
+
+<workflow>
+
+## 1. Parse Arguments
+
+```
+FOCUS = $ARGUMENTS or "all"
+```
+
+Valid focus areas:
+- `concerns` — Technical debt, bugs, security issues
+- `quality` — Code quality, conventions, test coverage
+- `arch` — Architecture, structure, patterns
+- `all` — Full analysis (default)
+
+## 2. Check Prerequisites
+
+```bash
+[ -d .specflow ] && echo "INITIALIZED" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+⚠️  Project not initialized
+
+Run /sf init first to set up SpecFlow.
+```
+STOP.
+
+## 3. Check Existing Scan
+
+```bash
+[ -f .specflow/SCAN.md ] && echo "EXISTS" || echo "NEW"
+```
+
+**If EXISTS:**
+Ask user:
+```
+📊 Previous scan found (.specflow/SCAN.md)
+
+Options:
+1) Refresh — Run new scan (overwrites existing)
+2) View — Show existing scan results
+3) Cancel
+
+Choice?
+```
+
+## 4. Launch Scanner Agent
+
+Use the Task tool to spawn codebase-scanner agent:
+
+```
+subagent_type="sf-codebase-scanner"
+prompt="""
+Focus: {FOCUS}
+Project: {from PROJECT.md}
+
+Scan the codebase and write findings to .specflow/SCAN.md
+
+Return only confirmation when done.
+"""
+```
+
+## 5. Verify Results
+
+After agent completes:
+
+```bash
+[ -f .specflow/SCAN.md ] && wc -l .specflow/SCAN.md
+```
+
+## 6. Display Summary
+
+Read `.specflow/SCAN.md` and extract summary:
+
+```
+📊 Codebase Scan Complete
+
+Focus: {FOCUS}
+Lines analyzed: ~{estimate}
+
+┌─────────────────────────────────────────────┐
+│ Summary                                      │
+├─────────────────────────────────────────────┤
+│ Tech Debt:        {count} issues            │
+│ Quality Issues:   {count} findings          │
+│ Security:         {count} considerations    │
+│ Test Gaps:        {count} areas             │
+└─────────────────────────────────────────────┘
+
+Top Priority Issues:
+1. {issue 1}
+2. {issue 2}
+3. {issue 3}
+
+📁 Full report: .specflow/SCAN.md
+
+Next steps:
+• /sf new "Fix: {top concern}" — Create spec for top issue
+• /sf todo {concern} — Add to backlog for later
+```
+
+</workflow>
+
+<fallback>
+If agent cannot be spawned, perform scan directly:
+
+1. Explore codebase structure
+2. Search for TODO/FIXME comments
+3. Identify large/complex files
+4. Check test coverage gaps
+5. Look for code smells
+6. Write findings to `.specflow/SCAN.md`
+</fallback>
+
+<output_format>
+**Success:**
+```
+📊 Codebase Scan Complete
+
+[Summary table]
+[Top issues]
+[Next steps]
+```
+
+**No issues found:**
+```
+✅ Codebase scan complete — no critical concerns found
+
+Minor observations saved to .specflow/SCAN.md
+```
+
+**Error:**
+```
+❌ Scan failed: {reason}
+
+Try running manually or check .specflow/ permissions.
+```
+</output_format>
+
+<success_criteria>
+- [ ] Focus area parsed correctly
+- [ ] Scanner agent spawned (or fallback executed)
+- [ ] .specflow/SCAN.md created with findings
+- [ ] Summary displayed to user
+- [ ] Next steps provided
+</success_criteria>

package/package.json

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

package/templates/scan.md

@@ -0,0 +1,96 @@
+# Codebase Scan Report
+
+**Date:** [YYYY-MM-DD]
+**Focus:** [all | concerns | quality | arch]
+
+## Executive Summary
+
+[2-3 sentence overview of codebase health and key findings]
+
+**Health Score:** [Good | Moderate | Needs Attention | Critical]
+
+---
+
+## Tech Debt
+
+### High Priority
+
+**[Issue Title]**
+- Files: `[file/path.ts]`
+- Problem: [What's wrong]
+- Impact: [Why it matters]
+- Fix: [How to address]
+
+### Medium Priority
+
+<!-- Add issues here -->
+
+### Low Priority
+
+<!-- Add issues here -->
+
+---
+
+## Code Quality Issues
+
+### Type Safety
+
+**[Issue]**
+- Files: `[paths]`
+- Count: [N occurrences]
+- Fix: [Approach]
+
+### Error Handling
+
+<!-- Swallowed errors, missing catches, etc. -->
+
+### Code Duplication
+
+<!-- Similar code patterns that should be abstracted -->
+
+---
+
+## 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
+   - Command: `/sf new "[title]"`
+
+2. **[Spec title]** — [brief description]
+   - Priority: ...
+   - Complexity: ...
+
+---
+
+*Scan completed: [timestamp]*