Host contract

Graphs name primitives. This file maps them onto the harness in front of you. If a node mentions a primitive, do that mapping here. Do not copy harness APIs into GRAPH.md.

In this repo, skills live under skills/<name>/. After install they are siblings (bulma-qa next to bulma-bus and kevin). Resolve a skill by name via the host skill loader, or by the relative path in git. Never hardcode ~/.agents/skills, ~/.grok, ~/.claude, or ~/.codex.

Primitives

Review model identity

For review attribution, read the executing session's model identity from host runtime metadata or explicit system-provided identity. Keep the reported model name or id, including its version. Do not infer it from the host name, a default in config, a requested worker tier, or a parent's model. If only a family or alias is exposed, keep that value without adding a version. If no identity is exposed, return unknown. This lookup does not select or change a model.

Each review worker resolves its own model and actual effort from runtime metadata or explicit system settings, else unknown per field. Never infer effort from requested tiers, defaults or parents. A critic does not replace the verdict reviewer. PR creation follows PR run attribution.

spawn_worker

Pass, and nothing else, in this order:

1. the node file as the contract
2. “do not spawn graph types”, never merge
3. job id
4. worktree path (or “host worktree”)
5. the ticket, finding, or PR this node is for (full text, not “read STATE”)
6. a file/path whitelist, plus 20–40 line excerpts if a snippet is required

Fixed text first, per-unit text last. Every provider Bulma runs on caches the prompt prefix, so two workers of the same node share the cached part only up to the first byte that differs. A job id or ticket at the top makes every spawn a cold read of the node file.

The child loads the node and any skill that node names.

Do not pass GRAPH.md, the parent skill tree, the parent MCP/tool catalog, how, or the session history. Isolation is a short prompt, not a copy of this thread.

Prefer host isolation worktree when the spawn API has it. Then do not also pass cwd.

Worktree

Prefer host isolation, then Orca, then the Git fallback. Resolve its root through bulma-memory, default $BULMA_HOME/workspaces. For Orca, read orca skills get orca-cli using the session's selected executable; check orca status --json and confirm flags and target repo in that guide. Keep host-created paths and returned ids. Do not launch an agent just to create a checkout. Check whether failed creation left a checkout before retrying. Raw Git does not register with Orca.

Worker tier

session_model is the default for every worker. Only the /bulma overlay may run a worker on another model or effort (../bulma/DISPATCH.md); the user maps the tiers in $BULMA_HOME/bulma.json. What each host can apply per call (checked 2026-09):

Never spawn_worker with types bulma_developer / bulma_qa / bulma_triage / bulma_reviewer / bulma_lstm. Those are load_graph on the main thread.

Fd workers (bulma-fd-coder, bulma-fd-tester, …) may be the child type when the host registered them. If it did not, use general-purpose and paste the node file into the prompt.

worker_usage

The token total for one finished worker, read from what the host returned for it. /bulma passes it to dispatch result --tokens (../bulma/DISPATCH.md) so cost per tier is measured, not guessed. Add the totals of every round of the same unit.

If the host shows no number, omit --tokens. Do not count characters, do not derive tokens from duration, and do not report the parent session's usage for a worker. A missing count is honest; a guessed one corrupts the tier comparison.

schedule_wake

Used by bulma-goal and bulma-code-review wait_ci. Interval 5m. One wake per PR. Store the host's id in STATE as loop_id.

The wake prompt is in the skill's LOOP.md. It must load_skill by name, not by an absolute home path.

Second opinion

One read-only critic on another vendor's model, through its CLI. Opt-in via memory second_opinion:. Calls and rules: SECOND_OPINION.md.

Optional MCP

Some nodes read better context when an MCP server happens to be installed. None of them require it. A graph names the capability; this table maps it, and every row degrades to the fallback rather than blocking.

When the git toplevel has .codegraph/ or .tokensave/, this capability is required for discovery. Query the graph before a Grep/Read loop. Do not spawn an extra explorer worker. Grep/Read of whole files is the fallback when the index is missing or the query misses.

Tools may be deferred: absent from the initial function list until a tool search selects them. Try the search before concluding a capability is missing.

A missing optional capability is never mcp_gate: failed. That flag means a detected, critical source is unreachable, such as a ticket URL the goal depends on. See MCP_CONTEXT.md.

Starting graphs

Codex reserves slash input for built-in commands. Never tell a Codex user to run /bulma-*; the parser rejects it before skill routing.

Short command aliases (Grok / Claude, via commands/): /developer, /reviewer, /lstm, /qa, /memory. Same skill. Skill folder names stay bulma-*. /memory is bulma-memory (lib), not a graph.

Disk

$BULMA_ROOT is host-neutral. See skills/bulma-bus/DISK.md. Claude, Codex, Grok, and Cursor on one machine share that tree.

Quality rubric

bulma-fd-quality loads bundled thermo-nuclear-code-quality-review in deep mode only. Follow quality.md for depth and ordering. Focused quality reuses the coder; independent review and tester always follow.

Product policy

Reviewers, assignee, sibling repos, test command, tracker, design system: PRODUCT.md plus the current repo (AGENTS.md, CLAUDE.md, CONTRIBUTING) plus bulma-memory (confirmed reviewers, chat language). Do not bake a company's GitHub handles or repo names into a graph node.

Trail Code context

Trail Code (@trailhq/trail-code, formerly graft) provides code maps and team memory. It is distinct from the log-capture tool also named Trail. Never infer capabilities from the binary name. Use the CLI's help or exposed MCP schema.

When .codegraph/ exists, CodeGraph remains the first discovery source. Otherwise, when graft/ or .trail/cache/ exists, query Trail Code before a grep/read loop:

python3 scripts/code-context.py --repo "$WORKTREE" --query "<symbols or question>" --limit 6

The adapter checks freshness and returns inline source with locations. Missing, stale or unsupported maps return status=fallback and exit 3; use targeted source reads instead. Do not initialize a map automatically. Refresh an existing map only when authorized, with trail build --no-gitignore --no-ignore "$WORKTREE". Do not run paid/deep build, --name analysis, team-memory writes or upgrades as part of ordinary discovery. Worktree maps must describe that worktree's revision.

For impact analysis on a fresh map, trail blast --base "$BASE" --format json --no-refresh "$WORKTREE" supplies dependent symbols. It supports the bundled blast-radius investigation; it does not replace behavioral proof. trail check may provide learned constraints, but its suggestions never override repo policy or gate correctness by themselves. No automatic note publication.

Runtime evidence

Tester and diagnose use PERFORMANCE.md. Project recipes use VERIFICATION.md, loaded only when needed. Pass session IDs, evidence paths and relevant errors. Never invent token usage. Load only the current node contract and its required references. Cache static contracts within a session; reload when their file content changes.