feed-the-machine 1.1.0 → 1.3.0

package/ftm-map/SKILL.md

@@ -207,3 +207,53 @@ After `map_updated` or session end:
 - Stay in your worktree.
 - ALWAYS use the venv python (`ftm-map/scripts/.venv/bin/python3`), never the system python.
 - For query mode, ALWAYS run `setup.sh` first if `.venv` does not exist.
+
+## Requirements
+
+- tool: `ftm-map/scripts/.venv/bin/python3` | required | Python with tree-sitter and SQLite bindings
+- tool: `ftm-map/scripts/setup.sh` | required | virtualenv and dependency installer
+- tool: `ftm-map/scripts/index.py` | required | bootstrap and incremental indexer
+- tool: `ftm-map/scripts/query.py` | required | blast radius, dependency, and FTS5 search queries
+- tool: `ftm-map/scripts/views.py` | required | INTENT.md and .mmd diagram generation from graph
+- tool: `git` | optional | changed file detection for incremental mode
+- config: `~/.claude/ftm-config.yml` | optional | model profile and skills.ftm-map.enabled flag
+
+## Risk
+
+- level: low_write
+- scope: writes and updates .ftm-map/map.db SQLite database; does not modify any project source files; also writes blackboard experience entry
+- rollback: delete .ftm-map/map.db to reset to unindexed state; re-run bootstrap to rebuild
+
+## Approval Gates
+
+- trigger: bootstrap requested on very large codebase (1000+ files) | action: report estimated file count before running, proceed unless user objects
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: .venv does not exist | action: run setup.sh first to create it before proceeding
+- condition: tree-sitter binary missing | action: run setup.sh to install dependencies
+- condition: .ftm-map/map.db missing when query requested | action: explain graph not indexed, offer to run bootstrap
+- condition: git not available for incremental changed-file detection | action: fall back to indexing all modified files detected from disk timestamps
+
+## Capabilities
+
+- cli: `ftm-map/scripts/.venv/bin/python3` | required | tree-sitter parsing and SQLite operations
+- cli: `git` | optional | changed file detection for incremental indexing
+
+## Event Payloads
+
+### map_updated
+- skill: string — "ftm-map"
+- project_path: string — absolute path to indexed project
+- symbols_count: number — total symbols in the graph
+- edges_count: number — total dependency edges
+- files_parsed: number — files processed in this operation
+- duration_ms: number — indexing duration
+- mode: string — "bootstrap" | "incremental"
+
+### task_completed
+- skill: string — "ftm-map"
+- operation: string — "bootstrap" | "incremental" | "query"
+- query_type: string | null — "blast-radius" | "deps" | "search" | "info" (for query mode)
+- duration_ms: number — total operation duration

package/ftm-mind/SKILL.md

@@ -3,7 +3,7 @@ name: ftm-mind
 description: Unified OODA cognitive loop for the ftm system. Use for freeform `/ftm` or `/ftm-mind` requests, vague asks, mixed-tool workflows, Jira/ticket-driven work, or any request that should be understood before routing. Also handles explicit ftm skill invocations by honoring the requested skill while still doing a fast orientation pass for context, prerequisites, and approval gates. Triggers on open-ended requests like "help me think through this", bug reports, plan execution asks, Jira URLs, "make this better", mixed MCP asks like "check my calendar and draft a Slack message", and direct skill invocations like "/ftm-debug ..." or "/ftm-brainstorm ...". Do NOT use only when another ftm skill is already actively handling the task and no re-orientation is needed.
 ---
 
-# FTM Mind
+# Panda Mind
 
 `ftm-mind` is the reasoning core of the ftm ecosystem. It does not route by keyword alone. It observes the request, orients against live state and accumulated memory, decides the smallest correct next move, acts, then loops.
 
@@ -133,6 +133,62 @@ Interpretation rules:
 - "what would other AIs think" is a council request, not generic brainstorming
 - "rename this variable" is usually a micro direct task, not a routed skill
 
