feed-the-machine 1.0.0 → 1.2.0

package/ftm-mind/SKILL.md

@@ -3,7 +3,7 @@ name: ftm-mind
 description: Unified OODA cognitive loop for the ftm system. Use for freeform `/ftm` or `/ftm-mind` requests, vague asks, mixed-tool workflows, Jira/ticket-driven work, or any request that should be understood before routing. Also handles explicit ftm skill invocations by honoring the requested skill while still doing a fast orientation pass for context, prerequisites, and approval gates. Triggers on open-ended requests like "help me think through this", bug reports, plan execution asks, Jira URLs, "make this better", mixed MCP asks like "check my calendar and draft a Slack message", and direct skill invocations like "/ftm-debug ..." or "/ftm-brainstorm ...". Do NOT use only when another ftm skill is already actively handling the task and no re-orientation is needed.
 ---
 
-# FTM Mind
+# Panda Mind
 
 `ftm-mind` is the reasoning core of the ftm ecosystem. It does not route by keyword alone. It observes the request, orients against live state and accumulated memory, decides the smallest correct next move, acts, then loops.
 
@@ -133,6 +133,62 @@ Interpretation rules:
 - "what would other AIs think" is a council request, not generic brainstorming
 - "rename this variable" is usually a micro direct task, not a routed skill
 
+### 1.5. Environment Discovery (Orient sub-phase)
+
+Before pattern matching or routing, probe the current environment to map available capabilities. This step runs automatically on the first request in a session, then caches results for 15 minutes.
+
+**Discovery sequence:**
+
+1. **MCP Server Probe** — List connected MCP servers by checking which tool namespaces are available:
+   - For each known MCP server (serena, supabase, playwright, freshservice-mcp, slack, gmail, mcp-atlassian-personal, lusha, apple-doc-mcp), check if tools with that prefix exist
+   - Record: server name, tools available, verified status
+
+2. **CLI Probe** — Check for installed CLIs on PATH:
+   - Essential: `node`, `python3`, `git`, `npm`
+   - FTM tools: `knip`, `codex` (OpenAI Codex CLI)
+   - Optional: `gh` (GitHub CLI), `jq`, `curl`
+   - For each: run `which <cmd>` and record path + version if available
+
+3. **Environment Variable Check** — Check for key env vars (existence only, never log values):
+   - `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`
+   - `JIRA_API_TOKEN`, `FRESHSERVICE_API_KEY`, `SLACK_BOT_TOKEN`
+   - Record: var name, is_set (boolean)
+
+4. **Write capabilities.json** to `~/.claude/ftm-state/blackboard/capabilities.json`:
+   ```json
+   {
+     "discovered_at": "2026-03-20T10:30:00Z",
+     "expires_at": "2026-03-20T10:45:00Z",
+     "capabilities": [
+       {
+         "name": "serena",
+         "type": "mcp",
+         "verified": true,
+         "last_verified_at": "2026-03-20T10:30:00Z",
+         "operations_verified": ["find_symbol", "search_for_pattern"],
+         "confidence": "verified"
+       },
+       {
+         "name": "node",
+         "type": "cli",
+         "verified": true,
+         "path": "/usr/local/bin/node",
+         "version": "20.11.0",
+         "confidence": "verified"
+       }
+     ]
+   }
+   ```
+
+5. **Cache logic** — If `capabilities.json` exists and `expires_at` > now, skip re-probing. If stale or missing, re-probe. User can force refresh by saying "refresh capabilities" or "recon".
+
+**How this affects planning:**
+
+When ftm-mind generates or routes to a plan, it MUST:
+- Check `capabilities.json` for every tool/MCP/CLI the plan references
+- If a required capability is `verified: false` or missing, use the skill's fallback from its manifest (## Fallbacks section)
+- If no fallback exists for a missing capability, warn the user: "Plan step N requires [capability] which is not available. Skip or find alternative?"
+
 ### 2. Blackboard Loading Protocol
 
 Read the blackboard in this order:
@@ -244,7 +300,7 @@ If `experiences/index.json` has no usable matches:
 - lean harder on current repo state and direct inspection
 - record the resulting experience aggressively after completion
 
