specflow-cc 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.13.0] - 2026-02-11
+
+### Added
+
+- **Autopilot mode** (`/sf:autopilot`) — run the full spec lifecycle autonomously
+  - Single spec: `/sf:autopilot` or `/sf:autopilot SPEC-XXX`
+  - Batch mode: `/sf:autopilot --all` processes entire queue sequentially
+  - Cycle detection: configurable limits for audit (default: 3) and fix (default: 3) cycles
+  - Graceful halt on `needs_decomposition` or `paused` specs
+  - Summary report with per-spec outcomes and cycle counts
+  - Agent failure handling: continues batch on single-spec failure
+  - Configurable via `.specflow/config.json` under `"autopilot"` key
+
+### Changed
+
+- **Replaced all Bash/awk/sed markdown mutations** with Read+Write tool instructions across 13 agent and command files
+  - Eliminates fragile shell-based file editing that could corrupt markdown structure
+  - All STATE.md, spec, and archive updates now use explicit Read→Write pattern
+  - Affected: spec-creator, spec-auditor, spec-reviser, spec-splitter, spec-executor, spec-executor-orchestrator, impl-reviewer, and 6 command files
+
+- `/sf:help` — added Autonomous Execution section with autopilot commands
+- README — added autopilot to workflow diagram, commands table, and typical session
+
+---
+
 ## [1.12.0] - 2026-02-10
 
 ### Added

package/README.md

@@ -241,6 +241,8 @@ Your spec becomes documentation: why the code exists, what decisions were made,
               ↓                          ↓              ↓
          /sf:revise                  /sf:fix      (optional UAT)
          (if needed)                 (if needed)
+
+         /sf:autopilot — runs the entire flow above automatically
 ```
 
 **Key principle:** Audits and reviews run in fresh context — no bias from creation.
@@ -312,6 +314,7 @@ Six months later, you can read the spec and understand not just *what* was built
 | `/sf:fix` | Fix based on review feedback |
 | `/sf:verify` | Interactive user acceptance testing |
 | `/sf:done` | Complete and archive |
+| `/sf:autopilot` | Run full lifecycle autonomously |
 
 **Quick mode:**
 
@@ -455,6 +458,10 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 /sf:review                               # Fresh context review
 /sf:verify                               # Manual verification
 /sf:done                                 # Archive
+
+# Or skip manual steps — run everything autonomously
+/sf:autopilot                            # Process active spec end-to-end
+/sf:autopilot --all                      # Process entire queue
 ```
 
 ---

package/agents/impl-reviewer.md

@@ -288,6 +288,14 @@ Append to specification's Review History:
 - If APPROVED: Status → "done", Next Step → "/sf:done"
 - If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/agents/sf-spec-executor-orchestrator.md

@@ -389,6 +389,14 @@ Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-auditor.md

@@ -685,6 +685,14 @@ Update status:
 - If NEEDS_DECOMPOSITION: Status → "needs_decomposition", Next Step → "/sf:split or /sf:run --parallel"
 - If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf:revise"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/agents/spec-creator.md

@@ -241,6 +241,16 @@ Update `.specflow/STATE.md`:
 - Set Next Step to "/sf:audit"
 - Add spec to Queue
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Active Specification:**" line changed to the new spec
+- "**Status:**" line changed to "drafting"
+- "**Next Step:**" line changed to "/sf:audit"
+- Queue table updated with new spec entry
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **If `<prior_discussion>` provided:**
 Update the discussion file (PRE-XXX.md or DISC-XXX.md):
 - Set `used_by: SPEC-XXX` in frontmatter

package/agents/spec-executor-orchestrator.md

@@ -330,6 +330,10 @@ Write `.specflow/execution/SPEC-XXX-state.json`:
 | SPEC-XXX | orchestrated | Wave 0/{total} (0%) | {timestamp} |
 ```
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row added/updated.
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 ## Step 3: Execute Waves
 
 For each wave:
@@ -597,6 +601,10 @@ After wave completes (all groups done):
 | SPEC-XXX | orchestrated | Wave 2/{total} (67%) | {timestamp} |
 ```
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row updated for this wave.
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 ## Step 4: Aggregate Results
 
 Combine all worker results:
