feed-the-machine 1.0.0 → 1.2.0

package/docs/INBOX.md

@@ -0,0 +1,233 @@
+# ftm-inbox
+
+ftm-inbox is an optional background service that polls your work tools (Jira, Freshservice, Slack, Gmail) and surfaces actionable items directly inside the FTM Operator Cockpit dashboard. It runs locally on your machine and never sends data to external services.
+
+## What It Does
+
+Without ftm-inbox, the Operator Cockpit is a static interface. With it:
+
+- Jira issues assigned to you appear as inbox items
+- Freshservice tickets awaiting your response are surfaced
+- Slack DMs and mentions are queued for triage
+- Gmail threads that match configurable filters are included
+
+Each item is stored in a local SQLite database. The FTM skills (`/ftm-mind`, `/ftm-executor`) can read from this inbox to generate plans and take action on your behalf.
+
+## Installation
+
+```bash
+npx feed-the-machine --with-inbox
+```
+
+This will:
+
+1. Install core FTM skills (same as `npx feed-the-machine`)
+2. Copy `ftm-inbox/` to `~/.claude/ftm-inbox/`
+3. Run `npm install` for Node dependencies
+4. Run `pip3 install -r requirements.txt` for Python dependencies
+5. Launch the interactive setup wizard
+6. Optionally install a macOS LaunchAgent for auto-start on login
+
+The core `npx feed-the-machine` install (without `--with-inbox`) is completely unchanged.
+
+### Requirements
+
+- Node.js 18+
+- Python 3.9+
+- `pip3` in PATH
+
+## Configuration
+
+The setup wizard writes credentials to `~/.claude/ftm-inbox/config.yml`. This directory is outside any git repository and should never be committed.
+
+### config.yml reference
+
+```yaml
+server:
+  port: 8042              # Port for the local API (default: 8042)
+
+adapters:
+  jira:
+    enabled: true
+    base_url: "https://yourorg.atlassian.net"
+    email: "you@example.com"
+    api_token: "your-jira-api-token"
+    poll_interval_seconds: 60
+
+  freshservice:
+    enabled: true
+    domain: "yourorg.freshservice.com"
+    api_key: "your-freshservice-api-key"
+    poll_interval_seconds: 120
+
+  slack:
+    enabled: true
+    bot_token: "xoxb-your-slack-bot-token"
+    poll_interval_seconds: 30
+
+  gmail:
+    enabled: false
+    credentials_path: "~/credentials.json"
+    poll_interval_seconds: 120
+
+database:
+  path: "~/.claude/ftm-inbox/inbox.db"
+
+logging:
+  level: "INFO"
+  path: "~/.claude/ftm-inbox/logs"
+```
+
+To re-run the wizard after initial setup:
+
+```bash
+node ~/.claude/ftm-inbox/bin/setup.mjs
+```
+
+To edit manually:
+
+```bash
+$EDITOR ~/.claude/ftm-inbox/config.yml
+```
+
+## Starting and Stopping
+
+```bash
+# Start the service
+~/.claude/ftm-inbox/bin/start.sh
+
+# Stop the service
+~/.claude/ftm-inbox/bin/stop.sh
+
+# Check status and last poll times
+~/.claude/ftm-inbox/bin/status.sh
+```
+
+The port can be overridden at runtime:
+
+```bash
+FTM_INBOX_PORT=9000 ~/.claude/ftm-inbox/bin/start.sh
+```
+
+## Auto-start on Login (macOS)
+
+To generate and load a LaunchAgent that starts ftm-inbox on login:
+
+```bash
+node ~/.claude/ftm-inbox/bin/launchagent.mjs
+```
+
+This creates `~/Library/LaunchAgents/com.ftm.inbox.plist` and loads it immediately. Logs are written to `~/.claude/ftm-inbox/logs/`.
+
+To remove the LaunchAgent:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.ftm.inbox.plist
+rm ~/Library/LaunchAgents/com.ftm.inbox.plist
+```
+
+## Architecture
+
+```
+External Services          ftm-inbox                   FTM Skills
+──────────────────         ─────────────────────────   ──────────────────
+Jira REST API    ──────► Jira Adapter (poller)   ─┐
+Freshservice API ──────► Freshservice Adapter    ─┤► SQLite DB ──► FastAPI ──► /ftm-mind
+Slack API        ──────► Slack Adapter           ─┤  inbox.db           8042    /ftm-executor
+Gmail API        ──────► Gmail Adapter           ─┘
+                                                          ▲
+                                                          │
+                                                    Svelte Dashboard
+                                                    (Operator Cockpit)
+```
+
+- **Adapters** poll their respective APIs on configurable intervals and write normalized `InboxItem` records to SQLite
+- **FastAPI backend** (`backend/main.py`) exposes a REST API at `http://localhost:8042`
+- **Svelte dashboard** reads from the API and renders the Operator Cockpit UI
+- **FTM skills** use the API to read inbox items and generate or execute plans
+
+## Adding a Custom Poller
+
+1. Create a new file in `ftm-inbox/backend/adapters/`:
+
+```python
+# ftm-inbox/backend/adapters/my_service.py
+from .base import BaseAdapter, InboxItem
+from typing import List
+
+class MyServiceAdapter(BaseAdapter):
+    name = "my_service"
+
+    async def fetch(self) -> List[InboxItem]:
+        # Hit your API, return a list of InboxItem objects
+        items = []
+        # ... your logic here ...
+        return items
+```
+
+2. Add credentials to `~/.claude/ftm-inbox/config.yml`:
+
+```yaml
+adapters:
+  my_service:
+    enabled: true
+    api_key: "your-key"
+    poll_interval_seconds: 60
+```
+
+3. Register it in `ftm-inbox/backend/adapters/__init__.py`:
+
+```python
+from .my_service import MyServiceAdapter
+ADAPTERS = [..., MyServiceAdapter]
+```
+
+4. Restart the service: `~/.claude/ftm-inbox/bin/stop.sh && ~/.claude/ftm-inbox/bin/start.sh`
+
+## Troubleshooting
+
+### Service won't start
+
+Check that Python 3 and uvicorn are installed:
+```bash
+python3 --version
+python3 -c "import uvicorn; print(uvicorn.__version__)"
+```
+
+If uvicorn is missing:
+```bash
+pip3 install -r ~/.claude/ftm-inbox/requirements.txt
+```
+
+### No items appearing in the dashboard
+
+1. Check the service is running: `~/.claude/ftm-inbox/bin/status.sh`
+2. Check logs: `tail -f ~/.claude/ftm-inbox/logs/*.log`
+3. Verify credentials in `~/.claude/ftm-inbox/config.yml`
+4. Confirm the adapter is set to `enabled: true`
+
+### Port conflict
+
+If port 8042 is already in use:
+```bash
+FTM_INBOX_PORT=9042 ~/.claude/ftm-inbox/bin/start.sh
+```
+
+Update `config.yml` to match so the dashboard connects to the right port.
+
+### Jira authentication errors
+
+Jira Cloud requires an API token, not your password. Generate one at:
+`https://id.atlassian.com/manage-profile/security/api-tokens`
+
+### Freshservice 403 errors
+
+Ensure the API key belongs to an agent with at least Viewer permissions on the relevant groups.
+
+### Re-running setup
+
+```bash
+node ~/.claude/ftm-inbox/bin/setup.mjs
+```
+
+This overwrites `~/.claude/ftm-inbox/config.yml` but does not touch the database.

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