+### 1.5. Environment Discovery (Orient sub-phase)
+
+Before pattern matching or routing, probe the current environment to map available capabilities. This step runs automatically on the first request in a session, then caches results for 15 minutes.
+
+**Discovery sequence:**
+
+1. **MCP Server Probe** — List connected MCP servers by checking which tool namespaces are available:
+   - For each known MCP server (serena, supabase, playwright, freshservice-mcp, slack, gmail, mcp-atlassian-personal, lusha, apple-doc-mcp), check if tools with that prefix exist
+   - Record: server name, tools available, verified status
+
+2. **CLI Probe** — Check for installed CLIs on PATH:
+   - Essential: `node`, `python3`, `git`, `npm`
+   - FTM tools: `knip`, `codex` (OpenAI Codex CLI)
+   - Optional: `gh` (GitHub CLI), `jq`, `curl`
+   - For each: run `which <cmd>` and record path + version if available
+
+3. **Environment Variable Check** — Check for key env vars (existence only, never log values):
+   - `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`
+   - `JIRA_API_TOKEN`, `FRESHSERVICE_API_KEY`, `SLACK_BOT_TOKEN`
+   - Record: var name, is_set (boolean)
+
+4. **Write capabilities.json** to `~/.claude/ftm-state/blackboard/capabilities.json`:
+   ```json
+   {
+     "discovered_at": "2026-03-20T10:30:00Z",
+     "expires_at": "2026-03-20T10:45:00Z",
+     "capabilities": [
+       {
+         "name": "serena",
+         "type": "mcp",
+         "verified": true,
+         "last_verified_at": "2026-03-20T10:30:00Z",
+         "operations_verified": ["find_symbol", "search_for_pattern"],
+         "confidence": "verified"
+       },
+       {
+         "name": "node",
+         "type": "cli",
+         "verified": true,
+         "path": "/usr/local/bin/node",
+         "version": "20.11.0",
+         "confidence": "verified"
+       }
+     ]
+   }
+   ```
+
+5. **Cache logic** — If `capabilities.json` exists and `expires_at` > now, skip re-probing. If stale or missing, re-probe. User can force refresh by saying "refresh capabilities" or "recon".
+
+**How this affects planning:**
+
+When ftm-mind generates or routes to a plan, it MUST:
+- Check `capabilities.json` for every tool/MCP/CLI the plan references
+- If a required capability is `verified: false` or missing, use the skill's fallback from its manifest (## Fallbacks section)
+- If no fallback exists for a missing capability, warn the user: "Plan step N requires [capability] which is not available. Skip or find alternative?"
+
 ### 2. Blackboard Loading Protocol
 
 Read the blackboard in this order:
@@ -244,7 +300,7 @@ If `experiences/index.json` has no usable matches:
 - lean harder on current repo state and direct inspection
 - record the resulting experience aggressively after completion
 
-### 4. Capability Inventory: 16 FTM Skills
+### 4. Capability Inventory: 15 Panda Skills
 
 Orient must know all ftm capabilities before deciding whether to route or act directly.
 
@@ -265,8 +321,7 @@ Orient must know all ftm capabilities before deciding whether to route or act di
 | `ftm-retro` | The user wants a post-run retrospective, lessons learned, or execution review. |
 | `ftm-config` | The user wants ftm settings, model profile, or feature configuration changed. |
 | `ftm-git` | Any git commit or push is about to happen, the user asks to scan for secrets/credentials/API keys, or wants to verify no secrets are hardcoded before sharing code. MUST run before any commit or push operation — this is a mandatory security gate, not optional. |
-| `ftm-researcher` | The user wants thorough research on a topic, comparison of approaches, state-of-the-art analysis, or evidence-based investigation. Not for ideation (that is ftm-brainstorm). |
-| `ftm-map` | The user wants structural code queries: blast radius ("what breaks if I change X"), dependency chains ("what depends on Y"), code search ("where do we handle auth"), or codebase indexing ("map this codebase", "index this project"). Not for documentation updates (that is ftm-intent/ftm-diagram). |
+| `ftm-capture` | The user just completed a repeatable workflow and wants to save it as a reusable routine + playbook + reference doc. Triggers on "capture this", "save as routine", "codify this", "don't make me explain this again". Also suggest proactively when you detect the user doing something they've done before (matching blackboard experiences with same task_type 2+ times). |
 
 Routing heuristic:
 