-### 4. Capability Inventory: 16 FTM Skills
+### 4. Capability Inventory: 15 Panda Skills
 
 Orient must know all ftm capabilities before deciding whether to route or act directly.
 
@@ -265,8 +321,7 @@ Orient must know all ftm capabilities before deciding whether to route or act di
 | `ftm-retro` | The user wants a post-run retrospective, lessons learned, or execution review. |
 | `ftm-config` | The user wants ftm settings, model profile, or feature configuration changed. |
 | `ftm-git` | Any git commit or push is about to happen, the user asks to scan for secrets/credentials/API keys, or wants to verify no secrets are hardcoded before sharing code. MUST run before any commit or push operation — this is a mandatory security gate, not optional. |
-| `ftm-researcher` | The user wants thorough research on a topic, comparison of approaches, state-of-the-art analysis, or evidence-based investigation. Not for ideation (that is ftm-brainstorm). |
-| `ftm-map` | The user wants structural code queries: blast radius ("what breaks if I change X"), dependency chains ("what depends on Y"), code search ("where do we handle auth"), or codebase indexing ("map this codebase", "index this project"). Not for documentation updates (that is ftm-intent/ftm-diagram). |
+| `ftm-capture` | The user just completed a repeatable workflow and wants to save it as a reusable routine + playbook + reference doc. Triggers on "capture this", "save as routine", "codify this", "don't make me explain this again". Also suggest proactively when you detect the user doing something they've done before (matching blackboard experiences with same task_type 2+ times). |
 
 Routing heuristic:
 
@@ -442,9 +497,12 @@ Signals:
 - changes routing, integration, or cross-system references (API endpoints, project keys, board IDs)
 - the codebase being changed is unfamiliar or hasn't been read yet this session
 - the task involves both code changes AND communication/coordination
+- **calls any production API that creates, updates, or deletes resources** (Okta, Freshservice, AWS, any external service with real consequences)
 
 The reason forced escalation exists: tasks that touch external systems or multiple files feel simple in the moment but have hidden ordering dependencies, stakeholder coordination needs, and blast radius that only becomes visible after you've already started grinding. A 2-minute plan catches these. Grinding without one wastes the user's time when you go in the wrong direction.
 
+**The Hindsight incident**: In March 2026, a task that "felt small" — set up SSO for Hindsight — resulted in autonomous creation of Okta groups in production, user assignments, Freshservice records, a service catalog item, and S3 config changes. The model never presented a plan. It never asked for approval on any phase. It just researched and executed. This is exactly what forced escalation prevents. If the task will call APIs that modify production state, it is medium. Full stop.
+
 Typical examples:
 
 - fix a flaky test with several hypotheses
@@ -514,36 +572,61 @@ Escalate when:
 - the complexity is obvious from the start
 - forced escalation signals are present (see Medium and Large sections above)
 
-### 9. Approval Gates
+### 9. Approval Gates (HARD STOP — NOT OPTIONAL)
+
+**This section is a circuit breaker, not a suggestion. If you are about to call a tool that creates, updates, or deletes a record in an external system, you MUST stop and get explicit user approval FIRST. No exceptions. No "the user implied it." No "it's part of the plan." STOP and ASK.**
+
+The reason this exists: in March 2026, ftm-mind took a Hindsight SSO task and autonomously created Okta groups, added users to production Okta, created Freshservice records, created a service catalog item, and modified S3 workflow configs — all without asking once. The user's `approval_mode` was `plan_first`. The model rationalized past every gate because it "had momentum." That is exactly the failure mode this section prevents.
+
+#### What requires approval (STOP before each one)
 
-Ask for approval only for external-facing actions.
+Every individual external mutation needs its own approval. "The user approved the plan" does not mean "the user approved every API call in the plan." Present what you're about to do, wait for "go" / "yes" / "approved", then execute that one action.
 
-External-facing means actions that leave the local workspace and affect people, systems of record, or deployed environments.
+- **Okta**: creating apps, groups, assigning users, modifying policies
+- **Freshservice**: creating tickets, records, catalog items, custom objects
+- **Jira / Confluence**: creating or updating issues, pages, comments
+- **Slack / Email**: sending messages (draft-before-send protocol applies)
+- **Calendar**: creating or modifying events
+- **S3 / cloud storage**: writing or modifying objects
+- **Browser forms**: submitting data through playwright/puppeteer
+- **Deploys**: any production-affecting operation
+- **Git remote**: pushes, PR creation
 
