@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/_general/methodology/AUTO_REVIEWER_SUBAGENT.md

@@ -0,0 +1,211 @@
+# Auto-Reviewer Subagent Pattern
+
+> Automatically spawn a read-only reviewer agent without manual copy-paste. Uses Claude Code's native `.claude/agents/` subagent system with worktree isolation.
+
+**When to use:** Any time code review is needed during a Dominion Flow workflow — especially in `/fire-3-execute` (post-breath review), `/fire-autonomous` (auto-review gate), or when a developer wants independent code review without leaving their session.
+
+---
+
+## The Problem
+
+Currently, `/fire-7-review` runs 16 reviewer personas in the SAME Claude Code instance. To get a truly independent review (separate context window, no confirmation bias), users must:
+1. Open a new terminal
+2. Copy-paste the review prompt
+3. Wait for results
+4. Manually collect and deduplicate findings
+
+This friction means reviews get skipped.
+
+---
+
+## Solution: Custom Subagent Files
+
+### Phase 1: Read-Only Reviewer (Recommended — works today)
+
+Create a markdown file at `.claude/agents/fire-code-reviewer.md` in your project:
+
+```yaml
+---
+name: fire-code-reviewer
+description: Independent code reviewer that analyzes code for bugs, security issues, and quality problems. Returns structured verdicts.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - LS
+model: sonnet
+---
+
+You are a senior code reviewer performing an independent review. You have NO context about what the developer intended — review the code purely on its merits.
+
+## Review Criteria
+
+1. **Security** — SQL injection, XSS, CSRF, auth bypass, secret exposure
+2. **Correctness** — Logic errors, off-by-one, null handling, race conditions
+3. **Error Handling** — Missing try/catch, swallowed errors, no fallbacks
+4. **Performance** — N+1 queries, unnecessary re-renders, missing indexes
+5. **Maintainability** — Dead code, unclear naming, missing types
+
+## Output Format
+
+Return your verdict as a structured block:
+
+VERDICT: APPROVE | APPROVE_WITH_FIXES | BLOCK
+CONFIDENCE: 1-100
+ISSUES_FOUND: N
+
+### Critical Issues (must fix)
+- [file:line] Description
+
+### Major Issues (should fix)
+- [file:line] Description
+
+### Minor Issues (nice to fix)
+- [file:line] Description
+
+### Summary
+One paragraph overall assessment.
+```
+
+### How to Invoke
+
+From any Dominion Flow command, the executor or orchestrator says:
+
+```
+Use the fire-code-reviewer agent to review the files changed in this phase:
+- src/routes/payment.ts
+- src/controllers/checkout.ts
+- src/middleware/auth.ts
+```
+
+Claude Code automatically routes this to the subagent, which runs in a separate context window with only Read/Grep/Glob tools (read-only).
+
+---
+
+### Phase 2: CLI Spawning (Fallback / CI Integration)
+
+For CI/CD or when subagent routing doesn't trigger:
+
+```bash
+# Review a git diff
+git diff main | claude -p "Review this diff for bugs, security issues, and code quality. Return a JSON verdict with: {verdict: APPROVE|BLOCK, confidence: 0-100, issues: [{severity, file, line, description}]}" --output-format json > /tmp/review-verdict.json
+
+# Review specific files
+claude -p "Review these files for security and correctness:
+$(cat src/routes/payment.ts)
+$(cat src/controllers/checkout.ts)
+Return a structured verdict." --output-format json --model sonnet
+
+# Parse verdict in parent session
+cat /tmp/review-verdict.json | jq '.result[0].content[] | select(.type=="text") | .text'
+```
+
+Key flags:
+- `-p` / `--print` — non-interactive mode, returns to stdout
+- `--output-format json` — structured output for programmatic parsing
+- `--model sonnet` — cheaper model for routine reviews
+- `--dangerously-skip-permissions` — unattended execution (use carefully)
+
+---
+
+### Phase 3: Agent Teams (Multi-Reviewer)
+
+Enable experimental agent teams for competing reviewers:
+
+```json
+// ~/.claude/settings.json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+Then spawn specialized reviewers as teammates:
+
+```
+Create three reviewer teammates:
+
+1. Security Reviewer — focus on auth bypass, injection, secret exposure
+2. Performance Reviewer — focus on N+1 queries, memory leaks, bundle size
+3. Architecture Reviewer — focus on coupling, abstraction, dependency direction
+
+Each should review the files in src/routes/ and src/controllers/.
+They can discuss findings with each other via inbox messages.
+When all three are done, synthesize their verdicts into a final recommendation.
+```
+
+Teammates can:
+- Talk to each other (not just back to parent)
+- Challenge each other's findings
+- Self-claim unassigned review tasks
+- Coordinate via shared task list
+
+---
+
+## Integration Points
+
+### In fire-3-execute.md (Post-Breath Review)
+
+Add after each breath completes:
+
+```markdown
+### Step 3.7: Auto-Review Gate
+
+After breath execution completes:
+
+1. Spawn fire-code-reviewer subagent with the list of modified files
+2. Wait for structured verdict
+3. Route verdict:
+   - APPROVE → proceed to next breath
+   - APPROVE_WITH_FIXES → log fixes needed, proceed (non-blocking)
+   - BLOCK → halt execution, present findings to developer
+
+Note: In autonomous mode (--autonomous flag), BLOCK triggers auto-fix
+cycle instead of halting.
+```
+
+### In fire-autonomous.md (Auto-Review)
+
+The autonomous loop already has Step 3.3 (AUTO-VERIFY). Add parallel review:
+
+```markdown
+### Step 3.2.5: AUTO-REVIEW (parallel with verification)
+
+Spawn fire-code-reviewer in background:
+  - isolation: worktree
+  - tools: Read, Grep, Glob (read-only)
+  - model: sonnet (cost optimization)
+
+Collect verdict when verification also completes.
+Merge verdicts per Step 8.5 arbitration protocol.
+```
+
+---
+
+## Verdict Aggregation
+
+When multiple reviewers return verdicts:
+
+```
+IF any reviewer says BLOCK:
+  final_verdict = BLOCK (unanimous APPROVE required for APPROVE)
+
+IF all reviewers say APPROVE:
+  final_verdict = APPROVE
+
+IF mix of APPROVE and APPROVE_WITH_FIXES:
+  final_verdict = APPROVE_WITH_FIXES
+  aggregate all issues from all reviewers
+  deduplicate by file:line (same issue from 2 reviewers = higher confidence)
+```
+
+---
+
+## Sources
+
+- Claude Code Docs: "Create custom subagents" (2026)
+- Claude Code Docs: "Orchestrate teams of Claude Code sessions" (2026)
+- Claude Code Docs: "CLI reference — non-interactive mode" (2026)
+- Anthropic: "How we built our multi-agent research system" (2026)
+- VoltAgent/awesome-claude-code-subagents (GitHub)

package/skills-library/_general/methodology/CONSISTENCY_CHECK_AMBIGUITY_GATE.md

@@ -0,0 +1,96 @@
+---
+name: CONSISTENCY_CHECK_AMBIGUITY_GATE
+category: methodology
+description: Re-read the full request for consistency before asking a clarifying question
+version: 1.0.0
+tags: [wizard, clarification, ambiguity, requirements, llm-reliability, clarify-gpt]
+---
+
+# Consistency-Check Ambiguity Gate
+
+## Problem
+
+A wizard detects ambiguity and immediately asks a clarifying question. But:
+
+1. The original request already answered the question — the LLM just didn't connect
+   the pieces.
+2. The clarifying question is redundant with information already given.
+3. The user gets asked to repeat themselves.
+
+This is the most common failure mode in requirements-gathering wizards: asking
+questions that were already answered.
+
+**User experience:** "I already told you that." Trust erodes. User disengages.
+
+## Solution
+
+Before asking any clarifying question, run a **consistency check**:
+
+```
+1. Re-read the full original request (from the beginning of this interaction)
+2. Check: Does any part of the existing input already resolve this ambiguity?
+3. If YES → extract the answer, proceed without asking
+4. If NO (confirmed gap) → ask the clarifying question
+```
+
+This is a **silent pre-check** — users never see it unless clarification is genuinely needed.
+
+## Implementation Pattern
+
+Add to any step that generates clarifying questions:
+
+```markdown
+**Per-step self-check before asking:**
+Ask internally: "Is the answer to this question already implied or stated in what
+the user has provided? Re-read from the beginning." If already answerable → resolve
+internally. Only ask if genuinely ambiguous after re-reading.
+```
+
+### Example: fire-1d-discuss.md Step 3.75
+
+```markdown
+### Step 3.75: Consistency-Check Ambiguity Gate
+
+Before asking any clarifying question during phase discussion:
+1. Re-read the full original phase description from Step 1
+2. Check for implicit answers: stated constraints, mentioned components,
+   implied scope limits
+3. If the question is answerable from context → resolve internally and proceed
+4. Only surface questions that remain genuinely ambiguous after the re-read
+```
+
+## When This Fires
+
+- Any wizard step that would generate a follow-up question
+- Requirements-gathering after a long initial description
+- When the user's input is dense with embedded context
+
+## Measurable Impact
+
+**ClarifyGPT** (arXiv 2310.10996) — Framework for when and how to ask clarifying
+questions in code generation. Using consistency-check before generating clarifications:
+**+9.84 percentage points improvement in GPT-4 Pass@1** on HumanEval and MBPP
+benchmarks.
+
+**Mechanism:** Most ambiguity is *apparent* ambiguity — the answer is present but
+requires synthesis across multiple parts of the request. A re-read finds it.
+True ambiguity (where the answer is genuinely absent) requires only a focused,
+targeted question.
+
+## Connection to Missing-Dimension Detector
+
+These two patterns are complementary:
+
+| Pattern | Fires when | Effect |
+|---------|-----------|--------|
+| Consistency-Check | About to ask a question | Eliminates redundant questions |
+| Missing-Dimension Detector | After collecting answers | Adds missing critical questions |
+
+Together: fewer questions, better coverage.
+
+## Research Basis
+
+> **ClarifyGPT** (arXiv 2310.10996) — Consistency-check before clarification generation.
+> +9.84pp GPT-4 Pass@1 on HumanEval + MBPP.
+> Applied: Step 3.75 added to fire-1d-discuss.md; per-step self-check added to
+> fire-scaffold.md Step 5 in v12.3.

package/skills-library/_general/methodology/DEAD_ENDS_SHELF.md

@@ -12,11 +12,11 @@ When an agent hits a wall — code that won't compile, an API that won't respond
 
 > **Philosophy:** A stuck agent with degraded context is the worst possible solver. A fresh agent with full context and documented prior attempts is the best. Stop burning tokens on dead ends — rotate the problem to a fresh mind.
 
-> **v11.3 change:** Dead ends are now tagged entries in `breadcrumbs/FAILURES.md` instead of a separate `DEAD-ENDS.md` file. This reduces file count and aligns with the on-demand breadcrumb protocol.
+> **v11.3 change:** Dead ends are tagged entries in the project's failure log, distinguished by the `[DEAD-END]` tag.
 
 ---
 
-## Location: `.planning/breadcrumbs/FAILURES.md`
+## Location: `.planning/FAILURES.md`
 
 Dead-end entries live alongside regular failure entries, distinguished by the `[DEAD-END]` tag. They are:
 - **Written by:** Any agent that hits a dead end (executor, planner, verifier, researcher)
@@ -84,7 +84,7 @@ For critical blockers: escalate to the user via checkpoint, don't shelve.
 When a task hits the shelve trigger:
 
 1. **Stop working on this task** — don't burn more tokens
-2. **Write a `[DEAD-END]` entry** to `.planning/breadcrumbs/FAILURES.md` using the format above
+2. **Write a `[DEAD-END]` entry** to `.planning/FAILURES.md` using the format above
 3. **On first write:** If FAILURES.md doesn't exist, create it with a `# Failures` header first
 4. **Move to next task** — the agent continues with remaining work
 5. **Note in RECORD.md** — "Task X tagged [DEAD-END], moved to Task Y"