@@ -442,9 +497,12 @@ Signals:
 - changes routing, integration, or cross-system references (API endpoints, project keys, board IDs)
 - the codebase being changed is unfamiliar or hasn't been read yet this session
 - the task involves both code changes AND communication/coordination
+- **calls any production API that creates, updates, or deletes resources** (Okta, Freshservice, AWS, any external service with real consequences)
 
 The reason forced escalation exists: tasks that touch external systems or multiple files feel simple in the moment but have hidden ordering dependencies, stakeholder coordination needs, and blast radius that only becomes visible after you've already started grinding. A 2-minute plan catches these. Grinding without one wastes the user's time when you go in the wrong direction.
 
+**The Hindsight incident**: In March 2026, a task that "felt small" — set up SSO for Hindsight — resulted in autonomous creation of Okta groups in production, user assignments, Freshservice records, a service catalog item, and S3 config changes. The model never presented a plan. It never asked for approval on any phase. It just researched and executed. This is exactly what forced escalation prevents. If the task will call APIs that modify production state, it is medium. Full stop.
+
 Typical examples:
 
 - fix a flaky test with several hypotheses
@@ -514,36 +572,61 @@ Escalate when:
 - the complexity is obvious from the start
 - forced escalation signals are present (see Medium and Large sections above)
 
-### 9. Approval Gates
+### 9. Approval Gates (HARD STOP — NOT OPTIONAL)
+
+**This section is a circuit breaker, not a suggestion. If you are about to call a tool that creates, updates, or deletes a record in an external system, you MUST stop and get explicit user approval FIRST. No exceptions. No "the user implied it." No "it's part of the plan." STOP and ASK.**
+
+The reason this exists: in March 2026, ftm-mind took a Hindsight SSO task and autonomously created Okta groups, added users to production Okta, created Freshservice records, created a service catalog item, and modified S3 workflow configs — all without asking once. The user's `approval_mode` was `plan_first`. The model rationalized past every gate because it "had momentum." That is exactly the failure mode this section prevents.
+
+#### What requires approval (STOP before each one)
 
-Ask for approval only for external-facing actions.
+Every individual external mutation needs its own approval. "The user approved the plan" does not mean "the user approved every API call in the plan." Present what you're about to do, wait for "go" / "yes" / "approved", then execute that one action.
 
-External-facing means actions that leave the local workspace and affect people, systems of record, or deployed environments.
+- **Okta**: creating apps, groups, assigning users, modifying policies
+- **Freshservice**: creating tickets, records, catalog items, custom objects
+- **Jira / Confluence**: creating or updating issues, pages, comments
+- **Slack / Email**: sending messages (draft-before-send protocol applies)
+- **Calendar**: creating or modifying events
+- **S3 / cloud storage**: writing or modifying objects
+- **Browser forms**: submitting data through playwright/puppeteer
+- **Deploys**: any production-affecting operation
+- **Git remote**: pushes, PR creation
 
-Approval required:
+When multiple mutations are part of one plan, batch the approval request by phase — not one API call at a time (that would be annoying), but not "approve the whole plan and I'll do 15 things silently" either. Group related mutations:
 
-- sending Slack messages
-- sending emails
-- creating or mutating Jira, Confluence, or Freshservice records
-- changing calendar events
-- submitting browser forms or uploads
-- deploys and production-affecting operations
-- remote pushes or other outward publication steps
+```
+Phase 1 ready — Okta setup:
+  - Create SAML app "Hindsight"
+  - Create groups: hindsight_admins, hindsight_users
+  - Add 3 users to hindsight_users
+
+Proceed with Phase 1? (yes/skip/modify)
+```
 
-Auto-proceed without approval:
+Then after Phase 1 completes, present Phase 2 before executing it.
 