-Approval required:
+When multiple mutations are part of one plan, batch the approval request by phase — not one API call at a time (that would be annoying), but not "approve the whole plan and I'll do 15 things silently" either. Group related mutations:
 
-- sending Slack messages
-- sending emails
-- creating or mutating Jira, Confluence, or Freshservice records
-- changing calendar events
-- submitting browser forms or uploads
-- deploys and production-affecting operations
-- remote pushes or other outward publication steps
+```
+Phase 1 ready — Okta setup:
+  - Create SAML app "Hindsight"
+  - Create groups: hindsight_admins, hindsight_users
+  - Add 3 users to hindsight_users
+
+Proceed with Phase 1? (yes/skip/modify)
+```
 
-Auto-proceed without approval:
+Then after Phase 1 completes, present Phase 2 before executing it.
 
-- local code edits
-- local documentation updates
+#### What auto-proceeds (no approval needed)
+
+- local code edits, documentation updates
 - tests, lint, builds, audits
-- local git inspection
-- local branches and local commits
-- reading from any MCP
+- local git operations (branch, commit, inspection)
+- reading from any MCP or API (GET requests)
 - blackboard reads and writes
-- saving drafts to `.ftm-drafts/` (the draft is local; sending is what needs approval)
+- saving drafts to `.ftm-drafts/`
+
+#### The momentum trap
 
-If the user has explicitly requested stricter gates, honor that preference.
+If you notice yourself thinking any of these, STOP — you are rationalizing past a gate:
 
-If authentication or permission is missing, ask instead of guessing.
+- "The user clearly wants this done, I'll just do it"
+- "This is part of the approved plan"
+- "I already started, might as well finish"
+- "It's just one more API call"
+- "The user will appreciate me being proactive"
+
+None of these override the gate. Present the action, wait for approval, then execute.
+
+If the user has explicitly requested stricter gates, honor that preference. If authentication or permission is missing, ask instead of guessing.
 
 ### 10. Ask-the-User Heuristic
 
@@ -723,45 +806,6 @@ Approve? Or adjust the approach.
 
 This gives the user control over the *strategy* even when delegating to skills.
 
-### Research tasks → ftm-researcher
-
-Route to ftm-researcher when the request is primarily about gathering information,
-comparing approaches, or understanding the state of the art on a topic.
-
-Signals:
-- "research X", "find out about Y", "what's the state of the art on Z"
-- "compare approaches to W", "how do others handle X"
-- "deep dive into X", "investigate Y", "look into Z"
-- "find me examples of X", "what's out there for Y"
-- The user wants facts and evidence, not ideation or planning
-
-Distinguish from ftm-brainstorm:
-- Brainstorm: user has an idea and wants to develop it → exploratory, iterative, extractive
-- Researcher: user wants information about a topic → factual, evidence-based, comprehensive
-- Ambiguous: if the user seems to want both exploration AND research, route to brainstorm (which calls researcher internally)
-
-Mode selection:
-- "quick look" / "briefly" → quick mode
-- Default → standard mode
-- "deep dive" / "thorough" / "comprehensive" → deep mode
-
-### Structural code queries → ftm-map
-
-Route to ftm-map when the request involves understanding code structure and dependencies:
-
-**Strong signals (route immediately):**
-- "what breaks if I change X" / "blast radius"
-- "what depends on X" / "dependency chain"
-- "what calls X" / "who calls X"
-- "where do we handle X" (code search, not docs)
-- "map this codebase" / "index this project"
-
-**Disambiguation:**
-- "document this function" → ftm-intent (documentation), NOT ftm-map
-- "show the architecture diagram" → ftm-diagram, NOT ftm-map
-- "search for X in the codebase" → could be ftm-map (if structural) or Grep (if text-literal)
-- If `.ftm-map/map.db` doesn't exist and the query is structural, suggest bootstrapping first
-
 ### 2. Choose direct vs routed execution
 
 Use direct execution when:
@@ -793,7 +837,15 @@ If the next move will reveal new information, plan to re-enter Observe after the
 
 ## Act
 
