feed-the-machine 1.0.0

package/ftm-mind/references/protocols/MCP-HEURISTICS.md

@@ -0,0 +1,32 @@
+# MCP Matching Heuristics and Chaining
+
+## Matching Rules
+
+Use the smallest relevant MCP set.
+
+- Jira issue key or Atlassian URL → `mcp-atlassian-personal`
+- "internal docs", "runbook", "Klaviyo", "Glean" → `glean_default`
+- "how do I use X library" → `context7`
+- "calendar", "meeting", "free time" → `google-calendar`
+- "Slack", "channel", "thread", "notify" → `slack`
+- "email", "Gmail", "draft" → `gmail`
+- "ticket", "hardware", "access request" → `freshservice-mcp`
+- "browser", "screenshot", "look at the page" → `playwright`
+- "profile performance in browser" → `chrome-devtools`
+- "talk through trade-offs" → `sequential-thinking`
+- "SwiftUI" or Apple framework names → `apple-doc-mcp`
+- "find contact/company" → `lusha`
+
+## Multi-MCP Chaining
+
+Detect mixed-domain requests early.
+
+Examples:
+- "check my calendar and draft a Slack message" → `google-calendar` + `slack`
+- "read the Jira ticket, inspect the repo, then propose a fix" → `mcp-atlassian-personal` + `git`
+- "search internal docs, then update a Confluence page" → `glean_default` + `mcp-atlassian-personal`
+
+Rules:
+- parallelize reads when safe
+- gather state before proposing writes
+- chain writes sequentially

package/ftm-mind/references/protocols/PLAN-APPROVAL.md

@@ -0,0 +1,80 @@
+# Interactive Plan Approval Protocol
+
+Read `~/.claude/ftm-config.yml` field `execution.approval_mode`. This controls whether the user sees and approves the plan before execution begins.
+
+## Mode: `auto` (default legacy behavior)
+Skip this section entirely. Execute as before — micro/small just go, medium outlines steps and executes, large routes to brainstorm/executor.
+
+## Mode: `plan_first` (recommended for collaborative work)
+For **medium and large** tasks, present a numbered task list and wait for the user to approve before executing anything.
+
+**Step 1: Generate the plan.**
+
+Build a numbered list of concrete steps based on Orient synthesis. Each step must have:
+- A number
+- A one-line description of what will be done
+- The files that will be touched
+- The verification method (test, lint, visual check, or "self-evident")
+
+Present it like this:
+
+```
+Here's my plan for this task:
+
+  1. [ ] Read auth middleware and map dependencies → src/middleware/auth.ts
+  2. [ ] Add OAuth token validation endpoint → src/routes/auth.ts, src/middleware/oauth.ts
+  3. [ ] Update existing auth tests for new flow → src/__tests__/auth.test.ts
+  4. [ ] Run full test suite → verify: pytest / npm test
+  5. [ ] Update INTENT.md for changed functions → docs/INTENT.md
+
+Approve all? Or tell me what to change.
+  - "approve" or "go" → execute all steps in order
+  - "skip 3" → execute all except step 3
+  - "for step 2, use passport.js instead" → modify step 2, then execute all
+  - "only 1,2" → execute only steps 1 and 2
+  - "add: step between 2 and 3 to update the config" → insert a step
+  - "deny" or "stop" → cancel entirely
+```
+
+**Step 2: Parse the user's response.**
+
+| User says | Action |
+|-----------|--------|
+| `approve`, `go`, `yes`, `lgtm`, `ship it` | Execute all steps in order |
+| `skip N` or `skip N,M` | Remove those steps, execute the rest |
+| `only N,M,P` | Execute only the listed steps in order |
+| `for step N, [instruction]` | Replace step N's approach with the user's instruction, then execute all |
+| `add: [description] after N` or `add: [description] before N` | Insert a new step at that position, renumber, then execute all |
+| `deny`, `stop`, `cancel`, `no` | Cancel. Do not execute anything. Ask what the user wants instead. |
+| A longer message with mixed feedback | Parse each instruction. Apply all modifications to the plan. Present the revised plan and ask for final approval. |
+
+**Step 3: Execute the approved plan.**
+
+Work through the approved steps sequentially. After each step:
+- Show a brief completion message: `Step 2/5 done: OAuth endpoint added.`
+- If a step fails, stop and report. Ask: "Step 3 failed: [error]. Fix and continue, skip this step, or stop?"
+- After all steps complete, show a summary of what was done.
+
+**Step 4: Post-execution update.**
+
+Update the blackboard with decisions made and experience recorded, same as normal Act phase.
+
+## Mode: `always_ask`
+Same as `plan_first` but applies to **small** tasks too. Only micro tasks (single obvious edit) skip the approval gate.
+
+## Combining with explicit skill routing
+
+When the mind decides to route to a skill (e.g., ftm-debug, ftm-executor), the plan approval still applies if the mode is `plan_first` or `always_ask`. Present:
+
+```
+For this task, I'd route to ftm-debug with this approach:
+
+  1. [ ] Launch ftm-debug war room on the flaky auth test
+  2. [ ] Apply the fix from debug findings
+  3. [ ] Run test suite to verify
+  4. [ ] Record experience to blackboard
+
+Approve? Or adjust the approach.
+```
+
+This gives the user control over the *strategy* even when delegating to skills.

