specflow-cc 1.17.1 → 1.18.1

package/commands/sf/migrate-todos.md

@@ -0,0 +1,252 @@
+---
+name: sf:migrate-todos
+description: One-time migration from monolithic TODO.md to per-file format
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<purpose>
+Migrate an existing monolithic `.specflow/todos/TODO.md` to the new per-file format where each TODO becomes an individual `.specflow/todos/TODO-XXX.md` file with YAML frontmatter.
+
+This is a one-time migration command. After migration:
+- `TODO.md` is renamed to `TODO.md.bak` (NOT deleted — safety net)
+- Each TODO becomes its own `TODO-XXX.md` file
+- `INDEX.md` is generated from the new files
+- All other commands will use the new per-file format automatically
+
+Use `--dry-run` to preview the migration without writing any files.
+</purpose>
+
+<arguments>
+- `[--dry-run]` — Preview migration without writing files. Shows what would be created.
+</arguments>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf:init` to start.
+```
+Exit.
+
+## Step 2: Check for Legacy TODO.md
+
+```bash
+[ -f .specflow/todos/TODO.md ] && echo "EXISTS" || echo "NO_TODO_MD"
+```
+
+**If NO_TODO_MD:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MIGRATE TODOS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No legacy TODO.md found at .specflow/todos/TODO.md.
+
+Nothing to migrate. If you already have per-file TODOs, run `/sf:todos` to view them.
+```
+Exit.
+
+## Step 3: Check for Existing Per-File TODOs
+
+```bash
+ls .specflow/todos/TODO-*.md 2>/dev/null | head -1
+```
+
+**If per-file TODOs already exist:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MIGRATE TODOS — WARNING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Found existing per-file TODO files alongside TODO.md.
+Migration may create duplicate IDs.
+
+Review existing files before continuing:
+  ls .specflow/todos/TODO-*.md
+
+Proceed anyway? (Use --dry-run first to check for conflicts)
+```
+
+Continue (do not abort — user may want to merge).
+
+## Step 4: Parse TODO.md
+
+Read `.specflow/todos/TODO.md` and extract all TODO blocks.
+
+Each block follows the pattern:
+```
+## TODO-XXX — YYYY-MM-DD
+**Description:** Short description
+**Priority:** high | medium | low | —
+**Notes:** Optional notes
+
+---
+```
+
+For each block, extract:
+- `id` — TODO-XXX
+- `created` — YYYY-MM-DD (from header)
+- `description` — from `**Description:**` line
+- `priority` — from `**Priority:**` line (normalize: strip whitespace, lowercase)
+- `notes` — from `**Notes:**` line (may be "—" or empty)
+
+**If no blocks found:**
+```
+TODO.md exists but contains no TODO blocks.
+
+Nothing to migrate. Renaming TODO.md to TODO.md.bak for safety.
+```
+Go to Step 7 (rename only).
+
+## Step 5: Preview Migration
+
+Display what will be created:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MIGRATE TODOS{If --dry-run: " — DRY RUN (no files written)"}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Found {N} TODO items in TODO.md:
+
+| ID       | Created    | Priority | Description (truncated) |
+|----------|------------|----------|-------------------------|
+| TODO-001 | 2024-01-10 | high     | Add caching for API...  |
+| TODO-003 | 2024-01-12 | medium   | Refactor AuthService... |
+| TODO-002 | 2024-01-11 | low      | Update documentation... |
+
+Will create:
+  .specflow/todos/TODO-001.md
+  .specflow/todos/TODO-002.md
+  .specflow/todos/TODO-003.md
+  .specflow/todos/INDEX.md
+
+Will rename:
+  TODO.md → TODO.md.bak
+```
+
+**If `--dry-run` flag:**
+```
+DRY RUN complete. No files were written.
+
+To run the actual migration: /sf:migrate-todos
+```
+Exit.
+
+## Step 6: Create Per-File TODOs
+
+For each parsed TODO block, create `.specflow/todos/TODO-{XXX}.md`:
+
+Derive `title` from description: first sentence (up to first `.`, `?`, or `!`), truncated to ~80 characters.
+
+```markdown
+---
+id: TODO-{XXX}
+title: "{derived title}"
+priority: {priority or —}
+complexity: —
+status: open
+effort: —
+depends_on: —
+created: {YYYY-MM-DD}
+---
+
+## Description
+
+{full description}
+
+## Notes
+
+{notes or "—"}
+```
+
+## Step 7: Generate INDEX.md
+
+Write `.specflow/todos/INDEX.md` with all migrated TODOs, sorted by priority then date:
+
+```markdown
+# To-Do Index
+
+> Auto-generated from individual TODO files. Do not edit manually.
+> Regenerate with `/sf:todos`.
+
+| # | ID | Title | Priority | Status | Created |
+|---|-----|-------|----------|--------|---------|
+{one row per TODO, sorted by priority then created date}
+
+**Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
+
+---
+*Last regenerated: {YYYY-MM-DD HH:MM}*
+```
+
+## Step 8: Rename Legacy TODO.md
+
+```bash
+mv .specflow/todos/TODO.md .specflow/todos/TODO.md.bak
+```
+
+**CRITICAL:** Do NOT delete TODO.md — rename to `.bak` for safety. The original data is preserved in case of migration issues.
+
+Verify:
+```bash
+[ -f .specflow/todos/TODO.md.bak ] && echo "RENAMED" || echo "RENAME_FAILED"
+```
+
+**If RENAME_FAILED:** Report error but continue (per-file TODOs are already created).
+
+## Step 9: Display Migration Summary
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MIGRATION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Migrated {N} TODOs from TODO.md to per-file format.
+
+**Created:**
+  {list of TODO-XXX.md files created}
+  .specflow/todos/INDEX.md
+
+**Renamed:**
+  TODO.md → TODO.md.bak (original preserved for safety)
+
+---
+
+**Actions:**
+- `/sf:todos` — view all to-do items
+- `/sf:priority` — set priorities
+- `/sf:plan TODO-XXX` — convert to specification
+
+**Cleanup:** Once you've verified the migration, you may delete TODO.md.bak:
+  rm .specflow/todos/TODO.md.bak
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Initialization verified
+- [ ] Legacy TODO.md existence checked
+- [ ] All TODO blocks parsed from TODO.md
+- [ ] `--dry-run` previews without writing files
+- [ ] Individual TODO-XXX.md files created for each block
+- [ ] Each file has valid YAML frontmatter (id, title, priority, status, created)
+- [ ] Title derived from description (first sentence, ~80 chars)
+- [ ] INDEX.md generated from migrated files
+- [ ] TODO.md renamed to TODO.md.bak (NOT deleted)
+- [ ] Clear migration summary shown
+- [ ] Cleanup instructions provided
+</success_criteria>

package/commands/sf/plan.md

@@ -17,7 +17,7 @@ Convert a to-do item from the backlog into a full specification. Reuses the spec
 </purpose>
 
 <context>
-@.specflow/todos/TODO.md
+@.specflow/todos/
 @.specflow/PROJECT.md
 @.specflow/STATE.md
 @~/.claude/specflow-cc/agents/spec-creator.md
@@ -46,10 +46,10 @@ Exit.
 ## Step 2: Check for Todos
 
 ```bash
