specflow-cc 1.17.1 → 1.18.0

package/commands/sf/todos.md

@@ -3,17 +3,22 @@ name: sf:todos
 description: List all to-do items sorted by priority
 allowed-tools:
   - Read
+  - Write
   - Bash
 ---
 
 <purpose>
-Display all to-do items from the backlog, sorted by priority. Shows ID, description, priority, and creation date. Provides quick access to convert items to specifications.
+Display all to-do items from the backlog, sorted by priority. Reads individual TODO-XXX.md files (or legacy TODO.md for backward compatibility). Writes an auto-generated INDEX.md after display. Provides quick access to convert items to specifications.
 </purpose>
 
 <context>
-@.specflow/todos/TODO.md
+@.specflow/todos/
 </context>
 
+<arguments>
+- `[--all]` — Include TODOs with `status: eliminated` in the output (shown as visually distinct).
+</arguments>
+
 <workflow>
 
 ## Step 1: Verify Initialization
@@ -30,13 +35,30 @@ Run `/sf:init` to start.
 ```
 Exit.
 
-## Step 2: Check for TODO.md
+## Step 2: List TODOs via CLI Tool
+
+Call the CLI tool, which handles format detection automatically:
 
+**If `--all` flag was passed:**
 ```bash
-[ -f .specflow/todos/TODO.md ] && echo "EXISTS" || echo "NO_TODOS"
+node bin/sf-tools.cjs todo list --all
 ```
 
-**If NO_TODOS:**
+**Otherwise:**
+```bash
+node bin/sf-tools.cjs todo list
+```
+
+The tool returns a JSON array of `{ id, title, priority, status, complexity, created }` objects, sorted by priority (high > medium > low > unset), then by created date (oldest first).
+
+Format detection is handled by `cmdTodoList` in `bin/lib/todo.cjs`:
+1. If `TODO-*.md` files exist in `.specflow/todos/` — uses per-file format
+2. If no per-file TODOs but `TODO.md` exists — uses legacy format
+3. If neither — returns empty list
+
+## Step 3: Handle Empty Result
+
+**If the list is empty:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  TO-DO LIST
@@ -47,41 +69,16 @@ No to-do items found.
 Add your first idea:
 `/sf:todo "your idea here"`
 ```
-Exit.
-
-## Step 3: Parse TODO.md
+Exit (skip INDEX.md regeneration).
 
-Read `.specflow/todos/TODO.md` and extract each todo block:
-- ID (TODO-XXX)
-- Date (from header)
-- Description
-- Priority (high | medium | low | —)
-- Notes (optional)
-
-Look for pattern:
-```
-## TODO-XXX — YYYY-MM-DD
-**Description:** ...
-**Priority:** ...
-**Notes:** ...
-```
+## Step 4: Count Statistics
 
-## Step 4: Sort by Priority
+From the list:
+- Total count
+- Count by priority (high, medium, low, unset/—)
+- If `--all`: note how many are `status: eliminated`
 
-Sort todos:
-1. high
-2. medium
-3. low
-4. — (unset)
-
-Within same priority, sort by date (oldest first).
-
-## Step 5: Count Statistics
-
-- Total todos
-- By priority (high, medium, low, unset)
-
-## Step 6: Display List
+## Step 5: Display List
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
 
@@ -90,14 +87,16 @@ Within same priority, sort by date (oldest first).
  TO-DO LIST
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-| #  | ID       | Description              | Priority | Created    |
-|----|----------|--------------------------|----------|------------|
-| 1  | TODO-001 | Add caching for API      | high     | 2024-01-10 |
-| 2  | TODO-003 | Refactor AuthService     | medium   | 2024-01-12 |
-| 3  | TODO-002 | Update documentation     | low      | 2024-01-11 |
-| 4  | TODO-004 | Research WebSocket       | —        | 2024-01-13 |
+| #  | ID       | Title                    | Priority | Status  | Created    |
+|----|----------|--------------------------|----------|---------|------------|
+| 1  | TODO-001 | Add caching for API      | high     | open    | 2024-01-10 |
+| 2  | TODO-003 | Refactor AuthService     | medium   | open    | 2024-01-12 |
+| 3  | TODO-002 | Update documentation     | low      | open    | 2024-01-11 |
+| 4  | TODO-004 | Research WebSocket       | —        | open    | 2024-01-13 |
+{If --all: show eliminated items with [eliminated] marker in Status column}
 
 **Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
+{If --all and eliminated exist: (+ {M} eliminated shown)}
 
 ---
 
@@ -108,28 +107,41 @@ Within same priority, sort by date (oldest first).
 - `/sf:todo "new idea"` — add new item
 ```
 
-## Step 7: Show Notes (if any have notes)
+## Step 6: Regenerate INDEX.md
 
-If any todo has non-empty notes:
+After displaying the list, write `.specflow/todos/INDEX.md` using the Write tool.
 
-```
----
+Use the format from `templates/todo-index.md`:
 
