feed-the-machine 1.5.0 → 1.6.0

package/ftm-mind/references/protocols/COMPLEXITY-SIZING.md

@@ -1,72 +1,72 @@
-# 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
-
-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
-
-## 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, or the complexity is obvious from the start.
+# 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
+
+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
+
+## 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, or the complexity is obvious from the start.

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

@@ -1,32 +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
+# 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

@@ -1,80 +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.
+# 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.