specflow-cc 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,80 @@ 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.14.0] - 2026-03-05
+
+### Added
+
+- **Context Monitor Hook** — agent-facing context awareness via PostToolUse hook
+  - Statusline writes bridge file to `/tmp/claude-ctx-{session}.json`
+  - New `hooks/context-monitor.js` reads metrics and injects WARNING (35% remaining) / CRITICAL (25%) warnings into agent context
+  - Debounce (5 tool uses between warnings), severity escalation bypasses debounce
+  - Integrates with `/sf:pause` for graceful session saves
+  - Installer auto-registers the hook in settings.json
+
+- **`/sf:health`** — diagnose `.specflow/` directory integrity
+  - 13 error codes across 3 severity levels (error, warning, info)
+  - Checks: STATE.md integrity, orphaned specs, queue consistency, missing directories, stale execution state
+  - `--repair` flag for safe auto-fixes (create missing dirs, regenerate STATE.md, clear stale state)
+  - Repair verification: re-runs checks after repair to confirm resolution
+
+- **`/sf:validate`** — run validation checklist from specification
+  - Executes automated checks (test commands), code verifications (grep/glob), and manual prompts
+  - Pass/fail report per checklist item with overall validation status
+  - Graceful handling when spec has no validation checklist
+
+- **Validation Checklist in spec template** — spec-creator generates `## Validation Checklist` section for medium/large specs
+  - 3-5 concrete verification steps with expected outcomes
+  - Each item: action + expected result (e.g., "Run `npm test` — all pass")
+
+- **Enriched completion summaries** in `/sf:done`
+  - New sections: Outcome, Key Files, Patterns Established, Deviations
+  - Decisions extracted from both spec content and completion section
+
+- **Centralized CLI Tooling** (`bin/sf-tools.cjs`) — single Node.js CLI for SpecFlow operations
+  - `spec load <id>` — parse spec file, return frontmatter + sections as JSON
+  - `spec list [--status <s>]` — list specs with optional status filter
+  - `spec next-id` — next available SPEC-XXX number (checks specs/ + archive/)
+  - `queue next` — first actionable spec from queue
+  - `state get` / `state set-active <id> <status>` — STATE.md CRUD
+  - `resolve-model <agent-type>` — model resolution by profile
+  - `verify-structure` — `.specflow/` integrity checks
+  - `generate-slug <text>` — URL-safe slug generation
+  - Modular architecture: `bin/lib/core.cjs`, `state.cjs`, `spec.cjs`, `config.cjs`, `verify.cjs`
+  - 42 tests using Node.js `assert` (no external dependencies)
+
+### Fixed
+
+- Parent spec now correctly archived after `/sf:split`
+- `.specflow/` directory excluded from git tracking
+
+---
+
+## [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

@@ -200,15 +200,16 @@ If issues are found, `/sf:fix` addresses them. Loop until approved.
 
 ---
 
-### 5. Verify (Optional)
+### 5. Validate & Verify (Optional)
 
 ```
+/sf:validate
 /sf:verify
 ```
 
-Automated checks confirm code exists and tests pass. But does it actually *work*?
+**Validate** runs the spec's validation checklist — automated test commands, code checks, and manual verification prompts. Pass/fail per item.
 
-This step walks you through manual verification:
+**Verify** walks you through interactive acceptance testing:
 
 - "Can you log in with OAuth?"
 - "Does the redirect work?"
@@ -216,7 +217,7 @@ This step walks you through manual verification:
 
 You confirm each item. If something's broken, the system helps diagnose and creates fix plans.
 
-**Creates:** Verification record
+**Creates:** Validation/verification record
 
 ---
 
