@eventmodelers/cli 0.0.22 → 0.0.23

package/README.md

@@ -59,6 +59,30 @@ npx @eventmodelers/cli init-modeling --global
 
 Everything else (the kit dir, project scaffold, credentials, MCP registration) still targets the current directory as usual — `--global` only changes where skills land.
 
+## Bridging to another spec framework
+
+If you drive development with a different spec/task framework (Spec Kitty today; more later) instead of build-kit's own code generation, a **bridge** kit keeps that framework's artifacts in sync with the board instead of writing application code:
+
+```bash
+npx @eventmodelers/cli init --bridge --target spec-kitty
+npx @eventmodelers/cli bridge
+```
+
+`init --bridge` installs a `.bridge-kit/` (mirrors `.build-kit/`'s realtime + task-queue loop) plus only the skills for the chosen `--target` (`shared/bridge/<target>/`) — a `spec-kitty` bridge never installs Kiro's skills, and vice versa. `bridge` starts the loop: on every board slice change (not just "Planned", unlike build-kit), it re-runs `bridge-<target>-specify` to regenerate that framework's spec artifacts from the current `.slices/` export. It doesn't build code and doesn't claim slices. Pass `--ollama` for the local-Ollama runner instead of Claude (same caveat as build-kit's `--ollama`: `lib/ollama-agent.js` is shared as-is).
+
+### Overriding the executor with a hook
+
+Claude is only the default — some teams don't want an AI agent in this loop at all, e.g. they'd rather just commit + push the board export and let a CI pipeline own the actual translation. `--hook` replaces the AI executor with an arbitrary shell command, run once per batch of slice changes:
+
+```bash
+npx @eventmodelers/cli init --bridge --target spec-kitty --hook "git add .slices && git commit -m sync && git push"
+npx @eventmodelers/cli bridge
+```
+
+`init --bridge --hook` persists the command to `.bridge-kit/bridge.json` — a plain, **committed** file (unlike `.eventmodelers/config.json`, which is gitignored for credentials) since the hook is project policy meant to be shared by every teammate and CI runner, not per-machine state. `bridge --hook "<command>"` overrides it for a single run without touching that file. Only one executor runs per invocation — `--ollama` and `--hook` are mutually exclusive.
+
+The hook command runs with `BRIDGE_TASK_COUNT`, `BRIDGE_SLICE_ID`/`_TITLE`/`_STATUS` (the most recent change in the batch), and `BRIDGE_BATCH_FILE` (path to the full batch as JSON) in its environment. It's invoked once per batch, not once per slice — any change that arrives while the hook is still running is left queued for the next batch rather than dropped.
+
 ## Claude execution & config resolution
 
 During install you can optionally point the agent at a local LLM server (vLLM, Ollama) instead of the default Claude Code endpoint, and/or pin a specific model:

package/cli.js

@@ -80,7 +80,32 @@ const MODELING_KIT = {
   needsBoardId: false,
 };
 
-const KIT_DIR_NAMES = [...new Set([...Object.values(STACKS), MODELING_KIT].map((s) => s.kitDirName))];
+// Frameworks a bridge install can translate board slices into. Each key needs
+// a matching `bridge-<key>-specify` skill under shared/bridge/ — see
+// stacks/bridge/templates/bridge/lib/prompt.md for how the loop picks it up.
+const BRIDGE_TARGETS = {
+  'spec-kitty': { label: 'Spec Kitty' },
+};
+
+// Also not a stack — no backend scaffold, just the bridge-*/shared skills +
+// the agent loop. Installed via `init --bridge --target <name>` instead of
+// the `init --stack <name>` picker. useShared:true (unlike modeling-kit): a
+// bridge agent reuses build-kit's cold-spawn/tasks.json engine as-is
+// (lib/ralph.js) — it just reacts to every slice change instead of only
+// "Planned" ones (see queueAllStatuses in lib/ralph.js) and translates
+// instead of building. Its own templates/bridge overlay swaps in
+// bridge-specific prompt.md/AGENT.md and a ralph-claude.js that omits
+// onPlannedSlice entirely — see stacks/bridge/templates/bridge.
+const BRIDGE_KIT = {
+  key: 'bridge',
+  label: 'Bridge — translate board slices into another spec framework, no backend scaffold',
+  kitSubdir: 'bridge',
+  kitDirName: '.bridge-kit',
+  useShared: true,
+  needsBoardId: true,
+};
+
+const KIT_DIR_NAMES = [...new Set([...Object.values(STACKS), MODELING_KIT, BRIDGE_KIT].map((s) => s.kitDirName))];
 
 // Same principle Playwright MCP uses per harness: one shared server, but each coding
 // agent has its own registration mechanism. Automate the ones with a real, verified
