@thierrynakoa/fire-flow 10.0.0 → 12.2.1

package/commands/{fire-1a-discuss.md → fire-1d-discuss.md}

@@ -2,7 +2,7 @@
 description: Gather implementation context through adaptive questioning before planning
 ---
 
-# /fire-1a-discuss
+# /fire-1d-discuss
 
 > Think before you plan
 
@@ -24,7 +24,7 @@ arguments:
     required: true
     type: integer
     description: "Phase number to discuss"
-    example: "/fire-1a-discuss 3"
+    example: "/fire-1d-discuss 3"
 
   --quick:
     required: false
@@ -195,6 +195,34 @@ Before presenting gray areas, validate that captured decisions reach FILE-LEVEL
 **IF score >= 8:**
   Proceed to Step 4 with high-specificity plan.
 
+### Step 3.7: Requirements Decomposition Check (v12.0)
+
+> **Source:** REQUIREMENTS_DECOMPOSITION skill — utility tree decomposition
+
+Before presenting gray areas, verify that requirements are decomposed to actionable depth:
+
+```
+FOR each requirement discussed so far:
+  CLASSIFY decomposition level:
+    Level 1: Quality attribute ("good performance")     → TOO VAGUE
+    Level 2: Sub-factor ("fast page loads")             → STILL VAGUE
+    Level 3: Refined sub-factor ("< 2s initial load")   → GETTING THERE
+    Level 4: Requirement ("Lazy-load images, code-split routes") → ACTIONABLE
+
+  IF requirement is Level 1 or Level 2:
+    → Generate follow-up question to decompose further
+    → "You mentioned '{requirement}' — what specifically does that mean?
+       For example: {suggest 2-3 Level 4 decompositions}"
+
+  IF requirement is Level 3:
+    → Accept but flag for planner to decompose to Level 4
+
+  IF requirement is Level 4:
+    → Accept as-is
+```
+
+**Goal:** No Level 1/2 requirements should survive the discuss phase. The planner receives Level 3+ requirements only.
+
 ### Step 4: Present Gray Areas
 
 ```
@@ -337,7 +365,7 @@ Track deferred ideas internally.
 
 > *Like humans need sleep to reset, AI agents need state files to resume after context resets.*
 
-**Create/Update:** `.claude/dominion-flow.local.md`
+**Create/Update:** `.claude/fire-flow.local.md`
 
 ```markdown
 ---
@@ -428,16 +456,16 @@ When reasonable, let user delegate to Claude's judgment.
 
 ```bash
 # Discuss phase 3 before planning
-/fire-1a-discuss 3
+/fire-1d-discuss 3
 
 # Quick discussion (2 questions per area)
-/fire-1a-discuss 5 --quick
+/fire-1d-discuss 5 --quick
 
 # Focus on specific areas only
-/fire-1a-discuss 2 --areas "layout,behavior"
+/fire-1d-discuss 2 --areas "layout,behavior"
 
 # Skip if already discussed
-/fire-1a-discuss 4 --skip-existing
+/fire-1d-discuss 4 --skip-existing
 ```
 
 ---

package/commands/fire-3-execute.md

@@ -555,10 +555,12 @@ MEDIUM (50-80%): Proceed with extra validation
   → Run Self-Judge before AND after
   → Log uncertainty reason in RECORD.md
 
-LOW (<50%): Pause and escalate
+LOW (<50%): Research first, then proceed
   → Search Context7 for current library docs
+  → Search skills library: /fire-search "{gap}"
   → Check if this is outside trained domain
-  → Ask user for guidance before proceeding
+  → IF < 30%: Spawn fire-researcher with the specific gap — get alternatives
+  → Only escalate to user if research returns no actionable path
   → Create checkpoint before attempting
 
 **Log confidence in RECORD.md:**
@@ -737,6 +739,57 @@ key_decisions:
 - Pause execution
 - Display error and recovery instructions
 
