Agent Guide

Canonical rules for all coding agents. Claude Code loads this via the CLAUDE.md symlink (edit AGENTS.md, never the symlink); Codex reads it directly. Laws only — architecture lives in standards/ARCHITECTURE.md, workflows in skills.

Volume pools

Use exact model and effort pins below. Default orchestrator: Claude Code claude-fable-5-1 medium; every Claude child: claude-opus-5-5 medium; Codex substantive work: gpt-6.1-sol medium. Preserve the lightweight route (gpt-6-luna, ANTHROPIC_DEFAULT_HAIKU_MODEL). Historical provenance and model-parsing fixtures keep the models they recorded. Codex CLI pin: --model gpt-6.1-sol -c 'model_reasoning_effort="medium"'; the Codex plugin uses --model gpt-6.1-sol --effort medium.

Before launching a provider, load agent-pools.md for its CLI recipe, quota floor, sandbox and credential constraints. Do not use model aliases, fast variants or silent same-provider substitutions.

• Fallback is allowed only for confirmed quota, availability or unsupported-model failures. Codex: approved Sol route → Cursor claude-opus-5-5-medium → Grok grok-4.7 medium. Claude: Opus → approved Sol route → the same Cursor → Grok. Direct Claude is not a Codex fallback. Code failures and unfavorable reviews require remediation on the current route.
• Use existing subscriptions and authorized billing only: no purchases, overages, credit top-ups or new paid endpoints. Report blockers when the chain is exhausted.
• The originating orchestrator owns cross-provider launches. Cursor, Grok and Junie workers do not delegate onward; native same-provider children retain their pins, bounded ownership and evidence requirements. A fallback retains reviewer separation, existing findings and the same acceptance gates.
• Delegated children run unsupervised (operator 2026-11-08, R12): Claude children in bypassPermissions, T3 delegate_task with runtimeMode: "full-access", and the per-CLI equivalents in the runbook's "Child permission mode". T3 rejects a child above its parent, so orchestrators and linked T3 environments open in Full access. Cursor's sandbox, D11, D21 and the money escalation still hold. A child that raises approvals is a route defect: stop and fix the route, never approve command by command.
• A named review.panel is three independent sessions: Astra, Fable and Grok at xhigh, with launch argv retained as effort evidence. The panel is used only when assigned. Muse is opt-in and never a fallback. Junie is the preferred bounded volume route while bun run beep accounts shows remaining JetBrains credits; it is not a fallback. Cursor and Junie receive no out-of-repo corpus, client documents or secrets (D11); preserve Cursor's sandbox and git/sudo/pkexec denials (D21). Do not work around a failing sandbox by disabling it.
• bun run beep models check verifies native and repository pins. The interactive Codex picker changes its config; leave it on the configured Sol default. Do not set CLAUDE_CODE_SUBAGENT_MODEL in proxy wrappers. Agent source changes are left for their owning lane to validate and commit.

The tool-owned projection below keeps this checkout self-contained for cloud and non-Claude agents. Operational detail belongs in the runbook, not this always-loaded file. Rulings and amendments: goals/agent-pool-doctrine/history/.

superseded: gpt-5.6-sol, gpt-6-sol, grok-4.6, gpt-5.6-luna, claude-opus-5, claude-opus-5-thinking-high, muse-spark-1.3, grok-4.5, gpt-5.4, gpt-5.4-mini

1Password

• Agents resolve op from PATH, never the system binary by absolute path. On managed workstations the user-local shim loads exactly one automation credential (a service account by default, the local Connect server with OP_AGENT_BACKEND=connect), disables desktop unlock, and exits 78 when no agent credential exists. Desktop-app integration, op signin, and desktop MCP approval loops are human paths: never retry them and never ask the operator to unlock 1Password to make an agent operation succeed.
• On any 1Password failure run op-doctor once and act on its count/type/mode-only output; report the failing line and stop if the secret operation still cannot proceed. Agent-side failure never proves the desktop app or the operator shell is signed out.
• For a pre-existing op://-backed env file, test the exact operation with output suppressed: op run --env-file=<path> -- true >/dev/null, then use that same lane-scoped wrapper for the real command. Size fan-outs against the live service-account quota (1,000 reads per hour per token; name-based references cost three reads) or run them on the Connect backend.
• Never copy, print, or inject OP_* values, resolved secrets, or raw item JSON; send verification reads to /dev/null or reduce them to counts.
• The 1Password MCP server is the desktop Environments MCP: it cannot return secrets and is not an agent secret path. MCP tools are fixed when a session starts; do not respond to a missing MCP tool by asking the operator to unlock 1Password or run op signin.

