Bitterblossom

Bitterblossom

Operate the event plane. Do not move workload judgment into the plane.

Bitterblossom is bb: tasks + agents + triggers as files, with a durable run ledger, budgets, retries, dead letters, and optional webhook/cron serving. Agents are CLI users, so prefer stable --json surfaces over prose parsing. When working in the Bitterblossom source checkout, read VISION.md for the runtime-vs-workload boundary before adding or reshaping tasks.

Stance

• Treat bb as runtime and ledger, not an agent brain.
• Workloads are config: plane.toml, agents/<name>.toml, tasks/<name>/task.toml, and tasks/<name>/card.md.
• New workload behavior should be a task/card/agent change, not a Rust branch.
• Use --config <plane> explicitly unless the user has set BB_PLANE_DIR.
• Use --json for agent-readable output. Text is for humans.
• Human-mode bb run prints an early run id and periodic stderr heartbeats; bb run --json stays quiet until it emits the final run bundle.
• If bb is not on PATH, use cargo run --quiet -- from the source repo or ./target/debug/bb after cargo build.

First Probe

Run these before changing or dispatching anything:

bb --config <plane> check
bb --config <plane> task list --json
bb --config <plane> runs list --json

Read the output for:

• loaded tasks and agent versions;
• parked tasks and budget ceilings;
• recent failures, dead letters, in-flight cap kills, and costs;
• whether a task is reflex (webhook/cron) or dispatch (manual).

Authority And Readiness

Classify the run before dispatch. Mode B work belongs in Bitterblossom, but the allowed authority depends on trigger source, auth class, and task policy.

A closeout receipt is incomplete until it names the exact command/surface used, run id or submission id, ledger state, cost/budget status, side effects, artifact reads via MCP or bb artifacts list/read, and residual risk.

Rollout Scorecards

Autonomous task families ship at less than full authority (read-only, report-only, dry-run, PR-only) and climb an authority ladder only on evidence. The single reusable scorecard template and promotion doctrine live in docs/rollout-scorecards.md.

Refuse autonomy expansion from vibes. Do not recommend or take a higher authority action (open a branch/PR, merge, deploy, resolve, unpark) for a task family unless that level's scorecard is green and an operator has approved the promotion. "It has been working" is not evidence; the scorecard is. Green metrics only make the next-level ticket eligible for explicit operator approval; they never flip authority by themselves. Merge, unpark, production mutation, and broad rollout stay operator authority until a scorecard plus an operator decision says otherwise.

Route

Detailed command recipes: references/operator-recipes.md. Authority-promotion rules and per-task scorecards: docs/rollout-scorecards.md.

Dispatch Rules

• A bb run can have external side effects. Do not blindly re-run a successful or executing task.
• Secrets travel through declared env/secrets and stdin plumbing. Never put tokens in argv, task cards, or payload JSON unless the task contract explicitly says the value is non-secret.
• For GitHub-backed runs, prefer GH_TOKEN=$(gh auth token) bb ... over copying tokens into shell history.
• Reflex triggers must use API-auth agents. Subscription-auth agents belong to manual dispatch only.
• The checked-in build task is a manual API-auth OMP/GLM builder lane. Use it for shaped implementation work only; it creates/pushes a branch and report but does not merge or replace the submission gate.
• For uncertain model fit, run a cohort: at least three materially different candidate tasks for the same flow and payload, then the model-eval task. First-class cohorts for build, review, gardener, ci-diagnose, and submission-storm members are listed under docs/model-evals/. Record accepted findings there before promoting a new default.
• A parked task is intentionally blocked. Inspect the reason before unpark.
• Dead letters are pre-execute failures. At/after execute, use operator resolution paths because the run may have side effects.
• Streaming harness usage is metered while the run is executing. If max_cost_per_run_usd is breached, the agent policy chooses kill, quarantine, or log; kill and quarantine must emit notification outbox rows such as run_in_flight_cap_killed.

Submission Storm

Verdict tasks (correctness, security, product, simplification, arbiter, verify) expect a submission payload. Do not call them with an arbitrary repo/rev payload.

Shape:

bb --config <plane> submit open --change <change> --rev <rev> --json
bb --config <plane> run correctness --payload '{"submission":"<submission>"}' --json
bb --config <plane> gate --submission <submission> --json

