feed-the-machine 1.0.0

package/ftm-council/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ftm-council
+description: Multi-AI deliberation council that sends problems to Claude, Codex, and Gemini as equal peers, then loops through rounds of debate until 2-of-3 agree on a decision. Use when the user wants a second (and third) opinion, says "council this", "get other opinions", "what would other AIs think", "debate this", "multi-model", "ftm-council", or wants to cross-check a decision, architecture choice, debugging approach, or any problem where diverse AI perspectives would reduce blind spots. Especially valuable for debugging hard problems, architecture decisions, code review, and any situation where confirmation bias from a single model is a risk. Even if the user just says "I'm not sure about this approach" or "sanity check this", consider invoking the council.
+---
+
+## Events
+
+### Emits
+- `review_complete` — when the council reaches a majority verdict (2-of-3 agreement) or synthesizes a final recommendation after 5 rounds
+- `task_completed` — when the deliberation session concludes and a verdict is returned to the caller
+
+### Listens To
+(none — council is invoked explicitly by the user or by ftm-executor when an INTENT.md conflict requires arbitration)
+
+## Blackboard Read
+
+Before starting, load context from the blackboard:
+
+1. Read `~/.claude/ftm-state/blackboard/context.json` — check current_task, recent_decisions, active_constraints
+2. Read `~/.claude/ftm-state/blackboard/experiences/index.json` — filter entries by tags matching the current decision domain
+3. Load top 3-5 matching experience files for past council verdicts and how well they held up
+4. Read `~/.claude/ftm-state/blackboard/patterns.json` — check execution_patterns for what types of decisions benefited most from multi-model review
+
+If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.
+
+# FTM Council
+
+Three peers — a subagent investigator, Codex, and Gemini — independently research the codebase and deliberate on a problem through structured rounds of debate. No single model is the authority. Each model explores the code on its own, forms its own conclusions from what it finds, and only then enters deliberation. The council converges through majority vote: when 2 of 3 agree, that's the decision. If 5 rounds pass without majority agreement, the orchestrator synthesizes the best elements from all three positions and presents the user with a clear summary of where the models agreed, where they diverged, and a recommended path forward.
+
+## Why Independent Research Matters
+
+Each model explores the codebase independently — different attention patterns, different navigation instincts, different focus areas. This produces genuinely diverse perspectives grounded in what each model actually found, not three reactions to one curated framing.
+
+## Prerequisites
+
+Check tool availability before starting. Read `references/protocols/PREREQUISITES.md` for the full availability check, fallback logic, timeout configuration, and working directory setup.
+
+Quick check:
+```bash
+which codex && which gemini
+```
+If either is missing, tell the user what to install and stop — don't try to run a degraded council without informing them.
+
+## The Protocol
+
+### Auto-Invocation Mode
+
+Two invocation modes:
+1. **User-invoked** (default): Frame the problem in Step 0, proceed through protocol.
+2. **Auto-invoked**: Another skill provides a pre-framed conflict payload (containing `CONFLICT TYPE`, `ORIGINAL INTENT`, `CODEX'S CHANGE`, etc.). Skip Step 0, use the payload directly, include DEBUG.md history, run Steps 1-5, and return a structured `COUNCIL VERDICT` to the caller without user interaction.
+
+---
+
+### Step 0: Frame the Problem
+
+> **Note:** Skipped in auto-invocation mode. If a structured conflict payload was provided, proceed directly to Step 1.
+
+Distill the user's request into a self-contained **council prompt** — a clear problem statement with investigation entry points but no pre-read code. Models read the code themselves.
+
+Read `references/protocols/STEP-0-FRAMING.md` for the full framing guide, including what to include, what to exclude, and the structured payload format.
+
+Show the user the framed prompt before proceeding: "Here's what I'll send to the council — does this capture the problem?" Wait for confirmation or edits.
+
+---
+
+### Step 1: Independent Research (Round 1)
+
+**You (the orchestrator) are NOT a peer in this step.** Do not form your own position yet. Spawn three independent investigations in parallel and collect the results.
+
+Read `references/prompts/CLAUDE-INVESTIGATION.md`, `references/prompts/CODEX-INVESTIGATION.md`, and `references/prompts/GEMINI-INVESTIGATION.md` for the full prompt templates for each model.
+
+Present results with a structured comparison showing each model's research, position, key evidence, and an alignment check (agreement areas, divergence points, majority forming?).
+
+---
+
+### Step 2: Check for Early Consensus
+
+After each round, check if 2 of 3 positions substantially agree. "Substantially agree" means they recommend the same approach, even if they phrase it differently or differ on minor details. Don't require identical wording — look for the same core recommendation.
+
+If majority exists → jump to **Step 5: Verdict**.
+If not → continue to the next rebuttal round.
+
+---
+
+### Step 3: Rebuttal Rounds (Rounds 2-5)
+
+Each model sees the other two models' previous positions and must respond directly to their evidence. Read `references/prompts/REBUTTAL-TEMPLATE.md` for the full rebuttal prompt template. Use same CLI flags for follow-up research. Present results highlighting what changed and whether consensus is forming.
+
+---
+
+### Step 4: Repeat or Escalate
+
+After each rebuttal round, check for majority agreement (Step 2).
+
+If after 5 rounds there's still no majority:
+- This is a genuinely hard problem with legitimate disagreement
+- Synthesize the three final positions into a summary
+- Highlight the core tension — what's the fundamental tradeoff they can't agree on?
+- Note which models examined which parts of the codebase — incomplete research might explain persistent disagreement
+- Present the user with 2-3 concrete options (mapped to the council positions) and let them decide
+
+---
+
+### Step 5: Verdict
+
+When 2 of 3 agree, present: decision, which models agreed, dissent, evidence basis, why the majority won, what the dissent raised that's still valid, and recommended action. Ask if the user wants to proceed or dig into the dissent.
+
+**Auto-invocation:** Return structured `COUNCIL VERDICT` with `decision` (update_intent/revert_fix), `round`, `agreed_by`, `dissent`, `reasoning`, `debug_log_entry`. Do not ask the user — return directly to the calling skill.
+
+---
+
+## Practical Considerations
+
+### Conversation State
+Orchestrator holds state between rounds. Codex and Gemini are stateless — every prompt must include full history.
+
+### When NOT to Council
+Trivial questions, pure execution requests, pure opinion with no code to investigate, or when the user says "just do it". Exception: always proceed when auto-invoked by ftm-executor.
+
+---
+
+## Blackboard Write
+
+After completing, update the blackboard:
+
+1. Update `~/.claude/ftm-state/blackboard/context.json`:
+   - Set current_task status to "complete"
+   - Append decision summary to recent_decisions including the verdict and which models agreed (cap at 10)
+   - Update session_metadata.skills_invoked and last_updated
+2. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` capturing decision domain, verdict, round reached, dissent summary, and whether the verdict held up
+3. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
+4. Emit `task_completed` event

package/ftm-council/references/prompts/CLAUDE-INVESTIGATION.md

@@ -0,0 +1,60 @@
+# Claude Investigation Prompt Template
+
+Use this for spawning the Claude subagent in Step 1 (and rebuttal rounds). Spawning via subagent keeps the investigation isolated from the orchestrator's accumulated context — this is critical for independent research.
+
+## Round 1: Independent Research
+
+```
+You are one of three AI peers in a deliberation council. The other two peers are Codex (OpenAI) and Gemini (Google). Your job is to independently investigate the following problem by reading the codebase, then give your honest, well-reasoned position.
+
+IMPORTANT: Do your own research. Read files, search code, trace through logic. Your position must be grounded in what you actually find in the code, not assumptions. Cite specific files and line numbers.
+
+PROBLEM:
+{council_prompt}
+
+WORKING DIRECTORY: {cwd}
+
+Instructions:
+1. Start by exploring the relevant parts of the codebase — read files, search for patterns, trace dependencies
+2. Take notes on what you find as you go
+3. After you've done sufficient research, formulate your position
+
+Give your response in this format:
+1. RESEARCH SUMMARY: What files you examined, what you found (with file:line references)
+2. POSITION: Your clear stance (1-2 sentences)
+3. REASONING: Why you believe this, grounded in specific code you read
+4. CONCERNS: What could go wrong with your approach
+5. CONFIDENCE: High/Medium/Low and why
+```
+
+## Rebuttal Rounds (Rounds 2-5)
+
+The rebuttal subagent also runs isolated so it doesn't anchor on the orchestrator's context.
+
+```
+Round {N} of the deliberation council.
+
+Here's what happened in the previous round. Each model independently researched the codebase and formed a position:
+
+PEER 1's research and position:
+{peer1_previous_full}
+
+PEER 2's research and position:
+{peer2_previous_full}
+
+YOUR previous research and position:
+{claude_previous_full}
+
+Now respond. You may do additional codebase research if you want to verify claims the other models made or investigate angles they raised. Then:
+
+1. Directly address the strongest point from each other model
+2. If another model cited code you haven't looked at, go read it and see if you agree with their interpretation
+3. State whether you've changed your position (and why, or why not)
+4. If you agree with another model, say so explicitly
+
+UPDATED POSITION: [same/changed] ...
+NEW EVIDENCE (if any): [anything new you found by following up on other models' research]
+KEY RESPONSE TO PEER 1: ...
+KEY RESPONSE TO PEER 2: ...
+REMAINING DISAGREEMENTS: ...
+```

package/ftm-council/references/prompts/CODEX-INVESTIGATION.md

@@ -0,0 +1,58 @@
+# Codex Investigation Prompt Template
+
+Use this for spawning Codex via CLI. The `--full-auto` flag gives Codex sandboxed read access to the workspace so it can explore files on its own.
+
+## Round 1: Independent Research
+
+```bash
+cd {cwd} && codex exec --full-auto "You are one of three AI peers in a deliberation council. The other two peers are a subagent investigator and Gemini (Google). Your job is to independently investigate the following problem by reading the codebase, then give your honest, well-reasoned position.
+
+IMPORTANT: Do your own research. Read files, search code, trace through logic. Your position must be grounded in what you actually find in the code, not assumptions. Cite specific files and line numbers.
+
+PROBLEM:
+{council_prompt}
+
+Instructions:
+1. Start by exploring the relevant parts of the codebase — read files, search for patterns, trace dependencies
+2. Take notes on what you find as you go
+3. After you have done sufficient research, formulate your position
+
+Give your response in this format:
+1. RESEARCH SUMMARY: What files you examined, what you found (with file:line references)
+2. POSITION: Your clear stance (1-2 sentences)
+3. REASONING: Why you believe this, grounded in specific code you read
+4. CONCERNS: What could go wrong with your approach
+5. CONFIDENCE: High/Medium/Low and why"
+```
+
+## Rebuttal Rounds (Rounds 2-5)
+
+Use `--full-auto` in rebuttal rounds as well — Codex may want to verify another model's claims by reading files it hadn't looked at before.
+
+```bash
+cd {cwd} && codex exec --full-auto "Round {N} of the deliberation council.
+
+Here's what happened in the previous round. Each model independently researched the codebase and formed a position:
+
+PEER 1's research and position:
+{peer1_previous_full}
+
+PEER 2's research and position:
+{peer2_previous_full}
+
+YOUR previous research and position:
+{codex_previous_full}
+
+Now respond. You may do additional codebase research if you want to verify claims the other models made or investigate angles they raised. Then:
+
+1. Directly address the strongest point from each other model
+2. If another model cited code you haven't looked at, go read it and see if you agree with their interpretation
+3. State whether you've changed your position (and why, or why not)
+4. If you agree with another model, say so explicitly
+
+UPDATED POSITION: [same/changed] ...
+NEW EVIDENCE (if any): [anything new you found by following up on other models' research]
+KEY RESPONSE TO PEER 1: ...
+KEY RESPONSE TO PEER 2: ...
+REMAINING DISAGREEMENTS: ..."
+```

package/ftm-council/references/prompts/GEMINI-INVESTIGATION.md

@@ -0,0 +1,58 @@
+# Gemini Investigation Prompt Template
+
+Use this for spawning Gemini via CLI. The `--yolo` flag lets Gemini auto-approve file reads so it can explore without getting stuck on permission prompts.
+
+## Round 1: Independent Research
+
+```bash
+cd {cwd} && gemini -p "You are one of three AI peers in a deliberation council. The other two peers are a subagent investigator and Codex (OpenAI). Your job is to independently investigate the following problem by reading the codebase, then give your honest, well-reasoned position.
+
+IMPORTANT: Do your own research. Read files, search code, trace through logic. Your position must be grounded in what you actually find in the code, not assumptions. Cite specific files and line numbers.
+
+PROBLEM:
+{council_prompt}
+
+Instructions:
+1. Start by exploring the relevant parts of the codebase — read files, search for patterns, trace dependencies
+2. Take notes on what you find as you go
+3. After you have done sufficient research, formulate your position
+
+Give your response in this format:
+1. RESEARCH SUMMARY: What files you examined, what you found (with file:line references)
+2. POSITION: Your clear stance (1-2 sentences)
+3. REASONING: Why you believe this, grounded in specific code you read
+4. CONCERNS: What could go wrong with your approach
+5. CONFIDENCE: High/Medium/Low and why" --yolo
+```
+
+## Rebuttal Rounds (Rounds 2-5)
+
+Use `--yolo` in rebuttal rounds as well — Gemini may want to verify another model's claims by reading files it hadn't looked at before.
+
+```bash
+cd {cwd} && gemini -p "Round {N} of the deliberation council.
+
+Here's what happened in the previous round. Each model independently researched the codebase and formed a position:
+
+PEER 1's research and position:
+{peer1_previous_full}
+
+PEER 2's research and position:
+{peer2_previous_full}
+
+YOUR previous research and position:
+{gemini_previous_full}
+
+Now respond. You may do additional codebase research if you want to verify claims the other models made or investigate angles they raised. Then:
+
+1. Directly address the strongest point from each other model
+2. If another model cited code you haven't looked at, go read it and see if you agree with their interpretation
+3. State whether you've changed your position (and why, or why not)
+4. If you agree with another model, say so explicitly
+
+UPDATED POSITION: [same/changed] ...
+NEW EVIDENCE (if any): [anything new you found by following up on other models' research]
+KEY RESPONSE TO PEER 1: ...
+KEY RESPONSE TO PEER 2: ...
+REMAINING DISAGREEMENTS: ..." --yolo
+```

package/ftm-council/references/prompts/REBUTTAL-TEMPLATE.md

@@ -0,0 +1,57 @@
+# Rebuttal Round Prompt Template
+
+Use this to construct the prompt sent to each model in rebuttal rounds (Steps 3-4). The prompt must be fully self-contained — Codex and Gemini are stateless between rounds, so every round's prompt must include the full history.
+
+## Template
+
+```
+Round {N} of the deliberation council.
+
+Here's what happened in the previous round. Each model independently researched the codebase and formed a position:
+
+MODEL A's research and position:
+{model_a_previous_full}
+
+MODEL B's research and position:
+{model_b_previous_full}
+
+MODEL C's research and position:
+{model_c_previous_full}
+
+Now respond. You may do additional codebase research if you want to verify claims the other models made or investigate angles they raised. Then:
+
+1. Directly address the strongest point from each other model
+2. If another model cited code you haven't looked at, go read it and see if you agree with their interpretation
+3. State whether you've changed your position (and why, or why not)
+4. If you agree with another model, say so explicitly
+
+UPDATED POSITION: [same/changed] ...
+NEW EVIDENCE (if any): [anything new you found by following up on other models' research]
+KEY RESPONSE TO MODEL A: ...
+KEY RESPONSE TO MODEL B: ...
+REMAINING DISAGREEMENTS: ...
+```
+
+## Construction Rules
+
+- Replace `{model_a/b/c_previous_full}` with each model's complete response from the prior round — research summary, position, reasoning, concerns, and confidence
+- Do NOT summarize or truncate prior responses — the full research context is what allows models to verify each other's findings
+- Include ALL prior rounds' positions if building a multi-round history, not just the most recent
+- Use the same CLI flags as Round 1 (`--full-auto` for Codex, `--yolo` for Gemini) so models can do follow-up research
+
+## Orchestrator State
+
+Between rounds, the orchestrator holds all state. Keep a running record of:
+- Each model's research findings per round (files examined, what was found)
+- Each model's position per round
+- Whether any model changed position and why
+
+This record feeds the next round's rebuttal prompt. Without it, models cannot engage meaningfully with each other's evidence.
+
+## What to Watch For
+
+When presenting round results to the user, highlight:
+- **Position changes**: which model moved and what evidence caused the shift
+- **New research**: if a model read files others hadn't looked at
+- **Convergence signal**: models independently finding the same evidence
+- **Persistent divergence**: models who've both read the same code and still disagree — this is a genuine hard problem

package/ftm-council/references/protocols/PREREQUISITES.md

@@ -0,0 +1,47 @@
+# Prerequisites: Tool Availability Checks
+
+## Required CLI Tools
+
+The council requires both external CLI tools to be installed and authenticated:
+
+- **Codex**: `npm install -g @openai/codex` (authenticated via `codex login`)
+- **Gemini**: `npm install -g @google/gemini-cli` (authenticated via Google)
+
+## Availability Check
+
+Before the first round, verify both tools are available:
+
+```bash
+which codex && which gemini
+```
+
+## Fallback Logic
+
+| Scenario | Action |
+|---|---|
+| Both tools missing | Tell the user what to install and stop — don't attempt a degraded council |
+| One tool missing | Report which tool is missing. A 2-model debate loses the tiebreaker benefit — ask the user if they want to proceed or install the missing tool first |
+| Auth failure at runtime | Report the error to the user. Continue with the remaining models. A 2-model debate is better than nothing |
+| Rate limit or sandbox error at runtime | Report the error. Continue with the remaining models |
+
+**Do not silently proceed with a degraded council.** Always tell the user which tool is unavailable and why. The tiebreaker value of a 3-model council is significant for close decisions.
+
+## Runtime Timeout Configuration
+
+Set timeouts per round type:
+
+- **Round 1 (Independent Research)**: 300s (5 minutes) — models are reading files and searching code
+- **Rebuttal rounds (2-5)**: 180s — less exploration, more focused follow-up
+
+If one model times out in any round, report it and continue with the other two.
+
+## Working Directory
+
+Make sure both CLI tools run from the same working directory as the current session. This ensures all models look at the same codebase.
+
+Pass `cd {cwd} &&` before CLI commands if needed:
+
+```bash
+cd /path/to/project && codex exec --full-auto "..."
+cd /path/to/project && gemini -p "..." --yolo
+```

package/ftm-council/references/protocols/STEP-0-FRAMING.md

@@ -0,0 +1,46 @@
+# Step 0: Frame the Problem
+
+> **Note:** This step is skipped in auto-invocation mode. If a structured conflict payload was provided, proceed directly to Step 1 using the payload as the council prompt.
+
+Take the user's request and distill it into a clear **council prompt** — a self-contained problem statement that makes sense without conversation history. The prompt should describe the problem and what a good answer looks like, but it should NOT include pre-read code. The models will read the code themselves.
+
+## What to Include
+
+- The specific question or decision to be made
+- File paths or areas of the codebase to start investigating (as pointers, not content)
+- Error messages or symptoms if it's a debugging problem
+- Decision criteria — what a good answer looks like
+- Any constraints the user has mentioned
+
+## What to Exclude
+
+- Pre-read file contents (each model reads files itself)
+- Your own analysis or opinion about the problem
+- Summaries of what the code does (let each model discover that)
+
+## Confirmation Gate
+
+Show the user the framed prompt before proceeding: "Here's what I'll send to the council — does this capture the problem?" Wait for confirmation or edits.
+
+## Structured Payload Format
+
+When creating the council prompt, use this structure:
+
+```
+PROBLEM:
+[Clear statement of the question or decision]
+
+CODEBASE ENTRY POINTS:
+[File paths or directories to investigate — no content, just paths]
+
+SYMPTOMS / ERROR MESSAGES:
+[If debugging: exact error text, stack traces, reproduction steps]
+
+DECISION CRITERIA:
+[What a good answer looks like — what tradeoffs matter here]
+
+CONSTRAINTS:
+[Any hard requirements, technology restrictions, or non-negotiables]
+```
+
+The prompt must be fully self-contained. A model dropped into a fresh session with only this prompt should know exactly what to investigate and what success looks like.

package/ftm-council.yml

@@ -0,0 +1,2 @@
+name: ftm-council
+description: Multi-AI deliberation council that sends problems to Claude, Codex, and Gemini as equal peers, then loops through rounds of debate until 2-of-3 agree on a decision. Use when the user wants a second (and third) opinion, says "council this", "get other opinions", "what would other AIs think", "debate this", "multi-model", "ftm-council", or wants to cross-check a decision, architecture choice, debugging approach, or any problem where diverse AI perspectives would reduce blind spots. Especially valuable for debugging hard problems, architecture decisions, code review, and any situation where confirmation bias from a single model is a risk. Even if the user just says "I'm not sure about this approach" or "sanity check this", consider invoking the council.

package/ftm-dashboard.yml

@@ -0,0 +1,4 @@
+---
+name: ftm-dashboard
+description: Session and weekly analytics dashboard for the FTM skill ecosystem. Reads events.log and blackboard state to show skills invoked, plans presented, approval rates, experiences recorded, and patterns promoted. Use when user says "dashboard", "analytics", "stats", "ftm-dashboard", "show session stats", or "how's the system doing".
+---

package/ftm-debug/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ftm-debug
+description: Deep multi-vector debugging war room that launches parallel agent teams to instrument, research, reproduce, hypothesize, solve, and verify tricky bugs. Use when a bug is stubborn, multi-turn debugging hasn't worked, the user says "debug this deeply", "war room this", "I can't figure out why", "this is driving me crazy", "launch the debug team", or any situation where standard debugging is insufficient. Also triggers on "/ftm-debug". Covers any codebase — frontend, backend, CLI tools, native apps, build systems, anything. Do NOT use for simple one-step fixes — this is the heavy artillery for problems that resist normal debugging.
+---
+
+## Events
+
+### Emits
+- `bug_fixed` — when the Reviewer agent approves a fix and the bug is confirmed resolved
+- `issue_found` — when investigation surfaces a specific problem (hypothesis confirmed, instrumentation reveals root cause)
+- `test_passed` — when the reproduction test passes after a fix, or when the full suite passes post-fix
+- `test_failed` — when the reproduction test fails, or when a fix attempt causes regressions
+- `error_encountered` — when an unexpected error halts the war room workflow (agent failure, unrecoverable blocker)
+- `task_completed` — when the debug session concludes with an approved and merged fix
+
+### Listens To
+- `test_failed` — auto-investigate: launch Phase 0 intake and deploy the war room agent team
+- `error_encountered` — diagnose the error: run codebase reconnaissance and begin targeted investigation
+
+## Blackboard Read
+
+Before starting, load context from the blackboard. Read `references/protocols/BLACKBOARD.md` for full protocol. Summary:
+
+1. Read `~/.claude/ftm-state/blackboard/context.json` — check current_task, recent_decisions, active_constraints
+2. Read `~/.claude/ftm-state/blackboard/experiences/index.json` — filter entries by task_type="bug" and tags matching the current error domain
+3. Load top 3-5 matching experience files for known fixes and failed approaches
+4. Read `~/.claude/ftm-state/blackboard/patterns.json` — check recurring_issues for matching symptoms and codebase_insights for relevant file patterns
+
+If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.
+
+---
+
+# Debug War Room
+
+Multi-vector deep debugging with parallel agent teams. When a bug resists normal debugging — you've tried the obvious, poked at it for multiple turns, and it's still not yielding — this skill escalates to a coordinated investigation across every angle simultaneously: instrumentation, research, reproduction, hypothesis, fix, and verification.
+
+## Why This Exists
+
+Hard bugs are hard because they hide across multiple dimensions. The symptom is in one place, the cause is in another, and the fix requires understanding both plus the invisible interactions between them. Single-threaded debugging (try a thing, see if it works, try another thing) is too slow and too narrow. The war room attacks from every direction at once.
+
+## Core Principle: Automate Everything Before Involving the User
+
+The entire point of the war room is that **agents do the work**. Every verification step, every test run, every log check, every "does it actually work?" confirmation must be performed by an agent before presenting results to the user. The user should receive a **verified, working result** — not a list of manual steps to try.
+
+- If you can run a command to check if the fix works, **run it**. Don't tell the user to run it.
+- "All tests pass" is necessary but NOT sufficient. The Reviewer must verify the actual runtime/visual result, not just test results.
+- If an agent produces a "How to Verify" section with manual steps, that's a failure of the process.
+
+Read `references/protocols/EDGE-CASES.md` for anti-patterns and fallback handling.
+
+---
+
+## The Process
+
+### Phase 0: Problem Intake
+
+Before launching agents, understand what you're debugging. This happens in the main conversation thread — no agents yet.
+
+**Flow:**
+1. Gather problem statement (ask targeted questions if needed — skip what's already known)
+2. Spawn an **Explore agent** for codebase reconnaissance
+3. Formulate investigation plan → present to user → proceed unless user objects
+
+Read `references/phases/PHASE-0-INTAKE.md` for full intake steps, Explore agent prompt, and investigation plan format.
+
+---
+
+### Phase 1: Parallel Investigation (the war room)
+
+Launch all investigation agents **simultaneously**. This is the core value — attacking from every angle at once.
+
+**Agents to launch in parallel:**
+- **Instrumenter** — adds debug logging and observability in its own worktree
+- **Researcher** — searches GitHub issues, Stack Overflow, docs, changelogs
+- **Reproducer** — creates a minimal failing test or trigger script
+- **Hypothesizer** — traces execution paths and forms ranked root cause theories
+
+**Decision:** Not every bug needs all agents. See agent selection guide in `references/phases/PHASE-1-TRIAGE.md` to determine which agents to skip for each bug type.
+
+Read `references/phases/PHASE-1-TRIAGE.md` for the agent selection guide and worktree strategy.
+
+Read `references/phases/PHASE-2-WAR-ROOM-AGENTS.md` for all four agent prompts (Instrumenter, Researcher, Reproducer, Hypothesizer).
+
+---
+
+### Phase 2: Synthesis & Solve
+
+After all Phase 1 agents complete:
+
+1. **Cross-reference findings** — do hypotheses match research? does reproduction confirm a hypothesis? are there contradictions?
+2. Present synthesis briefly to the user (Researcher finding / Reproducer status / top hypothesis / Instrumenter summary)
+3. **Launch the Solver agent** in a fresh worktree with full synthesis context
+
+**Decision:** If the Solver's fix is NEEDS REWORK, send feedback back for another iteration. Max 3 iterations before escalating.
+
+Read `references/phases/PHASE-3-TO-6-EXECUTION.md` for the full synthesis format, Solver agent prompt, and iteration rules.
+
+---
+
+### Phase 3: Review & Verify
+
+**HARD GATE — Cannot present to user without this phase.**
+
+1. Determine verification method BEFORE launching Reviewer (visual vs behavioral vs error-absence)
+2. If fix requires a restart, the Reviewer handles it — not the user
+3. Launch **Reviewer agent** independently of the Solver
+
+**Reviewer runs:** reproduction test → full test suite → build/lint → live runtime verification → visual verification (if applicable)
+
+**Decision:** APPROVED → proceed to Phase 4. NEEDS REWORK → back to Solver (max 3 total iterations). Still failing after 3 → escalate to user.
+
+Read `references/phases/PHASE-3-TO-6-EXECUTION.md` for Reviewer agent prompt, verification gate checklist, and escalation protocol.
+
+---
+
+### Phase 4: Present Results
+
+**Checkpoint before presenting:**
+- [ ] Reviewer agent was spawned (not Solver declaring victory)
+- [ ] Reviewer verdict includes actual evidence (output, screenshots, log snippets)
+- [ ] Visual evidence captured if bug was visual
+- [ ] Post-restart behavior verified if fix required restart
+- [ ] No "How to Verify" manual instructions in the presentation
+
+Once the Reviewer approves, present: root cause → what changed → verification already performed (with evidence) → commits.
+
+Wait for user confirmation, then: merge → clean up worktrees → remove debug instrumentation.
+
+Read `references/phases/PHASE-3-TO-6-EXECUTION.md` for the full result presentation format.
+
+---
+
+## Blackboard Write
+
+After completing, update the blackboard. Read `references/protocols/BLACKBOARD.md` for full write protocol. Summary:
+
+1. Update `~/.claude/ftm-state/blackboard/context.json` — set task complete, append decision summary
+2. Write experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` — root cause, hypotheses tested, fix approach, check_first_next_time
+3. Update `experiences/index.json` with the new entry
+4. Emit `task_completed` event
+
+## Config Read
+
+Before dispatching agents, read `~/.claude/ftm-config.yml`:
+- Use the `planning` model from the active profile for all investigation agents
+- If config missing, use session default