-[ -f .specflow/todos/TODO.md ] && echo "EXISTS" || echo "NO_TODOS"
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo list --raw
 ```
 
-**If NO_TODOS:**
+**If empty output (no todos):**
 ```
 No to-do items found.
 
@@ -59,14 +59,16 @@ Exit.
 
 ## Step 3: Determine Target Todo
 
+Format detection is handled automatically by the CLI tool.
+
 **If argument is a number (e.g., "1", "2"):**
-Parse TODO.md, sort by priority, and select the Nth item.
+Run `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo list` to get sorted array, pick the Nth item (1-indexed).
 
 **If argument is TODO-XXX format:**
-Find todo with matching ID.
+The target ID is known directly.
 
 **If no argument:**
-Display todos and prompt:
+Run `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo list` and display todos, then prompt:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -86,13 +88,14 @@ Use AskUserQuestion with options as todo items.
 
 ## Step 4: Extract Todo Details
 
-Read the selected todo:
-- ID
-- Description
-- Priority
-- Notes (if any)
+Read `.specflow/todos/TODO-{XXX}.md` and parse frontmatter:
+- ID (from frontmatter `id:`)
+- Title (from frontmatter `title:`)
+- Description (from `## Description` body section)
+- Priority (from frontmatter `priority:`)
+- Notes (from `## Notes` body section, if any)
 