Sensitive human input

When an authorized task needs sensitive human text (password, OTP, recovery code, token), use the plasma-sensitive-entry skill before collecting it. Its masked Plasma dialog delivers the value directly to the authorized consumer; never request or expose it through chat, question tools, terminal input, logs, arguments or files. Missing secure GUI delivery blocks collection. Canonical local YubiKey privilege wrappers, remote authentication wrappers and the agent 1Password lane take precedence; a dialog never replaces those routes.

Code Laws

• Use schema-first domain models; prefer typed errors and tagged unions.
• Prefer effect helper modules (String, Equal, ...) over native helpers; import every Effect module from its current effect/<Module> path (.patterns/effect-module-paths.md). Import pipe, flow, and identity from effect/Function. Do not import from the root effect barrel or nested barrels such as effect/cli and effect/http in code, JSDoc examples, or Markdown code blocks; use dedicated public leaves.
• Use every module and feature Effect ships, @stability unstable ones included: the tag means the API may change on a bump, not that it is unfit for production. Never hand-roll what an Effect module provides (e.g. effect/Graph algorithms) because of the tag.
• Prefer match helpers over conditional chains; prefer service composition over global state; keep service boundaries explicit.
• Prefer the tersest equivalent helper form when behavior is unchanged: direct helper refs over trivial lambdas, flow(...) over passthrough pipe(...) callbacks, shared thunks already in scope.
• Prefer named schema building blocks, derived S.is(...) guards, and named LiteralKit internal domains over ad-hoc predicate helpers; S.Literals for anonymous inline unions never referenced by name. Do not add as const to inline arrays passed to LiteralKit(...) — it uses const type parameters already.
• Apply schema defaults when safe. Keep changes focused and testable.
• JSDoc on exported symbols uses titled **Example** (Title) and **Details**/**Gotchas** prose sections — never @example or @remarks tags. Law: .patterns/jsdoc-documentation.md.
• In packages/**/test/**/*.{ts,tsx}, import package source through @beep/* aliases instead of relative paths into any workspace src/; relatives only for local helpers, fixtures, snapshots, and other non-src test files.
• .claude/skills/<name>/SKILL.md frontmatter follows the Agent Skills specification (agentskills.io): name, description, license, compatibility, metadata, allowed-tools, plus Claude Code's native keys. Repo extras such as version and status go under metadata; keep SKILL.md under 500 lines and move depth into references/. bun run beep skills update --check enforces the keys and advises on length.

Autonomy

Operator charter (2026-10-06): agents decide and keep moving; the operator is needed only for the escalation list below.

• Escalate only money: purchases, new paid services or endpoints, quota top-ups, plan changes. Everything else is agent-decided: record the call, its reason and how to reverse it as a decision file (bun run beep goals decisions add <slug> --title "..." --reversal "...", one file per decision under goals/<slug>/decisions/; --kind checkpoint for PLAN.md status notes), then continue. Never append to the tail of SPEC.md's Decision log or PLAN.md: the generated blocks are projections and sibling lanes appending to one tail conflict on merge. The operator reviews asynchronously and never blocks progress.
• Irreversible changes still need a safety net, not a person: land the reversal path (tested down-migration, backup of deleted state) before the change merges, and ship a breaking public API or schema change with a major changeset.
• A started goal runs to completed-retained: finish a phase and start the next, through closeout and the reflection. Do not stop at a phase boundary to ask permission.
• Agents merge their own PRs once mergeable (see Quality Operator). An orchestrator session may merge any PR that meets the same gate. A draft is flipped by its owner, or by the orchestrator only after the owner calls it final; nobody un-drafts and merges in one step. Whoever merges re-reads the review threads immediately before merging: a failed or rate-limited thread read is unknown, never zero.
• Fix findings where they are found (operator 2026-10-24): every actionable review finding, any severity and any round, and every defect observed while working is fixed in the current PR before it merges; a defect outside the PR's files gets a small PR opened the same hour. Never file a "tracked follow-up" issue to defer fixable work. File an issue only for work blocked on the operator, on elapsed time or on money, or for a deferral the operator explicitly authorized (such as an S11 merge over reds with one batch fix PR). A finding judged wrong is answered with the reason and resolved; that is not a deferral. Batch each round's fixes into one push.
• Inherited reds: attribute first, fix them once on main (one small PR) and tell dependent lanes to merge main once; do not copy the fix into each lane. The orchestrator declares one consolidated unblocker per red episode (unblocks-main label) and cancels runs, running ones included, on PRs that must re-run anyway so the unblocker gets runners and merges first.
• A base-conflict P0 inbox row is an unconditional "merge origin/main into the lane now" for the lane owner, whatever the acceptance or merge arrangement says; no brief or delegation model may forbid a lane from merging main. A goal packet has at most three concurrently open PRs (a fourth is sequenced through one lane or stacked), and the gate merges finals one at a time as they arrive, telling the remaining siblings to merge main between merges (operator 2026-11-05, goals/agent-pool-doctrine/history/2026-11-05-base-conflict-merge-main.md).
• One orchestrator session coordinates the rest: it routes threads, reds and conflicts to the owning session, merges at the gate, and relays the operator's answers. Sessions report blockers to it, not to the operator. The role is held, run and handed over by the orchestrate skill (register, HANDOFF.md, yeet merge-gate); bun run beep session open names the holder. Cross-session and cross-provider messaging runs only through T3 Code's MCP tools (t3_thread_send, t3_thread_wait, t3_thread_read, delegate_task, t3_thread_launch, schedule_task; environmentId for a linked host). The repo ships no mailbox, relay or dispatcher of its own; a message never moves ownership, model pins or Yeet authority.

Discovery & Reuse

• Before recreating a shared helper, schema, utility, model, or known symbol, search live source (packages/**/src/**) and package barrels (**/src/index.ts) first with targeted ripgrep.
• bun run beep create-package is the only way to bootstrap a workspace package or app. Never mkdir one, copy a sibling, or hand-write its manifest: the command emits the generated scripts block, tsconfig overlays, identity registration, and the per-package turbo.json that a noEmit build (tsrs -p tsconfig.check.json) needs so Turbo stops warning "no output files found". bun run beep lint package-scripts rejects a package missing that override; repair it with the command, not by hand.