+### Step 7.1: Error Classification Health Check (v10.1)
+
+> **Research basis (v10.1):** Microsoft "AutoGen StateFlow" (ICML 2024) — formal error
+> classification at execution boundaries reduces repeat failures by 28%. This integrates
+> the existing `references/error-classification.md` into breath-level execution flow.
+> Previously, error classification existed as a reference but was not wired into
+> the execution pipeline.
+
+**After each breath completes (success OR failure), classify execution health:**
+
+```
+INPUTS for classification:
+  - files_changed:   count of files in breath RECORD.md key_files
+  - error_hash:      normalized hash of any error message from breath
+  - previous_errors: error hashes from previous breaths in this phase
+  - output_volume:   total lines of code produced vs. baseline
+  - error_type:      classification of error (if any)
+
+CLASSIFY using references/error-classification.md algorithm:
+
+  1. BLOCKED?  → External dependency, permission, or service error
+     Action: Stop execution. Create BLOCKERS.md entry. Save state.
+     Display: EXECUTION BLOCKED banner (see error-classification.md)
+
+  2. SPINNING? → Same error hash seen in 3+ breaths
+     Action: Force approach rotation. Inject anti-patterns list.
+     Display: "Same error for {N} breaths. You MUST try a different approach."
+
+  3. DEGRADED? → Output volume declined 50%+ from first breath
+     Action: Trigger /fire-cost context check. If ORANGE+, compact.
+     Display: "Output quality declining. Consider /fire-5-handoff."
+
+  4. STALLED?  → No file changes AND no new errors
+     Action: Inject urgency. Search skills for alternative approach.
+     Display: "No progress detected. Pick ONE concrete change."
+
+  5. PROGRESS  → Files changed, errors are new/different
+     Action: Continue to next breath normally.
+
+RECORD health state in CONSCIENCE.md:
+  | Breath | Health | Trigger | Action |
+  | {W} | {state} | {trigger} | {action_taken} |
+```
+
+**Circuit breaker integration:**
+- If health is SPINNING for 2 consecutive breaths → trigger circuit breaker
+- If health is DEGRADED → check `/fire-cost` context tier. If RED+, force handoff.
+- If health is BLOCKED → do NOT retry. Save state and surface blocker to user.
+
+**Skip condition:** If breath completed successfully with no errors, mark PROGRESS and continue.
+
 ### Step 7.4: Post-Feature Config Sync (v10.0)
 
 After breath completion, check if new features need config file updates.

package/commands/fire-4-verify.md