If a verdict task fails with payload has no 'submission' field, the plane is correct; the invocation was wrong.

If bb gate --json reports a canonical member as run:failure, read that member's safe_next_command. Replays prove the failed pre-execute path can run, but they do not count for the canonical gate key; the safe recovery is a clean replacement submission after fixing the operator or infrastructure issue. The command includes the loaded plane's --config path so an agent can run it from another cwd.

Recovery

• bb recover classifies inherited running rows after a host restart.
• bb recover --json exposes probe_state, probe_reason, lease_disposition, and operator_action; unknown probes retain the host lease.
• bb runs resolve is for awaiting_recovery after side-effect inspection.
• bb status --json marks awaiting_recovery older than one hour as escalate_stale_recovery, with age fields, but the operator still resolves the run only after inspecting side effects.
• bb dlq replay --json mints a new run linked to a pre-execute dead letter and returns the replayed run bundle.
• bb dlq ack <id> --reason <text> --json acknowledges a superseded pre-execute dead letter without replaying it, recording reason + timestamp. Acknowledged DLQs cannot be replayed; bb status --json no longer counts them as open operator work.
• bb preflight <task> | --storm --json checks missing declared secrets, missing policy-bound provider keys, and unspawnable command-harness binaries before dispatch creates run rows.

Serving

bb serve exposes webhook ingress, cron scheduling, the HTML operator view, and read APIs. Do not bind publicly without BB_API_TOKEN; the server refuses non-loopback binds without it.

Useful API mirrors:

• GET /api/tasks
• GET /api/status
• GET /api/runs
• GET /api/runs/<id>
• GET /api/dlq
• GET /api/notify
• GET /api/submissions

MCP (read-only)

bb --config <plane> mcp serve runs a read-only MCP stdio server: JSON-RPC 2.0 over stdin/stdout, no network listener, no external credentials for local-plane inspection. Consume it MCP-first where a host agent supports it; fall back to bb ... --json for anything the MCP tool table does not yet cover. The registered read tools (bb_status, bb_check, bb_tasks, bb_runs_list, bb_runs_show, bb_artifacts_list, bb_artifact_read, bb_dlq_list, bb_preflight, bb_gate) return the same shapes as their CLI/API counterparts — MCP is a typed adapter, not a second implementation.

This slice ships read-only tools only. No mutating MCP tool exists; a tools/call for an unknown or would-be mutating name is rejected with a JSON-RPC -32602 error. Do not expect bb runs cancel, bb dlq replay, bb run, or submission/gate mutations over MCP until a separate writable-MCP backlog lands its graduation signals.

Routing:

Operator Dispatch Loop

Use the ergonomic dispatch surface when the operator wants bb to own a supervised lane instead of running a bare shell:

bb --config <plane> dispatch --repo <path> --brief <file> [--model <slug>] [--label <text>]
bb --config <plane> logs -f <run-id>

dispatch prints only the accepted run id and exits. It chooses the task from BB_DISPATCH_TASK, then dispatch, then build, then a single manual task if that is the only unambiguous option. The brief file is read at dispatch time and persisted into the run payload as bb.dispatch_job.v1 with repo, canonical prompt, optional model, label, and branch_slug; the brief file path itself is not persisted. model, when provided, overrides the selected task agent's model for that run. It does not run synchronously; a running local or deployed plane drains the pending run. logs -f follows ledger events plus released text artifacts until the run reaches a terminal state.

Distribution

The portable artifact is this whole folder: skills/bitterblossom/. Consumers should copy or symlink the folder, not just SKILL.md, so references and agent metadata travel with it.

Harness Kit integration should keep one source of truth. Prefer a source entry, bootstrap projection, or explicit symlink from Harness Kit to this folder over a manual copied skill that can drift. The durable decision is docs/adr/006-skill-projection.md.

Closeout Evidence

When using Bitterblossom, report:

• exact plane path and bb binary used;
• commands run and relevant run ids;
• ledger state, costs, parked/DLQ status, and external side effects;
• generated artifacts, inspected through bb artifacts list/read rather than local path spelunking, plus any API/CLI JSON read;
• residual risk, including failed probes that remain in the ledger.