specflow-cc 1.7.2 → 1.8.0

package/README.md

@@ -356,6 +356,7 @@ before showing interactive options.
 | `/sf:discuss "question?"` | Single question |
 | `/sf:discuss --pre "topic"` | Pre-spec discussion with feature-type questions |
 | `/sf:scan` | Analyze codebase for issues |
+| `/sf:triage` | Convert scan findings to TODOs |
 
 **Pre-spec discussion** identifies gray areas before creating a spec:
 

package/agents/spec-executor-worker.md

@@ -56,6 +56,13 @@ One commit per logical unit:
 - Clean, readable code
 - Handle edge cases mentioned in requirements
 
+## Code Comments Convention
+
+When writing or modifying code:
+- Do NOT add phase/spec/bug references in code comments (e.g., `// Phase 8.02`, `// BUG-06`, `// SPEC-011`)
+- Such references belong in commit messages, not in code
+- Instead, write WHY-comments explaining the reason for the code
+
 </philosophy>
 
 <process>

package/agents/spec-executor.md

@@ -63,6 +63,13 @@ One commit per logical unit:
 - Clean, readable code
 - Handle edge cases mentioned in spec
 
+## Code Comments Convention
+
+When writing or modifying code:
+- Do NOT add phase/spec/bug references in code comments (e.g., `// Phase 8.02`, `// BUG-06`, `// SPEC-011`)
+- Such references belong in commit messages, not in code
+- Instead, write WHY-comments explaining the reason for the code
+
 </philosophy>
 
 <process>

package/commands/sf/help.md

@@ -275,6 +275,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | /sf:research | Research topic for spec context         |
 | /sf:discuss  | Clarify requirements interactively      |
 | /sf:scan     | Deep codebase analysis                  |
+| /sf:triage   | Convert scan findings to TODOs          |
 
 ## Utilities
 

package/commands/sf/scan.md

@@ -130,8 +130,9 @@ Top Priority Issues:
 📁 Full report: .specflow/SCAN.md
 
 Next steps:
+• /sf:triage — Review findings and create TODOs
 • /sf:new "Fix: {top concern}" — Create spec for top issue