@@ -487,6 +487,67 @@ IF reviewer was spawned (--quick NOT set):
       → "Code is clean but doesn't work."
 ```
 
+### Step 5.6: FaR Confidence Calibration (v10.1)
+
+> **Research basis (v10.1):** Xiong et al. "Can LLMs Express Their Uncertainty?" (ACL 2024) —
+> Fact-and-Reflection (FaR) prompting reduces Expected Calibration Error by 23.5%.
+> Agents that first enumerate known facts, then reflect on uncertainty, produce
+> dramatically more accurate confidence scores than agents that just guess a number.
+> Applied: Added mandatory FaR step before final verification verdict.
+
+Before assigning the final verdict, the verifier MUST perform a two-phase confidence assessment:
+
+```
+═══════════════════════════════════════════════════════
+  FaR CONFIDENCE CALIBRATION
+═══════════════════════════════════════════════════════
+
+PHASE 1: FACT ELICITATION
+List every concrete, observable fact about this phase's correctness:
+
+  Facts FOR correctness (evidence it works):
+    1. {fact} — source: {test output / manual check / code review}
+    2. {fact} — source: {specific evidence}
+    3. ...
+
+  Facts AGAINST correctness (evidence of problems):
+    1. {fact} — source: {test failure / gap / uncertainty}
+    2. {fact} — source: {specific evidence}
+    3. ...
+
+  Unknown / Untestable:
+    1. {thing we cannot verify} — why: {reason}
+    2. ...
+
+PHASE 2: REFLECTION
+Given the facts above, reflect on overall confidence:
+
+  - How many critical paths have direct evidence? {N}/{total}
+  - Are the "against" facts blockers or minor gaps?
+  - What is the worst plausible failure mode?
+  - If this shipped to production right now, what breaks?
+
+CALIBRATED CONFIDENCE: {0-100}%
+
+  Interpretation:
+    90-100% — High confidence. Ship it.
+    70-89%  — Moderate confidence. Acceptable with noted gaps.
+    50-69%  — Low confidence. Significant unknowns remain.
+    <50%    — Very low. Do not approve without more evidence.
+
+═══════════════════════════════════════════════════════
+```
+
+**Integration with verdict:**
+- FaR confidence is INFORMATIONAL — it does not override the 70-point checklist
+- BUT if FaR confidence < 50% AND checklist score ≥ 70%, flag a WARNING:
+  "Checklist passes but verifier confidence is low. Review the 'Unknown/Untestable'
+  list before approving."
+- Include FaR confidence in the verification report under a "Confidence Assessment" section
+- Track FaR confidence across phases to detect calibration drift
+
+**Skip condition:** If `--quick` flag is set, skip FaR and use raw checklist score only.
+
 ### Step 5.75: Dual-Verification — Read from Authoritative Source (v11.0)
 
 > **Research basis (v11.0):** Failure pattern mining (8 instances of silent persistence

package/commands/fire-5-handoff.md

@@ -176,7 +176,7 @@ next_action: "{what to do next}"
 ### Important Paths:
 - **Project Root:** {path}
 - **Planning Docs:** {path}/.planning/
-- **Skills Library:** ~/.claude/plugins/dominion-flow/skills-library/
+- **Skills Library:** ~/.claude/plugins/fire-flow/skills-library/
 
 ---
 
@@ -470,7 +470,7 @@ This command does NOT spawn agents. It compiles information from existing docume
 â•‘                                                                              â•‘
 â•‘  No .planning/CONSCIENCE.md found.                                                â•‘
 â•‘                                                                              â•‘
-â•‘  Action: Run `/fire-1-new` to initialize project first.                     â•‘
+â•‘  Action: Run `/fire-1a-new` to initialize project first.                     â•‘
 â•‘                                                                              â•‘
 ╚══════════════════════════════════════════════════════════════════════════════╝
 ```

package/commands/fire-6-resume.md