-**If todo not found:**
+**If todo file not found:**
 ```
 Todo "{arg}" not found.
 
@@ -148,18 +151,25 @@ Use the priority from the todo as the spec's initial priority.
 ", subagent_type="sf-spec-creator", model="{profile_model}", description="Create specification from todo")
 ```
 
-## Step 7: Remove Todo from List — CRITICAL
+## Step 7: Remove Todo File — CRITICAL
 
 **This step is MANDATORY. Do NOT skip it after the agent returns.**
 
-1. Read `.specflow/todos/TODO.md`
-2. Use the **Edit** tool (NOT Write) to remove the entire todo block (from `## TODO-XXX` heading through the next `---` separator, inclusive) — replace the block with empty string
-3. Use the **Edit** tool to update `*Last updated:` timestamp with note: `TODO-XXX converted to SPEC-YYY`
-4. **Verify** by reading TODO.md again — the converted todo MUST NOT appear
+1. Delete the file `.specflow/todos/TODO-{XXX}.md`:
+
+```bash
+rm .specflow/todos/TODO-{XXX}.md
+```
+
+2. **Verify** the file no longer exists:
+
+```bash
+[ ! -f .specflow/todos/TODO-{XXX}.md ] && echo "DELETED" || echo "STILL_EXISTS"
+```
 
-**CRITICAL:** Never rewrite the entire file with Write. Use Edit to remove the specific block and update the timestamp — this preserves all other todos.
+**If STILL_EXISTS:** try deletion again and verify.
 
-**Important:** Only remove after confirmed spec creation.
+**Important:** Only remove after confirmed spec creation. No "Last updated" lines to update.
 
 ## Step 8: Display Result
 
@@ -210,7 +220,7 @@ Consider `/sf:split SPEC-{YYY}` to decompose.
 
 ### Get Todo Details
 
-Read from TODO.md.
+Read `.specflow/todos/TODO-{XXX}.md` and parse frontmatter and body.
 
 ### Create Spec (same as /sf:new)
 
@@ -222,18 +232,19 @@ Use `/sf:new "{todo description}"` logic:
 
 ### Remove Todo
 
-Delete todo block from TODO.md.
+Delete the file `.specflow/todos/TODO-{XXX}.md`.
 
 </fallback>
 
 <success_criteria>
 - [ ] Initialization verified
-- [ ] TODO.md exists and has items
+- [ ] TODOs checked via CLI tool (format-agnostic)
 - [ ] Target todo identified (by ID or number)
-- [ ] Todo details extracted
+- [ ] Todo file read and details extracted (frontmatter + body)
 - [ ] Spec-creator agent spawned with context
 - [ ] SPEC-XXX.md created
 - [ ] Priority inherited from todo
-- [ ] Todo removed from TODO.md
+- [ ] TODO-XXX.md file deleted (not edited — whole file removed)
+- [ ] Deletion verified (file no longer exists)
 - [ ] Clear result with next step
 </success_criteria>

package/commands/sf/priority.md

@@ -16,7 +16,7 @@ Interactively prioritize specifications and to-do items. Allows reordering, sett
 
 <context>
 @.specflow/STATE.md
-@.specflow/todos/TODO.md
+@.specflow/todos/
 </context>
 
 <workflow>
@@ -51,9 +51,13 @@ For each spec, extract:
 
 ### Load Todos
 