-• /sf:todo {concern} — Add to backlog for later
+• /sf:todo {concern} — Add single item to backlog
 ```
 
 </workflow>

package/commands/sf/triage.md

@@ -0,0 +1,252 @@
+---
+name: sf:triage
+description: Convert scan findings into actionable TODO items
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<purpose>
+Review findings from the last codebase scan and selectively convert them to TODO items. This bridges the gap between scanning and planning — you see what was found and decide what to act on.
+</purpose>
+
+<context>
+@.specflow/SCAN.md
+@.specflow/todos/TODO.md
+</context>
+
+<arguments>
+- `[--all]` — Convert all findings without prompting (batch mode)
+- `[--priority=high|medium|low]` — Only show findings of specified priority
+</arguments>
+
+<workflow>
+
+## Step 1: Verify Prerequisites
+
+```bash
+[ -d .specflow ] && echo "INITIALIZED" || echo "NOT_INITIALIZED"
+[ -f .specflow/SCAN.md ] && echo "SCAN_EXISTS" || echo "NO_SCAN"
+```
+
+**If NOT_INITIALIZED:**
+```
+⚠️  Project not initialized
+
+Run /sf:init first.
+```
+STOP.
+
+**If NO_SCAN:**
+```
+⚠️  No scan results found
+
+Run /sf:scan first to analyze the codebase.
+```
+STOP.
+
+## Step 2: Parse SCAN.md
+
+Read `.specflow/SCAN.md` and extract findings:
+
+**Structure to parse:**
+- `## Tech Debt` → `### High Priority`, `### Medium Priority`, `### Low Priority`
+- `## Code Quality Issues`
+- `## Security Considerations`
+- `## Test Coverage Gaps`
+- `## Suggested Specifications`
+
+For each finding, extract:
+- Title (from `**[Title]**`)
+- Files affected
+- Problem description
+- Priority/Severity
+- Suggested fix
+
+## Step 3: Build Findings List
+
+Create structured list:
+
+```
+findings = [
+  {
+    id: 1,
+    category: "Tech Debt",
+    priority: "high",
+    title: "...",
+    files: ["..."],
+    problem: "...",
+    fix: "..."
+  },
+  ...
+]
+```
+
+**If --priority flag provided:**
+Filter to only matching priority.
+
+## Step 4: Display Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SCAN TRIAGE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scan date: {date from SCAN.md}
+
+Found {N} actionable items:
+  🔴 High:   {count}
+  🟡 Medium: {count}
+  🟢 Low:    {count}
+
+---
+```
+
+## Step 5: Interactive Selection (unless --all)
+
+**If --all flag:**
+Skip to Step 6, converting all findings.
+
+**Otherwise:**
+For each priority level (high first, then medium, then low):
+
+```
+🔴 HIGH PRIORITY ({count} items)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. {title}
+   Files: {files}
+   Problem: {problem}
+
+2. {title}
+   Files: {files}
+   Problem: {problem}
+
+---
+```
+
+Use AskUserQuestion:
+- header: "High Priority"
+- question: "Which items do you want to add to TODO list?"
+- multiSelect: true
+- options:
+  - "1. {title}" (for each item)
+  - "All high priority"
+  - "Skip high priority"
+
+Repeat for medium and low priority.
+
+## Step 6: Create TODO Items
+
+For each selected finding:
+
+### 6.1 Generate TODO ID
+
+```bash
+grep -oP 'TODO-\K\d+' .specflow/todos/TODO.md 2>/dev/null | sort -n | tail -1
+```
+
+### 6.2 Format TODO Entry
+
+```markdown
+## TODO-{XXX} — {YYYY-MM-DD}
+**Description:** {category}: {title}
+**Priority:** {high|medium|low}
+**Notes:**
+- Source: SCAN.md ({scan date})
+- Files: {files}
+- Problem: {problem}
+- Suggested fix: {fix}
+
+---
+```
+
+### 6.3 Append to TODO.md
+
+Ensure `.specflow/todos/` directory exists:
+```bash
+mkdir -p .specflow/todos
+```
+
+If TODO.md doesn't exist, create with header:
+```markdown
+# To-Do List
+
+---
+
+{new todo entries}
+
+---
+*Last updated: {YYYY-MM-DD}*
+```
+
+If TODO.md exists, insert new entries after `# To-Do List` line and update timestamp.
+
+## Step 7: Display Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TRIAGE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created {N} TODO items:
+
+  TODO-{XXX}: {title}
+  TODO-{XXX}: {title}
+  TODO-{XXX}: {title}
+
+Skipped: {M} items
+
+---
+
+**Actions:**
+- `/sf:todos` — view all to-do items
+- `/sf:priority` — prioritize backlog
+- `/sf:plan TODO-XXX` — convert to specification
+```
+
+</workflow>
+
+<output_format>
+
+**Success:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TRIAGE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created {N} TODO items from scan findings.
+
+[List of created TODOs]
+
+Next: /sf:priority or /sf:plan TODO-XXX
+```
+
+**No findings:**
+```
+✅ No actionable findings in SCAN.md
+
+The scan found no issues to triage. Codebase is healthy!
+```
+
+**All skipped:**
+```
+ℹ️  Triage complete — no items selected
+
+Run /sf:triage again to review findings.
+```
+
+</output_format>
+
+<success_criteria>
+- [ ] SCAN.md exists and is parsed
+- [ ] Findings extracted with priority levels
+- [ ] User shown summary of findings
+- [ ] Interactive selection completed (or --all used)
+- [ ] TODO items created with full context
+- [ ] Priority preserved from scan
+- [ ] Source reference included in notes
+- [ ] Clear summary of created TODOs
+</success_criteria>

package/package.json

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

package/templates/spec.md

@@ -81,6 +81,7 @@ Critical connections that must work correctly:
 
 - [What NOT to do]
 - [Boundaries and limitations]
+- Do not add SPEC-XXX, Phase X, or BUG-XX references in generated code comments
 
 ## Implementation Tasks