-- local code edits
-- local documentation updates
+#### What auto-proceeds (no approval needed)
+
+- local code edits, documentation updates
 - tests, lint, builds, audits
-- local git inspection
-- local branches and local commits
-- reading from any MCP
+- local git operations (branch, commit, inspection)
+- reading from any MCP or API (GET requests)
 - blackboard reads and writes
-- saving drafts to `.ftm-drafts/` (the draft is local; sending is what needs approval)
+- saving drafts to `.ftm-drafts/`
+
+#### The momentum trap
 
-If the user has explicitly requested stricter gates, honor that preference.
+If you notice yourself thinking any of these, STOP — you are rationalizing past a gate:
 
-If authentication or permission is missing, ask instead of guessing.
+- "The user clearly wants this done, I'll just do it"
+- "This is part of the approved plan"
+- "I already started, might as well finish"
+- "It's just one more API call"
+- "The user will appreciate me being proactive"
+
+None of these override the gate. Present the action, wait for approval, then execute.
+
+If the user has explicitly requested stricter gates, honor that preference. If authentication or permission is missing, ask instead of guessing.
 
 ### 10. Ask-the-User Heuristic
 
@@ -723,45 +806,6 @@ Approve? Or adjust the approach.
 
 This gives the user control over the *strategy* even when delegating to skills.
 
-### Research tasks → ftm-researcher
-
-Route to ftm-researcher when the request is primarily about gathering information,
-comparing approaches, or understanding the state of the art on a topic.
-
-Signals:
-- "research X", "find out about Y", "what's the state of the art on Z"
-- "compare approaches to W", "how do others handle X"
-- "deep dive into X", "investigate Y", "look into Z"
-- "find me examples of X", "what's out there for Y"
-- The user wants facts and evidence, not ideation or planning
-
-Distinguish from ftm-brainstorm:
-- Brainstorm: user has an idea and wants to develop it → exploratory, iterative, extractive
-- Researcher: user wants information about a topic → factual, evidence-based, comprehensive
-- Ambiguous: if the user seems to want both exploration AND research, route to brainstorm (which calls researcher internally)
-
-Mode selection:
-- "quick look" / "briefly" → quick mode
-- Default → standard mode
-- "deep dive" / "thorough" / "comprehensive" → deep mode
-
-### Structural code queries → ftm-map
-
-Route to ftm-map when the request involves understanding code structure and dependencies:
-
-**Strong signals (route immediately):**
-- "what breaks if I change X" / "blast radius"
-- "what depends on X" / "dependency chain"
-- "what calls X" / "who calls X"
-- "where do we handle X" (code search, not docs)
-- "map this codebase" / "index this project"
-
-**Disambiguation:**
-- "document this function" → ftm-intent (documentation), NOT ftm-map
-- "show the architecture diagram" → ftm-diagram, NOT ftm-map
-- "search for X in the codebase" → could be ftm-map (if structural) or Grep (if text-literal)
-- If `.ftm-map/map.db` doesn't exist and the query is structural, suggest bootstrapping first
-
 ### 2. Choose direct vs routed execution
 
 Use direct execution when:
@@ -793,7 +837,15 @@ If the next move will reveal new information, plan to re-enter Observe after the
 
 ## Act
 
-Act is clean, decisive execution.
+Act is clean, decisive execution — but execution of **approved** work only.
+
+**Pre-Act checkpoint**: Before executing anything, verify:
+
+1. If `approval_mode` is `plan_first` or `always_ask`, did the user explicitly approve the plan? (Words like "go", "yes", "approved", "do it", "ship it" — not silence, not your own narration of the plan.)
+2. If the task involves external mutations (see Approval Gates section 9), have you presented the specific actions and received approval?
+3. If neither condition applies, proceed.
+
+If you cannot point to a specific user message that approved the plan, you have not received approval. Go back to Decide and present the plan.
 
 ### 1. Direct action
 
