feed-the-machine 1.7.0 → 1.7.2

package/README.md

@@ -24,11 +24,23 @@ Think of it like this: regular AI is a blank whiteboard every time you walk into
 
 ## Install
 
+**Everything** (26 skills + 15 hooks):
 ```bash
 npx feed-the-machine@latest
 ```
 
-That's it. Takes 30 seconds. Works with any existing Claude Code setup.
+**Just the skills you want:**
+```bash
+npx feed-the-machine --only ftm-council-chat,ftm-mind
+```
+This always includes `ftm` (the router) and `ftm-config` as base dependencies.
+
+**See what's available:**
+```bash
+npx feed-the-machine --list
+```
+
+Works with any existing Claude Code setup. After install, restart Claude Code or start a new session.
 
 ---
 
@@ -52,6 +64,20 @@ Describe something you're trying to figure out. It researches the web and GitHub
 ```
 Paste an error or describe weird behavior. It attacks the problem from multiple angles at once — way faster than stepping through it manually.
 
+**Get a second opinion:**
+```
+/ftm-council
+```
+Not sure about an architecture choice or debugging approach? This sends the problem to Claude, GPT, and Gemini independently. They debate in rounds until at least two agree. Like calling three contractors instead of trusting the first quote.
+
+**Open the chatroom:**
+```
+/ftm-council-chat
+```
+An AIM-styled browser chatroom where you, Claude, Codex, and Gemini all talk in real time. You're a full participant, not just watching.
+
+<img src="docs/images/council-chat.png" alt="ftm-council-chat screenshot — AIM-styled chatroom with Claude, Codex, and Gemini debating Jira token types" width="800" />
+
 ---
 
 ## Before / After
@@ -98,26 +124,84 @@ Every task makes it smarter. Fix a bug? It remembers the root cause. Ship a feat
 
 ## What's Included
 
-FTM comes with 20+ specialized skills. You don't need to memorize them — just use `/ftm` and it picks the right ones automatically. But here's what's under the hood:
+FTM ships with 26 skills and 15 automation hooks. You don't need to memorize them — just use `/ftm` and it picks the right ones automatically. But here's what's under the hood:
+
+### Core
+
+| Skill | Plain English |
+|-------|--------------|
+| **ftm-mind** | The brain. Reads your input, pulls memory, sizes complexity, picks the right approach |
+| **ftm-executor** | The hands. Takes the plan and does the work with parallel agents in isolated worktrees |
+| **ftm-ops** | Your ops dashboard. Task management, capacity tracking, stakeholder comms, meeting intel, burnout detection |
+| **ftm-config** | Settings. Choose which AI models handle planning vs execution vs review |
+
+### Thinking & Research
 
 | Skill | Plain English |
 |-------|--------------|
-| **ftm-mind** | The brain. Reads your input, pulls memory, picks the right approach, makes a plan |
-| **ftm-executor** | The hands. Takes the plan and actually does the work with parallel agents |
-| **ftm-debug** | Bug detective. Attacks problems from multiple angles simultaneously |
-| **ftm-brainstorm** | Thinking partner. Researches, challenges assumptions, surfaces options |
-| **ftm-council** | Second opinions. Asks Claude, GPT, and Gemini, then goes with the majority |
-| **ftm-browse** | Web automation. Opens browsers, fills forms, takes screenshots |
+| **ftm-brainstorm** | Thinking partner. Researches the web and GitHub in parallel, challenges assumptions, surfaces options |
+| **ftm-researcher** | Deep research engine. 7 specialized finder agents search in parallel, then adversarially review each other's findings |
+| **ftm-council** | Second opinions. Sends the problem to Claude, GPT, and Gemini — goes with the majority |
+| **ftm-council-chat** | AIM-styled chatroom. You, Claude, Codex, and Gemini all talking in a browser window |
+
+### Building & Debugging
+
+| Skill | Plain English |
+|-------|--------------|
+| **ftm-debug** | Bug war room. Attacks problems from multiple angles simultaneously |
+| **ftm-audit** | Wiring check. Makes sure all code is actually connected and working — static analysis + LLM audit |
+| **ftm-codex-gate** | Code validation gate. Sends your code to GPT for adversarial review before it ships |
+| **ftm-browse** | Web automation. Opens browsers, fills forms, takes screenshots, inspects pages |
 | **ftm-git** | Safety net. Scans for leaked passwords/keys before you push code |
-| **ftm-audit** | Quality check. Makes sure all the code is actually connected and working |
-| **ftm-map** | Codebase intelligence. Knows which files matter most and what breaks if you change something |
-| **ftm-intent** | Living docs. Keeps documentation updated automatically when code changes |
-| **ftm-diagram** | Architecture diagrams. Auto-generated and auto-updated |
-| **ftm-retro** | Self-improvement. Reviews its own work and learns from it |
-| **ftm-pause / resume** | Save and restore. Pick up exactly where you left off |
-| **ftm-config** | Settings. Choose which AI models to use for what |
+
+### Codebase Intelligence
+
+| Skill | Plain English |
+|-------|--------------|
+| **ftm-map** | Code knowledge graph. Knows what depends on what and what breaks if you change something |
+| **ftm-intent** | Living docs. Keeps function-level documentation updated automatically when code changes |
+| **ftm-diagram** | Architecture diagrams. Auto-generated mermaid diagrams that stay current |
+
+### Quality & Learning
+
+| Skill | Plain English |
+|-------|--------------|
+| **ftm-verify** | Post-execution verification. Two independent AI models audit the completed work, then auto-fix anything they find |
+| **ftm-retro** | Self-assessment. Reviews its own execution and scores it across 5 dimensions |
+| **ftm-capture** | Knowledge extraction. Turns what you just did into reusable routines and playbooks |
+| **ftm-dashboard** | Analytics. Shows which skills you use, approval rates, and session stats |
+
+### Workflow & Session
+
+| Skill | Plain English |
+|-------|--------------|
+| **ftm-routine** | Recurring workflows. Define multi-step routines in YAML and run them by name |
+| **ftm-pause / resume** | Save and restore. Pick up exactly where you left off in a new conversation |
 | **ftm-upgrade** | Self-update. Stay current with one command |
 
+### Hooks (16 automations)
+
+These run automatically in the background — no slash commands needed:
+
+| Hook | What It Does |
+|------|-------------|
+| **event-logger** | Logs every tool use to a JSONL file with debouncing and 30-day rotation |
+| **auto-log** | Detects when you report completing work and reminds Claude to log progress |
+| **learning-capture** | Captures edits and task completions into a learning database for pattern recognition |
+| **session-snapshot** | Saves the last 15 exchanges as a markdown snapshot when a session ends — crash recovery |
+| **session-end** | Marks the current session as completed in the blackboard |
+| **blackboard-enforcer** | Nudges Claude to record meaningful work to the blackboard before a session ends undocumented |
+| **plan-gate** | Prevents code edits without a plan — soft-warns at first, blocks after 3+ edits |
+| **task-loader** | Loads active tasks from your task database when a session starts |
+| **pre-compaction** | Monitors token usage and flushes state to disk before context hits 75% capacity |
+| **post-compaction** | After context compresses, reloads critical state from disk before responding |
+| **map-autodetect** | Detects unmapped projects on first use and bootstraps the code knowledge graph |
+| **post-commit-trigger** | After git commits, triggers code map sync and documentation updates |
+| **pending-sync-check** | Surfaces out-of-session commits that need code map syncing |
+| **discovery-reminder** | Reminds Claude to run a discovery interview for tasks involving external systems or migrations |
+| **drafts-gate** | Blocks Slack and Gmail sends unless a draft file exists first — no accidental messages |
+| **install-hooks** | Self-installer that registers all hooks into Claude Code's settings.json |
+
 ---
 
 ## The Secret Sauce
@@ -140,15 +224,33 @@ Three things make FTM different from "just using Claude Code":
 profile: balanced    # quality | balanced | budget
 
 profiles:
-  balanced:
+  quality:
     planning: opus      # the deep thinker
-    execution: sonnet   # the fast worker
+    execution: opus     # thorough but slower
     review: sonnet      # the checker
+
+  balanced:
+    planning: opus
+    execution: sonnet   # fast worker
+    review: sonnet
+
+  budget:
+    planning: sonnet
+    execution: sonnet
+    review: haiku       # cheapest
+```
+
+**Execution settings:**
+
+```yaml
+execution:
+  agent_mode: bypassPermissions   # how much autonomy agents get
+  max_parallel_agents: 5          # simultaneous agent workers
 ```
 
 **Optional extras** for the full experience:
 