-Read `.specflow/todos/TODO.md` and extract:
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo list
+```
+
+Extract from the JSON array:
 - ID
-- Description
+- Title
 - Priority
 
 ## Step 3: Display Current Prioritization
@@ -118,9 +122,10 @@ Your choice:
 If input matches pattern `{ID}={priority}`:
 
 1. Validate priority (high | medium | low)
-2. Update frontmatter in spec file OR use the **Edit** tool (NOT Write) to update the priority line in TODO.md — never rewrite the entire file
-3. Display confirmation
-4. Return to Step 3
+2. **If ID is a spec (SPEC-XXX):** Update `priority:` in frontmatter of `.specflow/specs/SPEC-XXX.md` using the Edit tool
+3. **If ID is a TODO (TODO-XXX):** Read `.specflow/todos/TODO-XXX.md`, update `priority:` line in frontmatter using the Edit tool
+4. Display confirmation
+5. Return to Step 3
 
 ### Reorder Specifications
 
@@ -192,12 +197,12 @@ Use `/sf:next` to work on highest priority task.
 <success_criteria>
 - [ ] Initialization verified
 - [ ] All specs loaded with current priorities
-- [ ] All todos loaded with current priorities
+- [ ] All todos loaded via CLI tool (format-agnostic)
 - [ ] Combined numbered list displayed
 - [ ] Set priority command works
 - [ ] Reorder command works
 - [ ] Technical order suggestion available
-- [ ] Changes persisted to files
+- [ ] TODO priority updated in individual file frontmatter (not TODO.md)
 - [ ] STATE.md Queue updated after spec reorder
 - [ ] Clear feedback on changes
 </success_criteria>

package/commands/sf/revise.md

@@ -474,14 +474,34 @@ NEXT_VERSION=$((RESPONSE_COUNT + 1))
 
 After recording the Response, if any items were marked "Deferred":
 
-1. Read `.specflow/todos/TODO.md` to find the highest existing TODO ID
-2. For each deferred item, create a new TODO entry:
-   - **Description:** `{item description} (deferred from {SPEC-XXX} audit v{N})`
-   - **Priority:** —
-   - **Notes:** `Origin: {SPEC-XXX} Response v{N}. {reason for deferral}`
+1. For each deferred item, generate next TODO ID:
+   ```bash
+   node ~/.claude/specflow-cc/bin/sf-tools.cjs todo next-id --raw
+   ```
+2. Create `.specflow/todos/TODO-{XXX}.md` for each deferred item:
+   ```markdown
+   ---
+   id: TODO-{XXX}
+   title: "{item description} (deferred from {SPEC-XXX} audit v{N})"
+   priority: —
+   complexity: —
+   status: open
+   effort: —
+   depends_on: —
+   created: {YYYY-MM-DD}
+   ---
+
+   ## Description
+
+   {item description} (deferred from {SPEC-XXX} audit v{N})
+
+   ## Notes
+
+   Origin: {SPEC-XXX} Response v{N}. {reason for deferral}
+   ```
 3. Append "**TODOs Created:**" subsection to the Response in Audit History listing created TODO IDs
 
-**This step is mandatory.** Every "Deferred" decision MUST produce a corresponding TODO.
+**This step is mandatory.** Every "Deferred" decision MUST produce a corresponding TODO-XXX.md file.
 
 ### Update Status
 
@@ -499,7 +519,7 @@ In STATE.md:
 - [ ] Revision scope determined (all/specific/custom)
 - [ ] Changes applied correctly
 - [ ] Response recorded in Audit History
-- [ ] Deferred items (if any) created as TODOs in `.specflow/todos/TODO.md`
+- [ ] Deferred items (if any) created as individual TODO-XXX.md files in `.specflow/todos/`
 - [ ] Spec frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes shown

package/commands/sf/status.md

@@ -57,8 +57,8 @@ TOTAL=$(ls .specflow/specs/SPEC-*.md 2>/dev/null | wc -l)
 # Completed specs
 DONE=$(ls .specflow/archive/SPEC-*.md 2>/dev/null | wc -l)
 
-# Pending todos
-TODOS=$(ls .specflow/todos/*.md 2>/dev/null | wc -l)
+# Pending todos (count TODO-*.md files, exclude INDEX.md)
+TODOS=$(ls .specflow/todos/TODO-*.md 2>/dev/null | wc -l)
 ```
 
 ## Step 4.5: Validate State Consistency