-Act is clean, decisive execution.
+Act is clean, decisive execution — but execution of **approved** work only.
+
+**Pre-Act checkpoint**: Before executing anything, verify:
+
+1. If `approval_mode` is `plan_first` or `always_ask`, did the user explicitly approve the plan? (Words like "go", "yes", "approved", "do it", "ship it" — not silence, not your own narration of the plan.)
+2. If the task involves external mutations (see Approval Gates section 9), have you presented the specific actions and received approval?
+3. If neither condition applies, proceed.
+
+If you cannot point to a specific user message that approved the plan, you have not received approval. Go back to Decide and present the plan.
 
 ### 1. Direct action
 
@@ -876,6 +928,7 @@ After every completed task — not just "meaningful" ones — update the blackbo
 
 1. Update `context.json` — set `current_task` to reflect what was done, append to `recent_decisions`
 2. Update `session_metadata.skills_invoked` if a skill was used
+3. If environment discovery ran this session, ensure `capabilities.json` is written to `/Users/kioja.kudumu/.claude/ftm-state/blackboard/capabilities.json` with the current snapshot (schema: `capabilities.schema.json` in the same directory)
 
 **After task completion, always record an experience file:**
 
@@ -934,13 +987,12 @@ Use these as behavioral tests.
 When the user asks for help, shows empty input, or says `?` or `menu`, show:
 
 ```text
-FTM Skills:
+Panda Skills:
   /ftm brainstorm [idea]     — Research-backed idea development
   /ftm execute [plan-path]   — Autonomous plan execution with agent teams
   /ftm debug [description]   — Multi-vector deep debugging war room
   /ftm audit                 — Wiring verification
   /ftm council [question]    — Multi-model deliberation
-  /ftm research [topic]      — Deep parallel research engine
   /ftm intent                — Manage INTENT.md documentation
   /ftm diagram               — Manage architecture diagrams
   /ftm codex-gate            — Run adversarial Codex validation
@@ -984,3 +1036,58 @@ Avoid these failures:
 6. Read before write.
 7. Session trajectory matters.
 8. The best route is often no route at all.
+
+## Requirements
+
+- tool: `git` | required | codebase state inspection (git status, git log)
+- config: `~/.claude/ftm-config.yml` | optional | approval_mode, execution preferences
+- reference: `~/.claude/skills/ftm-mind/references/mcp-inventory.md` | required | MCP capability routing table
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state and preferences
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | experience retrieval index
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | promoted patterns for orientation
+
+## Risk
+
+- level: low_write
+- scope: writes blackboard context and experience files; local code edits only on micro/small direct tasks; routes to other skills for larger work
+- rollback: blackboard writes can be reverted by editing JSON files; no destructive mutations performed directly
+
+## Approval Gates
+
+- trigger: task_size >= medium AND involves external systems | action: present numbered plan and wait for explicit user approval
+- trigger: any external mutation (Okta, Freshservice, Jira, Slack, email, calendar, S3, deploys, git push) | action: present phase-level approval request before executing each mutation
+- trigger: task_size == small AND approval_mode == always_ask | action: show pre-flight summary before proceeding
+- complexity_routing: micro → auto | small → auto (pre-flight summary if plan_first) | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: blackboard context.json missing or malformed | action: treat as empty state, proceed at full capability using live observation
+- condition: experiences/index.json empty or no matching entries | action: skip experience retrieval, lean on current repo state and direct inspection
+- condition: patterns.json missing | action: skip pattern application, rely on direct analysis
+- condition: ftm-config.yml missing | action: default to plan_first approval_mode and balanced model profile
+- condition: mcp-inventory.md missing | action: rely on built-in MCP routing heuristics from skill body
+- condition: requested ftm skill unavailable | action: notify user and attempt direct handling or alternate routing
+
+## Capabilities
+
+- mcp: `git` | optional | codebase state, diffs, history, commits
+- mcp: `mcp-atlassian-personal` | optional | Jira/Confluence reads for ticket-driven work
+- mcp: `slack` | optional | Slack context reads, draft messages
+- mcp: `gmail` | optional | email reads, drafts
+- mcp: `google-calendar` | optional | calendar inspection for scheduling requests
+- mcp: `freshservice-mcp` | optional | IT ticketing reads
+- mcp: `sequential-thinking` | optional | multi-step reflective reasoning
+- mcp: `playwright` | optional | browser automation for visual tasks
+- mcp: `glean_default` | optional | internal company knowledge search
+- mcp: `context7` | optional | external library documentation
+- env: none required
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-mind"
+- task_type: string — detected task type (feature, bug, refactor, investigation, etc.)
+- task_size: string — micro | small | medium | large
+- route: string — direct | skill name routed to
+- duration_ms: number — time from observe to act completion
+- blackboard_updated: boolean — whether context.json and experience were written

package/ftm-pause/SKILL.md

@@ -131,3 +131,46 @@ Tailor the counts to the skill: brainstorm shows decisions + turns, executor sho
 **Skill invoked, no user interaction yet:** Save what exists (Phase 0 scan, initial question). "Next Step" notes that the user hasn't answered yet.
 
 **Large state:** Do not truncate. Some sessions produce massive state files. Completeness is required for reliable restoration.
+
+## Requirements
+
+- reference: `~/.claude/ftm-state/STATE.md` | optional | existing state file to overwrite
+- reference: `~/.claude/ftm-pause/references/protocols/SKILL-RESTORE-PROTOCOLS.md` | required | per-skill capture field specifications
+- reference: `~/.claude/ftm-pause/references/protocols/VALIDATION.md` | required | pre-write and post-write validation checklist
+- tool: `git` | optional | git branch and commit hash capture for state file
+
+## Risk
+
+- level: low_write
+- scope: writes ~/.claude/ftm-state/STATE.md only; does not modify project source files or blackboard experiences; overwrites existing STATE.md without backup
+- rollback: no project mutations; prior STATE.md is overwritten (not backed up) by design
+
+## Approval Gates
+
+- trigger: multiple skills active and unclear which to pause | action: ask user which skill state to save before writing
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ~/.claude/ftm-state/ directory doesn't exist | action: create directory before writing STATE.md
+- condition: no ftm skill detected as active | action: report "No active ftm session detected" and list which skills this applies to
+- condition: git not available | action: omit git_branch and git_commit fields from state file frontmatter
+- condition: artifact files referenced in state don't exist on disk | action: note as "path recorded but file not found" in Artifacts section
+
+## Capabilities
+
+- cli: `git` | optional | branch name and commit hash for state file metadata
+
+## Event Payloads
+
+### session_paused
+- skill: string — "ftm-pause"
+- saved_skill: string — the ftm skill whose state was saved
+- phase: string — phase at which the session was paused
+- state_file: string — absolute path to written STATE.md
+- artifacts_count: number — number of artifact paths recorded
+
+### task_completed
+- skill: string — "ftm-pause"
+- saved_skill: string — the ftm skill whose state was saved
+- state_file: string — absolute path to STATE.md

package/ftm-researcher/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: ftm-researcher
+description: Deep parallel research engine with 7 domain-specialized finder agents, adversarial review via ftm-council, adaptive wave-based search, structured reconciliation with disagreement maps, credibility scoring, and conversational iteration. Use when the user wants thorough research on any topic — "research X", "find out about Y", "what's the state of the art on Z", "compare approaches to W", "deep dive into X", "look into Y". Also invoked by ftm-brainstorm for its research sprints. Triggers on "research", "investigate", "deep dive", "state of the art", "compare", "find examples of", "what's out there for", "how do others handle", "find me evidence", "look into". For idea exploration and brainstorming, use ftm-brainstorm instead (which calls ftm-researcher internally for research).
+---
+
+# ftm-researcher
+
+Deep parallel research engine with 7 domain-specialized finder agents, adversarial review via ftm-council, adaptive wave-based search, structured reconciliation with disagreement maps, credibility scoring, and conversational iteration.
+
+## Events
+
+### Emits
+- `research_complete` — when synthesis pipeline finishes and structured output is ready
+  - Payload: `{ query, mode, findings_count, consensus_count, contested_count, unique_count, sources_count, duration_ms }`
+- `task_completed` — when the full research session finishes (including any conversational iteration)
+  - Payload: `{ task_title, duration_ms }`
+
+### Listens To
+- `task_received` — begin research when ftm-mind or ftm-brainstorm routes a research request
+  - Expected payload: `{ task_description, plan_path, wave_number, task_number }`
+  - Note: `depth_mode` and `context_register` are derived internally from request context, not from event payload
+
+## Config Read
+
+Read `~/.claude/ftm-config.yml`:
+- Use `planning` model from the active profile for finder agents
+- Use `review` model for fallback challenger agents
+- Read `execution.per_skill_overrides.ftm-researcher` for agent cap (default 10 if override absent, fall back to `execution.max_parallel_agents` if neither is set)
+
+## Blackboard Read
+
+On startup, load context from the FTM blackboard:
+1. Load `~/.claude/ftm-blackboard/context.json`
+2. Filter experiences by `task_type: "research"`
+3. Load matching experience files to inform agent dispatch and subtopic decomposition
+4. Load `~/.claude/ftm-blackboard/patterns.json` for recurring research patterns
+
+## Mode System
+
+Three depth modes calibrate agent count, synthesis pipeline, and council invocation:
+
+```
+Quick:    3 finders (Web Surveyor, GitHub Miner, Codebase Analyst), no council, no reconciler.
+          Single-pass synthesis by orchestrator. ~1-2 min.
+
+Standard: 7 finders + reconciler, no council. Normalize → rank → reconcile. ~3-5 min.
+
+Deep:     7 finders → adaptive wave 2 → ftm-council → reconciler. Full pipeline. ~5-10 min.
+```
+
+Mode is detected from request context:
+- "quick look" / "briefly" / "just a quick" → quick mode
+- "deep dive" / "thorough" / "comprehensive" / "exhaustive" → deep mode
+- Default (no explicit signal) → standard mode
+
+## The Main Loop
+
+```
+PHASE 0: REPO SCAN
+  Silent background Explore agent scans the local codebase (same as ftm-brainstorm).
+  Produces: project_context { tech_stack, key_files, existing_patterns, integration_points }
+  Used by: Codebase Analyst finder + orchestrator subtopic decomposition
+
+PHASE 1: INTAKE
+  - Parse the research question
+  - Detect depth mode
+  - Decompose into 7 subtopics (one per finder domain)
+  - Load blackboard context and filter relevant prior research
+
+PHASE 2: WAVE 1
+  - Dispatch 7 finders in parallel, each with:
+    - Their unique domain constraint
+    - Their assigned subtopic
+    - Project context from Phase 0
+    - Context register (accumulated findings from prior waves/turns)
+    - Summary of previous findings to build on (do NOT re-search)
+  - Collect all findings (3-8 per agent = 21-56 total)
+
+PHASE 3: ADAPTIVE REFINEMENT (deep mode only)
+  - Analyze wave 1 findings across 4 dimensions:
+    SATURATED: subtopic has 3+ diverse findings — reassign agent to a gap
+    THIN: subtopic has 1-2 findings — same agent, more specific query
+    GAP: subtopic has 0 findings — agent gets broader query + alternative terms
+    CONTESTED: 2+ agents directly contradict — assign 2 agents (one per side) to resolve
+    SURPRISE: findings outside original subtopics — assign most relevant agent to explore
+  - Dispatch wave 2 agents with reshaped queries
+  - Merge wave 2 findings with wave 1 before synthesis
+
+PHASE 4: SYNTHESIS PIPELINE
+  See ftm-researcher/references/synthesis-pipeline.md for full pipeline.
+  Summary:
+  1. Normalize & deduplicate (group by semantic similarity, track agent_count, source diversity)
+  2. Adversarial review: ftm-council (deep mode) or fallback challengers (standard mode)
+  3. Pairwise rank contested claims (LLM-as-judge tournament)
+  4. Reconcile into disagreement map (consensus / contested / unique / refuted tiers)
+
+PHASE 5: PRESENT
+  - Render disagreement map as structured markdown
+  - Show consensus findings, contested pairs, unique insights (flagged), refuted claims
+  - Include source summary table (type | count | avg credibility)
+  - Emit `research_complete` event
+
+PHASE 6: ITERATE
+  - Enter conversational iteration mode
+  - Wait for user response
+  - Route based on intent (see Conversational Iteration Protocol below)
+```
+
+## Conversational Iteration Protocol
+
+After presenting results, the skill enters iteration mode. Route user responses:
+
+- "dig deeper on finding #N" / "more on #N" → spawn 3 targeted agents on that specific finding's topic
+- "I disagree with X" / "I think X is wrong because Y" → spawn counter-evidence agents, update findings
+- "focus on [angle]" / "what about the security angle" → reshape subtopics with new weighting, re-dispatch
+- "council finding #N" / "get more opinions on #N" → route specific claim to ftm-council
+- "more on [agent]'s findings" → re-dispatch that agent with broader query
+- "compare A vs B" → spawn comparison agent with both findings as context
+- "done" / "thanks" / "that's enough" / "looks good" → finalize, write blackboard, emit events
+
+Each iteration:
+1. Updates the structured JSON artifact
+2. Re-renders the markdown output
+3. Updates the context register for subsequent turns
+
+## Agent Roster
+
+See `ftm-researcher/references/agent-prompts.md` for full prompts.
+
+| Agent | Domain | Source Types |
+|---|---|---|
+| Web Surveyor | Blog posts, case studies, tutorials, technical write-ups | blog, news |
+| Academic Scout | Papers (arxiv, ACM, IEEE), official docs, RFCs, specs | peer_reviewed, primary, official_docs |
+| GitHub Miner | GitHub repos, OSS implementations, code patterns | code_repo |
+| Competitive Analyst | Products, user reviews (Reddit/HN/Twitter), market analysis | forum, news |
+| Stack Overflow Digger | Stack Overflow, community Q&A, pitfalls, solved problems | qa_site |
+| Codebase Analyst | Local repo only — Grep, Read, Glob tools, git log | codebase |
+| Historical Investigator | Solutions from 5-10+ years ago, evolution, failed approaches | primary, blog |
+
+## Synthesis Pipeline
+
+See `ftm-researcher/references/synthesis-pipeline.md` for full specification.
+
+5 phases: Normalize → Adversarial Review → Pairwise Rank → Reconcile → Render
+
+Output tiers:
+1. **Consensus** — 3+ agents agree, council agreed, multiple source types. Highest confidence.
+2. **Contested** — Council disagreed or pairwise ranking was close. Present both sides.
+3. **Unique Insights** — 1 agent only, not contradicted. High value OR hallucination — flag for user.
+4. **Refuted** — Council rejected or pairwise loser with weak evidence. Still present briefly.
+
+## Adaptive Search
+
+See `ftm-researcher/references/adaptive-search.md` for full protocol.
+
+Deep mode only. Reshapes wave 2 queries based on wave 1 coverage analysis across 4 dimensions: SATURATED, THIN, GAP, CONTESTED, SURPRISE.
+
+## Output Format
+
+See `ftm-researcher/references/output-format.md` for JSON schema and markdown template.
+
+Primary output: structured JSON artifact for skill-to-skill consumption (ftm-brainstorm, ftm-executor).
+Secondary output: rendered markdown for human display.
+
+## Council Integration
+
+See `ftm-researcher/references/council-integration.md` for full protocol.
+
+Deep mode only. Routes top claims through ftm-council (Claude + Codex + Gemini independent review).
+
+Fallback (council unavailable): 2 standalone agents on the `review` model:
+- Devil's Advocate — finds reasons each claim is WRONG
+- Edge Case Hunter — finds where each claim BREAKS
+
+## Credibility Scoring
+
+See `ftm-researcher/scripts/score_credibility.py` for implementation.
+
+4 dimensions (weighted):
+- Source type weight (35%): primary > peer_reviewed > official_docs > news > blog > forum
+- Recency (20%): decay based on age, faster for fast-moving topics
+- Domain authority (25%): HIGH_AUTHORITY domains (arxiv, MDN, AWS docs) score 0.9
+- Bias detection (20%): sensationalism penalties, balanced language bonuses
+
+Bonuses and penalties:
+- Corroboration bonus: +0.15 if independently found by 2+ agents from different source types
+- Circular sourcing: -0.20 flag if multiple sources trace to same original
+
+Trust levels: high (>=0.75) | moderate (>=0.55) | low (>=0.35) | verify (<0.35)
+
+## Blackboard Write
+
+After `research_complete` or session end:
+1. Update `~/.claude/ftm-blackboard/context.json` with research session summary
+2. Write experience file: `~/.claude/ftm-blackboard/experiences/research-[timestamp].json`
+   - Fields: query, mode, findings_count, top_consensus_claims, source_diversity, duration_ms
+3. Update `~/.claude/ftm-blackboard/index.json` with new experience entry
+4. Emit `task_completed` event
+
+## Session State (for ftm-pause/resume)
+
+The following state is persisted for pause/resume support:
+- Current phase (0-6)
+- Depth mode
+- All wave 1 and wave 2 findings (raw)
+- Synthesis state (normalized claims, council verdicts, ranked pairs)
+- Disagreement map (current version)
+- Conversation history (iteration turns)
+- Context register (accumulated findings across turns)
+- Project context from Phase 0 repo scan
+
+## References
+
+- `ftm-researcher/references/agent-prompts.md` — 7 finder agent prompts + orchestrator decomposition protocol
+- `ftm-researcher/references/synthesis-pipeline.md` — 5-phase synthesis pipeline + reconciler prompt
+- `ftm-researcher/references/adaptive-search.md` — Wave 1 → wave 2 refinement protocol
+- `ftm-researcher/references/output-format.md` — JSON schema + markdown template + iteration protocol
+- `ftm-researcher/references/council-integration.md` — ftm-council interface + fallback challenger prompts
+- `ftm-researcher/scripts/score_credibility.py` — Source credibility scoring
+- `ftm-researcher/scripts/validate_research.py` — Research output validation
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | planning and review model profiles, per_skill_overrides.ftm-researcher agent cap
+- reference: `ftm-researcher/references/agent-prompts.md` | required | 7 finder agent prompts and orchestrator decomposition protocol
+- reference: `ftm-researcher/references/synthesis-pipeline.md` | required | 5-phase synthesis pipeline
+- reference: `ftm-researcher/references/adaptive-search.md` | optional | wave 2 adaptive refinement (deep mode only)
+- reference: `ftm-researcher/references/output-format.md` | required | JSON schema and markdown template
+- reference: `ftm-researcher/references/council-integration.md` | optional | ftm-council interface (deep mode only)
+- reference: `~/.claude/ftm-blackboard/context.json` | optional | session state
+- reference: `~/.claude/ftm-blackboard/patterns.json` | optional | recurring research patterns
+
+## Risk
+
+- level: read_only
+- scope: reads web sources and local codebase via agents; writes blackboard experience entry; writes structured JSON artifact; does not modify project source files
+- rollback: no project mutations; blackboard write can be reverted by editing JSON files
+
+## Approval Gates
+
+- trigger: research complete and user says "done" / "thanks" | action: finalize, write blackboard, emit events
+- trigger: deep mode and ftm-council invoked | action: council runs automatically on top claims (no user gate needed for this step)
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ftm-council not available (deep mode) | action: use 2 fallback challenger agents (Devil's Advocate + Edge Case Hunter) instead
+- condition: agent cap exceeded | action: queue excess agents and dispatch after current wave completes
+- condition: research agent returns no findings | action: broaden query and retry; if still empty, report "No prior art found — this may be novel"
+- condition: blackboard missing | action: proceed without experience-informed shortcuts
+
+## Capabilities
+
+- mcp: `WebSearch` | optional | finder agents for web, GitHub, and competitive research
+- mcp: `WebFetch` | optional | fetching specific URLs found during research
+- mcp: `sequential-thinking` | optional | complex synthesis and reconciliation
+
+## Event Payloads
+
+### research_complete
+- skill: string — "ftm-researcher"
+- query: string — original research question
+- mode: string — "quick" | "standard" | "deep"
+- findings_count: number — total normalized findings
+- consensus_count: number — findings with 3+ agent agreement
+- contested_count: number — findings with council disagreement
+- unique_count: number — single-agent findings
+- sources_count: number — total sources cited
+- council_used: boolean — whether ftm-council was invoked
+- duration_ms: number — total research duration
+
+### task_completed
+- skill: string — "ftm-researcher"
+- task_title: string — research topic title
+- duration_ms: number — total session duration including iterations