@@ -876,6 +928,7 @@ After every completed task — not just "meaningful" ones — update the blackbo
 
 1. Update `context.json` — set `current_task` to reflect what was done, append to `recent_decisions`
 2. Update `session_metadata.skills_invoked` if a skill was used
+3. If environment discovery ran this session, ensure `capabilities.json` is written to `/Users/kioja.kudumu/.claude/ftm-state/blackboard/capabilities.json` with the current snapshot (schema: `capabilities.schema.json` in the same directory)
 
 **After task completion, always record an experience file:**
 
@@ -934,13 +987,12 @@ Use these as behavioral tests.
 When the user asks for help, shows empty input, or says `?` or `menu`, show:
 
 ```text
-FTM Skills:
+Panda Skills:
   /ftm brainstorm [idea]     — Research-backed idea development
   /ftm execute [plan-path]   — Autonomous plan execution with agent teams
   /ftm debug [description]   — Multi-vector deep debugging war room
   /ftm audit                 — Wiring verification
   /ftm council [question]    — Multi-model deliberation
-  /ftm research [topic]      — Deep parallel research engine
   /ftm intent                — Manage INTENT.md documentation
   /ftm diagram               — Manage architecture diagrams
   /ftm codex-gate            — Run adversarial Codex validation
@@ -984,3 +1036,58 @@ Avoid these failures:
 6. Read before write.
 7. Session trajectory matters.
 8. The best route is often no route at all.
+
+## Requirements
+
+- tool: `git` | required | codebase state inspection (git status, git log)
+- config: `~/.claude/ftm-config.yml` | optional | approval_mode, execution preferences
+- reference: `~/.claude/skills/ftm-mind/references/mcp-inventory.md` | required | MCP capability routing table
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state and preferences
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | experience retrieval index
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | promoted patterns for orientation
+
+## Risk
+
+- level: low_write
+- scope: writes blackboard context and experience files; local code edits only on micro/small direct tasks; routes to other skills for larger work
+- rollback: blackboard writes can be reverted by editing JSON files; no destructive mutations performed directly
+
+## Approval Gates
+
+- trigger: task_size >= medium AND involves external systems | action: present numbered plan and wait for explicit user approval
+- trigger: any external mutation (Okta, Freshservice, Jira, Slack, email, calendar, S3, deploys, git push) | action: present phase-level approval request before executing each mutation
+- trigger: task_size == small AND approval_mode == always_ask | action: show pre-flight summary before proceeding
+- complexity_routing: micro → auto | small → auto (pre-flight summary if plan_first) | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: blackboard context.json missing or malformed | action: treat as empty state, proceed at full capability using live observation
+- condition: experiences/index.json empty or no matching entries | action: skip experience retrieval, lean on current repo state and direct inspection
+- condition: patterns.json missing | action: skip pattern application, rely on direct analysis
+- condition: ftm-config.yml missing | action: default to plan_first approval_mode and balanced model profile
+- condition: mcp-inventory.md missing | action: rely on built-in MCP routing heuristics from skill body
+- condition: requested ftm skill unavailable | action: notify user and attempt direct handling or alternate routing
+
+## Capabilities
+
+- mcp: `git` | optional | codebase state, diffs, history, commits
+- mcp: `mcp-atlassian-personal` | optional | Jira/Confluence reads for ticket-driven work
+- mcp: `slack` | optional | Slack context reads, draft messages
+- mcp: `gmail` | optional | email reads, drafts
+- mcp: `google-calendar` | optional | calendar inspection for scheduling requests
+- mcp: `freshservice-mcp` | optional | IT ticketing reads
+- mcp: `sequential-thinking` | optional | multi-step reflective reasoning
+- mcp: `playwright` | optional | browser automation for visual tasks
+- mcp: `glean_default` | optional | internal company knowledge search
+- mcp: `context7` | optional | external library documentation
+- env: none required
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-mind"
+- task_type: string — detected task type (feature, bug, refactor, investigation, etc.)
+- task_size: string — micro | small | medium | large
+- route: string — direct | skill name routed to
+- duration_ms: number — time from observe to act completion
+- blackboard_updated: boolean — whether context.json and experience were written

package/ftm-pause/SKILL.md

@@ -131,3 +131,46 @@ Tailor the counts to the skill: brainstorm shows decisions + turns, executor sho
 **Skill invoked, no user interaction yet:** Save what exists (Phase 0 scan, initial question). "Next Step" notes that the user hasn't answered yet.
 
 **Large state:** Do not truncate. Some sessions produce massive state files. Completeness is required for reliable restoration.
+
+## Requirements
+
+- reference: `~/.claude/ftm-state/STATE.md` | optional | existing state file to overwrite
+- reference: `~/.claude/ftm-pause/references/protocols/SKILL-RESTORE-PROTOCOLS.md` | required | per-skill capture field specifications
+- reference: `~/.claude/ftm-pause/references/protocols/VALIDATION.md` | required | pre-write and post-write validation checklist
+- tool: `git` | optional | git branch and commit hash capture for state file
+
+## Risk
+
+- level: low_write
+- scope: writes ~/.claude/ftm-state/STATE.md only; does not modify project source files or blackboard experiences; overwrites existing STATE.md without backup
+- rollback: no project mutations; prior STATE.md is overwritten (not backed up) by design
+
+## Approval Gates
+
+- trigger: multiple skills active and unclear which to pause | action: ask user which skill state to save before writing
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ~/.claude/ftm-state/ directory doesn't exist | action: create directory before writing STATE.md
+- condition: no ftm skill detected as active | action: report "No active ftm session detected" and list which skills this applies to
+- condition: git not available | action: omit git_branch and git_commit fields from state file frontmatter
+- condition: artifact files referenced in state don't exist on disk | action: note as "path recorded but file not found" in Artifacts section
+
+## Capabilities
+
+- cli: `git` | optional | branch name and commit hash for state file metadata
+
+## Event Payloads
+
+### session_paused
+- skill: string — "ftm-pause"
+- saved_skill: string — the ftm skill whose state was saved
+- phase: string — phase at which the session was paused
+- state_file: string — absolute path to written STATE.md
+- artifacts_count: number — number of artifact paths recorded
+
+### task_completed
+- skill: string — "ftm-pause"
+- saved_skill: string — the ftm skill whose state was saved
+- state_file: string — absolute path to STATE.md

package/ftm-researcher/SKILL.md

@@ -218,3 +218,58 @@ The following state is persisted for pause/resume support:
 - `ftm-researcher/references/council-integration.md` — ftm-council interface + fallback challenger prompts
 - `ftm-researcher/scripts/score_credibility.py` — Source credibility scoring
 - `ftm-researcher/scripts/validate_research.py` — Research output validation
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | planning and review model profiles, per_skill_overrides.ftm-researcher agent cap
+- reference: `ftm-researcher/references/agent-prompts.md` | required | 7 finder agent prompts and orchestrator decomposition protocol
+- reference: `ftm-researcher/references/synthesis-pipeline.md` | required | 5-phase synthesis pipeline
+- reference: `ftm-researcher/references/adaptive-search.md` | optional | wave 2 adaptive refinement (deep mode only)
+- reference: `ftm-researcher/references/output-format.md` | required | JSON schema and markdown template
+- reference: `ftm-researcher/references/council-integration.md` | optional | ftm-council interface (deep mode only)
+- reference: `~/.claude/ftm-blackboard/context.json` | optional | session state
+- reference: `~/.claude/ftm-blackboard/patterns.json` | optional | recurring research patterns
+
+## Risk
+
+- level: read_only
+- scope: reads web sources and local codebase via agents; writes blackboard experience entry; writes structured JSON artifact; does not modify project source files
+- rollback: no project mutations; blackboard write can be reverted by editing JSON files
+
+## Approval Gates
+
+- trigger: research complete and user says "done" / "thanks" | action: finalize, write blackboard, emit events
+- trigger: deep mode and ftm-council invoked | action: council runs automatically on top claims (no user gate needed for this step)
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ftm-council not available (deep mode) | action: use 2 fallback challenger agents (Devil's Advocate + Edge Case Hunter) instead
+- condition: agent cap exceeded | action: queue excess agents and dispatch after current wave completes
+- condition: research agent returns no findings | action: broaden query and retry; if still empty, report "No prior art found — this may be novel"
+- condition: blackboard missing | action: proceed without experience-informed shortcuts
+
+## Capabilities
+
+- mcp: `WebSearch` | optional | finder agents for web, GitHub, and competitive research
+- mcp: `WebFetch` | optional | fetching specific URLs found during research
+- mcp: `sequential-thinking` | optional | complex synthesis and reconciliation
+
+## Event Payloads
+
+### research_complete
+- skill: string — "ftm-researcher"
+- query: string — original research question
+- mode: string — "quick" | "standard" | "deep"
+- findings_count: number — total normalized findings
+- consensus_count: number — findings with 3+ agent agreement
+- contested_count: number — findings with council disagreement
+- unique_count: number — single-agent findings
+- sources_count: number — total sources cited
+- council_used: boolean — whether ftm-council was invoked
+- duration_ms: number — total research duration
+
+### task_completed
+- skill: string — "ftm-researcher"
+- task_title: string — research topic title
+- duration_ms: number — total session duration including iterations

package/ftm-resume/SKILL.md

@@ -164,3 +164,50 @@ To save a session for later:
 2. When you need to stop, use /ftm-pause
 3. In a new conversation, use /ftm-resume to continue
 ```