package/ftm-mind/references/reflexion-protocol.md

@@ -0,0 +1,249 @@
+# Reflexion Protocol — Verbal RL for FTM-Mind
+
+**Location**: `~/.claude/skills/ftm-mind/references/reflexion-protocol.md`
+**Purpose**: Defines how ftm-mind stores and reuses execution experience through the Reflexion pattern — a lightweight verbal reinforcement learning loop that improves behavior across sessions without fine-tuning.
+
+---
+
+## The Reflexion Pattern
+
+Reflexion is a simple feedback mechanism: after each significant action, write a short natural-language reflection describing what happened and why. Before the next attempt at a similar task, retrieve and prepend relevant reflections to the working context.
+
+Core loop:
+1. **Act** — execute the task using available skills and tools
+2. **Reflect** — generate a structured verbal reflection on the outcome
+3. **Store** — write the reflection as an experience entry to the blackboard
+4. **Retrieve** — on the next similar task, load matching experiences during Orient
+5. **Adjust** — synthesize retrieved lessons into an adjusted approach before acting
+
+The key insight: language models do not update weights between conversations, but they can update behavior when prior experience is injected as context. Reflexion makes that injection systematic.
+
+### What "Prepend to Next Attempt" Means
+
+When ftm-mind enters the Orient phase of the OODA loop for a new task:
+
+1. Read `experiences/index.json`
+2. Filter entries matching the current `task_type` and any overlapping tags
+3. Load the top 3–5 most recent matching experience files
+4. Synthesize their `lessons` arrays into a short prior-experience summary
+5. That summary is the first input considered when forming the plan — not an afterthought
+
+This is the prepend. The retrieved experience shapes the approach before any analysis of the current task begins.
+
+---
+
+## Trigger Conditions
+
+Micro-reflections are written after any of the following events:
+
+| Event | When It Fires | What to Record |
+|---|---|---|
+| `task_completed` | Any task finishes — micro through large | Outcome, approach, what worked |
+| `bug_fixed` | A bug was diagnosed and resolved | Root cause, fix strategy, what was misleading |
+| `error_encountered` | An unexpected error during execution | Error context, what caused it, how to avoid |
+| `code_committed` | A meaningful commit is made | What changed, why, any surprising side effects |
+| `plan_generated` | A plan was created from brainstorming | Plan structure, assumptions made, expected risks |
+| `user_correction` | The user corrected the mind's approach | What the mind got wrong, what the correct approach was |
+
+Do not wait for a formal retro to record these. Write the experience file immediately after the triggering event resolves. Delayed recording produces lower-quality lessons.
+
+---
+
+## Reflection Format
+
+For each trigger, generate a structured verbal RL reflection before writing the experience entry:
+
+```
+I [succeeded / failed / partially succeeded] at [task description] because [specific reason].
+Next time I should [concrete, actionable adjustment].
+Confidence: [low / medium / high]
+```
+
+### Good Reflection Examples
+
+```
+I succeeded at adding the freshservice enrichment poller because the existing poller_runtime.py
+pattern was reusable with minimal modification.
+Next time I should check for existing runtime patterns before writing new polling infrastructure.
+Confidence: medium
+```
+
+```
+I partially succeeded at the Jira sync task because the field mapping worked but the
+attachment handling failed silently — no error was surfaced until the next run.
+Next time I should add explicit attachment count validation after every sync and log
+mismatches immediately rather than relying on downstream detection.
+Confidence: low
+```
+
+```
+I failed at the database migration because I assumed the staging schema matched production
+and did not read the migration history first.
+Next time I should always read the last 5 migration files before writing a new one.
+Confidence: high
+```
+
+### Bad Reflection Examples (Do Not Write These)
+
+```
+I did okay at the task. It was kind of complex.
+Next time I should be more careful.
+Confidence: medium
+```
+
+Why bad: "be more careful" is not actionable. No specific reason for the outcome. Cannot be acted on by a future skill loading this file.
+
+```
+I succeeded because I am good at code.
+```
+
+Why bad: No transferable lesson. Causation is not traced. Useless as a retrieval artifact.
+
+### Decomposing Into Lessons
+
+The verbal reflection maps to the `lessons` array in the experience entry. Decompose the "Next time I should..." clause into one or more concrete lesson strings:
+
+Reflection: "Next time I should check for existing runtime patterns before writing new polling infrastructure and validate attachment handling with explicit count checks."
+
+Lessons array:
+```json
+[
+  "Check for existing runtime patterns (e.g. poller_runtime.py) before writing new polling infrastructure from scratch.",
+  "Add explicit attachment count validation after every sync operation; do not rely on downstream error detection."
+]
+```
+
+---
+
+## Experience Entry Format Reference
+
+Full schema defined in `blackboard-schema.md`. Key fields for micro-reflections:
+
+```json
+{
+  "task_type": "bug | feature | refactor | investigation | configuration | documentation | test | deploy",
+  "description": "1-2 sentence summary of what was attempted",
+  "approach": "How the task was approached — tools, strategies, sequence of steps",
+  "outcome": "success | partial | failure",
+  "lessons": [
+    "Concrete, actionable takeaway derived from the verbal RL reflection",
+    "Each lesson string must be specific enough to act on without further context"
+  ],
+  "complexity_estimated": "trivial | low | medium | high | very_high",
+  "complexity_actual": "trivial | low | medium | high | very_high",
+  "capabilities_used": ["ftm-executor", "mcp__mcp-atlassian-personal__jira_get_issue", "backend-architect"],
+  "tags": ["python", "slack", "database", "auth"],
+  "confidence": "low | medium | high",
+  "recorded_at": "ISO8601 timestamp"
+}
+```
+
+Written to: `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
+
+After writing the file, append a metadata entry to `experiences/index.json` and increment `total_count`.
+
+---
+
+## Pattern Promotion Thresholds
+
+Patterns are promoted from individual experience files into `patterns.json` when the same lesson has been independently observed enough times to be considered reliable.
+
+| Occurrences | Action | Confidence Level |
+|---|---|---|
+| 1–2 | Stay in experience files only | — |
+| 3 | Promote to `patterns.json` | `low` |
+| 5+ | Raise confidence | `medium` |
+| 8+ | Raise confidence | `high` |
+
+### How to Detect Promotion Candidates
+
+After writing an experience entry:
+
+1. Read `experiences/index.json`
+2. Find all entries where `task_type` matches AND at least one `tag` overlaps with the new entry
+3. Load those experience files
+4. Compare `lessons` arrays across all loaded files — look for thematic overlap (same root cause, same fix pattern, same constraint)
+5. If 3+ entries share a lesson theme, the theme is ready to be promoted
+
+Promotion writes to the appropriate category in `patterns.json`:
+- `codebase_insights` — observations about the codebase structure, conventions, or tech choices
+- `execution_patterns` — what approaches work or fail for specific task types
+- `user_behavior` — observed user preferences, correction patterns, approval expectations
+- `recurring_issues` — problems that keep appearing, with their symptoms and known resolutions
+
+---
+
+## Pattern Decay Rules
+
+Patterns that are not reinforced within 30 days become less reliable. Apply decay when reading `patterns.json` during any blackboard operation:
+
+| Current Confidence | Days Since `last_reinforced` | Action |
+|---|---|---|
+| `high` | > 30 days | Reduce to `medium` |
+| `medium` | > 30 days | Reduce to `low` |
+| `low` | > 30 days | Remove from `patterns.json` |
+
+Decay is applied in-place: read `patterns.json`, compute which entries have expired, reduce or remove them, write the file back.
+
+Do not decay entries that have been reinforced recently — `last_reinforced` is updated each time a new experience confirms the same pattern.
+
+---
+
+## How the Mind Uses Reflexion During Orient
+
+Orient is the second phase of the OODA loop (Observe → Orient → Decide → Act). It is where the mind interprets current context and forms a plan. Reflexion inserts prior experience directly into Orient:
+
+```
+Orient Phase Protocol:
+
+1. Read experiences/index.json
+2. Filter by current task_type + tag overlap
+3. Load top 3–5 experience files (most recent first; prefer confidence: high)
+4. Read patterns.json → filter patterns relevant to the current task domain
+5. Apply decay to any patterns with last_reinforced > 30 days
+6. Synthesize a prior-experience summary:
+   - List the most relevant lessons from loaded experiences
+   - Note any patterns that apply (from patterns.json)
+   - Flag any recurring issues that match the current task's context
+7. Use this summary as the first input when forming the execution plan
+```
+
+The synthesis does not need to be formal. A short bullet list of 3–5 observations from past experience is sufficient. The goal is to surface "things that have gone wrong before in situations like this" before committing to an approach.
+
+### Retrieval Priority
+
+When loading experience files, prioritize in this order:
+1. `confidence: "high"` entries over `"medium"` over `"low"`
+2. `outcome: "success"` for positive lessons (what to repeat)
+3. `outcome: "failure"` for cautionary lessons (what to avoid)
+4. Most recent `recorded_at` as tiebreaker
+
+Load both success and failure experiences — learning what not to do is as valuable as learning what works.
+
+---
+
+## Cold-Start Behavior
+
+The blackboard starts empty. During the first ~10 interactions (`total_count < 10` in `index.json`):
+
+- Record EVERY completed task, even trivial ones
+- Set `confidence: "low"` on all entries — they have not been cross-validated
+- Prioritize breadth of recording over depth of analysis — getting entries into the index quickly is more valuable than perfect lesson articulation
+- Do not skip recording because a task "was simple" — even trivial tasks reveal conventions and constraints that are useful context
+
+The cold-start window is how the system bootstraps its memory. By the 10th interaction, retrieval should already be returning context that reduces repeated mistakes.
+
+---
+
+## Quick Reference
+
+| Concept | Rule |
+|---|---|
+| When to reflect | After every trigger event — do not wait for retro |
+| Reflection format | "I [outcome] at [task] because [reason]. Next time: [adjustment]. Confidence: [level]." |
+| Experience file location | `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` |
+| Schema reference | `blackboard-schema.md` section 3 |
+| Promotion threshold | 3+ occurrences → `low` confidence; 5+ → `medium`; 8+ → `high` |
+| Decay window | 30 days without reinforcement → reduce confidence one level; at `low` → remove |
+| Orient integration | Load 3–5 matching experiences + relevant patterns before forming any plan |
+| Cold-start rule | Record everything until `total_count >= 10`, all at `confidence: "low"` |

package/ftm-mind/references/routing/SCENARIOS.md

@@ -0,0 +1,22 @@
+# Routing Scenarios
+
+Use these as behavioral tests for the Orient → Decide pipeline.
+
+| Input | What Orient notices | Decision |
+|---|---|---|
+| `debug this flaky test` | bug, uncertainty, likely multiple hypotheses | route to `ftm-debug` |
+| `help me think through auth design` | ideation, architecture, not implementation yet | route to `ftm-brainstorm` |
+| `execute ~/.claude/plans/foo.md` | explicit plan path and execution ask | route to `ftm-executor` |
+| `rename this variable` | one obvious local edit, tiny blast radius | handle directly as `micro` |
+| `what would other AIs think about this approach` | explicit multi-model request | route to `ftm-council` |
+| `audit the wiring` | structural verification request | route to `ftm-audit` |
+| Jira ticket URL only | ticket-driven work, intent not yet clear | fetch via `mcp-atlassian-personal`, then re-orient |
+| `check my calendar and draft a slack message` | mixed-domain workflow, read + external draft/send boundary | read calendar, draft Slack, ask before send |
+| `make this better` | ambiguous, insufficient anchor | ask one focused clarifying question |
+| `/ftm help` | explicit help/menu request | show help menu |
+| `I just committed the fix, now check it` | continuation, recent commit validation | inspect diff, run tests or audit, then report |
+| `/ftm-debug auth race condition` | explicit skill choice | respect explicit route to `ftm-debug` |
+| `/ftm-brainstorm replacement for Okta hooks` | explicit design-phase route | respect explicit route to `ftm-brainstorm` |
+| `open the page and tell me what looks broken` | visual/browser task | route to `ftm-browse` or use browser support if already in-flow |
+| `add error handling to the API routes` | medium task, multi-file, `plan_first` mode | present numbered plan for approval, wait for user response, then execute approved steps |
+| `refactor auth to support OAuth` (with `plan_first`) | medium-large, multi-file with dependencies | present plan with 5-7 steps, user says "skip 4, for step 3 use passport.js" → adjust and execute |

package/ftm-mind/references/routing-scenarios.md

@@ -0,0 +1,35 @@
+# Routing Scenarios Reference
+
+Use these as behavioral tests for the Decide phase.
+
+| Input | What Orient notices | Decision |
+|---|---|---|
+| `debug this flaky test` | bug, uncertainty, likely multiple hypotheses | route to `ftm-debug` |
+| `help me think through auth design` | ideation, architecture, not implementation yet | route to `ftm-brainstorm` |
+| `execute ~/.claude/plans/foo.md` | explicit plan path and execution ask | route to `ftm-executor` |
+| `rename this variable` | one obvious local edit, tiny blast radius | handle directly as `micro` |
+| `what would other AIs think about this approach` | explicit multi-model request | route to `ftm-council` |
+| `audit the wiring` | structural verification request | route to `ftm-audit` |
+| Jira ticket URL only | ticket-driven work, intent not yet clear | fetch via `mcp-atlassian-personal`, then re-orient |
+| `check my calendar and draft a slack message` | mixed-domain workflow, read + external draft/send boundary | read calendar, draft Slack, ask before send |
+| `make this better` | ambiguous, insufficient anchor | ask one focused clarifying question |
+| `/ftm help` | explicit help/menu request | show help menu |
+| `I just committed the fix, now check it` | continuation, recent commit validation | inspect diff, run tests or audit, then report |
+| `/ftm-debug auth race condition` | explicit skill choice | respect explicit route to `ftm-debug` |
+| `/ftm-brainstorm replacement for Okta hooks` | explicit design-phase route | respect explicit route to `ftm-brainstorm` |
+| `open the page and tell me what looks broken` | visual/browser task | route to `ftm-browse` or use browser support if already in-flow |
+| `add error handling to the API routes` | medium task, multi-file, `plan_first` mode | present numbered plan for approval, wait for user response, then execute approved steps |
+| `refactor auth to support OAuth` (with `plan_first`) | medium-large, multi-file with dependencies | present plan with 5-7 steps, user says "skip 4, for step 3 use passport.js" → adjust and execute |
+| `research parallel agent architectures` | research task, factual inquiry, broad scope | route to `ftm-researcher` (deep) |
+| `what's the best way to handle auth in Next.js` | research task, specific technical question | route to `ftm-researcher` (standard) |
+| `quick look at how Stripe handles webhooks` | research task, explicit "quick" signal | route to `ftm-researcher` (quick) |
+| `compare Redis vs Memcached for our session store` | research task, comparative, codebase-relevant | route to `ftm-researcher` (deep, codebase-aware) |
+| `find me examples of rate limiting middleware` | research task, looking for implementations | route to `ftm-researcher` (standard) |
+| `I want to build a dashboard` | ideation, not research | route to `ftm-brainstorm` (calls researcher internally) |
+| `/ftm-researcher auth patterns in microservices` | explicit skill choice | respect explicit route to `ftm-researcher` |
+| `what breaks if I change handleAuth` | structural query, blast radius, specific symbol | route to `ftm-map` (query: blast-radius) |
+| `map this codebase` | indexing request, no map.db exists | route to `ftm-map` (bootstrap mode) |
+| `where do we handle authentication` | code search, structural | route to `ftm-map` (query: search) |
+| `what depends on the UserService class` | dependency chain, specific symbol | route to `ftm-map` (query: deps) |
+| `show me everything about the parseConfig function` | symbol info request | route to `ftm-map` (query: info) |
+| `/ftm-map blast-radius handlePayment` | explicit skill choice | respect explicit route to `ftm-map` |