@@ -441,17 +466,24 @@ function readJsonSafe(path) {
 // Distinguishes this agent process from any other agent pinging the same
 // token/board — e.g. a build-kit and a modeling-kit install in the same project
 // share one root config.json, and without a per-agent id both would upsert the
-// same alive row and race each other. Written to the kit's OWN config.json
-// (inside kitDir, not the shared root one credentials live in) so a build agent
-// and a modeling agent never end up with the same id, and persisted so restarts
-// of this same kit keep reporting under the same identity.
-function ensureAgentId(kitDir) {
-  const kitConfigPath = join(kitDir, '.eventmodelers', 'config.json');
-  const existing = readJsonSafe(kitConfigPath);
-  if (existing.agentId) return existing.agentId;
-  const agentId = randomUUID();
-  mkdirSync(dirname(kitConfigPath), { recursive: true });
-  writeFileSync(kitConfigPath, JSON.stringify({ ...existing, agentId }, null, 2));
+// same alive row and race each other. The platform already keys the alive-ping
+// on the (agent_type, agent_id) pair, so one shared file works: agentIds is
+// namespaced by agentType inside the project ROOT .eventmodelers/config.json —
+// the same file credentials already live in — instead of each kit dir keeping
+// its own separate config.json (mirrors shared/build-kit/lib/ralph.js's
+// ensureAgentId, duplicated here since this file isn't copied into projects).
+function ensureAgentId(kitDir, agentType) {
+  const rootConfigPath = join(dirname(kitDir), '.eventmodelers', 'config.json');
+  const rootCfg = readJsonSafe(rootConfigPath);
+  rootCfg.agentIds = rootCfg.agentIds || {};
+  if (rootCfg.agentIds[agentType]) return rootCfg.agentIds[agentType];
+
+  const legacyAgentId = readJsonSafe(join(kitDir, '.eventmodelers', 'config.json')).agentId;
+
+  const agentId = legacyAgentId || randomUUID();
+  rootCfg.agentIds[agentType] = agentId;
+  mkdirSync(dirname(rootConfigPath), { recursive: true });
+  writeFileSync(rootConfigPath, JSON.stringify(rootCfg, null, 2));
   return agentId;
 }
 
@@ -540,6 +572,14 @@ async function installStack(stackKey, stackCfg, options = {}) {
     // of sync with each other before (e.g. one stack's connect skill silently
     // missing a bugfix another stack's copy had).
     const sharedSkills = join(__dirname, 'shared', 'skills');
+    // Adapter skills that translate board slices for another spec framework —
+    // one subfolder per target (shared/bridge/spec-kitty/bridge-spec-kitty-*,
+    // shared/bridge/kiro/..., etc.), so a bridge install only ever pulls in
+    // the target it was actually configured for, not every framework's
+    // skills. Only relevant to a bridge install — never copied into the four
+    // backend stacks or modeling-kit.
+    const isBridge = stackKey === BRIDGE_KIT.key;
+    const sharedBridgeSkills = isBridge ? join(__dirname, 'shared', 'bridge', options.target) : null;
 
     if (!existsSync(templatesSource)) {
       console.error('❌ Templates directory not found at:', templatesSource);
@@ -552,6 +592,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     const claudeSkillsSrc = join(templatesSource, '.claude', 'skills');
     const installedSkills = [
       ...(existsSync(sharedSkills) ? readdirSync(sharedSkills) : []),
+      ...(isBridge && existsSync(sharedBridgeSkills) ? readdirSync(sharedBridgeSkills) : []),
       ...(existsSync(claudeSkillsSrc) ? readdirSync(claudeSkillsSrc) : []),
     ];
     let claudeExtras = [];
@@ -560,11 +601,13 @@ async function installStack(stackKey, stackCfg, options = {}) {
       const globalSkillsDir = join(homedir(), '.claude', 'skills');
       console.log('📦 Installing skills globally...');
       copyDirContents(sharedSkills, globalSkillsDir);
+      if (isBridge) copyDirContents(sharedBridgeSkills, globalSkillsDir);
       copyDirContents(claudeSkillsSrc, globalSkillsDir);
     } else {
       console.log('📦 Installing skills...');
       copyDirContents(join(templatesSource, '.claude'), join(targetDir, '.claude'));
       copyDirContents(sharedSkills, join(targetDir, '.claude', 'skills'));
+      if (isBridge) copyDirContents(sharedBridgeSkills, join(targetDir, '.claude', 'skills'));
       claudeExtras = existsSync(join(templatesSource, '.claude'))
         ? readdirSync(join(templatesSource, '.claude')).filter((f) => f !== 'skills')
         : [];
@@ -648,7 +691,11 @@ async function installStack(stackKey, stackCfg, options = {}) {
     );
 
     console.log('\n✅ Done! Start your agent:\n');
-    console.log('  npx @eventmodelers/cli run          (--ollama or --bash for other runners)\n');
+    if (isBridge) {
+      console.log('  npx @eventmodelers/cli bridge\n');
+    } else {
+      console.log('  npx @eventmodelers/cli run          (--ollama or --bash for other runners)\n');
+    }
     console.log('Connect this project to an MCP client (Claude Code, VS Code, ...):\n');
     console.log(`  npx @eventmodelers/cli init-mcp\n`);
     console.log('Expose these skills to other AI agent hosts (Cursor, Windsurf, Gemini CLI, Copilot, Codex CLI, Kiro, ...):\n');
@@ -846,7 +893,7 @@ async function runModeling(kitDir, projectDir) {
   const { createClient } = await import('@supabase/supabase-js');
 
   const local = loadLocalConfig(kitDir);
-  local.agentId = local.agentId ?? ensureAgentId(kitDir);
+  local.agentId = ensureAgentId(kitDir, 'MODELING');
   if (!local.token || !local.organizationId) {
     console.error('❌ --modeling needs platform credentials in .eventmodelers/config.json (token + organizationId) — run `/connect` once or paste your config first.');
     process.exit(1);
@@ -1075,6 +1122,7 @@ program.hook('preAction', (_thisCommand, actionCommand) => {
   console.error('   Run one of these first:');
   console.error(`     npx @eventmodelers/cli init --stack <name>   (${Object.keys(STACKS).join(', ')})`);
   console.error('     npx @eventmodelers/cli init --modeling');
+  console.error(`     npx @eventmodelers/cli init --bridge --target <name>   (${Object.keys(BRIDGE_TARGETS).join(', ')})`);
   process.exit(1);
 });
 
@@ -1097,19 +1145,25 @@ function credentialOverridesFromOpts(opts) {
 credentialFlags(program
   .command('init')
   .alias('install')
-  .description('Scaffold a stack + install the agent kit into the current directory (or --modeling for skills + agent loop only, no backend scaffold)')
+  .description('Scaffold a stack + install the agent kit into the current directory (or --modeling for skills + agent loop only, no backend scaffold; or --bridge to translate board slices into another spec framework)')
   .option('--stack <name>', `Stack to install (${Object.keys(STACKS).join(', ')})`)
-  .option('--modeling', 'Install skills + the agent loop only — no backend scaffold. Mutually exclusive with --stack.')
+  .option('--modeling', 'Install skills + the agent loop only — no backend scaffold. Mutually exclusive with --stack/--bridge.')
+  .option('--bridge', 'Install a bridge kit — translates board slices into another spec framework instead of building code. Mutually exclusive with --stack/--modeling. Requires --target.')
+  .option('--target <name>', `Bridge target framework (${Object.keys(BRIDGE_TARGETS).join(', ')}) — only meaningful with --bridge`)
+  .option('--hook <command>', 'Persist a default shell command hook for `bridge` to run per batch of slice changes instead of Claude/Ollama (e.g. commit + push .slices/ for a CI pipeline to pick up) — only meaningful with --bridge. Can also be set per-run with `bridge --hook`.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
 
-    if (opts.modeling) {
-      if (opts.stack) {
-        console.error('❌ --modeling and --stack are mutually exclusive — pick one.');
+    if (opts.modeling || opts.bridge) {
+      if (opts.stack || (opts.modeling && opts.bridge)) {
+        console.error('❌ --stack, --modeling, and --bridge are mutually exclusive — pick one.');
         process.exit(1);
       }
+    }
+
+    if (opts.modeling) {
       await installStack(MODELING_KIT.key, MODELING_KIT, {
         configPath: globalOpts.config,
         print: globalOpts.print,
@@ -1120,6 +1174,37 @@ credentialFlags(program
       return;
     }
 
+    if (opts.bridge) {
+      if (!opts.target) {
+        console.error(`❌ --bridge requires --target (${Object.keys(BRIDGE_TARGETS).join(', ')}).`);
+        process.exit(1);
+      }
+      if (!BRIDGE_TARGETS[opts.target]) {
+        console.error(`❌ Unknown bridge target "${opts.target}". Available: ${Object.keys(BRIDGE_TARGETS).join(', ')}`);
+        process.exit(1);
+      }
+      await installStack(BRIDGE_KIT.key, BRIDGE_KIT, {
+        configPath: globalOpts.config,
+        print: globalOpts.print,
+        global: opts.global,
+        force: opts.force,
+        credentialOverrides: credentialOverridesFromOpts(opts),
+        target: opts.target,
+      });
+      // Deliberately NOT under .bridge-kit/.eventmodelers/ — that whole name is
+      // gitignored (a bare `.eventmodelers` pattern matches at any depth, since
+      // it protects the root credentials file), so anything written there is
+      // per-machine only. target/hookCommand are project policy — how this repo
+      // reacts to board changes — meant to be committed and shared by every
+      // teammate and CI runner, so they live in a plain sibling file instead.
+      const bridgeConfigPath = join(process.cwd(), BRIDGE_KIT.kitDirName, 'bridge.json');
+      const existingBridgeCfg = readJsonSafe(bridgeConfigPath);
+      mkdirSync(dirname(bridgeConfigPath), { recursive: true });
+      writeFileSync(bridgeConfigPath, JSON.stringify({ ...existingBridgeCfg, target: opts.target, ...(opts.hook ? { hookCommand: opts.hook } : {}) }, null, 2));
+      console.log(`  ✓ Bridge target set to "${opts.target}"${opts.hook ? ` with hook: ${opts.hook}` : ''}`);
+      return;
+    }
+
     const stackKey = await resolveStack(opts.stack);
     await installStack(stackKey, STACKS[stackKey], {
       configPath: globalOpts.config,
@@ -1224,7 +1309,12 @@ program
     // we resolve each stack's dir independently instead of relying on that order.
     const installedKitDirs = findAllInstalledKitDirs(cwd);
     const modelingKitDir = installedKitDirs.find((d) => d.endsWith(MODELING_KIT.kitDirName)) ?? null;
-    const buildKitDir = installedKitDirs.find((d) => d !== modelingKitDir) ?? null;
+    const bridgeKitDir = installedKitDirs.find((d) => d.endsWith(BRIDGE_KIT.kitDirName)) ?? null;
+    // A bridge kit is not a build-kit stand-in even though it also reuses
+    // lib/ralph.js — it has its own `eventmodelers bridge` entrypoint (no
+    // onPlannedSlice/--ollama/--bash support), so it's excluded here rather
+    // than falling through to the generic build-kit runner below.
+    const buildKitDir = installedKitDirs.find((d) => d !== modelingKitDir && d !== bridgeKitDir) ?? null;
 
     // No overlap between the two stacks' runtimes: modeling-kit only ever runs the
     // warm, direct-dispatch loop (--modeling); build-kit only ever runs the
@@ -1258,6 +1348,8 @@ program
     if (!buildKitDir) {
       if (modelingKitDir) {
         console.error(`❌ A modeling-kit install (${MODELING_KIT.kitDirName}/) only runs via \`eventmodelers run --modeling\` — there is no cold-spawn/tasks.json loop for modeling-only projects.`);
+      } else if (bridgeKitDir) {
+        console.error(`❌ A bridge-kit install (${BRIDGE_KIT.kitDirName}/) only runs via \`eventmodelers bridge\` — it has no --modeling/--ollama/--bash modes.`);
       } else {
         console.error(`❌ No kit installed in ${cwd} — run \`eventmodelers install\` first.`);
       }
@@ -1291,6 +1383,53 @@ program
     }
   });
 
+program
+  .command('bridge')
+  .description('Start the bridge agent loop from the installed .bridge-kit/ — translates board slice changes into another spec framework instead of building code. Claude is the default executor; --ollama or --hook override it.')
+  .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner')
+  .option('--hook <command>', 'Run this shell command instead of an AI agent for each batch of slice changes (e.g. commit + push .slices/ for a CI pipeline to pick up) — overrides any hook persisted via `init --bridge --hook` for this run only')
+  .action((opts) => {
+    const cwd = process.cwd();
+    const kitDir = findAllInstalledKitDirs(cwd).find((d) => d.endsWith(BRIDGE_KIT.kitDirName)) ?? null;
+    if (!kitDir) {
+      console.error(`❌ No bridge-kit installed in ${cwd} — run \`eventmodelers init --bridge --target <name>\` first.`);
+      process.exit(1);
+    }
+
+    if (opts.ollama && opts.hook) {
+      console.error('❌ --ollama and --hook are mutually exclusive — pick one executor.');
+      process.exit(1);
+    }
+
+    // A persisted default (from `init --bridge --hook`) lives in bridge.json, a
+    // plain sibling file — NOT under .eventmodelers/, which is gitignored (see
+    // the comment in `init`'s --bridge branch) and would otherwise make this
+    // per-machine instead of a shared, checked-in team/CI convention.
+    const persistedHook = readJsonSafe(join(kitDir, 'bridge.json')).hookCommand;
+    const hookCmd = opts.hook || persistedHook;
+
+    // v1 has no --bash equivalent, unlike `run` — the default/--ollama path
+    // needs an actual agent, not a plain shell script; --hook is the escape
+    // hatch for teams who want a plain shell command instead of an AI agent.
+    const runner = hookCmd ? 'ralph-hook.js' : opts.ollama ? 'ralph-ollama.js' : 'ralph-claude.js';
+    const runnerPath = join(kitDir, runner);
+    if (!existsSync(runnerPath)) {
+      console.error(`❌ ${relative(cwd, runnerPath)} not found.`);
+      process.exit(1);
+    }
+
+    console.log(`▶ Starting ${relative(cwd, runnerPath)}${hookCmd ? ` (hook: ${hookCmd})` : ''}...\n`);
+    try {
+      execSync(`node "${runnerPath}"`, {
+        cwd: kitDir,
+        stdio: 'inherit',
+        env: hookCmd ? { ...process.env, BRIDGE_HOOK_CMD: hookCmd } : process.env,
+      });
+    } catch (err) {
+      process.exit(err.status || 1);
+    }
+  });
+
 program
   .command('listen')
   .description('Start the code-export listener (code-export.mjs) from the installed kit dir — receives slice/screen data pushed from the eventmodelers board UI and writes it into .slices/')
@@ -1409,14 +1548,16 @@ program
   .description('Remove everything init (with or without --modeling) installed: the kit dir, the skills it copied (project-local or ~/.claude/skills with --global), its MCP entry in .claude/settings.json, and any files written by init-agents. Leaves the root project scaffold untouched.')
   .option('--build-kit', `Remove ${STACKS.node.kitDirName}/ (the backend-stack kit dir)`)
   .option('--modeling-kit', `Remove ${MODELING_KIT.kitDirName}/ (the modeling-only kit dir)`)
+  .option('--bridge-kit', `Remove ${BRIDGE_KIT.kitDirName}/ (the bridge kit dir)`)
   .action((opts) => {
     const cwd = process.cwd();
     let targets;
 
-    if (opts.buildKit || opts.modelingKit) {
+    if (opts.buildKit || opts.modelingKit || opts.bridgeKit) {
       targets = [];
       if (opts.buildKit) targets.push(join(cwd, STACKS.node.kitDirName));
       if (opts.modelingKit) targets.push(join(cwd, MODELING_KIT.kitDirName));
+      if (opts.bridgeKit) targets.push(join(cwd, BRIDGE_KIT.kitDirName));
       targets = targets.filter((p) => existsSync(p));
       if (!targets.length) {
         console.log('ℹ️  Nothing to remove for the requested option(s).');
@@ -1429,7 +1570,7 @@ program
         return;
       }
       if (targets.length > 1) {
-        console.log('⚠️  Multiple kit dirs found — re-run with --build-kit or --modeling-kit to pick one, or both to remove everything.');
+        console.log('⚠️  Multiple kit dirs found — re-run with --build-kit, --modeling-kit, and/or --bridge-kit to pick which to remove.');
         targets.forEach((t) => console.log(`     ${t}`));
         return;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/bridge/spec-kitty/bridge-spec-kitty-specify/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: bridge-spec-kitty-specify
+description: "Adapter: generate a Spec Kitty mission spec.md (and auto-evaluate its quality checklist) from an Eventmodelers board's exported event model, instead of running the /spec-kitty.specify interview. Use when the user says \"use the event model as the spec\", \"sync the board to spec-kitty\", \"generate the spec from the event model\", or when a .slices/ export exists and a Spec Kitty mission needs to start or refresh from it."
+---
+
+# bridge-spec-kitty-specify
+
+Replaces the human interview in `/spec-kitty.specify` with a direct read of an
+Eventmodelers board export. The event model is the source of truth; `spec.md`
+becomes a **generated, read-only artifact** derived from it. Everything
+downstream of specify (`/spec-kitty.plan`, `/spec-kitty.tasks`,
+implement/review/merge) is untouched — this skill only produces the two
+artifacts that phase gate expects: `spec.md` and `checklists/requirements.md`.
+
+Do not use this to hand-author or hand-edit `spec.md` — if the event model is
+wrong, fix it on the board and re-run this skill. A `spec.md` produced here
+that gets manually edited afterward will be silently overwritten on the next
+sync; there is no merge/diff in this version (see Limitations).
+
+## Inputs
+
+The Eventmodelers `listen` server (`npx @eventmodelers/cli listen`) writes the
+board export locally. Read it directly — do not call the board API:
+
+- `.slices/current_context.json` → `{ "name": "<context>" }` — which context
+  to ingest if the user didn't name one.
+- `.slices/<context>/index.json` → `{ "slices": [{ id, slice, index, context,
+  folder, status, group }] }` — the ordered slice list.
+- `.slices/<context>/context.json` → context-level name/package info.
+- `.slices/<context>/<folder>/slice.json` → full slice detail per the
+  [event-modeling-spec](https://github.com/dilgerma/event-modeling-spec)
+  contract: `commands[]`, `events[]`, `readModels[]` (projections/queries),
+  `screens[]`, `automations[]`/`processors[]`, `specifications[]` (given/when/
+  then), plus free-text `description`/`notes`.
+
+If `.slices/` doesn't exist yet, stop and tell the user to run
+`npx @eventmodelers/cli listen` (or `init-modeling` first if the kit isn't
+installed) and push the board export before retrying.
+
+## Flow
+
+1. **Resolve the mission.** If an existing `kitty-specs/<slug>/meta.json`
+   already points at this context (check `purpose_tldr`/a stored context
+   reference), re-sync into it. Otherwise create a new mission dir the same
+   way `/spec-kitty.specify` does: kebab-case name + 8-char ULID suffix,
+   `mission_type: software-dev` (this adapter does not introduce a new
+   mission type — see project memory on why). Write `meta.json` matching the
+   shape in an existing mission (`mission_id`, `mission_slug`, `purpose_tldr`,
+   `purpose_context`, `target_branch`, etc.).
+2. **Load every slice** referenced in `index.json` by reading each
+   `<folder>/slice.json`. Do not skip slices with empty `specifications` —
+   surface them as gaps in the checklist instead (step 4).
+3. **Compose `spec.md`** using the standard Spec Kitty template sections,
+   sourced only from what the model actually states — never invent detail
+   the board doesn't have:
+   - **Purpose** ← `context.json` name/description, or ask the user for a
+     one-paragraph purpose if the board has none.
+   - **Primary User Story** ← walk the slices in `index.json` order (this is
+     already the chronological/timeline order from the board) and narrate
+     the SCREEN → COMMAND → EVENT → READMODEL flow across them.
+   - **Acceptance Scenarios** ← one bullet per `specifications[]` entry,
+     copied straight from its given/when/then — do not paraphrase away
+     precision the model already captured.
+   - **Edge Cases** ← `specifications[]` entries that describe rejection/
+     negative/boundary behavior (reject, invalid, already-exists, etc.).
+   - **Domain Language** ← distinct nouns from event/command/read-model field
+     names and titles, deduped.
+   - **Functional Requirements (FR-###)** ← one row per COMMAND (state-change
+     slice) and per AUTOMATION slice; wording from the command/automation
+     name + `description`.
+   - **Non-Functional Requirements / Constraints** ← only from explicit
+     `notes`/`description` content tagged as timing/authorization/volume
+     constraints. If the model states none, leave the table empty — do not
+     fabricate NFRs to fill it.
+   - **Key Entities** ← distinct read-model/event payload shapes.
+   - **Interfaces to Other Teams** ← any `TRANSLATION`-type slice or external
+     system mentioned in a slice's `description`.
+4. **Evaluate `checklists/requirements.md`** against the ingested model
+   instead of a human review pass. Check an item only if the model
+   demonstrably satisfies it:
+   - "No [NEEDS CLARIFICATION] markers remain" → fails if any slice has an
+     empty `specifications[]` or a `description` containing `TODO`/`TBD`.
+   - "Requirements are testable and unambiguous" → fails if an FR/NFR row has
+     no backing `specifications[]` entry.
+   - "Non-functional requirements include measurable thresholds" → fails
+     (leave unchecked, don't skip the row) if the NFR table is empty but the
+     model contains AUTOMATION slices implying a timing constraint the board
+     never made explicit.
+   - Leave any check unchecked with a `## Notes` explanation when the event
+     model genuinely doesn't provide enough to verify it — this checklist
+     gates `/spec-kitty.plan`, so a false pass defeats the point of the gate.
+5. **Hand off.** Once `spec.md` + `checklists/requirements.md` are written,
+   tell the user the mission is ready for `/spec-kitty.plan` as normal — do
+   not run plan/tasks yourself from this skill.
+
+## Re-sync behavior
+
+Re-running this skill against the same mission regenerates `spec.md` and
+`checklists/requirements.md` wholesale from the current `.slices/` state.
+There is no field-level diff against the previous generation — if the spec
+needs to reflect board changes, re-run this skill rather than hand-patching
+`spec.md`.
+
+## Guardrail
+
+If a required section can't be populated from the event model (e.g. no
+Purpose anywhere on the board), ask the user rather than inventing one — an
+invented Purpose defeats the reason this adapter exists (the event model,
+not the LLM, is the source of truth for product intent).
+
+## Limitations (by design, v1)
+
+- Does not itself generate `tasks/WP##-*.md` from slices — see the companion
+  `bridge-spec-kitty-tasks` skill, which enforces a 1:1
+  slice-to-WP mapping when `wps.yaml` is written during
+  `/spec-kitty.tasks-outline`.
+- Does not introduce a new Spec Kitty mission type. Spec Kitty 3.2.5's
+  built-in mission types are loaded from a flat directory inside the
+  installed package (`doctrine/missions/mission_types/*.yaml`) via
+  `MissionTypeRepository.default()`, and org-pack extension for the
+  `mission_types` kind is unwired in this version (fragments only add
+  governance-graph metadata, not an executable type). A real native mission
+  type would require patching the installed `spec-kitty-cli` package itself.
+  This adapter avoids that entirely — it stays inside `mission_type:
+  software-dev` and only replaces the specify phase's *inputs*.

package/shared/bridge/spec-kitty/bridge-spec-kitty-tasks/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: bridge-spec-kitty-tasks
+description: "Adapter: enforce a 1:1 mapping between Eventmodelers board slices and Spec Kitty work packages when writing wps.yaml. Use when the user says \"one slice should become one task/WP\", \"generate tasks from the event model\", or right after bridge-spec-kitty-specify, in place of freeform subtask-grouping judgment in /spec-kitty.tasks-outline."
+---
+
+# bridge-spec-kitty-tasks
+
+Companion to `bridge-spec-kitty-specify`. That skill turns the event model into
+`spec.md`; this one enforces that each **slice** on the board becomes exactly
+**one work package** — never split across WPs, never merged with another
+slice — when Spec Kitty's task-planning pipeline builds `wps.yaml`.
+
+This replaces only step 3–6 of `/spec-kitty.tasks-outline` (deriving
+subtasks and rolling them into WPs). `/spec-kitty.tasks-packages` and
+`/spec-kitty.tasks-finalize` run completely unmodified afterward — they only
+ever consume `wps.yaml`, and don't care where its groupings came from.
+
+## Why a hard 1:1 boundary
+
+Spec Kitty's default `tasks-outline` groups subtasks into WPs by
+judgment (target 3–7 subtasks, merge small ones, split large ones). That's
+the right default when subtask boundaries come from an LLM reading prose. It
+is the *wrong* default here: the event model already drew the real
+boundaries (each SLICE_BORDER is a reviewable, independently buildable unit
+the board's `Planned → InProgress → Done` slice lifecycle already governs).
+Re-grouping at the WP layer would create a second, competing notion of "unit
+of work" that drifts from the board over time. So this skill trades away
+`tasks-outline`'s sizing flexibility on purpose: WP boundary = slice
+boundary, full stop.
+
+## Inputs
+
+Same event-model export as `bridge-spec-kitty-specify`:
+`.slices/<context>/index.json` (slice list, board/timeline order) and each
+`.slices/<context>/<folder>/slice.json` (commands, events, readModels,
+automations, `specifications`). Also read, from `feature_dir`:
+`spec.md` (for FR/NFR ids — already generated by `bridge-spec-kitty-specify`) and
+`plan.md` (for the tech-stack/file-layout context needed to fill
+`owned_files`, since the event model doesn't know the codebase's directory
+structure).
+
+## Flow
+
+1. **One WP per slice, in board order.** Assign `WP01`, `WP02`, ... following
+   `index.json`'s order (already the board's chronological/timeline order).
+   Do not reorder for "phase grouping" the way default `tasks-outline` does —
+   the board order already encodes the intended build sequence.
+2. **Subtasks come from inside the slice, not across slices.** For each
+   slice, break its own commands/read-models/screens/automations into T-ids
+   (one per command handler, one per read-model endpoint, one per
+   screen/automation, one for its tests) — all nested under that slice's one
+   WP. Every subtask must trace to exactly one slice; never let a subtask
+   span two slices.
+3. **Dependencies from event flow, not guesswork.** WP *B* depends on WP *A*
+   iff slice B's commands/queries/automations consume an event that slice
+   A's commands/automations produce. Derive this by diffing each slice's
+   emitted event names against every other slice's consumed event names —
+   this is mechanical, not judgment-based, so don't also apply
+   `tasks-outline`'s "Phase 2 typically depends on Phase 1" heuristic on top
+   of it.
+4. **`requirement_refs` from the spec's own FR/NFR table.** Match each
+   slice's command/read-model/automation names against `spec.md`'s FR/NFR
+   rows (written by `bridge-spec-kitty-specify` from these same slices) and cite
+   whichever ids trace to this slice. A slice with no matching row means
+   `bridge-spec-kitty-specify` needs a re-run, not a fabricated ref here.
+5. **Write `wps.yaml`** using the exact schema `/spec-kitty.tasks-outline`
+   expects (`id`, `title`, `dependencies`, `owned_files`, `requirement_refs`,
+   `plan_concern_refs` or `cross_cutting: true`, `subtasks`, `prompt_file:
+   null`) — so `tasks-packages`/`finalize-tasks` need no awareness that this
+   skill (rather than default `tasks-outline`) produced it.
+6. **Hand off.** Tell the user to continue with `/spec-kitty.tasks-packages`
+   then `/spec-kitty.tasks-finalize` (or `spec-kitty next`) exactly as normal.
+
+## Guardrail: don't fix boundary problems here
+
+If a slice's own scope would blow past Spec Kitty's WP sizing ceiling (>10
+subtasks / >700 lines), **do not silently split it into two WPs** — that
+breaks the 1:1 invariant this skill exists to enforce, and produces the
+exact spec/code drift it's meant to prevent. Instead, flag it to the user:
+the slice is too coarse on the board itself, so split the SLICE_BORDER
+there and re-run both `bridge-spec-kitty-specify` and this skill. The event model
+stays the single place slice boundaries get decided.
+
+The same holds in the other direction: never merge two small slices into
+one WP for tidiness, even if `tasks-outline`'s default guidance would.
+
+## Limitations (v1)
+
+- `owned_files`/file-layout ownership still comes from `plan.md`, which is
+  still produced by the normal, LLM-authored `/spec-kitty.plan` — the event
+  model has no notion of source-file structure, so this isn't something to
+  push onto it.
+- Re-running this skill after the board changes regenerates `wps.yaml`
+  wholesale from the current slice set, same as `bridge-spec-kitty-specify`'s
+  re-sync behavior — no field-level diff against a prior run.

package/shared/build-kit/lib/ralph.js

@@ -109,26 +109,42 @@ function hasCredentials(cfg) {
 }
 
 // Distinguishes this agent process from any other agent pinging the same
-// token/board — e.g. a build-kit and a modeling-kit install in the same project
+// token/board — e.g. a build-kit and a bridge-kit install in the same project
 // share one root config.json, and without a per-agent id both would upsert the
-// same alive row and race each other. Written to the kit's OWN config.json
-// (inside kitDir, not the shared root one credentials live in) so a build agent
-// and a modeling agent never end up with the same id, and persisted so restarts
-// of this same kit keep reporting under the same identity.
-function ensureAgentId(kitDir) {
-  const kitConfigPath = join(kitDir, '.eventmodelers', 'config.json');
-  let existing = {};
-  if (existsSync(kitConfigPath)) {
+// same alive row and race each other. The platform already keys the alive-ping
+// on the (agent_type, agent_id) pair, so one shared file works: agentIds is
+// namespaced by agentType (BUILD/BRIDGE/MODELING/...) inside the project ROOT
+// .eventmodelers/config.json — the same file credentials already live in —
+// instead of each kit dir keeping its own separate config.json. Falls back to
+// a pre-existing kit-local agentId (older installs, before this consolidation)
+// so an upgrade doesn't mint a new identity the platform hasn't seen before.
+function ensureAgentId(kitDir, agentType) {
+  const rootConfigPath = join(dirname(kitDir), '.eventmodelers', 'config.json');
+  let rootCfg = {};
+  if (existsSync(rootConfigPath)) {
     try {
-      existing = JSON.parse(readFileSync(kitConfigPath, 'utf-8'));
+      rootCfg = JSON.parse(readFileSync(rootConfigPath, 'utf-8'));
     } catch {
-      console.warn(`[ralph] Skipping invalid config at ${kitConfigPath}`);
+      console.warn(`[ralph] Skipping invalid config at ${rootConfigPath}`);
     }
   }
-  if (existing.agentId) return existing.agentId;
-  const agentId = randomUUID();
-  mkdirSync(dirname(kitConfigPath), { recursive: true });
-  writeFileSync(kitConfigPath, JSON.stringify({ ...existing, agentId }, null, 2));
+  rootCfg.agentIds = rootCfg.agentIds || {};
+  if (rootCfg.agentIds[agentType]) return rootCfg.agentIds[agentType];
+
+  const legacyKitConfigPath = join(kitDir, '.eventmodelers', 'config.json');
+  let legacyAgentId;
+  if (existsSync(legacyKitConfigPath)) {
+    try {
+      legacyAgentId = JSON.parse(readFileSync(legacyKitConfigPath, 'utf-8')).agentId;
+    } catch {
+      console.warn(`[ralph] Skipping invalid config at ${legacyKitConfigPath}`);
+    }
+  }
+
+  const agentId = legacyAgentId || randomUUID();
+  rootCfg.agentIds[agentType] = agentId;
+  mkdirSync(dirname(rootConfigPath), { recursive: true });
+  writeFileSync(rootConfigPath, JSON.stringify(rootCfg, null, 2));
   return agentId;
 }
 
@@ -226,7 +242,7 @@ async function writeTask(payload, kitDir) {
   console.log(`[agent] Task written — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
 }
 
-async function startRealtimeAgent(cfg, kitDir) {
+async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllStatuses = false } = {}) {
   let realtimeToken = await retryOn401('getRealtimeToken', () => getRealtimeToken(cfg));
 
   await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
@@ -254,8 +270,11 @@ async function startRealtimeAgent(cfg, kitDir) {
       await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
         console.error('[agent] Slice persist error:', err),
       );
-      // Planned slices are handled by onPlannedSlice directly — no task needed
-      if ((payload.sliceStatus || '').toLowerCase() !== 'planned') {
+      // Planned slices are handled by onPlannedSlice directly — no task needed.
+      // queueAllStatuses opts out of that split entirely (e.g. bridge has no
+      // onPlannedSlice consumer, so a lingering Planned slice would otherwise
+      // never naturally clear its own trigger — see lib/ralph.js callers).
+      if (queueAllStatuses || (payload.sliceStatus || '').toLowerCase() !== 'planned') {
         await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
       }
     })
@@ -276,7 +295,7 @@ async function startRealtimeAgent(cfg, kitDir) {
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: 'BUILD', agent_id: cfg.agentId }),
+        body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: agentType, agent_id: cfg.agentId }),
         signal: AbortSignal.timeout(10_000),
       });
       if (!res.ok) console.error(`[agent] Ping failed: ${res.status} ${await res.text().catch(() => '')}`);
@@ -379,9 +398,9 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice) {
 
 export { loadLocalConfig, fetchPlatformConfig, retryOn401, startRealtimeAgent };
 
-export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice }) {
+export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false }) {
   const local = loadLocalConfig(kitDir);
-  local.agentId = local.agentId ?? ensureAgentId(kitDir);
+  local.agentId = ensureAgentId(kitDir, agentType);
 
   console.log(`Ralph — kit: ${kitDir}`);
   console.log(`         project: ${projectDir}`);
@@ -396,7 +415,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice })
   console.log(`         org=${cfg.organizationId}, board=${cfg.boardId}, base=${cfg.baseUrl}\n`);
 
   await Promise.all([
-    startRealtimeAgent(cfg, kitDir),
+    startRealtimeAgent(cfg, kitDir, { agentType, queueAllStatuses }),
     ralphLoop(kitDir, cfg, onTask, onPlannedSlice),
   ]);
 }

package/stacks/bridge/templates/bridge/lib/AGENT.md

@@ -0,0 +1,47 @@
+# Agent Learnings
+
+Patterns and gotchas discovered during task processing. Update this file
+whenever you encounter something reusable.
+
+## tasks.json
+
+- Tasks are objects with `id`, `createdAt`, and `payload` (a
+  `SliceChangedPayload`).
+- Unlike build-kit, every status change is queued (not just non-`Planned`
+  ones) — see `queueAllStatuses` in `lib/ralph.js`.
+- After completing a task, remove it from the array entirely — do not add a
+  status field.
+- Write `[]` to `tasks.json` if the last task is completed.
+
+## SliceChangedPayload fields
+
+```
+event           always "slice:changed"
+organizationId  org UUID or null
+boardId         board UUID
+sliceId         SLICE_BORDER node UUID
+sliceTitle      human-readable slice name (may be null)
+sliceStatus     e.g. "Created", "Planned", "InProgress", "Done" (may be null)
+timestamp       unix ms when the change was emitted
+```
+
+## Bridge target
+
+- The active target framework lives in `.bridge-kit/bridge.json`'s `target`
+  field, written at `init --bridge --target <name>` time. This file is
+  committed (unlike `.eventmodelers/config.json`, which is gitignored) since
+  it's project policy shared by every teammate and CI runner, not a
+  per-machine credential.
+- Skill naming convention: `bridge-<target>-specify` (kept in sync every
+  task) and `bridge-<target>-tasks` (invoked separately, by that framework's
+  own task-planning phase — not from this loop).
+
+## Executors
+
+- Claude (`ralph-claude.js`, this prompt) is the default. `bridge --ollama`
+  swaps in a local model instead — same prompt, different executor.
+- `bridge --hook "<command>"` (or a `hookCommand` persisted in
+  `bridge.json`) bypasses this prompt entirely: `ralph-hook.js` runs an
+  arbitrary shell command per batch of changes instead of any AI agent — e.g.
+  commit + push `.slices/` and let a CI pipeline do the actual translation.
+  If you're reading this file, a hook wasn't configured for this run.

package/stacks/bridge/templates/bridge/lib/prompt.md

@@ -0,0 +1,111 @@
+# Bridge Task Instructions
+
+You are an autonomous agent reacting to slice status change events on an
+Eventmodelers board. Unlike a build-kit agent, you do **not** write
+application code — you translate the board's event model into artifacts for
+another spec framework (e.g. Spec Kitty), keeping that framework's files in
+sync with the board as it changes.
+
+## Your Loop
+
+1. Read `AGENT.md` to load accumulated learnings before doing anything else.
+2. Read `.bridge-kit/tasks.json`.
+3. If `tasks.json` is empty or missing, reply with:
+   <promise>IDLE</promise>
+   and stop.
+4. Pick the **oldest task** (earliest `createdAt`).
+5. Execute the task — see the Execution section below.
+6. After execution, remove that task from the array and write
+   `.bridge-kit/tasks.json` back.
+7. Append a progress entry to `progress.txt` (create if missing).
+8. Update `AGENT.md` with any new reusable learnings discovered this
+   iteration.
+9. Reply normally so the next iteration can pick up the next task.
+
+## Execution
+
+Each task has a single `payload` of type `SliceChangedPayload`:
+
+```
+{
+  event:          "slice:changed"
+  organizationId: string | null
+  boardId:        string
+  sliceId:        string   ← SLICE_BORDER node UUID
+  sliceTitle:     string | null
+  sliceStatus:    string | null   ← e.g. "Planned", "InProgress", "Done"
+  timestamp:      number
+}
+```
+
+Unlike a build-kit agent, a bridge agent reacts to **every** status change
+(including `Planned`) — a task is queued regardless of `sliceStatus`. There
+is no separate "claim and build" step, so don't invoke `/update-slice-status`
+here; translation doesn't take ownership of a slice the way building does.
+
+### Step 1 — Load credentials
+
+Run `/connect` to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from
+`.eventmodelers/config.json`.
+
+### Step 2 — Resolve the bridge target
+
+Read `.bridge-kit/bridge.json`'s `target` field (e.g. `"spec-kitty"`). The
+matching translation skill is named `bridge-<target>-specify`.
+
+### Step 3 — Translate
+
+Invoke the `bridge-<target>-specify` skill. It reads `.slices/` (written by
+`npx @eventmodelers/cli listen`, which must be running separately — see that
+skill's own guardrail if `.slices/` doesn't exist yet) and regenerates that
+framework's spec artifacts **wholesale** from the current board state. Do
+not hand-author or patch those artifacts yourself — if they're wrong, the
+event model is wrong; fix it on the board and let the next slice change
+re-trigger this skill.
+
+Do **not** also invoke `bridge-<target>-tasks` from this loop. That
+companion skill enforces the 1:1 slice-to-work-package mapping during that
+framework's own task-planning phase (e.g. Spec Kitty's
+`/spec-kitty.tasks-outline`) — it's triggered by that framework's own
+tooling when the user reaches that phase, not by every board change.
+
+## Updating tasks.json
+
+After completing a task, remove it from the array and write the updated
+array back to `.bridge-kit/tasks.json`. If the array is now empty, write
+`[]`.
+
+## Progress Report Format
+
+APPEND to `progress.txt` (never replace):
+```
+## [ISO timestamp] — Task [task.id]
+
+Slice: [sliceTitle] ([sliceId])
+Status change: [sliceStatus]
+
+Action taken:
+- [what was translated / regenerated in response to the slice change]
+
+Learnings:
+- [any patterns, gotchas, or reusable knowledge discovered]
+---
+```
+
+## Stop Condition
+
+If `.bridge-kit/tasks.json` is empty (`[]`) or does not exist, reply with:
+<promise>IDLE</promise>
+
+## Updating AGENT.md
+
+After completing a task, add any **reusable** learnings to `AGENT.md` —
+patterns, gotchas, or skill behaviour that future iterations should know.
+Only add things that are general and applicable beyond this single task. Do
+not duplicate what is already there.
+
+## Important
+
+- Process **one task per iteration**.
+- Read `AGENT.md` first — it contains patterns from previous iterations.
+- Always start with `/connect` if credentials are not yet loaded.

package/stacks/bridge/templates/bridge/ralph-claude.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Bridge loop using Claude Code as the executor. Unlike build-kit's
+// ralph-claude.js, there is no onPlannedSlice consumer — a bridge agent
+// doesn't "build" a Planned slice, it just translates every slice change as
+// it arrives via tasks.json (see lib/prompt.md and queueAllStatuses below).
+// Usage: node ralph-claude.js [project_dir]
+
+import { startRalph, loadLocalConfig } from './lib/ralph.js';
+import { spawn } from 'child_process';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const kitDir = dirname(fileURLToPath(import.meta.url));
+const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
+
+const cfg = loadLocalConfig(kitDir);
+const inlineHeader = cfg.boardId
+  ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  : '';
+
+const claudeArgs = ['--dangerously-skip-permissions'];
+if (cfg.model) claudeArgs.push('--model', cfg.model);
+const claudeEnv = cfg.anthropicBaseUrl
+  ? { ...process.env, ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl }
+  : process.env;
+
+function runClaude(prompt) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
+      cwd: projectDir,
+      stdio: 'inherit',
+      env: claudeEnv,
+    });
+    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
+    proc.on('error', reject);
+  });
+}
+
+startRalph({
+  kitDir,
+  projectDir,
+  onTask: runClaude,
+  agentType: 'BRIDGE',
+  queueAllStatuses: true,
+}).catch((err) => {
+  console.error('[ralph] Fatal:', err);
+  process.exit(1);
+});

package/stacks/bridge/templates/bridge/ralph-hook.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Bridge loop that hands each batch of slice changes to an arbitrary external
+// command instead of an AI agent — e.g. commit + push .slices/ and let a CI
+// pipeline take it from there. No Claude/Ollama call happens in this mode.
+//
+// Configure the hook with `bridge --hook "<command>"` (one-off) or persist a
+// default with `init --bridge --target <name> --hook "<command>"`.
+//
+// Usage: node ralph-hook.js [project_dir]
+//        BRIDGE_HOOK_CMD="git add .slices && git commit -m sync && git push" node ralph-hook.js
+
+import { startRalph } from './lib/ralph.js';
+import { spawn } from 'child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const kitDir = dirname(fileURLToPath(import.meta.url));
+const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
+
+// bridge.json (not .eventmodelers/config.json) — a plain, committed sibling
+// file, since target/hookCommand are project policy meant to be shared with
+// every teammate and CI runner, not gitignored per-machine state.
+function loadBridgeConfig() {
+  const p = join(kitDir, 'bridge.json');
+  if (!existsSync(p)) return {};
+  try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return {}; }
+}
+
+const hookCmd = process.env.BRIDGE_HOOK_CMD || loadBridgeConfig().hookCommand;
+if (!hookCmd) {
+  console.error('[bridge-hook] No hook command configured.');
+  console.error('  Set one for this run: eventmodelers bridge --hook "<command>"');
+  console.error('  Or persist a default: eventmodelers init --bridge --target <name> --hook "<command>"');
+  process.exit(1);
+}
+
+const tasksPath = join(kitDir, 'tasks.json');
+
+function readTasks() {
+  try {
+    return JSON.parse(readFileSync(tasksPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+// Batched, not one-task-at-a-time: a hook like "commit + push .slices/" acts
+// on the whole current board export in one shot (already fresh — lib/ralph.js
+// re-syncs .slices/ before every task is queued), not on a single slice's
+// translation the way an AI agent does. Only the tasks present at invocation
+// time are cleared afterward — anything the realtime agent queues *while* the
+// hook is still running is left in place for the next tick, so a slice change
+// arriving mid-run is never silently dropped.
+function runHook() {
+  const batch = readTasks();
+  if (!batch.length) return Promise.resolve();
+
+  const batchFilePath = join(kitDir, 'last-hook-batch.json');
+  mkdirSync(kitDir, { recursive: true });
+  writeFileSync(batchFilePath, JSON.stringify(batch, null, 2));
+
+  const latest = batch[batch.length - 1]?.payload ?? {};
+
+  return new Promise((resolvePromise, reject) => {
+    console.log(`[bridge-hook] Running hook for ${batch.length} change(s): ${hookCmd}`);
+    const proc = spawn(hookCmd, {
+      cwd: projectDir,
+      shell: true,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        BRIDGE_BATCH_FILE: batchFilePath,
+        BRIDGE_TASK_COUNT: String(batch.length),
+        BRIDGE_SLICE_ID: latest.sliceId ?? '',
+        BRIDGE_SLICE_TITLE: latest.sliceTitle ?? '',
+        BRIDGE_SLICE_STATUS: latest.sliceStatus ?? '',
+        BRIDGE_BOARD_ID: latest.boardId ?? '',
+        BRIDGE_ORGANIZATION_ID: latest.organizationId ?? '',
+      },
+    });
+    proc.on('close', (code) => {
+      if (code !== 0) return reject(new Error(`hook exited ${code}`));
+      const handledIds = new Set(batch.map((t) => t.id));
+      const remaining = readTasks().filter((t) => !handledIds.has(t.id));
+      writeFileSync(tasksPath, JSON.stringify(remaining, null, 2), 'utf-8');
+      resolvePromise();
+    });
+    proc.on('error', reject);
+  });
+}
+
+startRalph({
+  kitDir,
+  projectDir,
+  onTask: runHook,
+  // onPlannedSlice omitted — see stacks/bridge/templates/bridge/ralph-claude.js
+  agentType: 'BRIDGE',
+  queueAllStatuses: true,
+}).catch((err) => {
+  console.error('[ralph] Fatal:', err);
+  process.exit(1);
+});

package/stacks/bridge/templates/bridge/ralph-ollama.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Bridge loop using a local Ollama model as the executor. Same caveats as
+// build-kit's ralph-ollama.js — lib/ollama-agent.js is shared as-is (see
+// useShared in cli.js), unmodified for bridge.
+// Run `ollama serve` first.
+// Usage: node ralph-ollama.js [project_dir]
+//        OLLAMA_MODEL=qwen3.5:9b node ralph-ollama.js
+//        OLLAMA_URL=http://host:11434 node ralph-ollama.js
+
+import { startRalph } from './lib/ralph.js';
+import { spawn } from 'child_process';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const kitDir = dirname(fileURLToPath(import.meta.url));
+const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
+const model = process.env.OLLAMA_MODEL || 'qwen3.5:9b';
+
+console.log(`[ralph-ollama] model=${model}`);
+
+function runOllama() {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('node', [join(kitDir, 'lib', 'ollama-agent.js'), model], {
+      cwd: projectDir,
+      stdio: 'inherit',
+      env: process.env,
+    });
+    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`ollama-agent exited ${code}`))));
+    proc.on('error', reject);
+  });
+}
+
+startRalph({
+  kitDir,
+  projectDir,
+  onTask: runOllama,
+  // onPlannedSlice omitted — ollama-agent manages its own task queue
+  agentType: 'BRIDGE',
+  queueAllStatuses: true,
+}).catch((err) => {
+  console.error('[ralph] Fatal:', err);
+  process.exit(1);
+});