+
+## Requirements
+
+- reference: `~/.claude/ftm-state/STATE.md` | required | saved session state file from ftm-pause
+- reference: `../ftm-pause/references/protocols/SKILL-RESTORE-PROTOCOLS.md` | required | per-skill state field restoration instructions
+- reference: `../ftm-pause/references/protocols/VALIDATION.md` | required | validation protocol for state file integrity
+- reference: `~/.claude/ftm-state/archive/` | optional | archived prior state files
+- tool: `git` | optional | checking git state drift since session was paused
+
+## Risk
+
+- level: low_write
+- scope: archives STATE.md by moving it to ~/.claude/ftm-state/archive/; invokes the target ftm skill with restored context; does not modify project source files
+- rollback: copy archived STATE.md back from archive if restoration was incorrect
+
+## Approval Gates
+
+- trigger: validation finds warnings (git drift, stale state, missing artifacts) | action: present consolidated validation summary and require user acknowledgment before proceeding
+- trigger: validation finds block-level failure | action: stop and report failure; do not invoke target skill
+- trigger: user provides new context along with "yes" | action: capture as post-pause update and inject into skill invocation
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: STATE.md not found | action: report "No saved ftm session found" with instructions for saving sessions
+- condition: STATE.md frontmatter missing required fields | action: report validation failure with specific missing fields
+- condition: multiple STATE.md files (STATE.md + STATE-*.md) | action: ask user which to resume, list each with skill type and timestamp
+- condition: state is >7 days old | action: flag as potentially stale with warning, require user acknowledgment
+
+## Capabilities
+
+- cli: `git` | optional | branch and commit state validation
+- env: none required
+
+## Event Payloads
+
+### session_resumed
+- skill: string — "ftm-resume"
+- resumed_skill: string — the ftm skill that was re-invoked
+- phase: string — phase the session is resuming at
+- state_age_hours: number — how long ago the session was paused
+- post_pause_update: boolean — whether user provided new context
+
+### task_completed
+- skill: string — "ftm-resume"
+- resumed_skill: string — the ftm skill re-invoked
+- state_file_archived: string — path where STATE.md was archived

