feed-the-machine 1.1.0 → 1.3.0

package/ftm/SKILL.md

@@ -33,6 +33,7 @@ If input starts with a recognized skill name, route directly to that skill:
 | `upgrade` | ftm-upgrade |
 | `retro` | ftm-retro |
 | `config` | ftm-config |
+| `capture`, `codify`, `save as routine` | ftm-capture |
 | `mind` | ftm-mind |
 
 When routing to a specific skill:
@@ -77,6 +78,7 @@ FTM Skills:
   /ftm upgrade               — Check for and install skill updates
   /ftm retro                 — Post-execution retrospective
   /ftm config                — View and edit ftm configuration
+  /ftm capture [name]        — Extract routine + playbook from current session
 
 Or just describe what you need and ftm-mind will handle it.
 ```
@@ -86,3 +88,35 @@ Or just describe what you need and ftm-mind will handle it.
 - Do not attempt to do the work yourself — route only.
 - Be fast — decisive routing, not conversation.
 - Case insensitive matching for all prefix detection.
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | legacy_router_fallback setting
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state for blackboard update on routing
+- tool: none beyond skill invocation mechanism
+
+## Risk
+
+- level: read_only
+- scope: reads blackboard context.json and updates session_metadata.skills_invoked before routing; does not modify any project files
+- rollback: no mutations to reverse; blackboard update is a metadata append
+
+## Approval Gates
+
+- trigger: ftm-mind failure AND legacy_router_fallback enabled | action: fall back to keyword routing automatically (no user gate needed)
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ftm-mind fails or times out | action: check legacy_router_fallback in ftm-config.yml; if true, use keyword matching; if false, report failure
+- condition: blackboard context.json missing | action: skip blackboard update, proceed with routing
+- condition: skill tool unavailable for target skill | action: report routing failure to user with the target skill name
+
+## Capabilities
+
+- env: none required
+
+## Event Payloads
+
+### (none)
+ftm is a pure router and does not emit events directly. Events are emitted by the target skill after routing.

package/ftm-audit/SKILL.md

@@ -144,3 +144,72 @@ After completing:
 ## Report Format
 
 See `references/templates/REPORT-FORMAT.md` for the full report template (summary, changelog table, layer-by-layer finding format with examples).
+
+## Requirements
+
+- tool: `knip` | optional | static dead-code and unused-export analysis (Layer 1)
+- tool: `node` | required | runtime for knip via npx
+- config: `knip.config.ts` | optional | custom knip configuration at project root
+- reference: `references/protocols/PROJECT-PATTERNS.md` | required | framework detection table and dimension activation matrix
+- reference: `references/strategies/AUTO-FIX-STRATEGIES.md` | required | fix actions by finding type
+- reference: `references/protocols/WIRING-CONTRACTS.md` | optional | wiring contract schema for plan-driven audits
+- reference: `references/protocols/RUNTIME-WIRING.md` | optional | runtime verification protocol
+- reference: `references/templates/REPORT-FORMAT.md` | required | structured report template
+- tool: `$HOME/.claude/skills/ftm-browse/bin/ftm-browse` | optional | runtime wiring verification via browser (Phase 3)
+
+## Risk
+
+- level: medium_write
+- scope: modifies source files to fix wiring issues (auto-fix layer); also adds/removes imports and route registrations; reads codebase broadly
+- rollback: git checkout on auto-fixed files; all changes are tracked in the changelog report before being applied
+
+## Approval Gates
+
+- trigger: auto-fix proposed for a finding | action: report proposed change before applying (show "Proposed: ..." format)
+- trigger: finding flagged MANUAL_INTERVENTION_NEEDED | action: surface to user with suggested action, do not auto-fix
+- trigger: re-verification still fails after 3 iterations | action: stop and report remaining issues to user
+- complexity_routing: micro → auto | small → auto | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: knip not installed and npx unavailable | action: skip Layer 1, run Layer 2 adversarial audit only
+- condition: no package.json found | action: skip knip entirely, run adversarial audit only
+- condition: ftm-browse not installed | action: skip Phase 3 runtime wiring check, log reason and continue
+- condition: dev server not running | action: skip Phase 3 runtime wiring check, log reason and continue
+- condition: wiring contracts absent | action: run pure Layer 1 + Layer 2 analysis without contract checking
+- condition: project has no identifiable entry point | action: skip knip, run adversarial audit only
+
+## Capabilities
+
+- cli: `knip` | optional | dead code detection via npx knip
+- cli: `node` | required | JavaScript runtime for npx
+- cli: `$HOME/.claude/skills/ftm-browse/bin/ftm-browse` | optional | headless browser for runtime wiring
+- mcp: `git` | optional | diff scope for Layer 2 adversarial audit
+
+## Event Payloads
+
+### audit_complete
+- skill: string — "ftm-audit"
+- findings_count: number — total issues found across all layers
+- auto_fixed_count: number — issues auto-remediated by Layer 3
+- manual_count: number — issues requiring manual intervention
+- scope: string[] — file paths audited
+- duration_ms: number — total audit duration
+- layers_run: string[] — which layers executed (e.g., ["layer1", "layer2", "layer3"])
+
+### issue_found
+- skill: string — "ftm-audit"
+- layer: string — "layer1" | "layer2" | "layer3"
+- dimension: string — D1 | D2 | D3 | D4 | D5 (for Layer 2 findings)
+- finding_type: string — exports | types | duplicates | UNWIRED_COMPONENT | etc.
+- file_path: string — affected file
+- symbol: string — affected symbol name
+- severity: string — CRITICAL | HIGH | MEDIUM | LOW
+- auto_fixable: boolean — whether Layer 3 can fix this automatically
+
+### task_completed
+- skill: string — "ftm-audit"
+- result: string — "pass" | "pass_with_fixes" | "fail"
+- findings_count: number — total findings
+- auto_fixed_count: number — auto-remediated count
+- manual_count: number — manual intervention needed

package/ftm-brainstorm/SKILL.md

@@ -377,3 +377,54 @@ After completing, update:
 3. Update `experiences/index.json` with the new entry
 4. Emit `plan_generated` with `{ plan_path, plan_title, task_count, wave_count }` (if Phase 3 completed)
 5. Emit `task_completed` with `{ task_title, plan_path, duration_ms }`
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | model profile for planning agents
+- reference: `references/agent-prompts.md` | required | research agent prompt templates
+- reference: `references/plan-template.md` | required | plan document generation template
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state and active constraints
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | past brainstorm lessons
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | execution and user behavior patterns
+
+## Risk
+
+- level: low_write
+- scope: writes plan documents to ~/.claude/plans/; writes blackboard context and experience files; does not modify project source code
+- rollback: delete generated plan file; blackboard writes can be reverted by editing JSON files
+
+## Approval Gates
+
+- trigger: Phase 3 plan generation ready | action: present "Here's what I think we've landed on" summary and wait for explicit user approval before generating plan
+- trigger: plan document generated | action: present plan incrementally (vision → tasks → agents/waves) and get approval at each step
+- trigger: research returns thin results on all agents | action: note research gaps, present fewer suggestions, do not fabricate citations
+- complexity_routing: micro → auto | small → auto | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: ftm-researcher not available | action: dispatch 3 direct parallel research agents (web/github/competitive) using built-in prompts from references/agent-prompts.md
+- condition: no git repo detected in Phase 0 | action: skip repo scan, ask about tech stack during intake
+- condition: blackboard missing or empty | action: proceed without experience-informed shortcuts, rely on direct analysis
+- condition: ftm-config.yml missing | action: use session default model for all agents
+
+## Capabilities
+
+- mcp: `WebSearch` | optional | web research agents use for blog posts and case studies
+- mcp: `WebFetch` | optional | GitHub exploration and competitive analysis
+- mcp: `sequential-thinking` | optional | complex trade-off analysis during synthesis
+- env: none required
+
+## Event Payloads
+
+### plan_generated
+- skill: string — "ftm-brainstorm"
+- plan_path: string — absolute path to generated plan file
+- plan_title: string — human-readable plan title
+- task_count: number — total tasks in the plan
+- wave_count: number — number of parallel execution waves
+
+### task_completed
+- skill: string — "ftm-brainstorm"
+- task_title: string — title of the brainstorm topic
+- plan_path: string | null — path to generated plan if Phase 3 completed
+- duration_ms: number — total session duration

package/ftm-browse/SKILL.md

@@ -413,3 +413,42 @@ When ftm-browse is used directly (not within a plan), supervised mode is OFF by
 - The daemon uses a 1280x800 headless Chromium viewport with a standard Mac Chrome user-agent, so most sites render predictably.
 - To stop the daemon explicitly: `$PB stop`. It will auto-restart on next use.
 - `$PB eval` is the escape hatch for anything the ARIA tree doesn't expose — hidden inputs, JS globals, localStorage, computed values.
+
+## Requirements
+
+- tool: `$HOME/.claude/skills/ftm-browse/bin/ftm-browse` | required | headless browser CLI binary
+- tool: `npx playwright install chromium` | required | Chromium browser engine (first-time setup)
+- reference: none required
+
+## Risk
+
+- level: low_write
+- scope: navigates browser, takes screenshots saved to ~/.ftm-browse/screenshots/; does not modify project source files; form fills and clicks can have side effects on the target application
+- rollback: no project file mutations; browser interactions on local dev servers are typically reversible by reloading
+
+## Approval Gates
+
+- trigger: auth redirect detected during supervised execution | action: STOP immediately, present options (retry/skip/abort/manual), wait for user choice
+- trigger: unexpected browser state during plan step | action: STOP, take screenshot, present situation to user, wait for explicit choice
+- trigger: supervised mode enabled AND state mismatch detected | action: halt and report before proceeding
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: daemon binary not found at expected path | action: report installation instructions and stop
+- condition: Chromium not installed | action: instruct user to run "npx playwright install chromium" and stop
+- condition: daemon fails to start within 10 seconds | action: check ~/.ftm-browse/ logs, report binary or Bun issue
+- condition: dev server not running when navigating to localhost | action: report timeout error with the URL attempted
+- condition: stale ref after navigation | action: re-run snapshot -i before retrying click/fill
+
+## Capabilities
+
+- cli: `$HOME/.claude/skills/ftm-browse/bin/ftm-browse` | required | headless Chromium control CLI
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-browse"
+- workflow: string — description of the visual verification or interaction performed
+- screenshots: string[] — absolute paths to screenshots taken
+- duration_ms: number — total workflow duration

package/ftm-capture/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: ftm-capture
+description: Extract reusable routines, playbooks, and reference docs from the current session's work. Reads session context (blackboard, daily log, tool history), asks clarifying questions about generalizability, then writes to all three ftm knowledge layers. Use when user says "capture this", "save this as a routine", "make a playbook from this", "ftm capture", "codify this", "turn this into a routine", "extract the pattern", "save what we did", "learn from this", "remember how to do this", "don't make me explain this again".
+---
+
+## Events
+
+### Emits
+- `capture_complete` — when all three artifacts (routine, playbook, reference doc) are written
+- `experience_recorded` — when the capture is logged to the blackboard experience layer
+- `known_issue_recorded` — when API gotchas or failure workarounds are encoded
+
+### Listens To
+- `task_completed` — can be auto-triggered after task completion to suggest capture
+- `pattern_discovered` — if ftm-retro identifies a recurring workflow, suggest capture
+
+# FTM Capture — Session-to-Knowledge Extractor
+
+Turns what you just did into reusable automation. Reads the current session's work (blackboard context, daily log, tool calls, experiences), asks 2-4 clarifying questions about generalizability, then writes to all three ftm knowledge layers simultaneously.
+
+## Why This Exists
+
+Every time you complete a repeatable workflow (SSO setup, service catalog creation, vendor onboarding, incident response), the knowledge lives only in the conversation. Next session starts from zero. ftm-capture closes this gap by extracting the pattern while context is fresh and writing it to durable storage that ftm-mind, ftm-routine, and eng-buddy can all access.
+
+## Output Artifacts
+
+ftm-capture writes to **three locations** simultaneously:
+
+| Artifact | Location | Format | Consumer |
+|---|---|---|---|
+| **Routine** | `~/.ftm/routines/{name}.yml` | YAML with phases/steps | `ftm-routine` (executable) |
+| **Playbook** | `~/.claude/eng-buddy/playbooks/{name}.json` | JSON with exact tool params | eng-buddy playbook engine |
+| **Reference Doc** | `~/Documents/Code/panda/docs/playbooks/{name}.md` | Markdown with gotchas | Future agents + humans |
+
+All three are kept in sync. The routine is the executable version, the playbook has exact tool parameters, and the reference doc has the context and gotchas.
+
+## Operating Modes
+
+### Mode 1: Explicit Capture (`/ftm capture [name]`)
+
+User invokes directly after completing work. This is the primary mode.
+
+### Mode 2: Auto-Suggest (via ftm-retro or ftm-mind)
+
+After ftm-retro scores an execution, if it detects a repeatable pattern, it suggests: "This looks like a reusable workflow. Run `/ftm capture` to save it."
+
+ftm-mind can also suggest capture when it detects the user doing something they've done before (matching experiences in the blackboard).
+
+### Mode 3: Inline Capture (mid-session)
+
+User says "capture this" or "save what we just did" while still working. Capture the completed portion and note what's still in progress.
+
+## Execution Protocol
+
+### Step 1: Gather Session Context
+
+Read these files in order:
+
+1. **Blackboard context**: `~/.claude/ftm-state/blackboard/context.json`
+   - Extract: `current_task`, `recent_decisions`, `active_constraints`
+2. **Today's daily log**: `~/.claude/eng-buddy/daily/{today}.md`
+   - Extract: completed items, tool calls, blockers encountered, lessons learned
+3. **Recent experiences**: `~/.claude/ftm-state/blackboard/experiences/index.json`
+   - Filter for entries from today's session
+   - Load matching experience files for their `lessons` and `decisions_made`
+4. **Existing routines**: `ls ~/.ftm/routines/` — check if a routine for this workflow already exists
+5. **Existing playbooks**: `ls ~/.claude/eng-buddy/playbooks/` — check for existing playbook
+6. **Existing reference docs**: `ls ~/Documents/Code/panda/docs/playbooks/` — check for existing doc
+
+If an existing artifact covers this workflow, the capture becomes an **update** not a create. Load the existing version and merge new learnings.
+
+### Step 2: Identify the Pattern
+
+From the gathered context, identify:
+
+- **Workflow name**: kebab-case identifier (e.g., `sso-full-setup`, `vendor-onboarding`, `incident-response`)
+- **Trigger**: What kicks off this workflow? (ticket type, user request, event)
+- **Phases**: Major stages of the workflow (e.g., "Okta setup", "Freshservice config", "Vendor coordination")
+- **Steps per phase**: Specific actions with tools, parameters, and verification
+- **Decision points**: Where does the workflow branch based on input? (e.g., "SCIM supported?" → yes/no path)
+- **Known issues**: API gotchas, workarounds, things that failed and were fixed
+- **Environment assumptions**: What repo, what API access, what tools are available?
+
+### Step 3: Clarifying Questions (2-4 max)
+
+Ask the user focused questions to determine generalizability. DO NOT ask more than 4 questions. Pick the most important from:
+
+**Generalizability questions:**
+- "Is this always [SAML/OIDC] or does it vary by vendor?"
+- "Are the approvers always [names] or does that change per app?"
+- "Should this routine always use the API, or sometimes browser?"
+- "Are there apps where [specific step] wouldn't apply?"
+
+**Scope questions:**
+- "Should this cover [adjacent step] too, or is that separate?"
+- "Does this workflow change if the app supports SCIM?"
+- "Should I parameterize [specific value] or hardcode it?"
+
+**Environment questions:**
+- "Does this only work in the ragnarok repo, or should it be repo-agnostic?"
+- "Are there API access requirements I should document?"
+
+### Step 4: Write the Routine (`~/.ftm/routines/{name}.yml`)
+
+Follow the exact YAML format used by ftm-routine:
+
+```yaml
+name: {kebab-case-name}
+description: |
+  {What this routine does, when to use it, critical ordering rules}
+trigger: manual
+tags: [{relevant, tags}]
+
+# Usage:
+#   /ftm-routine {name}
+#   or: "{natural language trigger}"
+#
+# Required context:
+#   - {param}: {description}
+
+phases:
+  - name: "Phase N: {Phase Name}"
+    steps:
+      - name: {Step description}
+        action: {api|playwright_cli|python_browser|mcp|skill|routine|comms|manual|wait}
+        tool: {tool_name}
+        params: {exact parameters}
+        notes: |
+          {Gotchas, workarounds, known issues}
+        approval: {none|review|approve}
+
+known_issues:
+  - issue: "{Issue name}"
+    description: "{What goes wrong}"
+    fix: "{How to fix it}"
+```
+
+**Critical rules for routine writing:**
+- Every step must specify the exact tool/action — no vague "do X"
+- Include `notes` on steps that have known gotchas
+- Use `approval: approve` for destructive or externally-visible actions
+- Parameterize with `{curly_braces}` for values that change per invocation
+- Include `known_issues` section with every API/tool gotcha discovered during the session
+- Include environment assumptions (repo, API access, etc.) in the description
+
+### Step 5: Write the Playbook (`~/.claude/eng-buddy/playbooks/{name}.json`)
+
+Follow the exact JSON format used by eng-buddy playbooks:
+
+```json
+{
+  "id": "{kebab-case-name}",
+  "name": "{Human-readable name}",
+  "description": "{What and when}",
+  "trigger_keywords": ["{keywords}"],
+  "input_params": {
+    "{param}": {"type": "string", "description": "...", "required": true}
+  },
+  "steps": [
+    {
+      "number": 1,
+      "description": "{What this step does}",
+      "tool": "{exact_tool_name}",
+      "tool_params": {"exact": "params"},
+      "requires_human": false,
+      "notes": "{Gotchas}"
+    }
+  ],
+  "rollback": {
+    "description": "{How to undo}",
+    "steps": ["{exact}", "{reversal}", "{steps}"]
+  },
+  "known_issues": [
+    {"issue": "{Name}", "description": "...", "fix": "..."}
+  ],
+  "confidence": 1.0,
+  "version": 1,
+  "executions": 0,
+  "source": "captured",
+  "related_links": {}
+}
+```
+
+**Critical rules for playbook writing:**
+- Every step must have exact `tool` and `tool_params` — eng-buddy executes these literally
+- Include `rollback` section with exact reversal steps
+- Set `requires_human: true` for steps needing auth, visual verification, or judgment
+- `source: "captured"` distinguishes from `"manual"` or `"observed"`
+
+### Step 6: Write the Reference Doc (`~/Documents/Code/panda/docs/playbooks/{name}.md`)
+
+This is the human-readable + agent-readable reference that captures context, gotchas, and decision rationale:
+
+```markdown
+# {Workflow Name} — {Type} Playbook
+
+## Purpose
+{What this workflow does and when to use it}
+
+## Execution Method
+{Primary: API / Browser / Mixed — and why}
+
+## Prerequisites
+{API access, repo, tools, credentials needed}
+
+## Phases
+### Phase 1: {Name}
+{Steps with exact tool calls, selectors, API endpoints}
+
+### Phase 2: {Name}
+...
+
+## Known Issues & Gotchas
+{Every API quirk, UI gotcha, and workaround discovered}
+
+## Decision Points
+{Where the workflow branches and how to decide}
+
+## Information Needed from User
+{What to collect before starting}
+```
+
+### Step 7: Record Experience
+
+Write to `~/.claude/ftm-state/blackboard/experiences/{name}-capture.json`:
+
+```json
+{
+  "id": "{name}-capture",
+  "timestamp": "{ISO timestamp}",
+  "task_type": "knowledge-capture",
+  "tags": ["{workflow-type}", "capture", "routine", "playbook"],
+  "outcome": "success",
+  "description": "Captured {workflow name} as routine + playbook + reference doc",
+  "lessons": ["{key learnings encoded}"],
+  "files_touched": [
+    "~/.ftm/routines/{name}.yml",
+    "~/.claude/eng-buddy/playbooks/{name}.json",
+    "~/Documents/Code/panda/docs/playbooks/{name}.md"
+  ],
+  "confidence": 1.0
+}
+```
+
+Update `experiences/index.json` with the new entry.
+
+### Step 8: Update Blackboard Context
+
+Update `~/.claude/ftm-state/blackboard/context.json`:
+- Set `current_task.status` to reflect capture completion
+- Add to `recent_decisions`: what was captured and why
+
+### Step 9: Report to User
+
+Show a summary:
+
+```
+Captured: {workflow name}
+
+Written to:
+  Routine:   ~/.ftm/routines/{name}.yml
+  Playbook:  ~/.claude/eng-buddy/playbooks/{name}.json
+  Reference: ~/Documents/Code/panda/docs/playbooks/{name}.md
+
+Known issues encoded: {count}
+Parameters: {list of parameterized values}
+Phases: {count} phases, {count} steps
+
+Next time, run: /ftm-routine {name}
+```
+
+## Updating Existing Artifacts
+
+If Step 1 finds an existing routine/playbook/reference doc:
+
+1. Load the existing version
+2. Show the user what exists vs what's new
+3. Ask: "Update existing or create new version?"
+4. If updating:
+   - Merge new steps into existing phases
+   - Add new known_issues (don't duplicate)
+   - Increment `version` in playbook JSON
+   - Add "Updated: {date} — {what changed}" to reference doc
+5. If creating new:
+   - Use a different name (e.g., `sso-full-setup-v2`)
+
+## Integration Points
+
+### ftm-mind
+ftm-mind knows about ftm-capture in its capability inventory. When ftm-mind detects:
+- User completing a repeatable workflow
+- Matching experiences in the blackboard (same task_type done 2+ times)
+- User saying anything about "remembering" or "next time"
+
+It should suggest: "This looks like a reusable pattern. Want me to `/ftm capture` it?"
+
+### ftm-retro
+After ftm-retro scores an execution, if the workflow is repeatable, it should note: "Consider running `/ftm capture {name}` to save this as a routine."
+
+### ftm-routine
+ftm-routine reads from `~/.ftm/routines/`. Anything ftm-capture writes there becomes immediately available via `/ftm-routine {name}`.
+
+### eng-buddy
+eng-buddy's playbook engine reads from `~/.claude/eng-buddy/playbooks/`. Captured playbooks show up on the dashboard's Playbooks tab.
+
+### Environment Awareness
+
+When capturing, always note the environment context:
+- **If in `~/Documents/Code/ragnarok`**: Full API access to Okta, Freshservice, Slack, AWS (via shared_services). Prefer API over browser.
+- **If in other repos**: May not have API access. Default to browser automation or MCP tools.
+- **Always document**: Which APIs are used, what credentials are needed, what repo provides the client libraries.
+
+This prevents future sessions from trying to use APIs they don't have access to.
+
+## Requirements
+
+- reference: `~/.claude/ftm-state/blackboard/context.json` | required | current task and recent decisions for pattern extraction
+- reference: `~/.claude/eng-buddy/daily/{today}.md` | optional | daily log for completed items and tool calls
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | required | today's session experiences
+- reference: `~/.ftm/routines/` | optional | check for existing routines before creating new one
+- reference: `~/.claude/eng-buddy/playbooks/` | optional | check for existing playbooks before creating
+- reference: `~/Documents/Code/panda/docs/playbooks/` | optional | check for existing reference docs before creating
+
+## Risk
+
+- level: low_write
+- scope: writes YAML routine to ~/.ftm/routines/, JSON playbook to ~/.claude/eng-buddy/playbooks/, and Markdown reference doc to ~/Documents/Code/panda/docs/playbooks/; writes experience to blackboard; does not modify project source code
+- rollback: delete the three written artifact files; remove experience entry from blackboard experiences/
+
+## Approval Gates
+
+- trigger: existing artifact found for this workflow name | action: show existing vs new content, ask user to confirm update or create new version
+- trigger: Step 3 clarifying questions answered | action: proceed to write all three artifacts automatically (no additional gate)
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: blackboard context.json missing | action: ask user directly about the workflow to capture instead of reading from blackboard
+- condition: daily log missing or empty | action: skip daily log extraction, rely on conversation context and blackboard experiences
+- condition: ~/.ftm/routines/ directory doesn't exist | action: create directory before writing routine
+- condition: docs/playbooks/ directory doesn't exist | action: create directory before writing reference doc
+- condition: existing artifact found but cannot be parsed | action: treat as missing, create fresh artifact
+
+## Capabilities
+
+- mcp: none required directly (reads files and writes artifacts)
+- env: none required
+
+## Event Payloads
+
+### capture_complete
+- skill: string — "ftm-capture"
+- workflow_name: string — kebab-case name of captured workflow
+- routine_path: string — absolute path to written routine YAML
+- playbook_path: string — absolute path to written playbook JSON
+- reference_path: string — absolute path to written reference doc
+- phases_count: number — number of workflow phases captured
+- steps_count: number — total steps across all phases
+- known_issues_count: number — API gotchas encoded
+
+### experience_recorded
+- skill: string — "ftm-capture"
+- experience_path: string — path to written experience file
+- workflow_name: string — name of captured workflow
+
+### known_issue_recorded
+- skill: string — "ftm-capture"
+- workflow_name: string — workflow this issue belongs to
+- issue: string — issue name
+- fix: string — remediation approach encoded

package/ftm-capture.yml

@@ -0,0 +1,4 @@
+---
+name: ftm-capture
+description: Extract reusable routines, playbooks, and reference docs from the current session's work. Reads session context (blackboard, daily log, tool history), asks clarifying questions about generalizability, then writes to all three ftm knowledge layers (~/.ftm/routines/, ~/.claude/eng-buddy/playbooks/, ~/Documents/Code/panda/docs/playbooks/). Use when user says "capture this", "save this as a routine", "make a playbook from this", "ftm capture", "codify this", "turn this into a routine", "extract the pattern", "save what we did", or after completing a repeatable workflow that should be reusable. Also triggers on "learn from this", "remember how to do this", "don't make me explain this again".
+---

package/ftm-codex-gate/SKILL.md

@@ -300,3 +300,62 @@ When returning an error before Codex runs:
 ### Remaining Issues
 - [error detail]
 ```