Quality Operator

• Every workspace manifest's scripts block is generated: run bun run beep lint package-scripts --write instead of hand-editing task-facing keys.
• Quality lane ids name the command they run (quality:fallow, lint:schema-first); the tier is GithubCheckLaneSpec.tier, never an id prefix, and the step label is the log prefix (TTC ruling 28).
• Yeet is the canonical repo-quality path: bun run beep yeet repair, ... publish --message "...", ... job wait <id>, ... ready. publish gates the push on cheap-gates and the head-install preflight only, opens a draft PR labelled ready-for-heavy, and submits the detached readiness monitor; hosted CI is the authoritative proof and yeet verify is on-demand. Never wait on a queued local full proof to publish. One push per fully addressed wave, never per file or comment (push-first-publish D1–D11).
• When local compute is constrained (operator 2026-10-24), push straight to hosted CI instead of queueing: if scheduler admission or a local gate has waited 10 minutes, stop that local run, keep the package-scoped checks that already passed (quality package-verify, or lint and check of the touched packages), and run bun run beep yeet open --body-file <md> on the committed HEAD. It pushes and opens the draft with ready-for-heavy, the provenance footer and the readiness monitor, and runs no local gate. Flip it with bun run beep yeet ready at content-final as usual. Hosted CI is the proof; the body file records which local checks ran and which were skipped. Never open a PR with raw gh pr create or replace a body with gh pr edit --body*: both drop the Yeet provenance footer. Use bun run beep yeet gh pr body <n> --body-file <md>, which keeps it.
• Draft means only "the owner is still pushing". "Final" means the pushed head passed bun run beep yeet final-check: the scoped local replay of every hosted gate the cheap tier skips (Lint Policy, Lint, Effect Diagnostics, Check, Docgen, Repo Sanity, Fallow, Coverage, and test expectations rewritten to match new output). Flip the PR ready with bun run beep yeet ready, which refuses without that head's passing receipt; do not wait for hosted heavy CI, which doubles as the review window. A gate parked by constrained compute is skipped only with --skip <gate>=<reason>, named in the PR body.
• Heavy admitted work and detached proofs run under systemd (agent-run-<ticket>.scope, beep-proof-<jobId>.service): use --detach plus yeet job wait <jobId> for a proof that may outlive the repair loop. Mechanics: yeet skill, references/detached-jobs.md.
• main is PR-only. Do not commit saving/wip/tmp checkpoints to shared branches; publish from a feature branch through Yeet and let hosted required checks gate the merge. GitHub merge/squash commit messages are also server-side commitlint input; keep body lines wrapped under 100 characters.
• Docgen: bun run docgen:local for edit loops (bounded to origin/main...HEAD + dirty files); full bun run docgen only for the repo-wide proof.
• Attribute verification failures before repairing — introduced / inherited / unrelated / environment-only; attribution decides fix vs rebase vs report, not blind rerun.
• Read a completed red job's log at once through the REST logs endpoint; never wait for the run to finish. Commands: yeet skill, references/gh-rest.md.