@@ -683,6 +691,10 @@ rm .specflow/execution/SPEC-XXX-state.json
 - Change row to show "Complete" or remove row entirely
 - Or archive: `mv .specflow/execution/SPEC-XXX-state.json .specflow/execution/archive/`
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row removed or updated to "Complete".
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **Note:** Only delete on FULL success. If any groups failed or are partial, keep state file for potential retry.
 
 ## Step 7: Update STATE.md
@@ -692,6 +704,15 @@ Update ONLY the Current Position section:
 - Next Step → "/sf:review"
 - Remove or update Execution Status row
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- Execution Status row removed or updated
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-executor.md

@@ -268,6 +268,14 @@ Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-reviser.md

@@ -139,6 +139,14 @@ Set status to "auditing" (ready for re-audit).
 - Status → "auditing"
 - Next Step → "/sf:audit"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/agents/spec-splitter.md

@@ -188,6 +188,16 @@ Update `.specflow/STATE.md`:
 - Set first child (no dependencies) as Active Specification
 - Add note to Decisions: "Split SPEC-XXX into N parts"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- Parent spec removed from Queue table
+- All child specs added to Queue table in dependency order
+- First child (no dependencies) set as Active Specification
+- Decisions section updated with split note
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/commands/sf/audit.md

@@ -242,75 +242,17 @@ The agent will:
 
 After the agent updates STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 7: Display Result
 

package/commands/sf/autopilot.md

