@eventmodelers/cli 1.0.163 → 2.0.2

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

@@ -1,47 +0,0 @@
-# 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 --local-ai`
-  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

@@ -1,111 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-#!/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) => {
-    // Prompt on stdin, not as a `-p` argument — Windows cuts a multi-line argv entry at its first newline.
-    const proc = spawn('claude', [...claudeArgs, '-p'], {
-      cwd: projectDir,
-      stdio: ['pipe', 'inherit', 'inherit'],
-      env: claudeEnv,
-    });
-    proc.stdin.end(inlineHeader + prompt);
-    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

@@ -1,103 +0,0 @@
-#!/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-local-ai.js

@@ -1,43 +0,0 @@
-#!/usr/bin/env node
-// Bridge loop using a local AI model as the executor. Same caveats as
-// build-kit's ralph-local-ai.js — lib/local-ai-agent.js is shared as-is (see
-// useShared in cli.js), unmodified for bridge.
-// Backend is selected by dialect, not by a separate runner: Ollama (native
-// /api/chat) or any OpenAI-compatible server (vLLM, LM Studio, llama.cpp, TGI).
-//
-// Usage: node ralph-local-ai.js [project_dir]
-//        LOCAL_AI_TARGET=ollama node ralph-local-ai.js          # run `ollama serve` first
-//        LOCAL_AI_TARGET=vllm  node ralph-local-ai.js
-//        LOCAL_AI_URL=http://gpu-box:8000/v1 LOCAL_AI_MODEL=Qwen/Qwen3-8B node ralph-local-ai.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, '..');
-
-
-function runLocalAi() {
-  return new Promise((resolve, reject) => {
-    const proc = spawn('node', [join(kitDir, 'lib', 'local-ai-agent.js')], {
-      cwd: projectDir,
-      stdio: 'inherit',
-      env: process.env,
-    });
-    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`local-ai-agent exited ${code}`))));
-    proc.on('error', reject);
-  });
-}
-
-startRalph({
-  kitDir,
-  projectDir,
-  onTask: runLocalAi,
-  // onPlannedSlice omitted — local-ai-agent manages its own task queue
-  agentType: 'BRIDGE',
-  queueAllStatuses: true,
-}).catch((err) => {
-  console.error('[ralph] Fatal:', err);
-  process.exit(1);
-});

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

@@ -1,90 +0,0 @@
-#!/usr/bin/env node
-// Bridge loop that hands each batch of slice changes to a deterministic JS
-// adapter instead of an AI agent or an arbitrary shell hook — no LLM call
-// happens in this mode. Which adapter runs is picked by bridge.json's target
-// (adapters/<target>-adapter.js); if the installed target has no adapter file
-// yet, this exits with a clear error rather than silently doing nothing.
-//
-// Usage: node ralph-static.js [project_dir]
-
-import { startRalph, loadLocalConfig, fetchPlatformConfig } from './lib/ralph.js';
-import { existsSync, readFileSync } from 'fs';
-import { dirname, join, resolve } from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
-
-const kitDir = dirname(fileURLToPath(import.meta.url));
-const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
-
-function loadBridgeConfig() {
-  const p = join(kitDir, 'bridge.json');
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, 'utf-8'));
-  } catch {
-    return {};
-  }
-}
-
-const target = loadBridgeConfig().target;
-if (!target) {
-  console.error('[bridge-static] No target configured in bridge.json — run `eventmodelers init --bridge --target <name>` first.');
-  process.exit(1);
-}
-
-const adapterPath = join(kitDir, 'adapters', `${target}-adapter.js`);
-if (!existsSync(adapterPath)) {
-  console.error(`[bridge-static] No static adapter for target "${target}" (expected ${adapterPath}).`);
-  console.error('  Use the default Claude runner for this target instead: `eventmodelers bridge`.');
-  process.exit(1);
-}
-
-const local = loadLocalConfig(kitDir);
-
-// The adapter itself doesn't know about the bridge loop's .slices/ convention
-// (fetch --spec-kitty calls the same run() with a context name of its own) —
-// this is the one place that convention still applies, so resolve it here.
-function readCurrentContext() {
-  const ctxPath = join(kitDir, '.slices', 'current_context.json');
-  if (!existsSync(ctxPath)) return null;
-  try {
-    return JSON.parse(readFileSync(ctxPath, 'utf-8')).name || null;
-  } catch {
-    return null;
-  }
-}
-
-async function runAdapter() {
-  const contextName = readCurrentContext();
-  if (!contextName) {
-    console.log('[bridge-static] No .slices/current_context.json yet — waiting for the first board sync.');
-    return;
-  }
-
-  const { run } = await import(pathToFileURL(adapterPath).href);
-  const cfg = await fetchPlatformConfig(local);
-  try {
-    await run({ cfg, projectDir, contextName });
-  } catch (err) {
-    // lib/ralph.js retries any onTask failure after 60s forever — right for
-    // transient errors (network blips, a slow spec-kitty command), wrong for
-    // a missing one-time setup step that retrying can never fix on its own.
-    // Adapters flag those with `err.fatal` so we stop instead of looping.
-    if (err.fatal) {
-      console.error(`[bridge-static] ${err.message}`);
-      process.exit(1);
-    }
-    throw err;
-  }
-}
-
-startRalph({
-  kitDir,
-  projectDir,
-  onTask: runAdapter,
-  // onPlannedSlice omitted — see ralph-claude.js in this same directory.
-  agentType: 'BRIDGE',
-  queueAllStatuses: true,
-}).catch((err) => {
-  console.error('[ralph] Fatal:', err);
-  process.exit(1);
-});