@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/commands/fire-cost.md

@@ -1,183 +1,179 @@
-# /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
+# /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.
+---
+
+## 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-debug.md

@@ -116,7 +116,6 @@ IF match found with >0.75 similarity:
 
 ### Step 3.5: Hypothesis Tree (ReflexTree v9.1)
 
-> **Research basis:** ReflexTree (2025) — tree-structured reflection catches root causes
 > faster than linear hypothesis lists by enabling branch-and-prune investigation.
 
 Structure debugging as a branching tree, not a flat list.
@@ -369,7 +368,6 @@ IF status == "resolved":
 
 ### Step 7.75: Index Resolved Debug for Replay (NEW — v5.0)
 
-**Research basis:** ECHO (2025) — 80% improvement via experience replay
 
 After resolution, index the debug file into vector memory for future replay:
 
@@ -392,7 +390,6 @@ and can shortcut investigation by applying known root causes.
 
 ### Step 7.8b: Failure Classification (v7.0 — AgentDebug)
 
-> **Research basis:** AgentDebug (Sep 2025) — AgentErrorTaxonomy with 24% higher accuracy;
 > PALADIN (ICLR 2026) — structured failure analysis enables targeted prevention strategies.
 
 After debug resolution, classify the root cause into AgentDebug taxonomy:
@@ -430,7 +427,6 @@ IF status == "resolved":
 
 ### Step 7.8: Hindsight Experience Replay (v6.0 — ECHO)
 
-> **Research basis:** ECHO (Oct 2025) — Hindsight optimization outperforms Reflexion by 80%.
 > When a task fails, generating "what should have been done" creates synthetic positive
 > examples that dramatically improve future performance. The key insight: learning from
 > failures is 80% more effective when you also generate what success looks like.
@@ -487,7 +483,6 @@ instead of requiring the agent to re-derive the solution from raw investigation
 
 ### Step 7.9: Record Resolution Sequence (v7.0 — AgentRR)
 
-> **Research basis:** AgentRR (May 2025) — dual-level record/replay with check functions;
 > RLEP (Jul 2025) — blend replayed with new experiences for faster learning.
 
 After debug resolution, record the exact steps at TWO levels:
@@ -531,7 +526,7 @@ IF status == "resolved":
 After resolution or checkpoint, update persistent state:
 
 ```markdown
-## .claude/fire-flow.local.md
+## .claude/dominion-flow.local.md
 
 ### Last Debug Session
 - Issue: {slug}

package/commands/fire-loop-resume.md

@@ -45,8 +45,8 @@ SABBATH_FILE=$(ls .planning/loops/sabbath-${LOOP_ID}*.md 2>/dev/null | head -1)
 **If no LOOP_ID (resume most recent):**
 ```bash
 # Check Sabbath Rest state first
-if [ -f ".claude/fire-flow.local.md" ]; then
-  LOOP_ID=$(grep "Loop ID:" .claude/fire-flow.local.md | head -1 | cut -d: -f2 | xargs)
+if [ -f ".claude/dominion-flow.local.md" ]; then
+  LOOP_ID=$(grep "Loop ID:" .claude/dominion-flow.local.md | head -1 | cut -d: -f2 | xargs)
 fi
 
 # Or find most recent sabbath file

package/commands/fire-loop-stop.md