@@ -237,10 +238,12 @@ Your spec becomes documentation: why the code exists, what decisions were made,
 ```
                         /sf:quick (trivial tasks)
                               ↓
-/sf:new  →  /sf:audit  →  /sf:run  →  /sf:review  →  /sf:verify  →  /sf:done
-              ↓                          ↓              ↓
-         /sf:revise                  /sf:fix      (optional UAT)
-         (if needed)                 (if needed)
+/sf:new → /sf:audit → /sf:run → /sf:review → /sf:validate → /sf:verify → /sf:done
+            ↓                      ↓            ↓               ↓
+       /sf:revise              /sf:fix    (checklist)      (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.
@@ -310,8 +313,10 @@ Six months later, you can read the spec and understand not just *what* was built
 | `/sf:run` | Implement specification |
 | `/sf:review` | Review implementation (fresh context) |
 | `/sf:fix` | Fix based on review feedback |
+| `/sf:validate` | Run validation checklist from spec |
 | `/sf:verify` | Interactive user acceptance testing |
 | `/sf:done` | Complete and archive |
+| `/sf:autopilot` | Run full lifecycle autonomously |
 
 **Quick mode:**
 
@@ -393,6 +398,7 @@ before showing interactive options.
 | `/sf:deps` | Show spec dependencies |
 | `/sf:pause` | Save session context |
 | `/sf:resume` | Restore session |
+| `/sf:health` | Diagnose `.specflow/` integrity |
 | `/sf:help` | Command reference |
 
 ---
@@ -455,6 +461,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
 ```
 
 ---
@@ -474,6 +484,10 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 - Use `/sf:split` to decompose into smaller specs
 - Or let the system auto-decompose during `/sf:run`
 
+**STATE.md or queue seems corrupted?**
+- Run `/sf:health` to diagnose issues
+- Use `/sf:health --repair` for safe auto-fixes
+
 ---
 
 ## Philosophy

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

@@ -146,8 +146,9 @@ Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 4. **Task:** What to do
 5. **Requirements:** Files, interfaces, deletions
 6. **Acceptance Criteria:** Specific, measurable
-7. **Constraints:** What NOT to do
-8. **Assumptions:** What you assumed (clearly marked)
+7. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
+8. **Constraints:** What NOT to do
+9. **Assumptions:** What you assumed (clearly marked)
    - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
 
 ## Step 5.5: Generate Implementation Tasks (for medium and large specs)
@@ -241,6 +242,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

@@ -1,7 +1,7 @@
 ---
 name: sf-spec-splitter
 description: Analyzes large specifications and splits them into manageable sub-specifications with dependencies
-tools: Read, Write, Glob, Grep
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 <role>
@@ -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/bin/install.js

@@ -266,6 +266,26 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
     console.log(`  ${green}✓${reset} Configured statusline`);
   }
 