• “Mergeable” describes the complete PR state, not GitHub's structural MERGEABLE field alone. It requires all of the following:

  • no outstanding review thread — one that is unresolved, or one the author resolved that carries a later human reviewer comment the author has not answered; a bot acknowledgement after the author resolved the thread and review-body nitpicks are advisory, and outdated threads still count until they are explicitly resolved;
  • no failing CI jobs except Vercel deployments failing only because they were rate limited;
  • the squash commit message GitHub will write passes the repo's commitlint (yeet merge-gate predicts it and holds squash-commitlint otherwise; yeet ready warns): GitHub squash messages are server-side commitlint input and bullet every commit subject as * <subject>, so keep commit subjects at 98 characters or fewer, and the PR title (the first commit subject by default) at 100 minus the (#n) suffix, about 92 for a four-digit PR, because the header is <title> (#n); and
  • the review window has elapsed: at least 20 minutes (BEEP_YEET_REVIEW_WINDOW) since the later of the latest "marked ready for review" event and the latest push to the head. No reviewer has to post (review bots never gate); a window that cannot be read is unknown, never elapsed. The one exception is the beep-reviewer check, and only while main's ruleset requires it; beep reviewer ruleset release|require --apply switches it off and on (docs/ops/beep-reviewer-app.md).

  S11 exception (operator 2026-10-09, standing repo-wide since 2026-10-13): a PR whose owner called final may merge over failing jobs, required ones included, when the thread and window conditions hold and it has no base conflict; record each red with its attribution. Every required red that reaches main gets a named owner and a fix PR the same working day.

