feed-the-machine 1.3.0 → 1.3.1

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.
 ---
 
-# Panda Mind
+# FTM 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.
 
@@ -62,7 +62,7 @@ At Observe time, note but do not finalize:
 
 Read:
 
-- `/Users/kioja.kudumu/.claude/ftm-state/blackboard/context.json`
+- `~/.claude/ftm-state/blackboard/context.json`
 
 Extract:
 
@@ -199,9 +199,9 @@ Read the blackboard in this order:
 
 Use these exact paths:
 
-- `/Users/kioja.kudumu/.claude/ftm-state/blackboard/context.json`
-- `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/index.json`
-- `/Users/kioja.kudumu/.claude/ftm-state/blackboard/patterns.json`
+- `~/.claude/ftm-state/blackboard/context.json`
+- `~/.claude/ftm-state/blackboard/experiences/index.json`
+- `~/.claude/ftm-state/blackboard/patterns.json`
 
 #### 2.1 `context.json`
 
@@ -227,7 +227,7 @@ Experience retrieval must be concrete, not hand-wavy.
 
 Protocol:
 
-1. Read `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/index.json`
+1. Read `~/.claude/ftm-state/blackboard/experiences/index.json`
 2. Parse `entries`
 3. Derive a current `task_type`
 4. Derive current tags from the request and codebase context
@@ -236,7 +236,7 @@ Protocol:
    - there is at least one overlapping tag
 6. Sort filtered entries by `recorded_at` descending
 7. Load the top 3-5 matching experience files from:
-   - `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/{filename}`
+   - `~/.claude/ftm-state/blackboard/experiences/{filename}`
 8. Prefer lessons from entries with:
    - `outcome: success`
    - higher `confidence`
@@ -333,7 +333,7 @@ Routing heuristic:
 
 Read:
 
-- `/Users/kioja.kudumu/.claude/skills/ftm-mind/references/mcp-inventory.md`
+- `~/.claude/skills/ftm-mind/references/mcp-inventory.md`
 
 Orient must know the available MCPs and their contextual triggers.
 
@@ -928,12 +928,862 @@ 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:**
 