package/ftm-mind.yml

@@ -0,0 +1,2 @@
+name: ftm-mind
+description: Unified cognitive loop for the ftm skill system. Receives any input and contextualizes it against codebase state, accumulated experience, available capabilities, and task complexity before deciding how to act. Use when user says "/ftm-mind", "/ftm" followed by freeform text, or provides any input that needs intelligent routing, decomposition, or multi-step reasoning. Handles everything from micro tasks ("rename this variable") to large projects ("build this feature") by sizing complexity and selecting the right execution strategy. Replaces keyword-matching routing with OODA-based reasoning. Do NOT use when user explicitly invokes a specific ftm skill by name — those route directly.

package/ftm-pause/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: ftm-pause
+description: Save the current ftm skill session state so work can be resumed in a new conversation. Use when user says "pause", "save state", "I need to stop", "continue later", "ftm pause", "save progress", or is about to end a session mid-workflow. Works with any ftm skill (brainstorm, executor, debug, council, audit).
+---
+
+## Events
+
+### Emits
+- `session_paused` — when the session state has been successfully serialized and written to disk
+- `task_completed` — when the pause workflow finishes (state file written and confirmation presented)
+
+### Listens To
+(none — ftm-pause is explicitly invoked by the user and does not respond to events)
+
+# FTM Pause — Session State Capture
+
+Save the full state of any active ftm skill session to disk so it can be resumed in a new conversation with zero context loss.
+
+## Step 1: Detect the Active FTM Skill
+
+Scan the current conversation context to determine which ftm skill is active. Look for these signals:
+
+| Signal | Skill |
+|--------|-------|
+| Phase 0 repo scan, intake rounds, research sprints, 5-suggestion format, plan generation | **ftm-brainstorm** |
+| Plan analysis, agent team assembly, worktree setup, wave dispatch, task completion tracking | **ftm-executor** |
+| Problem intake, investigation plan, war room agents (instrumenter/researcher/reproducer/hypothesizer), solver/reviewer loop | **ftm-debug** |
+| Council prompt framing, multi-model dispatch (Claude/Codex/Gemini), rebuttal rounds, alignment checks | **ftm-council** |
+| Project pattern detection, knip analysis, adversarial audit, auto-fix, wiring contracts | **ftm-audit** |
+
+If no ftm skill is active, tell the user: "No active ftm session detected. This skill saves state for ftm-brainstorm, ftm-executor, ftm-debug, ftm-council, and ftm-audit sessions."
+
+If multiple skills have been invoked in the same conversation (e.g., brainstorm followed by executor), capture the most recently active one. If the user says which one to save, respect that.
+
+## Step 2: Capture State by Skill Type
+
+Read `references/protocols/SKILL-RESTORE-PROTOCOLS.md` for the full per-skill capture specification. Each skill section defines exactly which fields must be captured and what is required for reliable restoration.
+
+Capture every field listed for the detected skill. Do not omit fields because a phase hasn't been reached yet — record those as "not started" or "N/A" so ftm-resume knows the session stopped before that phase.
+
+## Step 3: Gather Artifacts
+
+Scan the conversation and filesystem for artifacts created during the session:
+
+- **Plan files**: `~/.claude/plans/*.md`
+- **Research documents**: Any `.md` files created by agents (RESEARCH-FINDINGS.md, HYPOTHESES.md, REPRODUCTION.md, FIX-SUMMARY.md, REVIEW-VERDICT.md, DEBUG-INSTRUMENTATION.md)
+- **Worktree branches**: Run `git worktree list` and `git branch --list "plan-exec/*" "debug/*"` to capture active branches
+- **Audit changelogs**: Any ftm audit changelog output
+- **Brain dump extractions**: If Path B brainstorm, the structured extraction
+
+For each artifact, record its absolute path and verify it still exists on disk.
+
+## Step 4: Write the State File
+
+Create the directory if it doesn't exist:
+```bash
+mkdir -p ~/.claude/ftm-state
+```
+
+Write the state file to `~/.claude/ftm-state/STATE.md`. Required structure:
+
+```markdown
+---
+skill: <skill-name>
+phase: <phase-number-or-name>
+phase_detail: "<human-readable one-liner: exactly where the session stopped>"
+timestamp: <ISO-8601>
+project_dir: <absolute-path>
+git_branch: <branch>       # omit if no git repo
+git_commit: <short-hash>   # omit if no git repo
+---
+
+# FTM Session State
+
+## Active Skill
+[One paragraph: skill, phase, path, turn, and current direction]
+
+## Context Snapshot
+[Full state for this skill per references/protocols/SKILL-RESTORE-PROTOCOLS.md]
+
+## Decisions Made
+[Every decision the user confirmed — use real content, not placeholders]
+
+## Open Questions
+[Anything unresolved or about to be explored]
+
+## Next Step
+[Specific and actionable: what ftm-resume does first, what the user needs to respond to,
+what research runs next. Must be specific enough to resume without "where were we?"]
+
+## Artifacts
+[Absolute path for each artifact, or "none on disk"]
+```
+
+**Rules:**
+- `git_commit`: run `git rev-parse --short HEAD`. `git_branch`: run `git branch --show-current`.
+- Include actual content — real URLs, real decisions, real findings. No placeholders.
+- Omit raw agent prompts (the skill files have them) and full file contents (reference by path).
+
+See `references/protocols/VALIDATION.md` for the full pre-write and post-write validation checklist.
+
+## Step 5: Confirm to User
+
+After saving, present a brief confirmation:
+
+```
+Session saved to ~/.claude/ftm-state/STATE.md
+
+Captured:
+- Skill: <skill-name>
+- Phase: <phase and detail>
+- <skill-specific counts: decisions, tasks, rounds, findings, etc.>
+- Artifacts: <count and locations, or "none on disk">
+
+To resume in a new conversation:
+/ftm-resume
+```
+
+Tailor the counts to the skill: brainstorm shows decisions + turns, executor shows task completion, debug shows investigation agents, council shows round count + consensus status, audit shows layer completion + finding counts.
+
+## Edge Cases
+
+**Multiple skills active:** Ask which to save. If "both," save most recent to STATE.md and the other to STATE-[skill].md.
+
+**Very early session:** Save what exists — even a Phase 0 scan is worth capturing. "Next Step" should say the user needs to answer the first intake question.
+
+**State file already exists:** Overwrite it. Prior state was either consumed or abandoned. FTM-resume archives before loading if the user needs the old one.
+
+**No git repo:** Omit `git_branch` and `git_commit` fields. Record `project_dir` only.
+
+**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.