crumb

name	crumb
description	>-

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)

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):

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:

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:

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)

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)

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)

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":

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:

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.