+  // Configure context-monitor hook
+  const isGlobal = statuslineCommand.includes('$HOME');
+  const monitorCommand = isGlobal
+    ? 'node "$HOME/.claude/hooks/context-monitor.js"'
+    : 'node .claude/hooks/context-monitor.js';
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  const hasMonitor = settings.hooks.PostToolUse.some(h =>
+    h.command && h.command.includes('context-monitor')
+  );
+  if (!hasMonitor) {
+    settings.hooks.PostToolUse.push({
+      type: 'command',
+      command: monitorCommand
+    });
+    console.log(`  ${green}✓${reset} Configured context monitor hook`);
+  }
+
   writeSettings(settingsPath, settings);
 
   console.log(`

package/bin/lib/config.cjs

@@ -0,0 +1,91 @@
+/**
+ * bin/lib/config.cjs — Config reading and model resolution
+ *
+ * Exports: MODEL_PROFILES, loadConfig(), cmdResolveModel()
+ */
+
+'use strict';
+
+const path = require('path');
+const { output, error, safeReadFile } = require('./core.cjs');
+
+/**
+ * Hardcoded MODEL_PROFILES table.
+ * MUST exactly match the profile table in commands/sf/run.md.
+ */
+const MODEL_PROFILES = {
+  'spec-creator':               { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-auditor':               { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-splitter':              { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'discusser':                  { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-executor':              { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'spec-executor-orchestrator': { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'spec-executor-worker':       { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'impl-reviewer':              { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'spec-reviser':               { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'sonnet' },
+  'researcher':                 { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'codebase-scanner':           { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+
+/**
+ * Load .specflow/config.json. Returns defaults if not found.
+ * @param {string} cwd - Working directory
+ * @returns {Object} Config object
+ */
+function loadConfig(cwd) {
+  const configPath = path.join(cwd, '.specflow', 'config.json');
+  const content = safeReadFile(configPath);
+
+  if (!content) {
+    return { model_profile: 'balanced' };
+  }
+
+  try {
+    const config = JSON.parse(content);
+    return {
+      model_profile: config.model_profile || 'balanced',
+      ...config,
+    };
+  } catch (e) {
+    return { model_profile: 'balanced' };
+  }
+}
+
+/**
+ * Resolve model for a given agent type based on current profile.
+ * @param {string} cwd - Working directory
+ * @param {string} agentType - Agent type (e.g., "spec-executor")
+ * @param {boolean} raw - Output raw string
+ */
+function cmdResolveModel(cwd, agentType, raw) {
+  if (!agentType) {
+    error('Missing agent type. Usage: resolve-model <agent-type>');
+  }
+
+  const config = loadConfig(cwd);
+  const profile = config.model_profile || 'balanced';
+
+  const agentProfiles = MODEL_PROFILES[agentType];
+
+  if (!agentProfiles) {
+    error('Unknown agent type: ' + agentType + '. Known types: ' + Object.keys(MODEL_PROFILES).join(', '));
+  }
+
+  const model = agentProfiles[profile];
+
+  if (!model) {
+    error('Unknown profile: ' + profile + '. Known profiles: max, quality, balanced, budget');
+  }
+
+  output({
+    agent: agentType,
+    profile: profile,
+    model: model,
+  }, raw, model);
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  loadConfig,
+  cmdResolveModel,
+};

package/bin/lib/core.cjs

@@ -0,0 +1,120 @@
+/**
+ * bin/lib/core.cjs — Shared utilities for sf-tools CLI
+ *
+ * Exports: output(), error(), safeReadFile(), parseFrontmatter(), generateSlug()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Output result to stdout as JSON, or raw string if raw flag is set.
+ * @param {*} result - The result object to output
+ * @param {boolean} raw - If true, output rawValue as plain string
+ * @param {string} [rawValue] - Plain string to output when raw is true
+ */
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
+}
+
+/**
+ * Output error message to stderr and exit with code 1.
+ * @param {string} message - Error message
+ */
+function error(message) {
+  process.stderr.write('Error: ' + message + '\n');
+  process.exit(1);
+}
+
+/**
+ * Safely read a file, returning its contents as a string or null if not found.
+ * @param {string} filePath - Absolute or relative path to the file
+ * @returns {string|null} File contents or null
+ */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Expects `---` delimited YAML at the start of the file.
+ * Returns simple key: value pairs only (no nested objects, no arrays).
+ * All values are returned as strings. No type coercion is performed.
+ *
+ * @param {string} content - Full file content
+ * @returns {{ frontmatter: Object, body: string }}
+ */
+function parseFrontmatter(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: {}, body: content || '' };
+  }
+
+  const trimmed = content.trimStart();
+
+  if (!trimmed.startsWith('---')) {
+    return { frontmatter: {}, body: content };
+  }
+
+  // Find the closing ---
+  const secondDash = trimmed.indexOf('---', 3);
+  if (secondDash === -1) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const yamlBlock = trimmed.substring(3, secondDash).trim();
+  const body = trimmed.substring(secondDash + 3).replace(/^\r?\n/, '');
+
+  const frontmatter = {};
+  const lines = yamlBlock.split('\n');
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine || trimmedLine.startsWith('#')) continue;
+
+    const colonIndex = trimmedLine.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmedLine.substring(0, colonIndex).trim();
+    const value = trimmedLine.substring(colonIndex + 1).trim();
+
+    // All values returned as strings — no type coercion
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Generate a URL-safe slug from text.
+ * Lowercase, replace spaces/special chars with hyphens, collapse multiples, trim edges.
+ *
+ * @param {string} text - Input text
+ * @returns {string} URL-safe slug
+ */
+function generateSlug(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')  // replace non-alphanumeric with hyphens
+    .replace(/-+/g, '-')          // collapse multiple hyphens
+    .replace(/^-|-$/g, '');       // trim leading/trailing hyphens
+}
+
+module.exports = {
+  output,
+  error,
+  safeReadFile,
+  parseFrontmatter,
+  generateSlug,
+};