feed-the-machine 1.6.1 → 1.7.0

package/ftm-mind/references/complexity-guide.md

@@ -1,110 +1,110 @@
-# Complexity Sizing Guide
-
-Orient must size tasks from observed evidence, not vibes. Use these tiers.
-
----
-
-## 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
-
-**Typical examples:**
-- fix a flaky test with several hypotheses
-- add UI + API + tests for one feature
-- refactor a module with dependent updates
-
----
-
-## 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
-
-If it needs verification or carries plausible regression risk, it is at least small.
-
----
-
-## ADaPT Rule
-
-Try the simpler tier first.
-
-- If it looks small, start small.
-- If it looks medium, see whether a small direct pass resolves it.
-- If it looks large, ask whether a medium plan-plus-execute path is enough before invoking full orchestration.
-
-Escalate only when:
-- the simple approach fails
-- the user explicitly asks for the larger workflow
-- the complexity is obvious from the start
-
----
-
-## Research Tasks
-
-Research tasks don't follow the micro/small/medium/large sizing — they route directly
-to ftm-researcher regardless of complexity. The researcher's mode system (quick/standard/deep)
-handles the depth calibration internally.
-
-If a research request also implies implementation ("research X and then build it"),
-orient as a multi-phase workflow: research first (ftm-researcher), then plan (ftm-brainstorm
-or direct), then execute (ftm-executor).
+# Complexity Sizing Guide
+
+Orient must size tasks from observed evidence, not vibes. Use these tiers.
+
+---
+
+## 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
+
+**Typical examples:**
+- fix a flaky test with several hypotheses
+- add UI + API + tests for one feature
+- refactor a module with dependent updates
+
+---
+
+## 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
+
+If it needs verification or carries plausible regression risk, it is at least small.
+
+---
+
+## ADaPT Rule
+
+Try the simpler tier first.
+
+- If it looks small, start small.
+- If it looks medium, see whether a small direct pass resolves it.
+- If it looks large, ask whether a medium plan-plus-execute path is enough before invoking full orchestration.
+
+Escalate only when:
+- the simple approach fails
+- the user explicitly asks for the larger workflow
+- the complexity is obvious from the start
+
+---
+
+## Research Tasks
+
+Research tasks don't follow the micro/small/medium/large sizing — they route directly
+to ftm-researcher regardless of complexity. The researcher's mode system (quick/standard/deep)
+handles the depth calibration internally.
+
+If a research request also implies implementation ("research X and then build it"),
+orient as a multi-phase workflow: research first (ftm-researcher), then plan (ftm-brainstorm
+or direct), then execute (ftm-executor).

package/ftm-mind/references/complexity-sizing.md

@@ -0,0 +1,138 @@
+# 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)

package/ftm-mind/references/decide-act-protocol.md

@@ -0,0 +1,172 @@
+# Decide + Act Protocol
+
+## 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 reference. If any forced-medium signals fired, the task is medium regardless of how it feels.
+
+### 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. Not a formal gate — just visibility:
+
+```
+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.
+
+**Step 0: Discovery Interview (if applicable).** Before generating the plan, check whether a Discovery Interview is needed (see Orient reference). If the task involves external systems, stakeholder coordination, or unfamiliar code, run the interview FIRST.
+
+**Step 1: Generate the plan.** Build a numbered list of concrete steps. Each step has:
+- A number
+- A one-line description
+- The files that will be touched
+- The verification method
+
+**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, then execute all |
+| `add: [description] after N` | Insert a new step, renumber, then execute all |
+| `deny`, `stop`, `cancel`, `no` | Cancel. Do not execute anything. |
+| A longer message with mixed feedback | Parse each instruction. Apply all modifications. Present revised plan and ask for final approval. |
+
+**Step 3: Execute the approved plan.** Work through steps sequentially. After each step show: `Step 2/5 done: [summary].` If a step fails, stop and report.
+
+**Step 4: Post-execution update.** Update blackboard with decisions and experience.
+
+#### Mode: `always_ask`
+Same as `plan_first` but applies to **small** tasks too. Only micro tasks skip the approval gate.
+
+#### Combining with explicit skill routing
+When routing to a skill, plan approval still applies if mode is `plan_first` or `always_ask`. Present the strategy for user control.
+
+### 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.
+
+## 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?
+2. If the task involves external mutations (see Approval Gates), have you presented the specific actions and received approval?
+3. If neither condition applies, proceed.
+
+### 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
+- then do the work
+- verify
+- summarize what changed
+
+### 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.** Save every draft before presenting or sending:
+
+- Filename: `YYYY-MM-DD_HH-MM_<type>_<recipient-or-channel>.md`
+- Content includes frontmatter: type, to, subject (email only), drafted timestamp, status (draft/sent/cancelled)
+
+**Workflow:**
+1. Compose the message
+2. Save to `.ftm-drafts/`
+3. Present to user for approval
+4. If approved and sent, update `status: sent`
+5. If cancelled or modified, update accordingly
+
+### 4. Blackboard updates (mandatory)
+
+After every completed task, update the blackboard:
+
+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. 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`, `tags`, `outcome`, `lessons`, `files_touched`, `stakeholders`, `decisions_made`
+
+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

package/ftm-mind/references/direct-execution.md

@@ -0,0 +1,51 @@
+# Direct Execution — Micro and Small Tasks
+
+## Micro Execution
+
+For tasks sized as `micro` (one coherent local action, trivial blast radius):
+
+1. **Execute immediately** — no plan, no pre-flight, no approval gate
+2. **Do the work** — make the edit, answer the question, fix the typo
+3. **Summarize briefly** — one sentence about what changed
+4. **Update blackboard** — even micro tasks get an experience entry if they taught something
+
+Do not over-narrate micro tasks. The user asked for a rename, not a paragraph about renaming.
+
+## Small Execution
+
+For tasks sized as `small` (1-3 files, one concern, needs verification):
+
+### When `approval_mode` is `plan_first` or `always_ask`:
+
+1. **Show pre-flight summary** before starting:
+   ```
+   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.
+   ```
+2. **Proceed immediately** after showing the summary — this is not a gate, just visibility
+3. **Stop if the user objects** — if they say "wait" or "actually...", listen
+4. **Do the work**
+5. **Run verification** — the test, build check, or lint that confirms it works
+6. **Summarize** — what changed, what was verified
+
+### When `approval_mode` is `auto`:
+
+1. **Do the work** directly
+2. **Run verification**
+3. **Summarize**
+
+## When to Escalate from Direct Execution
+
+Stop and re-orient if any of these happen during execution:
+
+- You discover the change touches more files than expected
+- An external system is involved that wasn't obvious at sizing time
+- The verification step fails and the fix isn't obvious
+- You realize stakeholder coordination is needed
+- The blast radius is larger than initially assessed
+
+Escalation means going back to Orient with new information, not giving up.

package/ftm-mind/references/environment-discovery.md

@@ -0,0 +1,77 @@
+# Environment Discovery Protocol
+
+This is an Orient sub-phase that 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.
+
+> **Config note**: The Atlassian server names (`mcp-atlassian-personal`, `mcp-atlassian`) are defaults. Read `ops.mcp_account_rules` from `ftm-config.yml` for the configured names and probe those instead if they differ.
+
+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
+
+Write 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?"