package/ftm-retro/SKILL.md

@@ -187,3 +187,57 @@ After completing, update:
 2. Write experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
 3. Update `experiences/index.json` with the new entry
 4. Emit `task_completed`
+
+## Requirements
+
+- reference: `PROGRESS.md` | optional | executor progress log for auto-triggered mode
+- reference: `~/.claude/ftm-retros/` | optional | prior retro files for pattern analysis
+- reference: `references/protocols/SCORING-RUBRICS.md` | required | scoring scale breakpoints and evidence requirements
+- reference: `references/templates/REPORT-FORMAT.md` | required | retro report output template
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | experience inventory for micro-reflection mode
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | pattern registry for promotion and decay
+
+## Risk
+
+- level: low_write
+- scope: writes retro report to ~/.claude/ftm-retros/; writes experience files to blackboard; promotes patterns to patterns.json; does not modify project source files
+- rollback: delete retro report file; remove experience entry from blackboard
+
+## Approval Gates
+
+- trigger: pattern promotion triggered (3+ matching experiences) | action: auto-promote to patterns.json without user gate (learning system behavior)
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: PROGRESS.md not found and manual mode | action: check ~/.claude/ftm-retros/ for most recent .md file; ask user which execution to review if multiple found
+- condition: execution context not provided by ftm-executor | action: reconstruct from PROGRESS.md or ask user for context
+- condition: scoring rubric file missing | action: apply built-in scoring heuristics from skill body
+- condition: experiences/index.json has fewer than 10 entries | action: cold-start mode — record every task, set all confidence to low
+
+## Capabilities
+
+- env: none required
+
+## Event Payloads
+
+### experience_recorded
+- skill: string — "ftm-retro"
+- experience_path: string — path to written experience file
+- task_type: string — type of task recorded
+- outcome: string — success | partial | failure
+- confidence: string — low | medium | high
+
+### pattern_discovered
+- skill: string — "ftm-retro"
+- pattern_name: string — name of the promoted pattern
+- category: string — codebase_insights | execution_patterns | user_behavior | recurring_issues
+- occurrence_count: number — number of experiences that triggered promotion
+- confidence: string — low | medium | high
+
+### task_completed
+- skill: string — "ftm-retro"
+- report_path: string — absolute path to saved retro report
+- overall_score: number — total score out of 50
+- top_issue: string — most impactful bottleneck identified
+- patterns_promoted: number — new patterns added to patterns.json