-3. Write an experience file to `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
-4. Update `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
+3. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
+4. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
+
+The experience file should capture:
+- `task_type`: what kind of work this was (e.g., `integration-reroute`, `automation-update`, `bug-fix`)
+- `tags`: domain nouns for future retrieval (e.g., `jira`, `freshservice`, `llm-integration`, `aria`, `itwork2`)
+- `outcome`: `success` or `partial` or `failed`
+- `lessons`: what worked, what was missed, what to do differently next time
+- `files_touched`: list of files modified
+- `stakeholders`: people involved or notified
+- `decisions_made`: key choices and their rationale
+
+The reason this is mandatory: the Jira rerouting task involved discovering that ARIA uses Stories not CRs, has no active sprints, needs different custom fields, and requires stakeholder coordination with Mo. None of that is in the code — it's tribal knowledge that only exists if we record it.
+
+Follow the schema and full-file write rules from `blackboard-schema.md`.
+
+### 5. Loop
+
+After acting:
+
+- if complete, answer and stop
+- if new information appeared, return to Observe
+- if blocked by approval or missing info, ask the user
+- if the simple approach failed, re-orient and escalate one level
+
+## Routing Scenarios
+
+Use these as behavioral tests.
+
+| 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 |
+| `reroute the Jira automation from ITWORK2 to ARIA` | forced-medium: external systems (Jira), cross-system references, unfamiliar codebase, stakeholder coordination | present numbered plan listing all reference changes, stakeholder communication, and verification steps — do NOT start editing code |
+| `update the integration to point to the new API endpoint` | forced-medium: cross-system references, automation code, multiple files likely | present plan first — even if it looks like "just change a URL", the blast radius of integration changes is always higher than expected |
+
+## Help Menu
+
+When the user asks for help, shows empty input, or says `?` or `menu`, show:
+
+```text
+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 intent                — Manage INTENT.md documentation
+  /ftm diagram               — Manage architecture diagrams
+  /ftm codex-gate            — Run adversarial Codex validation
+  /ftm browse [url]          — Visual verification with browser tools
+  /ftm pause                 — Save session state for later
+  /ftm resume                — Resume a paused session
+  /ftm upgrade               — Check for skill updates
+  /ftm retro                 — Post-execution retrospective
+  /ftm config                — Configure ftm settings
+  /ftm git                   — Secret scanning & credential safety gate
+  /ftm mind [anything]       — Full cognitive loop
+
+Or just describe what you need and ftm-mind will figure out the smallest correct next move.
+```
+
+## Anti-Patterns
+
+Avoid these failures:
+
+- keyword routing without real orientation
+- routing a micro task just because a matching skill exists
+- asking broad open-ended clarifying questions when a focused one would do
+- apologizing for empty memory on cold start
+- using past experience to override present repo reality
+- escalating to planning when a direct pass would work
+- performing external-facing actions without approval
+- ignoring explicit skill invocation when it is coherent and safe
+- **downsizing past forced escalation boundaries** — if forced-medium signals fired, the task is medium. Period. "It's basically just find-and-replace" is the exact rationalization that leads to grinding through 15 edits without a plan.
+- **starting to edit code before presenting a plan** when `approval_mode` is `plan_first` and the task is medium+. The plan IS the first deliverable. Reading code to inform the plan is fine. Editing code before plan approval is not.
+- **treating unfamiliar codebases as simple** — if you haven't read the code yet this session, you don't know how complex the change is. Default to medium until you've oriented.
+- **skipping the discovery interview** for medium+ tasks that involve external systems or stakeholders. "I have enough context from the request" is almost never true — the user always knows things they haven't said yet.
+- **skipping blackboard writes** after task completion. If you don't record the experience, the next session starts from zero. Tribal knowledge about project-specific details (custom field IDs, board configurations, stakeholder preferences) is exactly what experiences are for.
+
+## Operating Principles
+
+1. Orient is the differentiator. Without it, this is just a router.
+2. Try simple first. Escalate only when reality demands it.
+3. Respect explicit user intent.
+4. Cold start is full capability, not degraded mode.
+5. Experience retrieval must be concrete and selective.
+6. Read before write.
+7. Session trajectory matters.
+8. The best route is often no route at all.
+
+## 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:
+
+1. `context.json`
+2. `experiences/index.json`
+3. `patterns.json`
+
+Use these exact paths:
+
+- `~/.claude/ftm-state/blackboard/context.json`
+- `~/.claude/ftm-state/blackboard/experiences/index.json`
+- `~/.claude/ftm-state/blackboard/patterns.json`
+
+#### 2.1 `context.json`
+
+Use `context.json` for live session state only.
+
+Pull out:
+
+- `current_task`: does the request continue the active thread or branch away from it?
+- `recent_decisions`: what did we already decide this session?
+- `active_constraints`: no auto-commit, avoid production, stay terse, etc.
+- `user_preferences`: communication and approval preferences
+- `session_metadata.skills_invoked`: what workflow is already underway?
+
+Key heuristic:
+
+- trajectory matters more than isolated wording
+
+If the last sequence was brainstorm -> plan -> execute, then "go ahead" means something different than if the session began 10 seconds ago.
+
+#### 2.2 Experience Retrieval
+
+Experience retrieval must be concrete, not hand-wavy.
+
+Protocol:
+
+1. Read `~/.claude/ftm-state/blackboard/experiences/index.json`
+2. Parse `entries`
+3. Derive a current `task_type`
+4. Derive current tags from the request and codebase context
+5. Filter entries where:
+   - `task_type` matches the current task type, or
+   - there is at least one overlapping tag
+6. Sort filtered entries by `recorded_at` descending
+7. Load the top 3-5 matching experience files from:
+   - `~/.claude/ftm-state/blackboard/experiences/{filename}`
+8. Prefer lessons from entries with:
+   - `outcome: success`
+   - higher `confidence`
+   - recent dates
+9. Synthesize the lessons into concrete adjustments to the current approach
+
+Derive tags from:
+
+- language or framework names
+- domain nouns like `auth`, `poller`, `slack`, `database`, `deploy`, `calendar`, `jira`
+- task shape like `flaky-test`, `refactor`, `ticket-triage`, `plan-execution`
+
+Use retrieved experience for:
+
+- complexity calibration
+- known pitfalls
+- better sequencing
+- better routing
+- faster first checks
+
+Never use experience to blindly repeat an old approach when the live context has changed.
+
+#### 2.3 Pattern Registry
+
+Read `patterns.json` after experience retrieval.
+
+Scan all four sections:
+
+- `codebase_insights`
+- `execution_patterns`
+- `user_behavior`
+- `recurring_issues`
+
+Apply patterns only when they materially match the present case.
+
+Examples:
+
+- matching `file_pattern` on touched files
+- recurring issue symptoms that fit the current failure
+- user behavior that affects response style or approval expectations
+- execution patterns that suggest a proven sequence
+
+Patterns are promoted summaries. They should speed up orientation, not replace it.
+
+### 3. Cold-Start Behavior
+
+Cold start is normal.
+
+When the blackboard is empty:
+
+- do not apologize
+- do not say capability is reduced
+- do not surface that memory is empty unless the user asked
+- operate at full capability using live observation, codebase state, MCP awareness, and base heuristics
+
+Warm start adds shortcuts. Cold start is still a smart engineer on day 1 at a new job.
+
+If `experiences/index.json` has no usable matches:
+
+- continue normally
+- lean harder on current repo state and direct inspection
+- record the resulting experience aggressively after completion
+
+### 4. Capability Inventory: 15 Panda Skills
+
+Orient must know all ftm capabilities before deciding whether to route or act directly.
+
+| Skill | Reach for it when... |
+|---|---|
+| `ftm-brainstorm` | The user is exploring ideas, designing a system, comparing approaches, or needs research-backed planning before build work exists. |
+| `ftm-executor` | The user has a plan doc or clearly wants autonomous implementation across multiple tasks or waves. |
+| `ftm-debug` | The core problem is broken behavior, an error, flaky tests, a crash, regression, race, or "why is this failing?" |
+| `ftm-audit` | The user wants wiring checks, dead code analysis, structural verification, or adversarial code hygiene review. |
+| `ftm-council` | The user wants multiple AI perspectives, debate, second opinions, or multi-model convergence. |
+| `ftm-codex-gate` | The user wants adversarial Codex review, validation, or a correctness stress test from Codex specifically. |
+| `ftm-intent` | The user wants function/module purpose documented or `INTENT.md` updated or reconciled. |
+| `ftm-diagram` | The user wants diagrams, architecture visuals, dependency maps, or Mermaid assets updated. |
+| `ftm-browse` | The task requires a browser, screenshots, DOM inspection, or visual verification. |
+| `ftm-pause` | The user wants to park the session and save resumable state. |
+| `ftm-resume` | The user wants to restore paused context and continue prior work. |
+| `ftm-upgrade` | The user wants ftm skills checked or upgraded. |
+| `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-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:
+
+- If a task is self-contained and small enough, do it directly.
+- Route to a skill only when the skill's workflow adds clear value.
+- Explicit skill invocation is a strong route signal.
+
+### 5. MCP Inventory Reference
+
+Read:
+
+- `~/.claude/skills/ftm-mind/references/mcp-inventory.md`
+
+Orient must know the available MCPs and their contextual triggers.
+
+| MCP server | Reach for it when... |
+|---|---|
+| `git` | You need repo state, diffs, history, branches, staging, or commits. |
+| `playwright` | You need browser automation, screenshots, UI interaction, console logs, or visual checks. |
+| `sequential-thinking` | The problem genuinely needs multi-step reflective reasoning or trade-off analysis. |
+| `chrome-devtools` | You need lower-level browser debugging, network, or performance inspection. |
+| `slack` | You need to read Slack context, inspect channels or threads, or send a Slack update. |
+| `gmail` | You need inbox search, email reading, drafting, sending, labels, or filters. |
+| `mcp-atlassian-personal` | Personal Jira or Confluence reads and writes: tickets, sprints, docs, comments, status changes. Default Atlassian account. |
+| `mcp-atlassian` | Admin-scope Jira or Confluence operations that must run with elevated org credentials. |
+| `freshservice-mcp` | IT ticketing, requesters, agent groups, products, or service requests. |
+| `context7` | External library and framework documentation. |
+| `glean_default` | Internal company docs, policies, runbooks, and institutional knowledge. |
+| `apple-doc-mcp` | Apple platform docs for Swift, SwiftUI, UIKit, AppKit, and related APIs. |
+| `lusha` | Contact or company lookup and enrichment. |
+| `google-calendar` | Schedule inspection, free/busy checks, event search, drafting scheduling actions, and calendar changes. |
+
+#### MCP matching heuristics
+
+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
+
+### 6. Session Trajectory
+
+Do not orient from the last user message alone.
+
+Look for the arc:
+
+- What skill or action happened just before this?
+- What did we learn?
+- Is the user moving from ideation -> execution -> validation?
+- Did we already choose an approach that this request assumes?
+
+Trajectory cues:
+
+- brainstorm -> "ok go" usually means plan or executor
+- debug -> "check it now" usually means verify, test, or audit
+- executor -> "pause" means checkpoint, not new work
+- resume -> "what's next?" means restore and continue
+
+If a request branches away from the active thread, note that mentally and avoid corrupting the current session model.
+
+### 7. Codebase State
+
+Orient must incorporate what is true in the repo right now.
+
+Check:
+
+- dirty worktree
+- recent commits
+- active branch
+- user changes in progress
+- whether the request conflicts with local state
+
+Use codebase state to answer:
+
+- is this safe to do directly?
+- do we need to avoid stepping on unfinished work?
+- is this request actually about the last commit or current unstaged diff?
+- should we inspect a particular module first because recent changes point there?
+
+Repo heuristics:
+
+- uncommitted changes imply continuity and risk
+- a clean tree lowers the cost of direct action
+- a just-landed commit suggests review or regression-check behavior
+- a ticket-linked branch suggests the user expects ticket-driven execution
+
+### 8. Complexity Sizing
+
+Size the task from observed evidence, not vibes.
+
+#### Micro
+
+`just do it`
+
+Signals:
+
+- one coherent local action
+- trivial blast radius
+- rollback is obvious
+- no meaningful uncertainty
+- no dedicated verification step needed
+
+Typical examples:
+
+- rename a variable
+- fix a typo
+- answer a factual question after one read
+- add an import
+- tweak a comment
+
+#### Small
+
+`do + test`
+
+Signals:
+
+- 1-3 files
+- one concern
+- clear done state
+- at least one verification step is warranted
+- still reversible without planning overhead
+
+Typical examples:
+
+- implement a simple helper
+- patch a bug in one area
+- add or update a focused test
+- update docs plus one code path
+
+#### Medium
+
+`lightweight plan`
+
+Signals:
+
+- multiple changes with ordering
+- moderate uncertainty
+- multi-file or multi-step
+- a bug or feature spans layers but not a full program of work
+- benefits from an explicit short plan before execution
+
+**Forced medium escalation** — if ANY of these are true, the task is medium at minimum regardless of how simple it feels:
+
+- touches more than 3 files
+- modifies automation, CI/CD, or infrastructure code
+- involves external system changes (Jira, Slack, Freshservice, calendar, email)
+- requires coordinating with other people (drafting messages, checking with stakeholders)
+- 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
+- add UI + API + tests for one feature
+- refactor a module with dependent updates
+- reroute an automation from one Jira project to another
+- update references across a codebase after a system migration
+- change API integration endpoints or credentials
+
+#### Large
+
+`brainstorm + plan + executor`
+
+Signals:
+
+- cross-domain work
+- major uncertainty or architectural choice
+- a plan document already exists
+- many files or multiple independent workstreams
+- would benefit from orchestration, parallel execution, or audit passes
+
+Typical examples:
+
+- build a feature from scratch
+- implement a long plan doc
+- re-architect a subsystem
+
+#### Boundary: where micro ends and small begins
+
+Micro ends the moment any of these become true:
+
+- more than one meaningful edit is required
+- a test or build check is needed to trust the change
+- the correct change is not self-evident
+- the blast radius is larger than the immediate line or local block
+
+That is the boundary. If it needs verification or carries plausible regression risk, it is at least small.
+
+#### Boundary: where small ends and medium begins
+
+Small ends the moment any of these become true:
+
+- more than 3 files will be touched
+- external systems are involved (Jira, Slack, email, calendar, Freshservice, APIs)
+- the task requires reading and understanding unfamiliar code before changing it
+- changes span multiple concerns (code + communication, automation + configuration)
+- there are ordering dependencies between the changes
+- the user mentioned coordination with other people
+- the change affects routing, integration points, or cross-system references
+
+That is the boundary. If external systems are involved or the user needs to see the plan before you execute, it is at least medium. This boundary is not optional — do not downsize past it.
+
+#### ADaPT rule
+
+Try the simpler tier first — but never downsize past a forced boundary.
+
+- If it looks small and no forced-medium signals are present, start small.
+- If it looks medium and no forced-large signals are present, try medium.
+- If it looks large, ask whether a medium plan-plus-execute path is enough before invoking full orchestration.
+
+**Critical constraint**: ADaPT allows you to *start* at a simpler tier and escalate if needed. It does NOT allow you to skip the plan approval gate when `approval_mode` is `plan_first` and forced escalation signals are present. If forced-medium signals fired during sizing, you must present a plan — ADaPT cannot override that.
+
+Escalate when:
+
+- the simple approach fails
+- the user explicitly asks for the larger workflow
+- the complexity is obvious from the start
+- forced escalation signals are present (see Medium and Large sections above)
+
+### 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)
+
+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.
+
+- **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
+
+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:
+
+```
+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)
+```
+
+Then after Phase 1 completes, present Phase 2 before executing it.
+
+#### What auto-proceeds (no approval needed)
+
+- local code edits, documentation updates
+- tests, lint, builds, audits
+- local git operations (branch, commit, inspection)
+- reading from any MCP or API (GET requests)
+- blackboard reads and writes
+- saving drafts to `.ftm-drafts/`
+
+#### The momentum trap
+
+If you notice yourself thinking any of these, STOP — you are rationalizing past a gate:
+
+- "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
+
+Ask the user only when one of these is true:
+
+- two materially different interpretations are both plausible
+- an external-facing action needs approval
+- a required credential, path, or identifier is missing
+- the user explicitly asked for options before action
+- **the task is medium+ and involves external systems, stakeholder coordination, or unfamiliar code** (see Discovery Interview below)
+
+When asking, ask one focused question with concrete choices.
+
+Good:
+
+- "Do you want me to treat this as a bug fix or a refactor?"
+- "I can draft the Slack message or send it. Which do you want?"
+
+Bad:
+
+- "What do you want to do?"
+
+#### Discovery Interview (medium+ tasks with external systems)
+
+When a task hits forced-medium or higher AND involves external systems, stakeholder coordination, or code you haven't read yet this session, run a brief discovery interview BEFORE generating the plan. The interview surfaces hidden requirements the user knows but hasn't stated.
+
+The interview should be 2-4 focused questions, not open-ended. Ask about things you cannot determine from the codebase alone:
+
+- Who else needs to know about this change?
+- Are there downstream systems or automations that depend on what's changing?
+- Is there a timeline or dependency on someone else's approval?
+- Should we also draft a message to anyone about this?
+- Are there parts of this you want left alone for now vs. changed?
+
+Present the questions as a numbered list so the user can answer efficiently:
+
+```
+Before I plan this out, a few quick questions:
+
+1. Who else needs to know about this change? (Slack message, email, etc.)
+2. Are there downstream systems that depend on [thing being changed]?
+3. Anything you want left as-is for now that I should avoid touching?
+```
+
+Then incorporate their answers into the plan. This takes 30 seconds and prevents the "oh wait, we also needed to do X" moment that comes after 5 minutes of grinding.
+
+**When to skip the interview:**
+- The user already provided comprehensive context (e.g., pasted a Slack thread with full background)
+- The task is purely local with no external dependencies
+- The user explicitly says "just do it" or "no questions, go"
+
+### 11. Orient Synthesis
+
+Before leaving Orient, silently synthesize all signals into one internal picture:
+
+- current outcome the user wants
+- current task type
+- session continuity
+- codebase constraints
+- relevant lessons
+- relevant patterns
+- capability mix
+- smallest correct task size
+- whether approval or clarification is needed
+
+Orient is complete only when the next move feels obvious.
+
+## Decide
+
+Decide turns the orientation model into one concrete next move.
+
+### 1. Choose the smallest correct execution mode
+
+- `micro` -> direct action
+- `small` -> pre-flight summary, then direct action plus verification
+- `medium` -> numbered plan, wait for approval, then execute
+- `large` -> `ftm-brainstorm` if no plan exists, or `ftm-executor` if a plan exists
+
+**Double-check before committing to a size**: Re-read the forced escalation signals from the Complexity Sizing section. If any forced-medium signals fired, the task is medium regardless of how it feels. Do not rationalize past this — "it's basically just find-and-replace" is exactly how the Jira rerouting task looked before it turned into 15 edits across a 1700-line file plus stakeholder coordination plus a Slack draft. Present the plan.
+
+### 1.5 Interactive Plan Approval
+
+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 small tasks**: Show a brief pre-flight summary before executing. This is not a formal approval gate — just visibility so the user knows what's about to happen. Present it inline and proceed unless the user objects:
+
+```
+Quick summary before I start:
+- Read [file] to understand current behavior
+- Change [X] to [Y] in [file]
+- Verify: [test/lint/manual check]
+
+Going ahead unless you say otherwise.
+```
+
+**For medium and large tasks**: Present a numbered task list and wait for the user to approve before executing anything. Do NOT start executing while presenting the plan — the plan IS the first deliverable.
+
+**Step 0: Discovery Interview (if applicable).**
+
+Before generating the plan, check whether a Discovery Interview is needed (see Orient section 10). If the task involves external systems, stakeholder coordination, or unfamiliar code, run the interview FIRST. The user's answers feed directly into the plan — without them, the plan will miss requirements.
+
+The sequence is: Orient → Discovery Interview → Generate Plan → User Approval → Execute. Not: Orient → Generate Plan → Execute → "oh wait, we also needed to..."
+
+**Step 1: Generate the plan.**
+
+Build a numbered list of concrete steps based on Orient synthesis AND discovery interview answers. 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.
+
+### 2. Choose direct vs routed execution
+
+Use direct execution when:
+
+- the work is micro or small
+- routing overhead adds no value
+- the answer can be delivered faster than a delegated workflow
+
+Use a ftm skill when:
+
+- its specialized workflow will materially improve the result
+- the user explicitly invoked it
+- the task is medium/large and the skill is the right vehicle
+
+### 3. Choose any supporting MCP reads
+
+If the request depends on external context, fetch the minimum required state first.
+
+Examples:
+
+- Jira URL -> read the ticket first
+- meeting request -> read calendar first
+- internal policy question -> search Glean first
+- UI bug -> snapshot or inspect browser first
+
+### 4. Decide whether to loop
+
+If the next move will reveal new information, plan to re-enter Observe after the action. This is normal for debugging, investigation, and mixed-tool workflows.
+
+## Act
+
+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
+
+For micro tasks:
+
+- do the work
+- summarize what changed
+
+For small tasks (when `approval_mode` is `plan_first` or `always_ask`):
+
+- show the pre-flight summary first (see Decide section 1.5)
+- then do the work
+- verify
+- summarize what changed
+
+The pre-flight summary is not a gate — you proceed immediately after showing it unless the user objects. But showing it is mandatory because it gives the user a chance to catch mis-sizing or redirect before work begins. If the user says "wait" or "actually..." after seeing the pre-flight, stop and listen.
+
+Do not over-narrate during execution.
+
+### 2. Skill routing
+
+Before invoking a skill, show one short routing line.
+
+Examples:
+
+- `Routing to ftm-debug: this is a flaky failure with real diagnostic uncertainty.`
+- `Routing to ftm-brainstorm: this is still design-stage and benefits from research-backed planning.`
+
+Then invoke the target skill with the full user input.
+
+### 3. MCP execution
+
+Use:
+
+- parallel reads when safe
+- sequential writes
+- approval gates only for external-facing actions
+
+### 3.5. Draft-before-send protocol
+
+When composing Slack messages, emails, or any outbound communication, always save the draft locally before sending.
+
+**Drafts folder**: `.ftm-drafts/` in the project root (or `~/.claude/ftm-drafts/` if no project context).
+
+**Ensure the folder exists and is gitignored:**
+
+1. Create `.ftm-drafts/` if it doesn't exist
+2. Check `.gitignore` — if `.ftm-drafts/` is not listed, add it
+
+**Save every draft** before presenting it to the user or sending it:
+
+- Filename: `YYYY-MM-DD_HH-MM_<type>_<recipient-or-channel>.md` (e.g., `2026-03-19_14-30_slack_mo-ali.md`)
+- Content format:
+  ```markdown
+  ---
+  type: slack | email
+  to: #channel-name | @person | email@address
+  subject: (email only)
+  drafted: 2026-03-19T14:30:00
+  status: draft | sent | cancelled
+  ---
+
+  [message body]
+  ```
+
+**Workflow:**
+1. Compose the message
+2. Save to `.ftm-drafts/`
+3. Present to user for approval (this is already required by the approval gates)
+4. If approved and sent, update `status: sent` in the file
+5. If cancelled or modified, update accordingly
+
+This gives the user a local audit trail of everything ftm drafted on their behalf, without polluting git history.
+
+### 4. Blackboard updates (mandatory)
+
+After every completed task — not just "meaningful" ones — update the blackboard. This is how ftm learns. If you skip this step, the next session starts from zero on tasks like this one.
+
+**Always do all of these:**
+
+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 `~/.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:**
+
+3. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
+4. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
 
 The experience file should capture:
 - `task_type`: what kind of work this was (e.g., `integration-reroute`, `automation-update`, `bug-fix`)