specflow-cc 1.18.3 → 1.20.0

package/commands/sf/revise.md

@@ -1,6 +1,7 @@
 ---
 name: sf:revise
 description: Revise specification based on audit feedback
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -37,17 +38,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided; strip non-SPEC-ID args first).
 
-**If no active specification:**
-```
-No active specification to revise.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to revise.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to revise?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -508,8 +519,9 @@ After recording the Response, if any items were marked "Deferred":
 In spec frontmatter: `status: auditing`
 
 In STATE.md:
-- Status → "auditing"
-- Next Step → "/sf:audit"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
+```
 
 </fallback>
 

package/commands/sf/run.md

@@ -1,6 +1,7 @@
 ---
 name: sf:run
 description: Execute the specification (implement the code)
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -39,17 +40,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to execute.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to execute.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to run?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -182,9 +193,9 @@ Use model for `spec-executor` or `spec-executor-orchestrator` from selected prof
 
 ## Step 7: Update Status
 
-Update STATE.md:
-- Status → "running"
-- Next Step → "(in progress)"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX running "(in progress)"
+```
 
 Update spec frontmatter:
 - status → "running"

package/commands/sf/show.md

@@ -1,6 +1,7 @@
 ---
 name: sf:show
 description: Display full specification details
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve when no arg
 allowed-tools:
   - Read
   - Bash
@@ -41,16 +42,22 @@ Exit.
 Use provided ID (e.g., SPEC-003).
 
 **If no argument:**
-Read `.specflow/STATE.md` and get Active Specification.
-
-**If no active specification and no argument:**
-```
-No specification specified and no active specification.
-
-Use `/sf:show SPEC-XXX` to view a specific spec
-or `/sf:list` to see all specifications.
-```
-Exit.
+Call `node bin/sf-tools.cjs state resolve` to get active spec.
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No specification specified and no active specification.
+
+  Use `/sf:show SPEC-XXX` to view a specific spec
+  or `/sf:list` to see all specifications.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to show?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Find Specification File
 

package/commands/sf/split.md

@@ -1,6 +1,7 @@
 ---
 name: sf:split
 description: Split a large specification into smaller sub-specifications
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve when no arg
 allowed-tools:
   - Read
   - Write
@@ -57,18 +58,22 @@ Use `/sf:list` to see available specifications.
 Exit.
 
 **If no ID provided:**
-Read active specification from `.specflow/STATE.md`:
-- Parse "Active Specification" field
-- Use that ID
-
-**If no active specification:**
-```
-No specification specified and no active specification.
-
-Usage: `/sf:split SPEC-001`
-   or: Set active spec with `/sf:show SPEC-001`
-```
-Exit.
+Call `node bin/sf-tools.cjs state resolve` to get active spec.
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → use SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No specification specified and no active specification.
+
+  Usage: `/sf:split SPEC-001`
+     or: Set active spec with `/sf:show SPEC-001`
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to split?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Check Complexity
 
@@ -356,9 +361,13 @@ Add split reference to archived parent.
 
 ### Update STATE.md
 
-- Remove parent from Queue
-- Add children to Queue
-- Set first child as Active Specification
+- Remove parent from Queue (using Read+Write)
+- Add children to Queue (using Read+Write)
+- Register first child in Active Specifications table:
+  ```bash
+  node bin/sf-tools.cjs state remove-active SPEC-PARENT
+  node bin/sf-tools.cjs state add-active SPEC-XXXa draft /sf:audit
+  ```
 
 </fallback>
 

package/commands/sf/status.md

@@ -1,6 +1,7 @@
 ---
 name: sf:status
 description: Show current SpecFlow state and recommended next step
+# SPEC-011: Uses state list-active and state resolve for multi-spec awareness
 allowed-tools:
   - Read
   - Bash
@@ -34,13 +35,22 @@ Exit.
 
 ## Step 2: Load State
 
-Read `.specflow/STATE.md` and extract:
-- Active Specification
-- Status
-- Next Step
-- Queue
-- Recent Decisions
-- Warnings
+Read `.specflow/STATE.md` and extract Queue, Recent Decisions, Warnings.
+
+Get active specs:
+```bash
+node bin/sf-tools.cjs state list-active
+```
+
+For single-spec display, also call:
+```bash
+node bin/sf-tools.cjs state resolve
+```
+
+Parse the resolve response:
+- `{"action":"use","id":"SPEC-XXX"}` → show single active spec
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → show idle state
+- `{"action":"ask","options":[...]}` → show all active specs in table format
 
 ## Step 3: Load Project Info
 
@@ -77,10 +87,10 @@ for f in .specflow/specs/SPEC-*.md; do
 done
 ```
 
-**If STATE.md shows "Active Specification: None" but specs exist in specs/:**
+**If the Active Specifications table is empty (no rows) but specs exist in specs/:**
 Add warning:
 ```
-STATE MISMATCH: Found {N} spec(s) in specs/ but STATE.md shows no active spec.
+STATE MISMATCH: Found {N} spec(s) in specs/ but the Active Specifications table is empty.
 Likely cause: STATE.md was not updated after spec creation.
 Run: Read the spec file and manually update STATE.md, or delete orphan spec if duplicate.
 ```

package/commands/sf/todo.md

@@ -96,6 +96,12 @@ created: {YYYY-MM-DD}
 
 Do NOT create or modify TODO.md. Do NOT update any "Last updated" lines.
 
+## Step 6.5: Reindex
+
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
 ## Step 7: Display Confirmation
 
 **IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:

package/commands/sf/verify.md

@@ -1,6 +1,7 @@
 ---
 name: sf:verify
 description: Interactive human verification of acceptance criteria
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -33,17 +34,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
-
-Read `.specflow/STATE.md` and extract Active Specification.
-
-**If no active specification:**
-```
-No active specification to verify.
-
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+## Step 2: Resolve Active Specification
+
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
+
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to verify.
+
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to verify?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 

package/package.json

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

package/templates/state.md

@@ -2,11 +2,13 @@
 
 <!-- This file is kept compact (<100 lines). Old decisions are automatically rotated to DECISIONS_ARCHIVE.md. -->
 
-## Current Position
+## Active Specifications
 
-- **Active Specification:** [none | SPEC-XXX]
-- **Status:** [idle | drafting | auditing | revision_requested | external_review | running | reviewing]
-- **Next Step:** [/sf:new | /sf:audit | /sf:revise | /sf:run | /sf:review | /sf:done]
+<!-- Multi-spec registry. Zero rows = no active specs. One row = single-spec ergonomics (no prompt). -->
+<!-- Multiple rows = resolver emits AskUserQuestion picker when no SPEC-ID argument provided. -->
+
+| SPEC-ID | Status | Next Step |
+|---------|--------|-----------|
 
 ## Queue