@@ -0,0 +1,601 @@
+---
+name: sf:autopilot
+description: Run full spec lifecycle autonomously (audit -> run -> review -> done)
+argument-hint: "[SPEC-XXX] [--all]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<purpose>
+Run the full specification lifecycle autonomously. Reads STATE.md to determine current phase, spawns appropriate agents, advances through audit -> revise -> run -> review -> fix -> done cycle without manual intervention. Includes cycle-detection safeguards to prevent infinite loops.
+</purpose>
+
+<context>
+@.specflow/STATE.md
+@.specflow/specs/SPEC-*.md
+@.specflow/config.json
+</context>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized.
+
+Run `/sf:init` first.
+```
+Exit.
+
+## Step 2: Parse Arguments and Determine Mode
+
+Parse the command argument to determine execution mode:
+
+| Argument | Mode | Behavior |
+|----------|------|----------|
+| (none) | single | Process the active spec in STATE.md |
+| `SPEC-XXX` | single | Set SPEC-XXX as active, then process it |
+| `--all` | batch | Process all actionable specs in Queue order |
+
+**If single mode:**
+- If SPEC-XXX argument provided: update STATE.md to set it as active spec
+- If no argument and no active spec exists: display error and exit
+
+**If batch mode (--all):**
+- Identify all actionable specs from Queue (any spec with status: draft, auditing, revision_requested, audited, running, review)
+
+**Error case (single mode, no active, no argument):**
+```
+No active specification to process.
+
+Provide a spec ID: `/sf:autopilot SPEC-XXX`
+Or run on all specs: `/sf:autopilot --all`
+```
+Exit.
+
+## Step 3: Set Configuration Constants
+
+Read `.specflow/config.json` for autopilot configuration:
+
+```bash
+[ -f .specflow/config.json ] && cat .specflow/config.json
+```
+
+Parse the `"autopilot"` section if it exists:
+
+```json
+{
+  "autopilot": {
+    "max_audit_cycles": 3,
+    "max_fix_cycles": 3
+  }
+}
+```
+
+**Configuration constants:**
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| MAX_AUDIT_CYCLES | 3 | Max audit->revise iterations before halt |
+| MAX_FIX_CYCLES | 3 | Max review->fix iterations before halt |
+
+If config file doesn't exist or autopilot section is missing, use defaults.
+
+## Step 4: Initialize Tracking State
+
+Initialize per-spec tracking variables (maintained in command memory, not persisted to files):
+
+```
+audit_cycles = 0
+fix_cycles = 0
+specs_processed = []   (batch mode)
+specs_failed = []      (batch mode)
+current_spec = null
+```
+
+## Step 5: Main Loop (per spec)
+
+### 5.1 Load Current Spec State
+
+Read `.specflow/STATE.md` to get active specification.
+Read `.specflow/specs/SPEC-XXX.md` to get frontmatter status.
+
+### 5.2 Determine Current Phase
+
+Based on spec status, determine the phase and action:
+
+| Spec Status | Phase | Action |
+|-------------|-------|--------|
+| `draft` | audit | Spawn spec-auditor agent |
+| `auditing` | audit | Spawn spec-auditor agent |
+| `revision_requested` | revise | Spawn spec-reviser agent with scope "all" |
+| `audited` | run | Spawn spec-executor or spec-executor-orchestrator agent |
+| `running` | run | Spawn spec-executor or spec-executor-orchestrator agent |
+| `review` | review-or-fix | Check for latest review result (see 5.3) |
+| `needs_decomposition` | halt | Halt with decomposition message |
+| `paused` | halt | Halt with paused message |
+| `done` | done | Run done logic (archive, update STATE.md) |
+
+**Halt messages:**
+
+**If `needs_decomposition`:**
+```
+Spec SPEC-XXX requires decomposition.
+
+Run `/sf:split` manually, then restart autopilot.
+```
+Record as failed in batch mode. Exit in single mode.
+
+**If `paused`:**
+```
+Spec SPEC-XXX is paused.
+
+Resume with `/sf:resume` first.
+```
+Record as failed in batch mode. Exit in single mode.
+
+### 5.3 Review Phase Logic
+
+When spec status is `review`, inspect the Review History section:
+
+**If no review exists yet OR last review entry is a Fix Response:**
+- Spawn impl-reviewer agent
+
+**If last review entry is APPROVED:**
+- Proceed to done phase (5.5)
+
+**If last review entry is CHANGES_REQUESTED:**
+- Spawn spec-executor in fix mode with scope "all"
+
+### 5.4 Spawn Agent for Phase
+
+Spawn the appropriate agent based on phase (see Step 6 for details).
+
+Include `<autopilot>true</autopilot>` context tag in all Task prompts.
+
+**Agent spawning example:**
+
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+
+Execute this specification following the spec-executor agent instructions.
+Implement all requirements with atomic commits.
+", subagent_type="sf-spec-executor", model="{profile_model}", description="Execute specification (autopilot mode)")
+```
+
+### 5.5 After Agent Completes
+
+1. **Re-read STATE.md and spec file** to get updated status
+2. **Check STATE.md size and rotate if needed:**
+   - Use Read tool to read `.specflow/STATE.md` and count total lines
+   - If total lines <= 100, no action needed
+   - If total lines > 100:
+     a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+     b. Count decision rows. If <= 7, no rotation needed
+     c. If > 7 decisions:
+        - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+        - Identify older decisions (all rows except last 5) -- these MOVE to archive
+        - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+        - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+        - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
+
+3. **Increment cycle counters:**
+   - If just completed revise phase: `audit_cycles++`
+   - If just completed fix phase: `fix_cycles++`
+
+4. **Check cycle limits:**
+   - If `audit_cycles >= MAX_AUDIT_CYCLES`: HALT with "Audit cycle limit reached (3/3)"
+   - If `fix_cycles >= MAX_FIX_CYCLES`: HALT with "Fix cycle limit reached (3/3)"
+
+5. **Reset cycle counters when transitioning between major phases:**
+   - If spec transitions from audit/revise phase to run phase (status becomes "audited"): `audit_cycles = 0`
+   - If spec enters review/fix phase (status becomes "review"): `fix_cycles = 0`
+
+6. **Loop back to 5.2** with the updated status
+
+**Halt behavior when cycle limit reached:**
+1. Leave the spec in its current state in STATE.md (do not archive, do not clear active)
+2. Record as failed in specs_failed list with reason "Audit cycle limit (3/3)" or "Fix cycle limit (3/3)"
+3. In batch mode: attempt next spec in queue (do not abort the entire batch)
+4. In single mode: proceed directly to summary report (Step 9)
+
+### 5.6 Done Phase (inline)
+
+When spec reaches done status OR last review is APPROVED, execute the done logic inline:
+
+1. **Create archive directory:**
+```bash
+mkdir -p .specflow/archive
+```
+
+2. **Update spec frontmatter:**
+   - status → "done"
+   - Add Completion section with timestamp and commit/review counts
+
+```markdown
+---
+
+## Completion
+
+**Completed:** {date} {time}
+**Total Commits:** {count from Execution Summary}
+**Review Cycles:** {count of Review v[N] entries}
+```
+
+3. **Extract decisions:**
+   - Scan specification for technology choices mentioned in Context or Assumptions
+   - Scan for patterns established during implementation
+   - If significant decisions found, add to STATE.md Decisions table:
+   ```markdown
+   | {date} | SPEC-XXX | {decision description} |
+   ```
+
+4. **Archive specification:**
+```bash
+mv .specflow/specs/SPEC-XXX.md .specflow/archive/
+```
+
+5. **Update STATE.md:**
+   - Active Specification → "none"
+   - Status → "idle"
+   - Next Step → "/sf:new or /sf:next"
+   - Remove SPEC-XXX row from Queue table
+
+6. **Check STATE.md size and rotate** (same logic as 5.5 step 2)
+
+7. **Create final commit:**
+```bash
+git add .specflow/
+git commit -m "docs(sf): complete SPEC-XXX"
+```
+
+8. **Record completion:**
+   - In batch mode: add to specs_processed list with outcome "COMPLETED"
+
+## Step 6: Agent Spawning Details
+
+For each phase, determine the agent type and model profile:
+
+| Phase | Agent | Subagent Type | Auto-Resolution |
+|-------|-------|---------------|-----------------|
+| audit | spec-auditor | sf-spec-auditor | N/A (no interactive prompts) |
+| revise | spec-reviser | sf-spec-reviser | scope = "all" |
+| run | spec-executor or spec-executor-orchestrator | sf-spec-executor / sf-spec-executor-orchestrator | Skip audit-status warning (proceed anyway) |
+| review | impl-reviewer | sf-impl-reviewer | N/A (no interactive prompts) |
+| fix | spec-executor (fix mode) | sf-spec-executor | scope = "all" |
+| done | (inline logic) | N/A | Skip review/verify warnings (proceed anyway) |
+
+### 6.1 Determine Model Profile
+
+Check `.specflow/config.json` for model profile setting:
+
+```bash
+[ -f .specflow/config.json ] && cat .specflow/config.json | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4 || echo "balanced"
+```
+
+**Profile Table:**
+
+| Profile | spec-auditor | spec-reviser | spec-executor | spec-executor-orchestrator | spec-executor-worker | impl-reviewer |
+|---------|--------------|--------------|---------------|---------------------------|---------------------|---------------|
+| max | opus | opus | opus | opus | opus | opus |
+| quality | opus | sonnet | opus | opus | opus | sonnet |
+| balanced | opus | sonnet | sonnet | sonnet | sonnet | sonnet |
+| budget | sonnet | sonnet | sonnet | sonnet | sonnet | haiku |
+
+### 6.2 Determine Execution Mode (run phase)
+
+When spawning execution agent, check specification complexity:
+
+**If `## Implementation Tasks` section exists in spec:**
+- Count task groups (G1, G2, G3, etc.)
+- Check for parallel opportunities (groups with no dependencies on each other)
+- If groups > 1 AND parallelism exists → use `spec-executor-orchestrator`
+- Otherwise → use `spec-executor`
+
+**If no Implementation Tasks section:**
+- Use `spec-executor`
+
+### 6.3 Agent Prompts
+
+**Audit phase (spec-auditor):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+
+Audit this specification following the spec-auditor agent instructions.
+Check for completeness, clarity, feasibility, and alignment with project patterns.
+", subagent_type="sf-spec-auditor", model="{profile_model}", description="Audit specification (autopilot mode)")
+```
+
+**Revise phase (spec-reviser):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+<scope>all</scope>
+
+Revise this specification to address ALL audit findings.
+Follow the spec-reviser agent instructions.
+", subagent_type="sf-spec-reviser", model="{profile_model}", description="Revise specification (autopilot mode)")
+```
+
+**Run phase (spec-executor):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+
+Execute this specification following the spec-executor agent instructions.
+Implement all requirements with atomic commits.
+Proceed even if audit status is not 'audited'.
+", subagent_type="sf-spec-executor", model="{profile_model}", description="Execute specification (autopilot mode)")
+```
+
+**Run phase (spec-executor-orchestrator):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+
+Orchestrate execution of this large specification.
+Parse task groups from Implementation Tasks section.
+Determine execution waves based on dependencies.
+Spawn worker subagents in parallel where possible.
+Proceed even if audit status is not 'audited'.
+", subagent_type="sf-spec-executor-orchestrator", model="{profile_model}", description="Orchestrate specification execution (autopilot mode)")
+```
+
+**Review phase (impl-reviewer):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+
+Review the implementation against the specification.
+Follow the impl-reviewer agent instructions.
+", subagent_type="sf-impl-reviewer", model="{profile_model}", description="Review implementation (autopilot mode)")
+```
+
+**Fix phase (spec-executor):**
+```
+Task(prompt="
+<specification>
+@.specflow/specs/SPEC-XXX.md
+</specification>
+
+<project_context>
+@.specflow/PROJECT.md
+</project_context>
+
+<autopilot>true</autopilot>
+<mode>fix</mode>
+<scope>all</scope>
+
+Fix ALL issues identified in the latest review.
+Follow the spec-executor agent instructions in fix mode.
+", subagent_type="sf-spec-executor", model="{profile_model}", description="Fix implementation issues (autopilot mode)")
+```
+
+## Step 7: Batch Mode — Advance to Next Spec
+
+If `--all` mode (batch execution):
+
+1. **Record completed spec** in specs_processed list:
+   - Spec ID
+   - Title
+   - Outcome (COMPLETED or reason for failure)
+   - Audit cycles used
+   - Fix cycles used
+
+2. **Read STATE.md Queue** for next actionable spec:
+   - First spec in Queue by Priority that has an actionable status
+   - Actionable statuses: draft, auditing, revision_requested, audited, running, review
+
+3. **If next spec found:**
+   - Update STATE.md active spec to the next spec
+   - Reset cycle counters: `audit_cycles = 0`, `fix_cycles = 0`
+   - Loop to Step 5
+
+4. **If no more actionable specs:**
+   - Proceed to Step 9 (summary report)
+
+## Step 8: Handle Agent Failures
+
+If a Task agent fails to spawn or encounters an unrecoverable error:
+
+1. **Log the error** with full details:
+   - Phase where failure occurred
+   - Spec ID
+   - Error message from Task agent
+
+2. **Record as failed:**
+   - Add to specs_failed list with reason: "Agent failure: [phase] - {error message}"
+
+3. **Continue execution:**
+   - In batch mode: continue to next spec in queue (do not abort the entire batch)
+   - In single mode: proceed directly to summary report (Step 9)
+
+4. **Leave spec in current state:**
+   - Do not archive
+   - Do not modify status
+   - Leave in `.specflow/specs/` directory
+
+## Step 9: Display Summary Report
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+**Single mode:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AUTOPILOT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Mode:** single
+**Spec:** SPEC-XXX
+
+### Result
+
+**Outcome:** {COMPLETED | HALTED}
+**Audit Cycles:** {count}/{MAX_AUDIT_CYCLES}
+**Fix Cycles:** {count}/{MAX_FIX_CYCLES}
+
+{If COMPLETED:}
+✓ Specification processed from {start_status} to done
+  - Files created: {count}
+  - Files modified: {count}
+  - Total commits: {count}
+  - Total review cycles: {count}
+
+{If HALTED:}
+✗ Halted at phase: {phase}
+  Reason: {reason}
+
+---
+
+## Next Steps
+
+{If COMPLETED and queue has more specs:}
+`/sf:autopilot --all` — process remaining queue
+
+{If COMPLETED and queue is empty:}
+All specs completed. Queue is empty.
+
+{If HALTED:}
+Review spec status with `/sf:status` and `/sf:show SPEC-XXX`.
+Address the issue manually, then resume autopilot.
+```
+
+**Batch mode:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AUTOPILOT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Mode:** batch
+**Specs Processed:** {count}
+**Specs Completed:** {completed_count}
+**Specs Failed:** {failed_count}
+
+### Results
+
+| Spec | Title | Outcome | Audit Cycles | Fix Cycles |
+|------|-------|---------|--------------|------------|
+{For each spec in specs_processed:}
+| SPEC-XXX | {title} | COMPLETED | 2 | 1 |
+
+{If any failures:}
+### Failures
+
+| Spec | Title | Halted At | Reason |
+|------|-------|-----------|--------|
+{For each spec in specs_failed:}
+| SPEC-ZZZ | {title} | {phase} | Fix cycle limit (3/3) |
+
+---
+
+## Next Steps
+
+{If all succeeded and queue empty:}
+All specs processed successfully. Queue is empty.
+
+{If all succeeded and queue has more:}
+Queue has {count} remaining specs.
+`/sf:autopilot --all` — process remaining queue
+
+{If failures occurred:}
+Failed specs remain in `.specflow/specs/` with their current status.
+Review manually with `/sf:status` and `/sf:show SPEC-ZZZ`.
+Fix issues, then resume with `/sf:autopilot --all`.
+```
+
+</workflow>
+
+<fallback>
+
+If Task agent spawning fails for any phase, the command handles it via Step 8 (Handle Agent Failures).
+
+The autopilot does NOT have an inline fallback for agent logic itself — it relies on the specialized agents to execute their phases correctly.
+
+**Agent failure handling:**
+1. Log error details (phase, spec ID, error message)
+2. Record spec as failed with reason "Agent failure: [phase]"
+3. In batch mode: continue to next spec
+4. In single mode: proceed to summary report
+5. Leave spec in current state (do not archive or modify status)
+
+This ensures one agent failure does not crash the entire autopilot run.
+
+</fallback>
+
+<success_criteria>
+- [ ] Mode determined correctly (single vs batch)
+- [ ] Configuration constants loaded from config.json
+- [ ] Spec processed from current status through to "done" (single mode)
+- [ ] All actionable specs processed (batch mode)
+- [ ] Audit cycle limit enforced (MAX_AUDIT_CYCLES)
+- [ ] Fix cycle limit enforced (MAX_FIX_CYCLES)
+- [ ] Cycle counters reset when transitioning between major phases
+- [ ] STATE.md decision rotation performed when needed
+- [ ] Summary report displayed with accurate metrics
+- [ ] AskUserQuestion never called by autopilot command itself
+- [ ] STATE.md accurate at every point
+- [ ] No infinite loops possible
+- [ ] Agent failures handled gracefully (do not crash entire run)
+</success_criteria>

package/commands/sf/done.md

@@ -228,75 +228,17 @@ If implementation established new patterns, add to Project Patterns section.
 
 After updating STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 10: Create Final Commit (if needed)
 

package/commands/sf/help.md

@@ -236,6 +236,12 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 |--------------|-----------------------------------------|
 | /sf:quick    | Execute minor tasks (1-3 files) fast    |
 
+## Autonomous Execution
+
+| Command      | Description                             |
+|--------------|-----------------------------------------|
+| /sf:autopilot | Run full lifecycle autonomously         |
+
 ## Navigation
 
 | Command      | Description                             |
@@ -296,6 +302,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 5. `/sf:run` — Implement
 6. `/sf:review` — Review implementation
 7. `/sf:done` — Complete and archive
+8. Or skip steps 4-7: `/sf:autopilot` -- run everything autonomously
 
 ## Typical Session
 
@@ -309,6 +316,13 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 /sf:done          # Complete
 ```
 
+## Autonomous Alternative
+
+```
+/sf:autopilot          # Process active spec end-to-end
+/sf:autopilot --all    # Process entire queue
+```
+
 ---
 
 **Detailed help:** `/sf:help <command>`

package/commands/sf/review.md

@@ -129,75 +129,17 @@ The agent will:
 
 After the agent updates STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 8: Display Result
 

package/commands/sf/revise.md

@@ -156,13 +156,10 @@ Continue to Step 5 with analysis context available.
 | "..." | Treat as custom revision instructions |
 
 **Check for `--no-analysis` flag:**
-```bash
-if echo "$ARGS" | grep -q "\-\-no-analysis"; then
-    SKIP_ANALYSIS=true
-    # Remove flag from args for further processing
-    ARGS=$(echo "$ARGS" | sed 's/--no-analysis//g' | xargs)
-fi
-```
+
+If the arguments string contains `--no-analysis`:
+- Set SKIP_ANALYSIS to true
+- Remove the `--no-analysis` flag from the arguments string for further processing
 
 ### If Interactive Mode (no arguments):
 

package/commands/sf/run.md

@@ -251,75 +251,17 @@ The agent will:
 
 After updating STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 10: Display Result
 

package/package.json

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