-**Notes:**
+```markdown
+# To-Do Index
 
-**TODO-001:** Consider Redis or in-memory
-**TODO-003:** Split into smaller services first
+> Auto-generated from individual TODO files. Do not edit manually.
+> Regenerate with `/sf:todos`.
+
+| # | ID | Title | Priority | Status | Created |
+|---|-----|-------|----------|--------|---------|
+{rows from sorted list — one row per TODO}
+
+**Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
+
+---
+*Last regenerated: {YYYY-MM-DD HH:MM}*
 ```
 
+**Important:** INDEX.md is a display cache only. Never edit it manually — it is regenerated here each time `/sf:todos` runs.
+
 </workflow>
 
 <success_criteria>
 - [ ] Initialization verified
-- [ ] TODO.md parsed if exists
-- [ ] All todos extracted with ID, description, priority, date
-- [ ] Sorted by priority then date
-- [ ] Numbered list displayed (# column for easy reference)
-- [ ] Statistics shown
+- [ ] TODOs listed via `node bin/sf-tools.cjs todo list` (format-agnostic)
+- [ ] Empty state handled with helpful message
+- [ ] Sorted by priority then date (oldest first within same priority)
+- [ ] Numbered list displayed with Status column
+- [ ] `--all` flag shows eliminated items visually distinct
+- [ ] Statistics shown (total, by priority)
 - [ ] Clear actions provided
-- [ ] Notes shown if present
+- [ ] INDEX.md written to `.specflow/todos/INDEX.md` after display
+- [ ] INDEX.md contains "Do not edit manually" notice
 </success_criteria>

package/commands/sf/triage.md

@@ -15,7 +15,7 @@ Review findings from the last codebase scan and selectively convert them to TODO
 
 <context>
 @.specflow/SCAN.md
-@.specflow/todos/TODO.md
+@.specflow/todos/
 </context>
 
 <arguments>
@@ -146,48 +146,47 @@ 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
+node bin/sf-tools.cjs todo next-id --raw
 ```
 
-### 6.2 Format TODO Entry
+This handles both per-file format and legacy TODO.md automatically (uses Node.js fs/regex — not grep -oP).
 
-```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
+### 6.2 Create TODO File
 
 Ensure `.specflow/todos/` directory exists:
 ```bash
 mkdir -p .specflow/todos
 ```
 
-If TODO.md doesn't exist, create with header:
-```markdown
-# To-Do List
+Create `.specflow/todos/TODO-{XXX}.md` using the Write tool:
 
+```markdown
+---
+id: TODO-{XXX}
+title: "{category}: {title}"
+priority: {high|medium|low}
+complexity: —
+status: open
+effort: —
+depends_on: —
+created: {YYYY-MM-DD}
 ---
 
-{new todo entries}
+## Description
 
----
-*Last updated: {YYYY-MM-DD}*
-```
+{category}: {title}
+
+{problem description}
+
+## Notes
 
-If TODO.md exists, use the **Edit** tool (NOT Write) to make two targeted edits:
-1. Insert new entries after the first `---` following `# To-Do List`
-2. Update the `*Last updated:` timestamp
+- Source: SCAN.md ({scan date})
+- Files: {files affected}
+- Problem: {problem}
+- Suggested fix: {fix}
+```
 
-**CRITICAL:** Never rewrite the entire file with Write. Use Edit to insert new blocks and update the timestamp — this preserves all existing todos.
+Do NOT append to TODO.md. Do NOT update any "Last updated" lines. Each finding gets its own separate TODO-XXX.md file.
 
 ## Step 7: Display Results
 
@@ -252,8 +251,9 @@ Run /sf:triage again to review findings.
 - [ ] Findings extracted with priority levels
 - [ ] User shown summary of findings
 - [ ] Interactive selection completed (or --all used)
-- [ ] TODO items created with full context
+- [ ] Individual TODO-XXX.md files created (one per finding)
+- [ ] Each file has valid YAML frontmatter (id, title, priority, status, created)
 - [ ] Priority preserved from scan
-- [ ] Source reference included in notes
+- [ ] Source reference included in notes (scan date, files, problem)
 - [ ] Clear summary of created TODOs
 </success_criteria>

package/package.json

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

package/templates/todo-file.md

@@ -0,0 +1,18 @@
+---
+id: TODO-XXX
+title: "Short title"
+priority: —
+complexity: —
+status: open
+effort: —
+depends_on: —
+created: YYYY-MM-DD
+---
+
+## Description
+
+{description}
+
+## Notes
+
+{notes or "—"}

package/templates/todo-index.md

@@ -0,0 +1,13 @@
+# To-Do Index
+
+> Auto-generated from individual TODO files. Do not edit manually.
+> Regenerate with `/sf:todos`.
+
+| # | ID | Title | Priority | Status | Created |
+|---|-----|-------|----------|--------|---------|
+{rows sorted by priority then date}
+
+**Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
+
+---
+*Last regenerated: {YYYY-MM-DD HH:MM}*

package/templates/todo.md

@@ -1,15 +0,0 @@
-# To-Do List
-
-<!--
-  Format for each todo:
-
-  ## TODO-XXX — YYYY-MM-DD
-  **Description:** Short description
-  **Priority:** high | medium | low | —
-  **Notes:** Optional notes
-
-  ---
--->
-
----
-*Last updated: [date]*