• PR closeout: flip the PR ready at content-final, then run bun run beep yeet monitor --until-ready --detach and block on bun run beep yeet job wait <jobId> until it prints merge-ready: yes; exit 2 is a wave of inbox rows to act on. Unanswered review threads are a hard merge gate: answer and resolve every actionable one via bun run beep yeet reply; never ask the operator to relay them. Mechanics: yeet skill, references/monitor-and-inbox.md.
• Post-merge closeout is the agent's job: once the PR is MERGED, retire the lane from inside it with bun run beep yeet sweep --retire. Preserve other live checkouts, never bypass a holder refusal, and refresh affected systemd timers yourself. Mechanics: yeet skill, references/sweep-retire.md.
• Package handoff: any agent or sub-agent that edits a workspace package runs bun run beep quality package-verify <@beep/package> before handing the work back. Use --quick only when the touched surface justifies the lint+check subset. The default runs the package audit and docgen; failures arm the same checkout P0 inbox used by Yeet.
• Full git checkouts and tool clones never go under /tmp (tmpfs is zram-backed memory): agent worktrees belong in the sibling -worktrees root, disposable installs under ~/.cache/beep/. beep quality tmpfs-reap is the janitor; retire a lane with bun run beep worktree remove <name> --archive [--delete-branch] (sibling root or the clone's .claude/worktrees/<name>; its archive fence grants the same invoker and CLAUDE_PID session exemption as --retire, so a desktop session removes its own lane), or from inside it after the merge with bun run beep yeet sweep --retire.

Touch → Skill / Command

If you touch this, load or run this first. Do not hand-author around it.

Dev Servers

• Dev servers run only through the portless-wrapped package scripts (http://<name>.beep.localhost:1355). Never launch raw vite/next/ storybook dev or test numeric localhost ports; PORTLESS=0 is diagnostic-only.

Cloud Environments

• Vendor cloud VMs (Claude cloud sessions, Codex cloud, Cursor Cloud Agents) bootstrap only through scripts/cloud/bootstrap.sh; .cursor/install.sh and every per-account dashboard setup script are one-line callers of it. Never hand-build a toolchain in a vendor dashboard. Per-vendor paste text, allowlists, and gotchas: docs/runbooks/cloud-environments.md.
• Claude and Codex environments are per account with no API: anything a cloud lane needs must be committed under .claude/ or .codex/; user-level settings, enabledPlugins, and user MCP never reach the VM.

Docs & Knowledge

• docs/ is tracked authored documentation (docs/README.md has the layout); docs/_internal/ is private and must never be committed — this repo is public.
• Top-level research/ is the nightly research routine's machine-generated intel surface (laws in research/README.md): packets are immutable, truth is per-packet claims.jsonl + single-writer research/ledger/, and the machine proposes via SUGGESTED_ACTIONS.md — agents never auto-append to explorations/INBOX.md or goals/ from research output.
• Goal closeout is two PRs: the final PR lands the work, the reflection and proposedCloseout (status stays active or paused); after it merges, goals completion refresh --slug <slug> verifies it and goals set-status <slug> <status> adopts it in a packet-state PR that also rewrites the packet's status prose (README, statusNote). A goal is done only once that PR merges and origin/main's manifest has closeout.status == initiative.status; goals doctor reports a verified, unadopted proposal as closeout-adoption-pending.
• Friction is a first-class output: when work is slower, harder, or riskier than it should be, record a receipt — what you were doing, the evidence (command, error text, PR/file), what would have prevented it — in the active packet's ledger (research/OPPORTUNITIES.md) at the moment it happens, never saved for closeout. This repo is public: before recording, redact secrets/tokens/credentials, replace absolute home paths with ~, drop session/machine ids, and quote only the minimal identifying error text.

Agent Memory

• File memory is the memory layer: each agent's own durable files plus repo docs. There is no shared external memory service; do not reintroduce one or wire another code index without a new decision in standards/memory-architecture/04-decision-log.md.
• If context is missing, fall back to repo-local docs, code search, and this file.

Tool Routing

• effect v3↔v4 differences: validate against the Effect reference checkout (.repos/effect, the Effect child at $HOME/YeeBois/references/effect/effect), never training-data priors. bun run beep refs provision provisions the workspace from packages/tooling/policy-pack/repo-configs/data/references.json; BEEP_REFERENCES_ROOT overrides its $HOME/YeeBois/references/effect root. beep refs plan and beep refs install-timer --refresh are agent-permitted; beep refs refresh and a fresh beep refs install-timer are operator-only.
• shadcn: editor app = app workspace, shared UI package = shared base; prefer the shadcn skill + shadcn MCP for registry discovery and installs.
• UI motion evidence comes from bun run beep qa artifacts. There is no QA MCP server; the chrome-devtools MCP is slim and default-disabled, for perf-trace/computed-style introspection during QA sessions.
• Codex Cloud security findings: export the CSV from the signed-in findings view, then bun run beep codex findings ingest --from <export.csv>; prefer the codex-findings skill. Never hand-build the packet.

Context Economy

• Keep the MCP/tool surface stable within a session; settle .mcp.json and enabled tools before working, not mid-task.
• Always-loaded files (this file, skill frontmatter, settings) are the prompt cache prefix: batch edits to them, keep them lean; durable cross-session knowledge belongs in file-memory, not here.
• Continue related follow-ups on an existing subagent (SendMessage) instead of spawning fresh ones.
• Durable on-disk handoffs: agent/session transitions exchange deliverables as files on disk (packet research/, scratchpad), never chat-only summaries.

Guided Closeout

• Every stopping point ends with a structured prompt, never a prose list of options: task done, blocked on the operator, PR merge-ready, post-merge closeout, and before yielding on any question. Claude Code calls AskUserQuestion; Codex calls request_user_input. Give 2-4 concrete next steps, the recommended one first and labelled "(Recommended)", always including a "stop here" option, with a one-line state summary (clone, lane, PR, what landed) in the question itself. Keep the prose recap above it short; the operator reads the prompt, not the essay. Workflow and option shapes: the closeout skill.
• Direction-setting decisions go through /grill-with-docs first; the closeout prompt then carries the frontier's remaining questions.
• Before the prompt, write the ledger row: bun run beep session note --state <open|blocked|done> --next "<one line>" [--summary "<one line>"] [--pr <n>]. It appends to the workstation ledger (~/.local/state/beep/sessions/<repo>.jsonl), shared by every clone and lane; a later note for the same checkout supersedes, and yeet sweep / yeet sweep --retire write the done row themselves. At session start, read bun run beep session open (the Claude SessionStart hook prints it; Codex runs it) and offer the live rows as resume options.