@@ -116,7 +116,7 @@ Add to history:
 ### Step 7: Update Sabbath Rest State
 
 ```markdown
-## .claude/fire-flow.local.md
+## .claude/dominion-flow.local.md
 
 ### Power Loop - Stopped
 - Loop ID: ${LOOP_ID}

package/commands/fire-loop.md

@@ -254,7 +254,6 @@ To cancel: `/fire-loop-stop`
 
 ### Step 6.5: Difficulty Classification (v7.0)
 
-> **Research basis:** Difficulty-Aware Agent Orchestration (Sep 2025) — +11.21% accuracy at 64% cost
 > by routing tasks through different pipeline depths based on complexity.
 
 Classify current task before entering the iteration pipeline:
@@ -284,7 +283,6 @@ Step 8.8 (reward scoring). Go directly from Step 7 → Step 8 → Step 9.
 
 ### Parallelizability Axis (v10.0)
 
-> **Research basis (v10.0):** Google/MIT "Scaling Laws for Agent Systems" (Dec 2025) —
 > multi-agent parallel execution improves parallelizable tasks by 80.9% but DEGRADES
 > sequential reasoning by 39-70%. The difficulty axis alone is insufficient — a COMPLEX
 > task that is inherently sequential gets WORSE with parallel agents.
@@ -332,7 +330,6 @@ Store in recitation: "Difficulty: {X} | Parallelizability: {PARALLEL|SEQUENTIAL|
 
 ### Agent Profile Selection (ATLAS v9.1)
 
-> **Research basis:** ATLAS (2025) — Adaptive Task-Level Agent Selection.
 > Dynamically choosing agent capability per task improves efficiency without sacrificing quality.
 
 After classifying difficulty, select the agent profile:
@@ -442,7 +439,6 @@ IF confidence < 50:
 
 **Confidence Propagation (v7.0 — AUQ):**
 
-> **Research basis:** AUQ (Jan 2026) — System 1/System 2 uncertainty split; AgentPRM
 > (Feb 2025) — process reward hacking detection. Metacognition limits paper (Sep 2025)
 > warns: don't trust self-reported confidence alone.
 
@@ -480,7 +476,6 @@ IF iteration >= 3:
 
 ### Step 7.1: Per-Turn Episodic Auto-Injection (v6.0)
 
-> **Research basis:** CoALA (Berkeley 2024) — Cognitive architecture requires automatic
 > episodic injection every decision cycle, not just on stall or low confidence.
 > "Every action cycle should: retrieve relevant episodic memory → inject into working
 > context → decide → store outcome."
@@ -559,7 +554,6 @@ Work on the task described in the prompt.
 
 ### Step 8.5: Behavioral Directive Check + HAC Enforcement (v6.0 + v7.0)
 
-> **Research basis:** CoALA procedural memory + SICA self-modifying agent (ICLR 2025)
 > v7.0 addition: MPR (Sep 2025) — Predicate-form rules with Hard Admissibility Checks
 
 **(Skip if difficulty = SIMPLE — see Step 6.5)**
@@ -606,9 +600,6 @@ IF task resolution revealed a reusable pattern or anti-pattern:
 ```
 
 ### Step 8.7: Iteration Checkpoint (v6.0 — GCC)
-
-> **Research basis:** GCC (Jul 2025) — Git-style checkpoints enable structured rollback.
-
 After each iteration that made file changes:
 
 ```
@@ -617,7 +608,7 @@ IF git_diff_stat(HEAD) shows changes:
   git commit -m "loop-checkpoint: iteration {i} — {task summary (50 chars max)}"
   checkpoint = git rev-parse HEAD
 
-  # Record in fire-flow.local.md
+  # Record in dominion-flow.local.md
   Append:
     checkpoint_hash: {checkpoint:7}
     iteration: {i}
@@ -631,7 +622,6 @@ IF git_diff_stat(HEAD) shows changes:
 
 ### Step 8.8: Turn-Level Reward Scoring (v6.0 — AgentPRM)
 
-> **Research basis:** AgentPRM (Feb 2025) — Process reward models that score each turn
 > in a multi-turn interaction enable fine-grained learning signals. Binary success/fail
 > is like grading pass/fail — you can't improve. Per-turn rewards enable identifying
 > which task types the agent handles well vs poorly.
@@ -647,7 +637,7 @@ context_efficiency = 5 - min(4, floor(tokens_used / 20000))  # 5=<20k, 1=>80k to
 # Weighted turn reward
 turn_reward = (0.5 * task_completion) + (0.3 * approach_quality) + (0.2 * context_efficiency)
 
-# Store in fire-flow.local.md
+# Store in dominion-flow.local.md
 Append to iteration_rewards:
   - iteration: {i}
     reward: {turn_reward, 1 decimal}
@@ -963,9 +953,6 @@ circuit_breaker_state: [current CB state]
 ```
 
 **Compaction Protocol (v6.0):**
-
-> **Research basis:** JetBrains "Cutting Through the Noise" (Dec 2025) — LLM summarization hides stop signals, extending runs ~15% past useful points.
-
 ```
 WHEN context approaches limit and compaction triggers:
 

package/commands/fire-map-codebase.md

@@ -236,7 +236,7 @@ EOF
 Update persistent state:
 
 ```markdown
-## .claude/fire-flow.local.md
+## .claude/dominion-flow.local.md
 
 ### Codebase Map
 - Generated: {timestamp}