@@ -114,7 +114,7 @@ In recovery mode, read FAILURES.md and filter for `[DEAD-END]` entries:
 
 **On every session start, a fresh Claude instance:**
 
-1. Read `.planning/breadcrumbs/FAILURES.md` (if it exists)
+1. Read `.planning/FAILURES.md` (if it exists)
 2. Filter for `[DEAD-END]` tagged entries
 3. For the highest-priority entry:
    - Review the problem, prior attempts, and untested hypotheses

package/skills-library/_general/methodology/DISTILL_NOT_DUMP.md

@@ -0,0 +1,108 @@
+---
+name: DISTILL_NOT_DUMP
+category: methodology
+description: Handoffs and context transfers must distill decisions, not dump exploration reasoning
+version: 1.0.0
+tags: [handoff, context-management, session-continuity, warrior, planning-execution-gap]
+---
+
+# DISTILL — NOT DUMP
+
+## Problem
+
+A handoff or context file contains:
+- Full planning discussion transcripts
+- "We considered A, B, C... decided on B because..."
+- Every intermediate hypothesis from debugging
+- All the reasoning that led to the current architecture
+
+A fresh Claude instance reads this and now has a **planning-contaminated context**.
+It knows WHY decisions were made, which makes it second-guess WHAT to execute.
+Execution quality degrades because the agent is still in planning mode.
+
+**Goose (Block) research finding:** Planning context actively degrades execution.
+An agent that knows all the alternatives considered will hedge, caveat, and
+reconsider instead of executing decisively.
+
+## Solution
+
+Separate WHAT WAS DECIDED from HOW WE GOT THERE. Handoffs capture only the first.
+
+### What to INCLUDE
+
+```
+- Final decision: "Use JWT with 15-minute expiry + refresh tokens"
+- Current phase and task: "Phase 3 / Task 2 — implement refresh endpoint"
+- Known constraints: "MySQL 8.0, no Redis available in this environment"
+- Blockers: "migration 096 must run before this task"
+- File paths and exact names: "auth/refreshToken.js — does not exist yet"
+```
+
+### What to PRUNE
+
+```
+- Why we chose JWT over sessions (exploration history)
+- The 3 approaches we considered for token storage
+- The failed experiment with cookies
+- "We discussed whether to use..."
+- "Originally we thought... but then decided..."
+```
+
+## Implementation: Context Pruning Step
+
+Add this step to handoff creation commands (fire-5-handoff.md, warrior-handoff.md):
+
+```markdown
+### Step 2.5: Context Pruning Discipline
+
+Before writing the handoff, classify each piece of context:
+
+KEEP (execution-critical):
+  - Current task and next action
+  - Final decisions made (what, not why)
+  - Constraints that affect implementation
+  - Known blockers or prerequisites
+  - File paths, names, and state
+
+PRUNE (planning artifacts):
+  - Reasoning chains that led to decisions
+  - Alternatives that were rejected
+  - Exploration history and "we tried X"
+  - Hypothesis chains from debugging (keep SOLUTION, prune PATH TO SOLUTION)
+  - Discussion summaries
+
+Rule: If removing this information would not prevent a fresh agent from
+executing the next task correctly → PRUNE IT.
+```
+
+## The Litmus Test
+
+For every sentence in a handoff, ask:
+
+> "Does a fresh agent NEED this to execute the next task, or does it just help
+> understand HOW WE GOT HERE?"
+
+If the answer is "understand how we got here" → prune it.
+
+## Why This Matters for Dominion Flow
+
+The WARRIOR handoff cycle is the core continuity mechanism. Its value is **session
+velocity** — a fresh instance should be able to pick up exactly where we left off
+at full speed. Verbose handoffs slow this down:
+- Fresh agent must read more before acting
+- Planning context bleeds into execution mode
+- Hedging and reconsideration appear in execution output
+
+A distilled handoff of 200 lines outperforms a comprehensive dump of 2000 lines
+every time.
+
+## Related Patterns
+
+- `TIERED_CONTEXT_ARCHITECTURE.md` — Context hierarchy: project → phase → task
+
+## Research Basis
+
+> **Goose (Block) history-clear pattern** — Planning context degrades execution quality.
+> Agents with full planning history in context hedge and reconsider during execution.
+> Applied: Step 2.5 (Context Pruning Discipline) added to fire-5-handoff.md in v12.3.
+> Core principle: WARRIOR handoff must DISTILL not DUMP.

