feed-the-machine 1.0.0 → 1.2.0

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

package/ftm-config/SKILL.md

@@ -308,3 +308,38 @@ If the YAML cannot be parsed, the skill will back up the broken file as `~/.clau
 
 ### Changes not taking effect
 Other ftm skills read the config at startup. If a ftm skill is already running, it will use the config that was active when it started. Changes apply to the next invocation.
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | main config file (created with defaults if missing)
+
+## Risk
+
+- level: low_write
+- scope: reads and writes ~/.claude/ftm-config.yml only; backs up malformed config to ftm-config.yml.bak before overwriting; no project files touched
+- rollback: restore from ~/.claude/ftm-config.yml.bak or delete the file to reset to defaults on next invocation
+
+## Approval Gates
+
+- trigger: reset command issued | action: show current config and ask "Proceed?" before restoring defaults
+- trigger: invalid model name or profile name provided | action: reject with clear error showing valid options, do not write
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ftm-config.yml missing | action: create file with default balanced profile and all defaults
+- condition: ftm-config.yml malformed YAML | action: back up as ftm-config.yml.bak, create fresh default config
+- condition: invalid model or profile value provided | action: reject and show valid options without writing
+
+## Capabilities
+
+- env: none required
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-config"
+- action: string — "display" | "set_profile" | "set_value" | "reset" | "show_profiles" | "show_skills"
+- changed_key: string | null — dotted path of changed setting
+- old_value: string | null — value before change
+- new_value: string | null — value after change

package/ftm-council/SKILL.md

@@ -130,3 +130,59 @@ After completing, update the blackboard:
 2. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` capturing decision domain, verdict, round reached, dissent summary, and whether the verdict held up
 3. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
 4. Emit `task_completed` event
+
+## Requirements
+
+- tool: `codex` | required | Codex CLI for independent peer investigation
+- tool: `gemini` | required | Gemini CLI for independent peer investigation
+- reference: `references/protocols/PREREQUISITES.md` | required | availability check, fallback logic, timeout config
+- reference: `references/protocols/STEP-0-FRAMING.md` | required | problem framing format
+- reference: `references/prompts/CLAUDE-INVESTIGATION.md` | required | Claude investigation prompt template
+- reference: `references/prompts/CODEX-INVESTIGATION.md` | required | Codex investigation prompt template
+- reference: `references/prompts/GEMINI-INVESTIGATION.md` | required | Gemini investigation prompt template
+- reference: `references/prompts/REBUTTAL-TEMPLATE.md` | required | rebuttal round prompt template
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state
+
+## Risk
+
+- level: read_only
+- scope: reads codebase for independent investigation; does not modify source files; writes blackboard experience after verdict
+- rollback: no source mutations; blackboard write can be reverted by editing JSON files
+
+## Approval Gates
+
+- trigger: council prompt framed in Step 0 | action: show framed prompt to user and wait for confirmation before dispatching to council
+- trigger: 2-of-3 majority reached | action: present verdict summary to user and ask if they want to proceed or dig into dissent
+- trigger: auto-invocation by ftm-executor (INTENT.md conflict) | action: skip user framing confirmation, run immediately and return structured COUNCIL VERDICT to caller
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: codex CLI not found | action: report missing dependency with install instructions and stop (do not run degraded council)
+- condition: gemini CLI not found | action: report missing dependency with install instructions and stop
+- condition: no majority after 5 rounds | action: synthesize final positions, highlight core tension, present 2-3 concrete options for user decision
+- condition: model times out during a round | action: note timeout for that model, continue round with remaining models' responses
+
+## Capabilities
+
+- cli: `codex` | required | OpenAI Codex CLI peer reviewer
+- cli: `gemini` | required | Google Gemini CLI peer reviewer
+- env: `OPENAI_API_KEY` | required | for Codex CLI authentication
+- env: `GEMINI_API_KEY` | required | for Gemini CLI authentication
+
+## Event Payloads
+
+### review_complete
+- skill: string — "ftm-council"
+- verdict: string — "update_intent" | "revert_fix" | "option_a" | "option_b" | custom decision
+- round: number — round in which majority was reached (1-5, or 5+ for synthesis)
+- agreed_by: string[] — which models agreed on the verdict
+- dissent: string | null — summary of dissenting position
+- reasoning: string — why the majority won
+
+### task_completed
+- skill: string — "ftm-council"
+- decision_domain: string — topic the council deliberated on
+- verdict: string — final decision
+- round: number — rounds taken to reach verdict
+- duration_ms: number — total deliberation time