+
+## Requirements
+
+- tool: `codex` | required | OpenAI Codex CLI for adversarial validation
+- reference: `{project_root}/INTENT.md` | optional | root intent documentation for conflict detection
+- reference: `{project_root}/STYLE.md` | optional | code style standards for quality enforcement
+- reference: module-level `INTENT.md` files | optional | per-module intent for targeted conflict detection
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | prior validation patterns
+
+## Risk
+
+- level: medium_write
+- scope: Codex modifies source files and commits fixes directly in the project working directory (--yolo mode); writes entries to DEBUG.md; writes structured output to /tmp/codex-result-*.md
+- rollback: git revert codex fix commits; delete /tmp/codex-result-*.md cleanup is automatic
+
+## Approval Gates
+
+- trigger: codex gate returns PASS_WITH_FIXES and INTENT.md conflict detected | action: auto-invoke ftm-council for arbitration before accepting or reverting the fix
+- trigger: codex gate returns FAIL after 2 fix attempts | action: report remaining issues to ftm-executor caller, wait for direction
+- trigger: codex CLI not found | action: return FAIL immediately with install instructions, do not proceed
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: codex CLI not installed | action: return FAIL with "Codex CLI not found. Install with: npm install -g @openai/codex"
+- condition: codex times out after 600s | action: read partial output if available, return PARTIAL results with note; if no output, return FAIL
+- condition: output file empty or missing | action: return FAIL with "Codex output not found — may have crashed"
+- condition: INTENT.md missing at project root | action: note in prompt to Codex and continue without INTENT validation
+- condition: STYLE.md missing | action: note in prompt to Codex and continue without style enforcement
+
+## Capabilities
+
+- cli: `codex` | required | OpenAI Codex CLI (npm install -g @openai/codex)
+- env: `OPENAI_API_KEY` | required | authentication for Codex CLI execution
+
+## Event Payloads
+
+### review_complete
+- skill: string — "ftm-codex-gate"
+- mode: string — "wave" | "single-task"
+- status: string — "PASS" | "PASS_WITH_FIXES" | "FAIL"
+- tests_formed: number — adversarial test scenarios generated
+- tests_passed: number — test scenarios that passed
+- fixes_applied: number — fixes committed by Codex
+- quality_issues: number — style/quality violations found
+- intent_conflicts: number — INTENT.md conflicts detected
+
+### issue_found
+- skill: string — "ftm-codex-gate"
+- file_path: string — file where issue was found
+- line: number | null — line number if available
+- description: string — issue description
+- type: string — "test_failure" | "quality_violation" | "intent_conflict"
+
+### task_completed
+- skill: string — "ftm-codex-gate"
+- status: string — "PASS" | "PASS_WITH_FIXES" | "FAIL"
+- output_file: string — path to Codex result file