feed-the-machine 1.1.0 → 1.2.0

package/bin/generate-manifest.mjs

@@ -131,10 +131,214 @@ function extractBlackboardPaths(lines) {
   return paths;
 }
 
+// ---------------------------------------------------------------------------
+// New section parsers for the 6 structured YAML contracts
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses the ## Requirements section.
+ * Format: - type: `name` | required|optional | description
+ * Returns: Array of { type, name, required, description }
+ */
+function parseRequirements(lines) {
+  const requirements = [];
+  // Match lines like: - tool: `knip` | required | static analysis engine
+  // or: - config: `knip.config.ts` | optional | custom knip config
+  const reqRegex = /^-\s+(tool|config|reference|env):\s+`([^`]+)`\s*\|\s*(required|optional)\s*\|\s*(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(reqRegex);
+    if (match) {
+      requirements.push({
+        type: match[1],
+        name: match[2],
+        required: match[3] === 'required',
+        description: match[4].trim(),
+      });
+    }
+  }
+
+  return requirements;
+}
+
+/**
+ * Parses the ## Risk section.
+ * Format:
+ *   - level: read_only | low_write | medium_write | high_write | destructive
+ *   - scope: description
+ *   - rollback: description
+ * Returns: { level, scope, rollback }
+ */
+function parseRisk(lines) {
+  let level = null;
+  let scope = null;
+  let rollback = null;
+
+  for (const line of lines) {
+    const levelMatch = line.match(/^-\s+level:\s+(.+)/);
+    const scopeMatch = line.match(/^-\s+scope:\s+(.+)/);
+    const rollbackMatch = line.match(/^-\s+rollback:\s+(.+)/);
+
+    if (levelMatch) level = levelMatch[1].trim();
+    if (scopeMatch) scope = scopeMatch[1].trim();
+    if (rollbackMatch) rollback = rollbackMatch[1].trim();
+  }
+
+  return { level, scope, rollback };
+}
+
+/**
+ * Parses the ## Approval Gates section.
+ * Format:
+ *   - trigger: condition | action: what happens
+ *   - complexity_routing: micro → auto | small → auto | ...
+ * Returns: { gates: Array<{ trigger, action }>, complexity_routing: object }
+ */
+function parseApprovalGates(lines) {
+  const gates = [];
+  let complexity_routing = null;
+
+  for (const line of lines) {
+    // complexity_routing line
+    const crMatch = line.match(/^-\s+complexity_routing:\s+(.+)/);
+    if (crMatch) {
+      // Parse: micro → auto | small → auto | medium → plan_first | ...
+      const routing = {};
+      const parts = crMatch[1].split('|').map(s => s.trim());
+      for (const part of parts) {
+        const arrowMatch = part.match(/^(\w+)\s+[→>-]+\s+(.+)/);
+        if (arrowMatch) {
+          routing[arrowMatch[1].trim()] = arrowMatch[2].trim();
+        }
+      }
+      complexity_routing = routing;
+      continue;
+    }
+
+    // trigger/action line
+    const triggerMatch = line.match(/^-\s+trigger:\s+(.+?)\s*\|\s*action:\s+(.+)/);
+    if (triggerMatch) {
+      gates.push({
+        trigger: triggerMatch[1].trim(),
+        action: triggerMatch[2].trim(),
+      });
+    }
+  }
+
+  return { gates, complexity_routing };
+}
+
+/**
+ * Parses the ## Fallbacks section.
+ * Format: - condition: description | action: what happens
+ * Returns: Array of { condition, action }
+ */
+function parseFallbacks(lines) {
+  const fallbacks = [];
+  const fallbackRegex = /^-\s+condition:\s+(.+?)\s*\|\s*action:\s+(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(fallbackRegex);
+    if (match) {
+      fallbacks.push({
+        condition: match[1].trim(),
+        action: match[2].trim(),
+      });
+    }
+  }
+
+  return fallbacks;
+}
+
+/**
+ * Parses the ## Capabilities section.
+ * Format: - mcp|cli|env: `name` | required|optional | description
+ * Returns: Array of { type, name, required, description }
+ */
+function parseCapabilities(lines) {
+  const capabilities = [];
+  const capRegex = /^-\s+(mcp|cli|env):\s+`([^`]+)`\s*\|\s*(required|optional)\s*\|\s*(.+)/;
+
+  for (const line of lines) {
+    const match = line.match(capRegex);
+    if (match) {
+      capabilities.push({
+        type: match[1],
+        name: match[2],
+        required: match[3] === 'required',
+        description: match[4].trim(),
+      });
+    }
+  }
+
+  return capabilities;
+}
+
+/**
+ * Parses the ## Event Payloads section.
+ * Format:
+ *   ### event_name
+ *   - field: type — description
+ * Returns: object mapping event_name -> Array<{ field, type, description }>
+ */
+function parseEventPayloads(content) {
+  const payloads = {};
+
+  // We need to parse ### sub-sections within ## Event Payloads.
+  // Find the section start, then extract up to the next ## heading or end of string.
+  // Using manual indexing is more reliable than regex for the "last section" case.
+  const sectionStart = content.indexOf('\n## Event Payloads\n');
+  if (sectionStart < 0) return payloads;
+
+  const afterHeading = content.substring(sectionStart + '\n## Event Payloads\n'.length);
+  const nextH2 = afterHeading.indexOf('\n## ');
+  const sectionContent = nextH2 >= 0 ? afterHeading.substring(0, nextH2) : afterHeading;
+  const lines = sectionContent.split('\n');
+
+  let currentEvent = null;
+
+  for (const line of lines) {
+    // ### event_name header
+    const h3Match = line.match(/^###\s+(.+)/);
+    if (h3Match) {
+      currentEvent = h3Match[1].trim();
+      payloads[currentEvent] = [];
+      continue;
+    }
+
+    if (!currentEvent) continue;
+
+    // - field: type — description
+    const fieldMatch = line.match(/^-\s+(\w+):\s+([\w\[\]|]+)\s+[—-]+\s+(.+)/);
+    if (fieldMatch) {
+      payloads[currentEvent].push({
+        field: fieldMatch[1],
+        type: fieldMatch[2],
+        description: fieldMatch[3].trim(),
+      });
+    }
+  }
+
+  return payloads;
+}
+
 // ---------------------------------------------------------------------------
 // Per-skill metadata extraction
 // ---------------------------------------------------------------------------
 
+/**
+ * Required sections for the structured YAML contract.
+ * Used to generate warnings when sections are missing.
+ */
+const REQUIRED_CONTRACT_SECTIONS = [
+  'Requirements',
+  'Risk',
+  'Approval Gates',
+  'Fallbacks',
+  'Capabilities',
+  'Event Payloads',
+];
+
 function processSkill({ skillFile, skillDir, triggerFile }) {
   const raw = fs.readFileSync(skillFile, 'utf8');
   const stat = fs.statSync(skillFile);
@@ -151,6 +355,24 @@ function processSkill({ skillFile, skillDir, triggerFile }) {
   const blackboardReads = extractBlackboardPaths(sections['Blackboard Read'] || []);
   const blackboardWrites = extractBlackboardPaths(sections['Blackboard Write'] || []);
 
+  // New structured contract sections
+  const requirements = parseRequirements(sections['Requirements'] || []);
+  const risk = parseRisk(sections['Risk'] || []);
+  const { gates: approval_gates, complexity_routing } = parseApprovalGates(
+    sections['Approval Gates'] || []
+  );
+  const fallbacks = parseFallbacks(sections['Fallbacks'] || []);
+  const capabilities = parseCapabilities(sections['Capabilities'] || []);
+  const event_payloads = parseEventPayloads(parsed.content);
+
+  // Warnings — flag any missing required contract sections
+  const warnings = [];
+  for (const section of REQUIRED_CONTRACT_SECTIONS) {
+    if (!sections[section]) {
+      warnings.push(`Missing required section: ## ${section}`);
+    }
+  }
+
   // References directory
   const referencesDir = path.join(ROOT, skillDir, 'references');
   let references = [];
@@ -178,8 +400,16 @@ function processSkill({ skillFile, skillDir, triggerFile }) {
     events_listens: eventsListens,
     blackboard_reads: blackboardReads,
     blackboard_writes: blackboardWrites,
+    requirements,
+    risk,
+    approval_gates,
+    complexity_routing,
+    fallbacks,
+    capabilities,
+    event_payloads,
     references,
     has_evals: hasEvals,
+    warnings,
     size_bytes: stat.size,
     enabled: true,
   };
@@ -196,15 +426,38 @@ function main() {
   // Sort alphabetically by name
   skills.sort((a, b) => a.name.localeCompare(b.name));
 
+  // Collect manifest-level warnings for skills with missing sections
+  const manifestWarnings = [];
+  for (const skill of skills) {
+    if (skill.warnings && skill.warnings.length > 0) {
+      manifestWarnings.push({
+        skill: skill.name,
+        warnings: skill.warnings,
+      });
+    }
+  }
+
   const manifest = {
     generated_at: new Date().toISOString(),
     skills,
+    warnings: manifestWarnings,
   };
 
   const outputPath = path.join(ROOT, 'ftm-manifest.json');
   fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
   process.stderr.write(`Generated manifest for ${skills.length} skills\n`);
+
+  if (manifestWarnings.length > 0) {
+    process.stderr.write(
+      `Warnings: ${manifestWarnings.length} skill(s) missing required contract sections\n`
+    );
+    for (const w of manifestWarnings) {
+      process.stderr.write(`  ${w.skill}: ${w.warnings.join(', ')}\n`);
+    }
+  } else {
+    process.stderr.write(`All ${skills.length} skills have complete contract sections\n`);
+  }
 }
 
 main();

package/bin/install.mjs

@@ -7,10 +7,11 @@
  * and symlinking them into the Claude Code skills directory.
  */
 
-import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
 import { join, basename, dirname } from "path";
-import { homedir } from "os";
+import { homedir, platform } from "os";
 import { fileURLToPath } from "url";
+import { execSync, spawnSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -20,6 +21,10 @@ const SKILLS_DIR = join(HOME, ".claude", "skills");
 const STATE_DIR = join(HOME, ".claude", "ftm-state");
 const CONFIG_DIR = join(HOME, ".claude");
 const HOOKS_DIR = join(HOME, ".claude", "hooks");
+const INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
+
+const ARGS = process.argv.slice(2);
+const WITH_INBOX = ARGS.includes("--with-inbox");
 
 function log(msg) {
   console.log(`  ${msg}`);
@@ -139,6 +144,100 @@ function main() {
   console.log("  Option B: Copy entries from hooks/settings-template.json manually");
   console.log("  See docs/HOOKS.md for details.");
   console.log("");
+
+  if (WITH_INBOX) {
+    installInbox();
+  } else {
+    console.log("Try: /ftm help");
+    console.log("     To also install the inbox service: npx feed-the-machine --with-inbox");
+  }
+}
+
+function installInbox() {
+  const inboxSrc = join(REPO_DIR, "ftm-inbox");
+  if (!existsSync(inboxSrc)) {
+    console.error("ERROR: ftm-inbox/ not found in package. Cannot install inbox service.");
+    process.exit(1);
+  }
+
+  console.log("Installing ftm-inbox service...");
+  console.log(`  Source:      ${inboxSrc}`);
+  console.log(`  Destination: ${INBOX_INSTALL_DIR}`);
+  console.log("");
+
+  // Copy ftm-inbox/ to ~/.claude/ftm-inbox/
+  ensureDir(INBOX_INSTALL_DIR);
+  cpSync(inboxSrc, INBOX_INSTALL_DIR, { recursive: true });
+  log("COPY ftm-inbox → ~/.claude/ftm-inbox/");
+
+  // Make shell scripts executable
+  const binDir = join(INBOX_INSTALL_DIR, "bin");
+  const scripts = ["start.sh", "stop.sh", "status.sh"];
+  for (const script of scripts) {
+    const scriptPath = join(binDir, script);
+    if (existsSync(scriptPath)) {
+      chmodSync(scriptPath, 0o755);
+      log(`CHMOD +x bin/${script}`);
+    }
+  }
+
+  // Install Node deps if package.json exists
+  const pkgJson = join(INBOX_INSTALL_DIR, "package.json");
+  if (existsSync(pkgJson)) {
+    console.log("");
+    console.log("Installing Node.js dependencies...");
+    const npmResult = spawnSync("npm", ["install", "--prefix", INBOX_INSTALL_DIR], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (npmResult.status !== 0) {
+      console.warn("WARNING: npm install failed. Check Node.js version and try manually.");
+    }
+  }
+
+  // Install Python deps if requirements.txt exists
+  const reqTxt = join(INBOX_INSTALL_DIR, "requirements.txt");
+  if (existsSync(reqTxt)) {
+    console.log("");
+    console.log("Installing Python dependencies...");
+    const pipResult = spawnSync("pip3", ["install", "-r", reqTxt], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (pipResult.status !== 0) {
+      console.warn("WARNING: pip3 install failed. Check Python 3 and try manually:");
+      console.warn(`  pip3 install -r ${reqTxt}`);
+    }
+  }
+
+  // Run setup wizard
+  console.log("");
+  console.log("Running setup wizard...");
+  const setupScript = join(binDir, "setup.mjs");
+  if (existsSync(setupScript)) {
+    const setupResult = spawnSync("node", [setupScript], { stdio: "inherit" });
+    if (setupResult.status !== 0) {
+      console.warn("WARNING: Setup wizard exited with errors.");
+      console.warn(`Re-run manually: node ${setupScript}`);
+    }
+  } else {
+    console.warn("WARNING: setup.mjs not found. Run setup manually.");
+  }
+
+  // Offer LaunchAgent (macOS only)
+  if (platform() === "darwin") {
+    console.log("");
+    console.log("macOS detected. To auto-start ftm-inbox on login, run:");
+    console.log(`  node ${join(binDir, "launchagent.mjs")}`);
+  }
+
+  console.log("");
+  console.log("ftm-inbox installed.");
+  console.log(`  Start:  ${join(binDir, "start.sh")}`);
+  console.log(`  Stop:   ${join(binDir, "stop.sh")}`);
+  console.log(`  Status: ${join(binDir, "status.sh")}`);
+  console.log("");
+  console.log("See docs/INBOX.md for full documentation.");
   console.log("Try: /ftm help");
 }
 

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.