package/ftm-routine/SKILL.md

@@ -132,3 +132,39 @@ Create accounts → set permissions → send welcome email → schedule onboardi
 
 ### incident-response
 Check Sentry → check logs → notify channel → create Jira ticket → start investigation
+
+## Requirements
+
+- reference: `~/.ftm/routines/` | required | YAML routine definitions directory
+- config: `~/.claude/ftm-config.yml` | optional | model preferences for skill-type steps
+
+## Risk
+
+- level: medium_write
+- scope: executes MCP tool calls, skill invocations, and bash commands as defined by the routine; external-facing mutations depend entirely on routine definition; approval gates in the routine control which steps require user confirmation
+- rollback: depends on individual routine steps; steps with approval: approve gate let user review before execution; MCP writes (Jira, Slack, email) may not be reversible
+
+## Approval Gates
+
+- trigger: routine step with approval: approve | action: show plan for that step and wait for "go" before executing
+- trigger: routine step with approval: review | action: execute step, show results, wait for "continue" or "stop"
+- trigger: routine step with approval: none | action: execute automatically and show results
+- complexity_routing: micro → auto | small → auto | medium → plan_first (show full routine plan first) | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: routine YAML file not found | action: show "Routine not found" with list of available routines from ~/.ftm/routines/
+- condition: MCP tool referenced in routine not available | action: report unavailable tool, ask user whether to skip that step or abort
+- condition: skill referenced in routine not available | action: report unavailable skill, ask user whether to skip or abort
+- condition: bash command in step fails with non-zero exit | action: report failure output, ask user whether to continue or abort
+
+## Capabilities
+
+- mcp: various | optional | determined by individual routine definitions
+- cli: various | optional | bash steps in routine definitions
+- env: none required directly
+
+## Event Payloads
+
+### (none)
+ftm-routine does not emit its own events. Events are emitted by the MCPs and skills invoked during routine execution.

package/ftm-state/blackboard/capabilities.json

@@ -0,0 +1,5 @@
+{
+  "discovered_at": null,
+  "expires_at": null,
+  "capabilities": []
+}