package/commands/sf/todo.md

@@ -4,17 +4,18 @@ description: Add a new to-do item for future work
 allowed-tools:
   - Read
   - Write
-  - Edit
   - Bash
   - AskUserQuestion
 ---
 
 <purpose>
 Add a new to-do item to the backlog. To-dos are ideas or tasks that don't need immediate specification but should be captured for later. They can later be converted to specifications with `/sf:plan`.
+
+Each TODO is stored as an individual file `.specflow/todos/TODO-XXX.md` with YAML frontmatter.
 </purpose>
 
 <context>
-@.specflow/todos/TODO.md
+@.specflow/todos/
 </context>
 
 <arguments>
@@ -56,53 +57,46 @@ Use AskUserQuestion:
 
 ## Step 4: Generate TODO ID
 
-Check existing TODO.md for highest ID:
+Run the CLI tool to get the next available ID:
 
 ```bash
-grep -oP 'TODO-\K\d+' .specflow/todos/TODO.md 2>/dev/null | sort -n | tail -1
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo next-id --raw
 ```
 
-If no existing todos, start with 001.
-Next ID = last + 1, zero-padded to 3 digits.
-
-## Step 5: Create or Update TODO.md
+This handles both per-file format (TODO-XXX.md) and legacy TODO.md automatically.
 
-**If TODO.md doesn't exist:**
-Create from template:
+## Step 5: Derive Title
 
-```markdown
-# To-Do List
+Extract the first sentence of the description (up to the first period, `?`, or `!`, or truncate at ~80 characters). This becomes the `title` field in frontmatter.
 
----
+## Step 6: Create TODO File
 
-## TODO-{XXX} — {YYYY-MM-DD}
-**Description:** {description}
-**Priority:** —
-**Notes:** —
+Create `.specflow/todos/TODO-{XXX}.md` using the Write tool:
 
+```markdown
+---
+id: TODO-{XXX}
+title: "{derived title}"
+priority: —
+complexity: —
+status: open
+effort: —
+depends_on: —
+created: {YYYY-MM-DD}
 ---
-*Last updated: {YYYY-MM-DD}*
-```
 
-**If TODO.md exists:**
-Use the **Edit** tool (NOT Write) to make two targeted edits:
+## Description
 
-1. Insert new todo block after the first `---` following `# To-Do List`:
+{description}
 
-```markdown
-## TODO-{XXX} — {YYYY-MM-DD}
-**Description:** {description}
-**Priority:** —
-**Notes:** —
+## Notes
 
----
+—
 ```
 
-2. Update the `*Last updated:` line at the bottom.
-
-**CRITICAL:** Never rewrite the entire file. Use Edit to insert the new block and update the timestamp — this preserves all existing todos.
+Do NOT create or modify TODO.md. Do NOT update any "Last updated" lines.
 
-## Step 6: Display Confirmation
+## Step 7: Display Confirmation
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
 
@@ -129,9 +123,9 @@ Use the **Edit** tool (NOT Write) to make two targeted edits:
 - [ ] Initialization verified
 - [ ] Todos directory exists
 - [ ] Description obtained (from arg or prompt)
-- [ ] Unique TODO-XXX ID generated
-- [ ] TODO.md created or updated
-- [ ] New todo added at top of list
-- [ ] Last updated timestamp refreshed
+- [ ] Unique TODO-XXX ID generated via CLI tool
+- [ ] Title derived from first sentence of description (~80 chars max)
+- [ ] TODO-XXX.md created with valid YAML frontmatter
+- [ ] All required frontmatter fields present (id, title, priority, complexity, status, effort, depends_on, created)
 - [ ] Clear confirmation and next actions shown
 </success_criteria>