feed-the-machine 1.6.0 → 1.7.0

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

@@ -1,249 +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"` |
+# 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

@@ -1,22 +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 |
+# 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` (configured name — see `ops.mcp_account_rules` in ftm-config.yml), 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

@@ -1,35 +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` |
+# 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` (configured name — see `ops.mcp_account_rules` in ftm-config.yml), 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

@@ -1,2 +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.
+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-ops.yml

@@ -0,0 +1,4 @@
+---
+name: ftm-ops
+description: Personal operations intelligence — task management, capacity tracking, stakeholder comms, meeting intel, incident tracking, and pattern recognition. Use when user says "what's blocking me", "am I overcommitted", "wrap up", "what happened today", "what happened this week", task CRUD, capacity check, stakeholder update, meeting notes, incident report, pattern analysis, "add a task", "close task", "mark done", "daily summary", "weekly rollup", "follow up with", "draft message to", "how busy am I", "burnout check", "context switches", "recurring issue", "doc gap", "ftm-ops".
+---