-- [Codex CLI](https://github.com/openai/codex) — Powers the second-opinion council and code validation
+- [Codex CLI](https://github.com/openai/codex) — Powers the council, code validation, and adversarial review
 - [Gemini CLI](https://github.com/google/gemini-cli) — Third voice in the council
 - Playwright MCP server (`npx @playwright/mcp@latest`) — Powers browser automation
 
@@ -158,13 +260,29 @@ Everything else runs on Claude Code alone.
 
 ```bash
 git clone https://github.com/kkudumu/feed-the-machine.git ~/feed-the-machine
-cd ~/feed-the-machine && ./install.sh
+cd ~/feed-the-machine && ./install.sh                          # everything
+# or: ./install.sh --only ftm-council-chat                     # just one skill
+# or: ./install.sh --list                                      # see what's available
 ```
 
 **Uninstall:** `./uninstall.sh` (removes skills, keeps your memory data)
 
 ---
 
+## Current Version
+
+**v1.7.0** (April 2026) — [Full changelog](CHANGELOG.md)
+
+Recent highlights:
+- **ftm-ops**: Personal operations intelligence (task management, capacity tracking, burnout detection, stakeholder comms)
+- **ftm-mind slimmed from 87KB to 10KB** via progressive disclosure
+- **ftm-verify**: Dual-model adversarial verification (Codex + Gemini audit your completed work independently)
+- **ftm-council-chat**: AIM-styled browser chatroom for multi-AI conversations
+- **15 automation hooks** for event logging, learning capture, secret scanning, and session management
+- **Configurable agent permissions** and parallel agent limits
+
+---
+
 ## License
 
 MIT

package/bin/install.mjs

@@ -7,9 +7,12 @@
  * Safe to re-run — idempotent.
  *
  * Flags:
- *   --with-inbox    Also install the inbox service
- *   --no-hooks      Skip hooks entirely
- *   --skip-merge    Install hook files but don't touch settings.json
+ *   --only skill1,skill2  Install specific skills (always includes ftm + ftm-config)
+ *   --list                List available skills with descriptions
+ *   --with-inbox          Also install the inbox service
+ *   --no-hooks            Skip hooks entirely
+ *   --with-hooks          Include hooks even with --only
+ *   --skip-merge          Install hook files but don't touch settings.json
  */
 
 import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
@@ -31,8 +34,25 @@ const INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
 
 const ARGS = process.argv.slice(2);
 const WITH_INBOX = ARGS.includes("--with-inbox");
-const NO_HOOKS = ARGS.includes("--no-hooks");
 const SKIP_MERGE = ARGS.includes("--skip-merge");
+const LIST_MODE = ARGS.includes("--list");
+const WITH_HOOKS_FLAG = ARGS.includes("--with-hooks");
+
+// Parse --only (supports --only=x,y and --only x,y)
+const ONLY_RAW = ARGS.find(a => a.startsWith("--only="))?.split("=")[1]
+  || (ARGS.includes("--only") ? ARGS[ARGS.indexOf("--only") + 1] : null);
+
+const ONLY_SKILLS = ONLY_RAW
+  ? new Set(["ftm", "ftm-config", ...ONLY_RAW.split(",").map(s => s.trim())])
+  : null;
+
+// When --only is used, skip hooks unless --with-hooks or explicit --no-hooks
+const NO_HOOKS = ARGS.includes("--no-hooks") || (ONLY_SKILLS && !WITH_HOOKS_FLAG);
+
+function skillWanted(name) {
+  if (!ONLY_SKILLS) return true;
+  return ONLY_SKILLS.has(name);
+}
 
 let warnCount = 0;
 
@@ -268,29 +288,58 @@ function verify(skillCount, hookCount) {
   return { errors };
 }
 
+// --- List Mode ---
+
+function listSkills() {
+  console.log("\nAvailable FTM skills:\n");
+  const ymlFiles = readdirSync(REPO_DIR).filter(
+    (f) => f.startsWith("ftm-") && f.endsWith(".yml") && !f.includes("config.default")
+  );
+  for (const yml of ymlFiles) {
+    const name = yml.replace(".yml", "");
+    const content = readFileSync(join(REPO_DIR, yml), "utf8");
+    const descMatch = content.match(/^description:\s*(.+)/m);
+    const desc = descMatch ? descMatch[1].slice(0, 80) : "";
+    console.log(`  ${name.padEnd(22)} ${desc}`);
+  }
+  console.log("\nInstall specific skills: npx feed-the-machine --only ftm-council-chat,ftm-mind");
+  console.log("Install everything:      npx feed-the-machine\n");
+  process.exit(0);
+}
+
 // --- Main ---
 
 function main() {
+  if (LIST_MODE) {
+    listSkills();
+  }
+
   preflight();
 
-  console.log(`Installing ftm skills from: ${REPO_DIR}`);
+  if (ONLY_SKILLS) {
+    const requested = [...ONLY_SKILLS].filter(s => s !== "ftm" && s !== "ftm-config").join(", ");
+    console.log(`Installing selected FTM skills: ${requested} (+ ftm, ftm-config)`);
+  } else {
+    console.log(`Installing all FTM skills from: ${REPO_DIR}`);
+  }
   console.log(`Linking into: ${SKILLS_DIR}`);
   console.log("");
 
   ensureDir(SKILLS_DIR);
 
-  // Link all ftm*.yml files
+  // Link ftm*.yml files (filtered by --only if set)
   const ymlFiles = readdirSync(REPO_DIR).filter(
     (f) => f.startsWith("ftm") && f.endsWith(".yml") && !f.includes("config.default")
-  );
+  ).filter((f) => skillWanted(f.replace(".yml", "")));
   for (const yml of ymlFiles) {
     safeSymlink(join(REPO_DIR, yml), join(SKILLS_DIR, yml));
   }
 
-  // Link all ftm* directories (skills with SKILL.md)
+  // Link ftm* directories (filtered by --only if set)
   const dirs = readdirSync(REPO_DIR).filter((f) => {
     if (!f.startsWith("ftm")) return false;
     if (f === "ftm-state") return false;
+    if (!skillWanted(f)) return false;
     const fullPath = join(REPO_DIR, f);
     try {
       return lstatSync(fullPath).isDirectory();

package/ftm-audit/SKILL.md

@@ -194,6 +194,51 @@ Append a row to the root INTENT.md module map table:
 
 ---
 
+## Layer 1.75: Filesystem Path Resolution Check
+
+**Purpose:** Verify that all file paths and CLI commands referenced in SKILL.md and reference files actually resolve from the installed skill location. This catches the most dangerous class of wiring bug — code that passes every static check but fails at runtime because a path doesn't exist where the skill expects it.
+
+**When to run:** After Layer 1.5, before Layer 2. Runs on ANY project that has `.md` files with path references (not just code projects). This is especially critical after tasks that change path references, move files, or update directory structures.
+
+**Scope:** Scan all `.md` files in the changed diff for path references.
+
+**Check protocol:**
+
+1. **Find changed markdown files:** `git diff HEAD~1 --name-only -- '*.md' '*.yml'`
+2. **For each changed file, extract path references** matching these patterns:
+   - Absolute paths: `~/.claude/`, `/Users/`, `/home/`
+   - CLI commands: `python3 <path>`, `bash <path>`, `node <path>`
+   - Skill-relative paths: `bin/`, `references/`, `scripts/`
+   - Config-referenced paths: any path that appears after a `paths.` config key
+3. **Resolve each path from the installed location:**
+   - For skill files (in `~/.claude/skills/<name>/`): resolve relative to the skill's install directory
+   - For absolute paths (`~/.claude/...`): resolve directly
+   - For CLI commands: extract the path argument, resolve it, then verify execution with `--help` or `--version`
+4. **Verify existence:** `test -e <resolved-path>` for each
+5. **For CLI commands:** additionally verify `python3 <path> --help 2>&1` exits without "No such file or directory"
+
+**Finding types:**
+
+| Finding | Severity | Auto-fixable? |
+|---------|----------|---------------|
+| `BROKEN_PATH` — path in .md file doesn't resolve from installed location | HARD FAIL | No — requires human decision on correct path |
+| `BROKEN_CLI` — CLI command path doesn't exist or errors on execution | HARD FAIL | No — requires fixing the path or creating a symlink |
+| `HARDCODED_USER_PATH` — absolute path contains a specific username (e.g., `/Users/kioja.kudumu/`) | WARN | Yes — replace with `~/` or `$HOME/` equivalent |
+| `STALE_PATH_REFERENCE` — path references a directory/file that was moved or renamed in this diff | HARD FAIL | Yes — update to new path |
+
+**Output format:**
+```
+Layer 1.75 findings:
+- [BROKEN_PATH] ftm-ops/SKILL.md:53 — `~/.claude/skills/ftm/bin/brain.py` does not exist (ftm/ points to router subdirectory, not repo root)
+- [BROKEN_CLI] ftm-mind/references/orient-protocol.md:210 — `python3 ~/.claude/skills/eng-buddy/bin/brain.py` → file not found
+- [HARDCODED_USER_PATH] ftm-mind/references/ops-routing.md:44 — `/Users/kioja.kudumu/.claude/eng-buddy/drafts/` contains hardcoded username
+- [STALE_PATH_REFERENCE] ftm-ops/references/task-management.md:15 — `~/.claude/eng-buddy/active-tasks.md` was moved to `~/.claude/ftm-ops/active-tasks.md`
+```
+
+**Why this layer exists:** In the v1.7.0 merge, 160+ path references were updated across 23 files. Every static check passed. The integration test verified brain.py worked from the repo path. But when a user invoked `/ftm-ops`, it called `python3 ~/.claude/skills/ftm/bin/brain.py` — which didn't exist because the `ftm` skill symlink pointed to the `ftm/` subdirectory (the router), not the repo root. A 2-second `test -e` would have caught this. This layer ensures it always does.
+
+---
+
 ## Layer 2: LLM Adversarial Audit
 
 **Mindset:** You are an adversary trying to PROVE code is dead. Not "confirm it works" — PROVE it's dead. Every new/modified export is guilty until proven innocent. You must find a complete chain from app entry point to the code in question, or it's flagged.
@@ -508,7 +553,8 @@ When invoked (manually via `/ftm-audit` or automatically post-task):
 1. Run Phase 0 (detect project patterns — framework, router, state, API layer)
 2. Run Layer 1 (knip static analysis)
 3. Run Layer 1.5 (documentation coverage check — INTENT.md entries for changed functions)
-4. Run Layer 2 (LLM adversarial audit, calibrated to detected patterns)
+4. Run Layer 1.75 (filesystem path resolution — verify all referenced paths exist from installed location)
+5. Run Layer 2 (LLM adversarial audit, calibrated to detected patterns)
 5. Combine findings, deduplicate
 6. Run Layer 3 (auto-fix) for each finding (including missing INTENT.md entries)
 7. Re-verify (re-run Layers 1+1.5+2)
@@ -540,6 +586,10 @@ After completing, update the blackboard:
 - Findings: [N]
 - [list each finding — missing entries, stale entries, missing module docs]
 
+### Layer 1.75: Path Resolution
+- Findings: [N]
+- [list each finding — broken paths, broken CLI commands, hardcoded user paths]
+
 ### Layer 2: Adversarial Audit
 - Findings: [N]
 - [list each finding with file:line and evidence]

package/ftm-council-chat.yml

@@ -0,0 +1,2 @@
+name: ftm-council-chat
+description: AIM-styled browser chatroom where Claude, Codex, and Gemini hold real-time conversations with the user as a full participant. Use when user says "chatroom", "aim chat", "council chat", "live debate", "open the chatroom", or "council-chat".

package/ftm-executor/references/phases/PHASE-4-5-AUDIT.md

@@ -19,7 +19,16 @@ Before running ftm-audit, verify these four checks for every task:
 
    **Graceful degradation**: If ftm-browse binary is not installed, skip visual checks with a note: "Visual smoke test skipped — ftm-browse not installed." Do not fail the task.
 
-A task is NOT marked complete until checks 1–4 pass (check 5 is optional).
+6. **Path resolution check** — If the task changed any file/CLI path references in SKILL.md or reference files:
+   - Extract all paths matching patterns: `~/.claude/`, `bin/`, `python3 `, `bash `
+   - Resolve each path from the installed skill location (`~/.claude/skills/<skill-name>/`)
+   - Verify the target exists: `test -e <resolved-path>`
+   - For CLI commands (`python3 <path>`), verify execution: `python3 <path> --help` exits 0
+   - Flag any path that doesn't resolve as a BLOCKER — the skill will fail at runtime
+
+   **Why this exists**: In the v1.7.0 eng-buddy merge, all brain.py references were updated from `~/.claude/skills/eng-buddy/bin/brain.py` to `~/.claude/skills/ftm/bin/brain.py`. The path existed in the repo but `~/.claude/skills/ftm/` pointed to the `ftm/` subdirectory (the router skill), not the repo root — so the path didn't resolve at runtime. This was caught by a user, not by the audit. A 2-second `test -e` check would have caught it.
+
+A task is NOT marked complete until checks 1–4 pass (checks 5-6 are conditional).
 
 **Failure handling:**
 - Test failures → agent must fix before task completes

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

@@ -108,3 +108,22 @@ 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
+
+## Recording Code Patterns and API Gotchas
+
+When writing an experience after task completion, actively check for these:
+
+**code_patterns** — If during the task you wrote code that interacts with an API, library, or module, save the **final working version** (not the failed attempts). Include imports, setup, and the actual call. This is the copy-pasteable snippet future sessions will use.
+
+**api_gotchas** — If you hit errors because an API behaved differently than expected (wrong return type, unexpected method name, None instead of Response, objects instead of dicts), record each one. Format: what the module is, what's surprising, and what you'd wrongly assume.
+
+**playbook_ref** — If a brain.py playbook was created (via ftm-capture or auto-playbook trigger), record the path so the experience and playbook cross-reference each other.
+
+**When to populate these fields:**
+- You hit 2+ errors on the same module before getting it right → record code_patterns + api_gotchas
+- You used an API/library for the first time in this project → record code_patterns
+- The auto-playbook hook fired → record all three fields
+
+**When to skip:**
+- Pure file editing, config changes, or git operations — no API interaction worth capturing
+- The code pattern is already in an existing experience (check by module name before duplicating)

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

@@ -37,11 +37,7 @@ Going ahead unless you say otherwise.
 
 **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 1: Generate the plan.** Build a numbered checkbox list. This format is **mandatory** — no narrative steps, no prose paragraphs. Every plan MUST use: `N. [ ] One-line action → target`. See `references/protocols/PLAN-APPROVAL.md` for the full format spec, examples for code/ops/comms/infra tasks, and the list of NEVER-produce anti-patterns.
 
 **Step 2: Parse the user's response.**
 

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

@@ -10,11 +10,30 @@ For **medium and large** tasks, present a numbered task list and wait for the us
 
 **Step 1: Generate the plan.**
 
-Build a numbered list of concrete steps based on Orient synthesis. Each step must have:
+Build a numbered checkbox list. This format is **mandatory** — no narrative steps, no prose paragraphs, no bullet-point summaries. Every plan, whether it's code, ops, comms, or infrastructure, MUST use this exact format:
+
+```
+  N. [ ] One-line action → target (file, channel, system, or person)
+```
+
+Each step must have:
 - A number
+- A `[ ]` checkbox (literal characters, not rendered)
 - 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")
+- An arrow `→` pointing to the target: file path for code, channel/email for comms, system name for infra, or "self-evident" for simple actions
+- If applicable, a verification method after the target: `verify: test / lint / visual check / confirmation`
+
+**This applies to ALL task types, not just code:**
+- Code tasks: `3. [ ] Add OAuth validation → src/middleware/oauth.ts  verify: npm test`
+- Ops/comms tasks: `1. [ ] Reply to Everett requesting domain mapping → Braintrust support thread`
+- Infra tasks: `2. [ ] Create Freshservice webhook trigger → freshservice admin / workflows`
+- Admin tasks: `4. [ ] Close out ITWORK2-9772 → Jira`
+
+**NEVER produce:**
+- Narrative paragraphs describing steps
+- Numbered steps without `[ ]` checkboxes
+- Steps with sub-bullets explaining details (put that in execution, not the plan)
+- Headers like "Step 1:" or "### Step 1" — use the numbered checkbox format only
 
 Present it like this:
 
@@ -36,6 +55,21 @@ Approve all? Or tell me what to change.
   - "deny" or "stop" → cancel entirely
 ```
 
+**Ops example:**
+
+```
+Here's my plan for the Braintrust post-SSO setup:
+
+  1. [ ] Reply to Everett requesting domain mapping + group mappings → Braintrust support thread
+  2. [ ] Reply to Spencer with admin process answer → #proj-braintrust
+  3. [ ] Request API key from Everett or Spencer → Braintrust org settings
+  4. [ ] Build Freshservice webhook → Braintrust API integration → freshservice workflows + Lambda
+  5. [ ] Reconcile existing users vs Okta groups → Braintrust API + Okta
+  6. [ ] Close out ITWORK2-9772 → Jira
+
+Approve all? Or tell me what to change.
+```
+
 **Step 2: Parse the user's response.**
 
 | User says | Action |

package/ftm-state/schemas/experience.schema.json

@@ -73,6 +73,56 @@
       "items": {
         "type": "string"
       }
+    },
+    "code_patterns": {
+      "type": "array",
+      "description": "Working code snippets discovered during this task — the final correct version, not the failed attempts. Include imports, setup, and the actual call pattern.",
+      "items": {
+        "type": "object",
+        "required": ["module", "code"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "The primary module/library this pattern uses (e.g. shared_services.okta.groups)"
+          },
+          "code": {
+            "type": "string",
+            "description": "The working code snippet — complete and copy-pasteable"
+          },
+          "description": {
+            "type": "string",
+            "description": "One-line description of what this pattern does"
+          }
+        }
+      }
+    },
+    "api_gotchas": {
+      "type": "array",
+      "description": "Surprising API behaviors, wrong assumptions, and type mismatches discovered during this task. Things that caused errors and would cause them again without this note.",
+      "items": {
+        "type": "object",
+        "required": ["module", "gotcha"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "The module/API where the gotcha was discovered"
+          },
+          "gotcha": {
+            "type": "string",
+            "description": "What's surprising or wrong — e.g. 'list_members() returns OktaUser objects, not dicts'"
+          },
+          "wrong_assumption": {
+            "type": "string",
+            "description": "What you'd naturally assume that turns out to be wrong"
+          }
+        }
+      }
+    },
+    "playbook_ref": {
+      "type": "string",
+      "description": "Path to the brain.py playbook entry if one was created from this experience, for cross-referencing"
     }
   }
 }

package/hooks/ftm-learning-capture.sh

@@ -100,6 +100,139 @@ except Exception:
   fi
 fi
 
+# --- Auto-Playbook Trigger: detect repeated errors then success on same module ---
+ERROR_TRACKER="$FTM_STATE/.error-tracker.jsonl"
+
+if [ "$TOOL_NAME" = "Bash" ]; then
+  # Extract module/import and error status from the tool result
+  ANALYSIS=$(printf '%s' "$PAYLOAD" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    output = d.get("tool_result", "") or ""
+    tool_input = d.get("tool_input", {})
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    is_error = "Error:" in output or "Traceback" in output or "AttributeError" in output or "TypeError" in output or "ImportError" in output or "ModuleNotFoundError" in output
+    # Extract the primary module from import statements in the command
+    module = ""
+    for line in command.split("\n"):
+        line = line.strip()
+        if line.startswith("from ") and " import " in line:
+            module = line.split("from ")[1].split(" import")[0].strip()
+            break
+        elif line.startswith("import "):
+            module = line.split("import ")[1].split()[0].strip()
+            break
+    import json as j
+    j.dump({"is_error": is_error, "module": module}, sys.stdout)
+except Exception:
+    import json as j
+    j.dump({"is_error": False, "module": ""}, sys.stdout)
+' 2>/dev/null)
+
+  IS_ERROR=$(printf '%s' "$ANALYSIS" | python3 -c 'import json,sys; print("1" if json.load(sys.stdin).get("is_error") else "0")' 2>/dev/null)
+  MODULE=$(printf '%s' "$ANALYSIS" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("module",""))' 2>/dev/null)
+
+  if [ -n "$MODULE" ]; then
+    TIMESTAMP=$(date +%s)
+    if [ "$IS_ERROR" = "1" ]; then
+      # Append error event
+      echo "{\"ts\":$TIMESTAMP,\"module\":\"$MODULE\",\"type\":\"error\"}" >> "$ERROR_TRACKER"
+    else
+      # Success — check if this module had 3+ recent errors
+      if [ -f "$ERROR_TRACKER" ]; then
+        ERROR_COUNT=$(python3 -c "
+import json, sys
+count = 0
+cutoff = $TIMESTAMP - 600  # last 10 minutes
+for line in open('$ERROR_TRACKER'):
+    line = line.strip()
+    if not line: continue
+    try:
+        ev = json.loads(line)
+        if ev.get('module') == '$MODULE' and ev.get('type') == 'error' and ev.get('ts', 0) >= cutoff:
+            count += 1
+    except: pass
+print(count)
+" 2>/dev/null)
+
+        if [ "$ERROR_COUNT" -ge 3 ]; then
+          # Write a blackboard experience with the module and error count
+          SLUG=$(echo "$MODULE" | tr '.' '-' | tr '[:upper:]' '[:lower:]')
+          DATE_STAMP=$(date +%Y-%m-%d)
+          EXP_FILE="$FTM_STATE/blackboard/experiences/${DATE_STAMP}_auto-playbook-${SLUG}.json"
+          python3 -c "
+import json, os, datetime
+exp = {
+    'task_type': 'api-discovery',
+    'task_description': 'Auto-captured: $ERROR_COUNT errors on $MODULE before finding the working pattern',
+    'lessons_learned': [
+        '$MODULE required $ERROR_COUNT attempts to get right — working pattern saved as playbook',
+        'Check experience code_patterns before using this module in future sessions'
+    ],
+    'code_patterns': [],
+    'api_gotchas': [],
+    'playbook_ref': None,
+    'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+    'confidence': 0.7,
+    'tags': ['auto-playbook', '$(echo "$MODULE" | tr "." " ")']
+}
+os.makedirs(os.path.dirname('$EXP_FILE'), exist_ok=True)
+with open('$EXP_FILE', 'w') as f:
+    json.dump(exp, f, indent=2)
+
+# Update index
+idx_path = '$FTM_STATE/blackboard/experiences/index.json'
+try:
+    with open(idx_path) as f:
+        idx = json.load(f)
+except:
+    idx = {'entries': [], 'metadata': {'total_count': 0, 'last_updated': None, 'max_entries': 200, 'pruning_strategy': 'remove_oldest_low_confidence'}}
+
+idx['entries'].append({
+    'id': 'auto-playbook-${SLUG}-${DATE_STAMP}',
+    'file': os.path.basename('$EXP_FILE'),
+    'task_type': 'api-discovery',
+    'tags': ['auto-playbook', '$(echo "$MODULE" | tr "." " ")'],
+    'timestamp': exp['timestamp'],
+    'confidence': 0.7
+})
+idx['metadata']['total_count'] = len(idx['entries'])
+idx['metadata']['last_updated'] = exp['timestamp']
+with open(idx_path, 'w') as f:
+    json.dump(idx, f, indent=2)
+" 2>/dev/null
+
+          echo ""
+          echo "[Auto-Playbook] Detected $ERROR_COUNT errors on '$MODULE' followed by a success in this session."
+          echo "A skeleton experience has been saved to the blackboard at: $EXP_FILE"
+          echo "NOW you MUST do two things:"
+          echo "1. Proactively invoke ftm-capture to save the working code pattern as a playbook"
+          echo "2. Update the experience file at $EXP_FILE — fill in the code_patterns array with the working snippet and api_gotchas with every wrong assumption you hit"
+          echo "Tell the user: \"That was rough — I'm saving the working pattern so next time it's one clean shot.\""
+          echo ""
+
+          # Clear tracked errors for this module so we don't re-trigger
+          python3 -c "
+import json
+lines = []
+for line in open('$ERROR_TRACKER'):
+    line = line.strip()
+    if not line: continue
+    try:
+        ev = json.loads(line)
+        if ev.get('module') != '$MODULE':
+            lines.append(line)
+    except: pass
+with open('$ERROR_TRACKER', 'w') as f:
+    f.write('\n'.join(lines) + '\n' if lines else '')
+" 2>/dev/null
+        fi
+      fi
+    fi
+  fi
+fi
+
 # --- Feed Playbook Tracer if active trace exists ---
 ACTIVE_TRACE_FILE="$FTM_STATE/.active-trace-id"
 if [ -f "$ACTIVE_TRACE_FILE" ] && [ -f "$BRAIN_PY" ]; then

package/hooks/ftm-task-loader.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# ftm-task-loader.sh
+# PostToolUse hook that fires after the Skill tool is invoked.
+# When ftm-ops or ftm is the invoked skill, loads tasks from brain.py
+# and injects TaskCreate instructions as additionalContext.
+#
+# This is deterministic — brain.py runs in the hook (fast), and the
+# model receives pre-parsed TaskCreate calls it must execute.
+#
+# Hook: PostToolUse (matcher: Skill)
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract the tool name and check it's the Skill tool
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+if [[ "$TOOL_NAME" != "Skill" ]]; then
+  exit 0
+fi
+
+# Extract which skill was invoked from the tool input
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // ""' 2>/dev/null)
+
+# Only fire for ftm-ops, ftm, or ftm-mind (which routes to ftm-ops for task requests)
+case "$SKILL_NAME" in
+  ftm-ops|ftm|ftm-mind|eng-buddy) ;;
+  *) exit 0 ;;
+esac
+
+# Find brain.py — check multiple locations
+BRAIN_PY=""
+for candidate in \
+  "$HOME/.claude/skills/ftm/bin/brain.py" \
+  "$HOME/.claude/skills/ftm-ops/../bin/brain.py" \
+  "$HOME/Documents/Code/feed-the-machine/bin/brain.py"; do
+  if [[ -f "$candidate" ]]; then
+    BRAIN_PY="$candidate"
+    break
+  fi
+done
+
+if [[ -z "$BRAIN_PY" ]]; then
+  # brain.py not found — skip silently
+  exit 0
+fi
+
+# Run brain.py and capture task JSON
+TASKS_JSON=$(python3 "$BRAIN_PY" --tasks --task-json 2>/dev/null) || exit 0
+
+# Count active tasks
+TASK_COUNT=$(echo "$TASKS_JSON" | python3 -c "
+import sys, json
+try:
+    tasks = json.load(sys.stdin)
+    active = [t for t in tasks if t.get('status') in ('pending', 'in_progress')]
+    print(len(active))
+except:
+    print(0)
+" 2>/dev/null)
+
+if [[ "$TASK_COUNT" == "0" ]]; then
+  exit 0
+fi
+
+# Generate TaskCreate instructions from the task data
+TASK_INSTRUCTIONS=$(echo "$TASKS_JSON" | python3 -c "
+import sys, json
+try:
+    tasks = json.load(sys.stdin)
+    active = [t for t in tasks if t.get('status') in ('pending', 'in_progress')]
+    lines = []
+    for t in active:
+        tid = t.get('id', t.get('legacy_number', '?'))
+        title = t.get('title', 'Untitled')
+        status = t.get('status', 'pending')
+        priority = t.get('priority', 'medium')
+        jira = t.get('jira_key', '')
+        desc_parts = [status, priority]
+        if jira:
+            desc_parts.append(jira)
+        desc = ' | '.join(desc_parts)
+        lines.append(f'TaskCreate(subject: \"#{tid} {title}\", description: \"{desc}\")')
+    print('\n'.join(lines))
+except:
+    pass
+" 2>/dev/null)
+
+if [[ -z "$TASK_INSTRUCTIONS" ]]; then
+  exit 0
+fi
+
+# Output as additionalContext — the model MUST process this
+cat <<EOF
+[ftm-task-loader] Loaded $TASK_COUNT active tasks from tasks.db. You MUST now call TaskCreate for each one so they appear in Claude Code's sidebar task list. Do NOT skip this — rendering a table is not enough. Call each one:
+
+$TASK_INSTRUCTIONS
+
+Call all of these TaskCreate invocations NOW, before doing anything else. This is non-negotiable.
+EOF

package/hooks/settings-template.json

@@ -55,6 +55,16 @@
           }
         ]
       },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/ftm-task-loader.sh",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Bash|mcp__git__git_commit",
         "hooks": [

package/install.sh

@@ -7,9 +7,13 @@ set -euo pipefail
 # Safe to re-run — idempotent.
 #
 # Usage:
-#   ./install.sh              # Full install (skills + hooks + settings merge)
-#   ./install.sh --no-hooks   # Skills and state only, skip hooks entirely
-#   ./install.sh --skip-merge # Install hook files but don't touch settings.json
+#   ./install.sh                              # Full install (all skills + hooks)
+#   ./install.sh --only ftm-council-chat      # Install specific skill(s)
+#   ./install.sh --only ftm-mind,ftm-debug    # Install multiple specific skills
+#   ./install.sh --list                       # List available skills
+#   ./install.sh --no-hooks                   # Skills only, skip hooks
+#   ./install.sh --only ftm-mind --with-hooks # Specific skills + all hooks
+#   ./install.sh --skip-merge                 # Install hook files but don't touch settings.json
 
 REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILLS_DIR="$HOME/.claude/skills"
@@ -20,21 +24,85 @@ SETTINGS_FILE="$CONFIG_DIR/settings.json"
 
 NO_HOOKS=false
 SKIP_MERGE=false
-for arg in "$@"; do
+WITH_HOOKS=false
+LIST_MODE=false
+ONLY_SKILLS=""
+
+i=1
+while [ "$i" -le "$#" ]; do
+  arg="${!i}"
   case "$arg" in
     --no-hooks) NO_HOOKS=true ;;
     --skip-merge) SKIP_MERGE=true ;;
+    --with-hooks) WITH_HOOKS=true ;;
+    --list) LIST_MODE=true ;;
+    --only=*) ONLY_SKILLS="${arg#--only=}" ;;
+    --only)
+      i=$((i + 1))
+      ONLY_SKILLS="${!i}"
+      ;;
     # Keep --setup-hooks for backwards compat (now a no-op since merge is default)
     --setup-hooks) ;;
   esac
+  i=$((i + 1))
 done
 
+# When --only is used, skip hooks by default unless --with-hooks
+if [ -n "$ONLY_SKILLS" ] && [ "$WITH_HOOKS" != true ]; then
+  NO_HOOKS=true
+fi
+
 WARN_COUNT=0
 warn() {
   echo "  WARN: $1"
   WARN_COUNT=$((WARN_COUNT + 1))
 }
 
+# --- List Mode ---
+
+if [ "$LIST_MODE" = true ]; then
+  echo ""
+  echo "Available FTM skills:"
+  echo ""
+  for yml in "$REPO_DIR"/ftm-*.yml; do
+    [ -f "$yml" ] || continue
+    name=$(basename "$yml" .yml)
+    [[ "$name" == *".default"* ]] && continue
+    desc=$(grep '^description:' "$yml" | head -1 | sed 's/^description: *//' | cut -c1-80)
+    printf "  %-22s %s\n" "$name" "$desc"
+  done
+  echo ""
+  echo "Install specific skills: ./install.sh --only ftm-council-chat,ftm-mind"
+  echo "Install everything:      ./install.sh"
+  exit 0
+fi
+
+# --- Skill Filter ---
+
+declare -a SKILL_FILTER=()
+if [ -n "$ONLY_SKILLS" ]; then
+  # Always include base dependencies
+  SKILL_FILTER+=("ftm" "ftm-config")
+  IFS=',' read -ra REQUESTED <<< "$ONLY_SKILLS"
+  for s in "${REQUESTED[@]}"; do
+    s=$(echo "$s" | xargs) # trim whitespace
+    SKILL_FILTER+=("$s")
+  done
+fi
+
+skill_wanted() {
+  local name="$1"
+  if [ ${#SKILL_FILTER[@]} -eq 0 ]; then
+    return 0  # no filter = install all
+  fi
+  for wanted in "${SKILL_FILTER[@]}"; do
+    if [ "$name" = "$wanted" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
 # --- Preflight Checks ---
 
 echo "Preflight checks..."
@@ -76,7 +144,11 @@ else
 fi
 
 echo ""
-echo "Installing FTM skills from: $REPO_DIR"
+if [ -n "$ONLY_SKILLS" ]; then
+  echo "Installing selected FTM skills: $ONLY_SKILLS (+ ftm, ftm-config)"
+else
+  echo "Installing all FTM skills from: $REPO_DIR"
+fi
 echo "Linking into: $SKILLS_DIR"
 echo ""
 
@@ -84,12 +156,13 @@ mkdir -p "$SKILLS_DIR"
 
 # --- Skills ---
 
-# Link all ftm*.yml files
+# Link ftm*.yml files (filtered by --only if set)
 for yml in "$REPO_DIR"/ftm*.yml; do
   [ -f "$yml" ] || continue
   name=$(basename "$yml")
   # Skip ftm-config.default.yml — it's a template, not a skill
   [[ "$name" == *".default."* ]] && continue
+  skill_wanted "${name%.yml}" || continue
   target="$SKILLS_DIR/$name"
   if [ -L "$target" ]; then
     rm "$target"
@@ -101,11 +174,12 @@ for yml in "$REPO_DIR"/ftm*.yml; do
   echo "  LINK $name"
 done
 
-# Link all ftm* directories (skills with SKILL.md)
+# Link ftm* directories (filtered by --only if set)
 for dir in "$REPO_DIR"/ftm*/; do
   [ -d "$dir" ] || continue
   name=$(basename "$dir")
   [ "$name" = "ftm-state" ] && continue  # state is handled separately
+  skill_wanted "$name" || continue
   target="$SKILLS_DIR/$name"
   if [ -L "$target" ]; then
     rm "$target"
@@ -121,6 +195,8 @@ SKILL_COUNT=0
 for _f in "$REPO_DIR"/ftm*.yml; do
   [ -e "$_f" ] || continue
   case "$_f" in *.default.*) continue ;; esac
+  _name=$(basename "$_f" .yml)
+  skill_wanted "$_name" || continue
   SKILL_COUNT=$((SKILL_COUNT + 1))
 done
 echo ""

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feed-the-machine",
-  "version": "1.7.0",
-  "description": "A unified intelligence layer for Claude Code — 22 skills with OODA-based reasoning, persistent memory, multi-model deliberation, and optional operator cockpit inbox",
+  "version": "1.7.2",
+  "description": "A brain upgrade for Claude Code — 26 skills that teach it how to think before acting, remember across conversations, debug like a war room, run plans on autopilot with agent teams, and get second opinions from GPT & Gemini. Plus 15 hooks that automate the boring stuff.",
   "license": "MIT",
   "author": "kkudumu",
   "type": "module",
@@ -26,6 +26,7 @@
     "bin/",
     "hooks/",
     "docs/HOOKS.md",
+    "docs/images/",
     "install.sh",
     "uninstall.sh",
     "ftm.yml",