package/skills-library/_general/methodology/EXECUTION_PROGRESS_MONITOR.md

@@ -0,0 +1,157 @@
+# Execution Progress Monitor & Heartbeat
+
+> Real-time progress tracking for long-running autonomous sessions with timeout enforcement and health checks.
+
+**When to use:** During `/fire-autonomous` runs, long `/fire-3-execute` sessions, or any multi-phase execution that runs 30+ minutes.
+
+---
+
+## Progress File Pattern
+
+Write a progress file that any external tool can read:
+
+```javascript
+// .planning/execution-progress.json
+{
+  "session_id": "auto-2026-03-09-1430",
+  "started_at": "2026-03-09T14:30:00Z",
+  "last_heartbeat": "2026-03-09T14:45:23Z",
+  "status": "executing",  // executing | verifying | reviewing | blocked | completed
+  "current_phase": 3,
+  "total_phases": 7,
+  "current_task": "Implementing cart checkout API",
+  "progress": {
+    "phases_completed": 2,
+    "phases_remaining": 5,
+    "current_phase_progress": 0.6,  // 60% of current phase
+    "tasks_completed": 12,
+    "tasks_total": 20
+  },
+  "agents": {
+    "active": 2,
+    "completed": 5,
+    "failed": 0,
+    "names": ["executor-backend", "executor-frontend"]
+  },
+  "metrics": {
+    "elapsed_seconds": 923,
+    "estimated_remaining_seconds": 1500,
+    "tokens_used": 45000,
+    "tool_calls": 89
+  },
+  "last_event": "Completed breath 2 of phase 3 — 4 tasks done, 3 remaining",
+  "errors": []
+}
+```
+
+---
+
+## Heartbeat Integration in fire-3-execute
+
+Add heartbeat updates at key points during execution:
+
+```markdown
+### Heartbeat Protocol
+
+Update `.planning/execution-progress.json` at these events:
+
+1. **Phase start:** status = "executing", current_phase = N
+2. **Breath complete:** Update current_phase_progress, tasks_completed
+3. **Agent spawn:** Increment agents.active, add to agents.names
+4. **Agent complete:** Decrement agents.active, increment agents.completed
+5. **Agent failure:** Increment agents.failed, add to errors
+6. **Verification start:** status = "verifying"
+7. **Review start:** status = "reviewing"
+8. **Phase complete:** Increment phases_completed
+9. **Blocker:** status = "blocked", add to errors
+10. **Session end:** status = "completed"
+
+Always update `last_heartbeat` timestamp on every write.
+```
+
+---
+
+## Timeout Enforcement
+
+```markdown
+### Per-Agent Timeout
+
+When spawning any agent (executor, reviewer, verifier):
+
+  timeout = agent_type == "executor" ? 10 minutes
+          : agent_type == "reviewer" ? 5 minutes
+          : agent_type == "verifier" ? 5 minutes
+          : 3 minutes  # default
+
+  IF agent does not return within timeout:
+    1. Log timeout to execution-progress.json errors
+    2. Mark agent as failed
+    3. Continue with remaining agents (don't block on hung agent)
+    4. If critical agent (executor), trigger circuit breaker
+
+### Session Timeout
+
+  max_session_duration = 60 minutes (configurable)
+
+  IF elapsed_seconds > max_session_duration:
+    1. Complete current agent (don't interrupt mid-task)
+    2. Save progress to execution-progress.json
+    3. Create WARRIOR handoff with resume point
+    4. Display: "Session timeout — use /fire-autonomous --from-phase {N} to resume"
+```
+
+---
+
+## Status Display Command
+
+Read the progress file and display human-readable status:
+
+```markdown
+### Progress Display (for /fire-dashboard integration)
+
+Read .planning/execution-progress.json and display:
+
+┌──────────────────────────────────────────────┐
+│ EXECUTION PROGRESS                            │
+├──────────────────────────────────────────────┤
+│ Phase: 3/7 — Cart Checkout API                │
+│ Progress: ████████████░░░░░░░░ 60%            │
+│ Tasks: 12/20 completed                        │
+│ Active agents: 2 (executor-backend, frontend) │
+│ Elapsed: 15m 23s | ETA: ~25m                  │
+│ Last: Completed breath 2 — 4 tasks done       │
+│ Health: ✓ (heartbeat 3s ago)                  │
+└──────────────────────────────────────────────┘
+
+IF last_heartbeat > 2 minutes ago:
+  Display: "⚠ Heartbeat stale (last update {N}s ago) — agent may be stuck"
+
+IF errors.length > 0:
+  Display: "Errors: {errors.length} — {errors[0]}"
+```
+
+---
+
+## Kill Switch
+
+```markdown
+### Emergency Stop
+
+Create `.planning/.stop-execution` file to signal graceful shutdown:
+
+  IF file_exists('.planning/.stop-execution'):
+    1. Finish current task (don't abandon mid-write)
+    2. Save progress
+    3. Create handoff
+    4. Delete .stop-execution file
+    5. Display: "Execution stopped by kill switch"
+
+Alternative: Ctrl+C or /fire-loop-stop
+```
+
+---
+
+## Sources
+
+- Internal gap analysis: GAP-AGENT-5 (Progress Monitor/Heartbeat)
+- Anthropic: Agent Teams progress tracking patterns (2026)