crumb

# Crumb — Multi-Agent Game Prototyping Skill (v0.1) Multi-agent collaboration tool for the Bagelcode new-IP team (mobile casual). One natural-language pitch and Planner Lead → Builder → qa_check effect → Verifier (CourtEval) collaborate to ship a Phaser 3.80 multi-file PWA under `artifacts/game/` plus `spec.md` + `DESIGN.md` + `tuning.json`. > **3-layer separation** (`wiki/synthesis/bagelcode-host-harness-decision.md`): > 1. NL interface = Claude Code (this skill's host) — top of the multi-host 4-entry list > 2. NL → backend routing = this SKILL.md + `agents/*.md` sandwiches + 5 procedural skills (`skills/*.md`) > 3. Orchestration control plane = `src/{transcript,reducer,validator,adapter,dispatcher,loop}/` > > **v0.1 highlights** (`wiki/concepts/bagelcode-system-architecture-v0.1.md`): > - Engineering Lead → **builder + verifier actor split** (true cross-provider boundary) > - `--cross-provider` flag → **`--preset <name>`** (named preset, BYO) > - 38 kind → **39 kind** (+`qa.result` deterministic effect) > - scores → **D1-D6 source-of-truth matrix** (reducer-auto / qa-check-effect / verifier-llm — single origin per dim; D3/D5 split into LLM + auto components combined deterministically in code) > - Multi-host 4-entry (Claude Code / Codex CLI / Gemini CLI / headless) + ambient fallback > - MCP Provider (cross-host fan-in) + auth-manager (`crumb doctor`) + persistence boost (`crumb resume`) ## When to trigger NL trigger recognition: - "**60초 매치-3 게임 만들어줘**", "**make a swipe-to-merge game**", "**build a 30s clicker**" — casual game pitches - Explicit command: "**/crumb \<pitch\>**", "**crumb start \<pitch\>**" - Preset intent: "키 없이 돌려봐" → `mock`, "video research" / "YouTube 영상 분석" → `video-research`, "cross-vendor verifier" / "Codex 빌더" → per-actor `--bind` flags (no named cross-3way preset since 2026-05-07; explain the binding override path) - **Mid-flight follow-up** (right after the SessionStart hook surfaces an in-flight session): "지금 어디까지 갔어?", "진행 상황", "이거 끝났어?", "what's the status?" → route to `mcp__crumb__crumb_status` + `mcp__crumb__crumb_suggest` instead of spawning a new session Do NOT activate on: - Code review / debugging / library questions - Non-casual games (3D / FPS / MMO etc. — Phaser single-file fit ❌) - Generic multi-agent system design discussion (refer to `wiki/` only) ## In-flight session branching The Claude Code SessionStart hook (`.claude/hooks/session-start.cjs`) scans `~/.crumb/projects/<id>/sessions/*/meta.json` at startup and injects ULIDs + goals + last kinds for any session with `status ∈ {running, paused}` into the system context. When the user's utterance is ambiguous between a new game pitch and a follow-up: 1. Context has an in-flight ULID AND the user uses "진행" / "상황" / "어디까지" / "끝났어" / "next" vocabulary → respond with `mcp__crumb__crumb_status` + `mcp__crumb__crumb_suggest` (or guide the user to the `/crumb-watch <ulid>` slash command). 2. The user explicitly states a new game pitch → spawn a fresh `mcp__crumb__crumb_run` regardless of existing sessions (concurrent sessions are fine). 3. Otherwise, ask the user once. Additionally, the Stop hook (`.claude/hooks/stop.cjs`) emits one line per turn: `[crumb] <ulid> · <last_kind> · agg=N verdict=X` into the system context — keeps progress visibility inline without requiring the user to ask. ## How to run ### 1. Extract pitch + preset From the user's utterance: - **goal** string — strip `/crumb` prefix, Korean particles, sentence-ending markers like "만들어줘". - **preset** — only use what the user explicitly named. Otherwise ambient (follow the entry host; Crumb does NOT force a default). - Only when the user asks "어떤 preset 있어?" / "추천해줘" → run `crumb doctor` and show the preset list, then defer the choice. - When the user names a preset ("video-research", "mock") → pass it through verbatim. The `cross-3way` named preset was retired 2026-05-07 — if user types it, recommend per-actor `--bind` flags instead (e.g. `--bind builder=codex --bind verifier=gemini-cli:gemini-3.1-pro-preview`). - When user intent ("키 없이 돌려봐") and an explicit name conflict, the explicit name wins. → Core principle: **provider × harness × model is the user's call.** Crumb is a helper, never a default-setter (Anthropic 2026-03 "wrong tradeoff" lesson). ### 2. Start a Crumb session — `mcp__crumb__crumb_run` (preferred) ```ts mcp__crumb__crumb_run({ goal: "<extracted goal>", preset: "<name>" /* optional — pass only when user named one */, // adapter / idle_timeout_ms / label are also optional }) ``` → The MCP tool spawns `crumb run` as a detached subprocess and immediately returns `{ session_id, session_dir, log_path }`. The host CLI is never blocked. Report the session ULID to the user and announce the next step. > **Bash fallback** — for environments where the MCP server is not active (use the installed `crumb` bin or `npx tsx`): > ```bash > crumb run --goal "$GOAL" ${PRESET:+--preset "$PRESET"} > # Or, without npm link: > npx tsx "$CLAUDE_PROJECT_DIR/src/index.ts" run --goal "$GOAL" > ``` > Prefer `mcp__crumb__crumb_run` whenever possible — no permission prompt, one shot. > **Environment doctor** — when the user asks "어떤 preset 가능?" or you suspect the environment is incomplete: > ```bash > npx tsx src/index.ts doctor > ``` > Outputs 4 host entries × adapter health × installed/authenticated preset matrix. **The user picks** — Crumb only surfaces the runnable options. ### 3. Streaming the transcript While the session runs, surface only meaningful events to the user: ```bash tail -f sessions/<ulid>/transcript.jsonl | jq -r ' select(.kind | IN("goal","question.socratic","spec","build","qa.result","judge.score","done","error","handoff.requested")) | "[\(.ts | split("T")[1] | split(".")[0])] \(.from)\t\(.kind)\t\(.body // (.data | tostring) | .[0:120])" ' ``` Skip these kinds: `ack`, `audit`, `tool.call`, `tool.result`, `agent.thought_summary`. Surface these: the 4 sub-steps of `step.judge` (grader/critic/defender/regrader) + `qa.result` (the v0.1 deterministic ground truth). ### 4. User natural-language intervention (mid-flight) While the session runs, user intervention lands on the same transcript line regardless of which of the 5 surfaces is used — routing is source-agnostic (`agents/coordinator.md` Routing Rules). **Preference order** (on top of Claude Code): 1. **`mcp__crumb__crumb_intervene` MCP tool** — direct call from NL. One permission prompt and done. 2. **Slash commands** — `/crumb-approve <ulid>`, `/crumb-veto <ulid> <reason>`, `/crumb-redo <ulid>`, `/crumb-pause <ulid> [@actor]`, `/crumb-resume <ulid> [@actor]`, `/crumb-watch <ulid>`, `/crumb-cancel <ulid>`. Each is a thin wrapper around the MCP tool above. 3. Append directly to `inbox.txt` (headless / other host). 4. `crumb event` CLI — direct JSON event input (low-level). 5. `crumb tui` slash bar (only when the user has a separate terminal open). #### Surface 1 — `mcp__crumb__crumb_intervene` (Claude Code preferred) ```ts mcp__crumb__crumb_intervene({ session: "<ulid>", action: "approve" | "veto" | "pause" | "resume" | "redo" | "goto" | "append" | "note" | "reset_circuit" | "swap" | "free", body?: "<reason or free text>", target_actor?: "builder" | "verifier" | ..., swap_to?: "<adapter>" /* required only when action=swap */, }) ``` → Internally appends one line to `sessions/<ulid>/inbox.txt`. The watcher (500 ms tick) parses it into a transcript event. Grammar matches `src/inbox/parser.ts`. #### Surface 2 — `inbox.txt` (other hosts / fallback) ```bash SESSION_ID="<active ulid>" echo "@builder use red/green palette only" >> sessions/$SESSION_ID/inbox.txt ``` The 500 ms watcher parses each line and appends it to the transcript. This skill should map natural-language user input like "빌더한테 빨강/초록만 쓰라고 해" into the slash-bar grammar above and append to the inbox. #### Surface 3 — TUI slash bar (only when the user has `crumb tui` open) ``` /approve /veto <id> /pause [@<a>] [reason] /resume [@<a>] /goto <a> [body] /swap <from>=<adapter> /reset-circuit <a|all> /append [@<a>] <text> /note <text> /redo [body] /q /quit @<a> <body> (free text mention) ``` The TUI and `inbox.txt` share one grammar (`src/inbox/parser.ts`). Bidirectional muscle-memory compatible. #### Surface 4 — JSON event directly (low-level) ```bash SESSION_ID="<active ulid>" echo '{"from":"user","kind":"user.intervene","body":"<original text>","data":{"target_actor":"builder","sandwich_append":"phaser 3.80 only"}}' \ | CRUMB_TRANSCRIPT_PATH="sessions/$SESSION_ID/transcript.jsonl" \ CRUMB_SESSION_ID="$SESSION_ID" \ CRUMB_SESSION_DIR="sessions/$SESSION_ID" \ crumb event ``` #### `data` field semantics (shared by all 5 user.* events) | `data.<key>` | Effect (reducer handling) | |---|---| | `target_actor: <actor>` | Fact tagged `@<actor>` — surfaced in the next `<actor>` spawn's sandwich (no routing change). | | `goto: <actor>` | `next_speaker = <actor>` forced + immediate spawn (LangGraph `Command(goto)`). | | `swap: { from: <a>, to: <adapter> }` | `progress_ledger.adapter_override[a] = <adapter>` (Paperclip BYO swap). | | `reset_circuit: <a> \| true` | Clears `circuit_breaker[<a>]` (or all when `true`). | | `sandwich_append: <text>` | Adds a fact with `category='sandwich_append'` — the dispatcher concatenates it onto every subsequent matching spawn's system prompt (v0.2.0 G4). | | `actor: <actor>` (only on `user.pause` / `user.resume`) | Pause/resume that single actor instead of the whole session. | > **Frontier mapping**: LangGraph `Command(goto/update={...})` 53/60 + Paperclip BYO swap 38/60 + Codex `APPEND_SYSTEM.md` 38/60. Background: `wiki/synthesis/bagelcode-user-intervention-frontier-2026-05-02.md`. The reducer applies it and updates `progress.next_speaker` (typically falls back to planner-lead and emits `spec.update`; if `data.goto` is set, jumps directly to the named actor). ### 5. Surface the result When `kind=done` arrives: ``` ✅ session complete — sessions/<ulid>/ ▸ artifacts/game/ (multi-file PWA — open game/index.html) ▸ artifacts/spec.md (acceptance criteria + rule book) ▸ artifacts/DESIGN.md (color / mechanics / motion) ▸ artifacts/tuning.json (balance numbers) ▸ transcript.jsonl (replay-deterministic, 40 kind × 11 field × 8 from) ▸ judge.score (D1-D6) (source-of-truth matrix: reducer-auto / qa-check-effect / verifier-llm) ``` If the user says "열어줘" / "play": ```bash open sessions/<ulid>/artifacts/game/index.html ``` ### 6. Resume after an interrupt (v0.1 persistence boost) If the session is Ctrl-C'd or crashes mid-run: ```bash npx tsx src/index.ts resume <session-id> ``` Reads the adapter-native session id (Claude Code `--resume` / Codex `--thread`) from `metadata` and restores host-harness state, preserving `cache_carry_over`. ## Preset options (user choice, Crumb only recommends) `provider × harness × model` is the user's call. Crumb only surfaces what `crumb doctor` says is runnable; it does not force a default. | Preset | Composition | Install / auth required | Use case | |---|---|---|---| | **(no preset)** ambient ★ | Every actor follows the entry host (Claude Code → Opus 4.7) — Crumb does NOT decide bindings | One auth on the entry host | **Recommended default** — strongest model your env offers across every actor. | | **`video-research`** | researcher=gemini-sdk (Gemini 3.1 Pro video Part) / rest=ambient | claude + GEMINI_API_KEY | **Use case — video evidence path**: gameplay clip → mechanic extraction. | | **`mock`** | All actors = mock adapter, deterministic | 0 | **Use case — CI / evaluator env**: works without keys, replay-deterministic | → Detailed preset format: `.crumb/presets/*.toml`. **The user picks**. Crumb does not guess or force.