@@ -201,6 +201,41 @@ Use AskUserQuestion:
 
 **Skip condition:** If `--quick` flag is set, still load directives (they're tiny and high-value).
 
+### Step 2.9: Dead Ends Review (v11.3)
+
+> **Philosophy:** A fresh Claude instance with clean context is the best solver for problems that burned a previous instance. Check for dead ends FIRST — you might solve in 30 seconds what the last instance couldn't in 15 minutes.
+
+**Read `.planning/breadcrumbs/FAILURES.md`** — if it exists, look for entries tagged `[DEAD-END]`:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ DEAD ENDS — {N} unsolved problem(s) from previous sessions                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  1. [{priority}] {title}                                                    │
+│     Shelved: {date} by {agent} — Attempts: {N}                             │
+│     Untested hypotheses: {N}                                                │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**For the highest-priority `[DEAD-END]` entry:**
+
+1. Read the full entry (problem, prior attempts, untested hypotheses, relevant files)
+2. With your fresh context, **attempt the top untested hypothesis**
+3. **If solved:**
+   - Move the entry to `breadcrumbs/LESSONS.md` with `[DEAD-END-SOLVED]` tag
+   - Remove the `[DEAD-END]` tag from `FAILURES.md`
+   - Log the solution approach for future reference
+4. **If still stuck after one focused attempt:**
+   - Update the entry with your new attempt
+   - Don't burn more tokens — move on to normal work
+   - The NEXT fresh instance will try again
+
+**Time budget:** Max 5 minutes on dead-end problems. This is a bonus attempt, not the main work.
+
+**Skip condition:** If `--quick` flag or no `FAILURES.md` exists, skip.
+
 ### Step 3: Display Project Status Summary
 
 ```
@@ -426,7 +461,7 @@ This command does NOT spawn agents. It loads context and provides routing recomm
 ║                                                                              ║
 ║  Options:                                                                    ║
 ║    A) Check if project exists: look for .planning/CONSCIENCE.md                   ║
-║    B) Initialize new project: /fire-1-new                                   ║
+║    B) Initialize new project: /fire-1a-new                                   ║
 ║    C) Check handoff directory: ls ~/.claude/warrior-handoffs/                ║
 ║                                                                              ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
@@ -486,7 +521,7 @@ This command does NOT spawn agents. It loads context and provides routing recomm
 ║  Options:                                                                    ║
 ║    A) Create CONSCIENCE.md from handoff context                                   ║
 ║    B) Navigate to correct project directory                                  ║
-║    C) Initialize fresh: /fire-1-new                                         ║
+║    C) Initialize fresh: /fire-1a-new                                         ║
 ║                                                                              ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 ```

package/commands/fire-add-new-skill.md

@@ -407,7 +407,7 @@ Unlike the security scan (Step 4.5) which allows "save anyway" for suspicious co
 ### Save and Update Index
 
 1. Save skill file:
-   - Path: `~/.claude/plugins/dominion-flow/skills-library/{category}/{skill-name}.md`
+   - Path: `~/.claude/plugins/fire-flow/skills-library/{category}/{skill-name}.md`
 
 2. Update SKILLS-INDEX.md:
    - Add entry to category section
@@ -416,7 +416,7 @@ Unlike the security scan (Step 4.5) which allows "save anyway" for suspicious co
 
 3. Git commit (if skills library is versioned):
    ```bash
-   cd ~/.claude/plugins/dominion-flow/skills-library
+   cd ~/.claude/plugins/fire-flow/skills-library
    git add {category}/{skill-name}.md SKILLS-INDEX.md
    git commit -m "feat(skills): add {category}/{skill-name}"
    ```

package/commands/fire-autonomous.md

@@ -180,7 +180,7 @@ FOR phase_number in range(from_phase, to_phase + 1):
 
     Run /fire-3-execute {phase_number} --auto-continue --autonomous
     // --auto-continue: no breath-boundary interrupts
-    // --autonomous: merge gate auto-routes verdicts (v9.0)
+    // --autonomous: merge gate auto-routes verdicts (v9.0, enhanced v12.0)
 
     // ──────────────────────────────────────────────────────
     // Step 3.3: AUTO-VERIFY (read results)
@@ -312,6 +312,23 @@ Write .planning/autonomous-log.md:
 
 ### Behavioral Directive Proposals
 {Any HIGH/CRITICAL findings from reviewer that should become rules}
+
+### DORA Metrics (v12.0 — AUTONOMOUS_ORCHESTRATION skill)
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Deployment Frequency | {phases_completed}/{elapsed_time} | Phases per hour |
+| Change Lead Time | {avg time from plan to verified} | Plan→Execute→Verify avg |
+| Change Failure Rate | {failed_attempts}/{total_attempts} | Lower = better quality plans |
+| Recovery Time | {avg time from NEEDS FIX to next PASS} | Re-plan + re-execute avg |
+
+### Supervised Autonomy Assessment (v12.0)
+
+| Tier | Description | This Session |
+|------|-------------|-------------|
+| Human-in-the-loop | Every decision approved | Not used |
+| Human-on-the-loop | Monitoring, intervenes on blockers | Active (via circuit breaker) |
+| Human-out-of-loop | Full autonomy with instrumentation | {if no blockers: "Achieved"} |
 ```
 
 ### Step 6: Completion Banner
@@ -402,7 +419,7 @@ forward-looking context that the memory system doesn't capture.
 ### Step 8: Sabbath Rest — Session State
 
 ```
-Update .claude/dominion-flow.local.md:
+Update .claude/fire-flow.local.md:
 
 ---
 last_session: {timestamp}
@@ -524,5 +541,5 @@ WHAT IS DISABLED in autonomous mode:
 
 ---
 
-*Dominion Flow v9.0 — Full autopilot with instrumentation over restriction*
+*Dominion Flow v12.0 — Full autopilot with instrumentation over restriction*
 *Boris Cherny principle: "You don't trust; you instrument."*

package/commands/fire-brainstorm.md

@@ -361,7 +361,7 @@ This ensures:
 ```bash
 /fire-brainstorm "project architecture for {idea}"
 # Then
-/fire-1-new
+/fire-1a-new
 ```
 
 ### Before Planning Phase

package/commands/fire-complete-milestone.md

@@ -157,7 +157,7 @@ Key accomplishments:
 - {accomplishment 2}
 
 ## Next Milestone Goals
-<!-- Defined by /fire-1-new or /fire-new-milestone -->
+<!-- Defined by /fire-1a-new or /fire-new-milestone -->
 ```
 
 ### Step 7: Commit and Tag
@@ -197,7 +197,7 @@ Use AskUserQuestion:
 Update persistent state:
 
 ```markdown
-## .claude/dominion-flow.local.md
+## .claude/fire-flow.local.md
 
 ### Milestone Completion
 - Version: v{version}

package/commands/fire-cost.md

@@ -0,0 +1,183 @@
+# /fire-cost — Token & Cost Intelligence
+
+> Track context usage, estimate session costs, and trigger strategic compaction before hitting limits.
+
+---
+
+## Purpose
+
+Provide real-time visibility into context window consumption and session costs. Prevents the silent failure mode where agents hit context limits mid-task with no recovery path.
+
+> **Research basis (v10.1):** Spotify "Honk" Architecture (2024) — tiered context management reduces context-related failures by 40%. Google DeepMind "Cost-Aware Agent Planning" (NeurIPS 2024) — agents that track resource consumption make 31% fewer wasteful API calls.
+> Applied: Added explicit context/cost monitoring as a first-class command.
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--detail` | No | Show per-file and per-agent breakdown |
+| `--warn` | No | Only show if above 60% context usage |
+| `--budget <amount>` | No | Set a session cost budget (e.g., `--budget $5.00`) |
+
+---
+
+## Process
+
+<step number="1">
+### Measure Current Context State
+
+Assess the current session's context consumption:
+
+**Context Window Tiers:**
+| Tier | Usage | Status | Action |
+|------|-------|--------|--------|
+| GREEN | 0-50% | Healthy | No action needed |
+| YELLOW | 50-70% | Caution | Consider compaction soon |
+| ORANGE | 70-85% | Warning | Compact non-essential context NOW |
+| RED | 85-95% | Critical | Emergency compaction — preserve only active task |
+| BLACK | 95%+ | Terminal | Save state immediately, prepare handoff |
+
+Estimate context usage from:
+- Number of files read in session
+- Conversation turn count
+- Agent spawns and their responses
+- Skills loaded
+- Tool call results accumulated
+</step>
+
+<step number="2">
+### Token Cost Estimation
+
+Estimate session costs based on model usage:
+
+**Claude Opus 4 Pricing:**
+- Input: $15 / 1M tokens
+- Output: $5 / 1M tokens
+
+**Claude Sonnet 4 Pricing:**
+- Input: $3 / 1M tokens
+- Output: $15 / 1M tokens
+
+**Estimation heuristics:**
+- Average file read: ~2,000 tokens
+- Average tool call result: ~500 tokens
+- Average agent spawn (round-trip): ~8,000 tokens
+- Average user message: ~200 tokens
+- Average assistant response: ~1,500 tokens
+
+Track cumulative estimates across the session.
+</step>
+
+<step number="3">
+### Strategic Compaction Recommendations
+
+When context usage exceeds YELLOW tier, recommend specific compaction strategies:
+
+**Priority 1 — Drop stale context:**
+- Files read >10 turns ago that aren't referenced in active task
+- Completed agent results (keep summary, drop details)
+- Resolved error messages and their debug traces
+
+**Priority 2 — Compress active context:**
+- Replace full file contents with relevant excerpts
+- Summarize long tool outputs
+- Collapse completed task details into one-line summaries
+
+**Priority 3 — Archive and handoff:**
+- Run `/fire-5-handoff` to save state
+- Use `/compact Focus on [active task]` for targeted compaction
+- Split remaining work into a new session
+
+</step>
+
+<step number="4">
+### Display Dashboard
+
+```
+=============================================================
+            COST & CONTEXT INTELLIGENCE
+=============================================================
+
+Session Duration: {hours}h {minutes}m
+Conversation Turns: {N}
+
+-------------------------------------------------------------
+CONTEXT WINDOW
+-------------------------------------------------------------
+
+Usage: [████████████░░░░░░░░] 62% — YELLOW ⚠️
+
+Files read: {N} (~{tokens} tokens)
+Agent spawns: {N} (~{tokens} tokens)
+Tool calls: {N} (~{tokens} tokens)
+Conversation: {N} turns (~{tokens} tokens)
+
+Estimated total: ~{tokens} tokens
+
+-------------------------------------------------------------
+COST ESTIMATE
+-------------------------------------------------------------
+
+Input tokens: ~{N} × ${rate} = ${amount}
+Output tokens: ~{N} × ${rate} = ${amount}
+                              ─────────
+Estimated session cost:         ${total}
+Budget remaining:               ${remaining} (if --budget set)
+
+-------------------------------------------------------------
+RECOMMENDATIONS
+-------------------------------------------------------------
+
+{If GREEN: "Context is healthy. No action needed."}
+{If YELLOW: "Consider running /compact soon. N files from early session could be dropped."}
+{If ORANGE+: "COMPACT NOW. Specific recommendations:
+  - Drop: [file1, file2] (read >10 turns ago, not in active task)
+  - Compress: [agent results] (keep summaries only)
+  - Archive: Run /fire-5-handoff to save state before continuing"}
+
+=============================================================
+```
+</step>
+
+---
+
+## Budget Alerts
+
+When `--budget` is set, display warnings at these thresholds:
+
+| Threshold | Alert |
+|-----------|-------|
+| 50% of budget | "Half your budget spent. {N} tokens remaining at current rate." |
+| 75% of budget | "Budget warning: ${remaining} left. Consider wrapping up current task." |
+| 90% of budget | "Budget critical: ${remaining} left. Save state with /fire-5-handoff." |
+| 100% of budget | "Budget exceeded. Recommend ending session after current task." |
+
+---
+
+## Integration Points
+
+- **`/fire-3-execute`** — Check context tier before each breath. If ORANGE+, compact before continuing.
+- **`/fire-autonomous`** — Auto-check after every 3 phases. If ORANGE+, trigger handoff.
+- **`/fire-loop`** — Include cost check in each loop iteration status.
+- **`/fire-5-handoff`** — Include final cost summary in handoff document.
+
+---
+
+## Success Criteria
+
+- [ ] Context tier accurately assessed (GREEN/YELLOW/ORANGE/RED/BLACK)
+- [ ] Token estimates within reasonable range
+- [ ] Cost estimates calculated with current model pricing
+- [ ] Compaction recommendations specific and actionable
+- [ ] Budget tracking functional when --budget flag used
+- [ ] Dashboard displays cleanly
+
+---
+
+## Related Commands
+
+- `/fire-dashboard` — Project overview (includes cost widget)
+- `/fire-5-handoff` — Save session state
+- `/fire-autonomous` — Uses cost checks for auto-pause decisions

package/commands/fire-dashboard.md

@@ -34,7 +34,7 @@ Read current project state from .planning/CONSCIENCE.md and related files.
 ```bash
 # Check for required state files
 if [ ! -f ".planning/CONSCIENCE.md" ]; then
-  echo "Error: No .planning/CONSCIENCE.md found. Run /fire-1-new first."
+  echo "Error: No .planning/CONSCIENCE.md found. Run /fire-1a-new first."
   exit 1
 fi
 ```
@@ -316,7 +316,7 @@ Categories:
 ║  Could not find .planning/CONSCIENCE.md in current directory.                    ║
 ║                                                                              ║
 ║  To initialize a new project:                                               ║
-║    /fire-1-new                                                             ║
+║    /fire-1a-new                                                             ║
 ║                                                                              ║
 ║  To resume an existing project:                                             ║
 ║    /fire-6-resume                                                          ║