Working in this monorepo

Where to work

Use the guidance for the area you are changing:

Work safely in this checkout

Boxes live outside this repo at ~/src/boxes/ so they do not inherit dev-repo instructions. The primary test box is ~/src/boxes/test1/; each managed worktree has an isolated clone at ~/src/box-worktrees/<name>/test1/. Read box work before running anything against a box or production.

When asked to spin off work, use launch-worktree-session. Managed worktrees live at ~/src/beebox-worktrees/<name>/ on worktree-<name> branches. Repository hooks own cleanup; do not use native claude --worktree for this workflow.

One shared dev router serves every checkout at http://localhost:3210/<main|worktree>/<box>/.... Use the worktree's short name, without the branch's worktree- prefix. HTTP requests wake idle worktrees; WebSockets do not. Do not restart or panic the shared router from a worktree without asking the boxholder. Lifecycle details: bin/AGENTS.md.

Never search the whole home directory (find ~, grep -r ~, rg ~). It walks iCloud Drive, Photos, Music, and Calendars and raises macOS privacy prompts. Search the specific directory, or ask where a file lives.

Use browse and bin/browse for browser work; /-leading paths resolve in this worktree. Tracked HTML and Markdown in dev/ are served at /<worktree>/dev/; the repository doc browser is at /<worktree>/dev/docs/. See dev/README.md.

For recurring work or missed scheduled runs, use bbx-authoring-schedules. bin/schedules list shows the catalog, last runs, and overdue work; bin/AGENTS.md covers scheduling mechanics.

How much to do

The human's wording sets the ceiling; when it is unclear, take the lowest level the wording supports and say which you took.

A bare "go ahead" after a proposal means do for that proposal. Destructive or outward-facing actions (deleting data, pushing, touching prod, spending money) need their own yes at any level. A docs-only workstream may land each verified change.

Implement and verify

Use the package's test guidance. For beebox changes, run change-selected tests; the full suite is scheduled hourly on main. See beebox/AGENTS.md and finish for the applicable checks. Write code in TypeScript; a .js or .mjs file is only a thin loader for TypeScript. A foreground sleep is blocked; to wait on a condition, run an until loop in the background or use the Monitor tool. A check piped through tail or head reports the pipe's exit status and can hide the failure; redirect output to a file and read it. On macOS, in-place sed needs sed -i ''.

Real model and API calls are allowed for experiments and verification; Jev and small models are cheap. Check which keys your test box is granted before assuming you cannot, and ask before sending real box content out or spending real money: real model calls.

Do not disable or weaken lint rules to make code pass without explicit permission for that change. This includes rule removal, lower severity, looser options, and suppressions. Fix the code; ask if the rule needs changing. The existing exception is one eslint-disable-next-line <rule> -- <concrete justification> for a true, narrow false positive. Finish coordinated edits before reacting to per-edit lint output, then verify any diagnostics that remain.

Treat unsolicited tool output—including warnings, deprecations, ignored-build-script lists, and peer-dependency mismatches—as a bug. Fix diagnostics introduced by this work or relevant to its correctness. For pre-existing systemic noise outside the task, find or file one focused issue and leave dependency cleanup to that scope. Keep actionable failures visible; routine-success diagnostics belong behind debug. Moving noise to stderr does not help.

Delegate when useful without asking first, using the lightest capable worker: lightweight models for bounded searches, mid-tier models for most implementation/research, and stronger models for difficult reasoning. When a most-capable model drives, favor delegation for substantial independent work; trivial or tightly coupled work can stay inline. Give workers concrete tasks and the context, constraints, and completion criteria they need. Shorter repo instructions are not a reason to strip scaffolding from subagent briefings. Agent and skill files only ever grow unless pruned: when touching one, remove more than you add, move mechanics into a script the agent runs, keep only rules that need judgment, and give a rewrite a line budget. Tell workers to run long commands such as test suites in the foreground: a subagent waiting on its own background job can stall with nothing running.

For anything beyond a small-scope bug fix, get cross-model review before declaring it done. The reviewer must use the other model family, regardless of the driving model. Adjudicate findings and report material changes, unresolved risks, or human decisions.

Record and show work

Human document comments live outside git. At pickup run bin/comments list --workstream <name>; use bin/comments show <path> when opening a document that may have comments. Read, act, then clear. Comment mechanics.

Use issues to retain worthwhile out-of-scope finds. Filing does not authorize implementation. Keep track of this workstream's own finds and offer to fix them at natural pauses and finish. Formats and re-encounter rules: issues/AGENTS.md.

Private box content and personal/operational specifics belong in private-issues/, a separate gitignored repository mounted by symlink. Ask when unsure whether content is public-safe. Commit private changes from inside that repository; public files must never link into it. A missing mount means the developer has not opted in. Privacy rules and setup/mechanics.

Show useful UI screenshot evidence as one labeled exhibit. Write its prose and captions by what a person sees in the app, not by plan or code names (exhibit writing rule). Put the exhibit URL on the first line of the message that presents it; ask any question in chat. A lone incidental debug capture does not need an exhibit. Use bin/exhibits add to create one. Exhibits survive worktree culling and do not merge; durable apps belong in dev/apps/<name>/ (bin/exhibits add --permanent). Exhibit contract and commands.

Commit and land

Commit verified work at good checkpoints without asking; merge to main only when the human asks (the finish skill is that ask). Parallel agents in one worktree share its git index: one agent commits, and the others return the paths to stage. Each worker runs pnpm typecheck and pnpm layout-check from beebox/ before reporting; these read the working tree, so it reports failures in its own files only. Pre-commit checks read only the commit's staged content (staged snapshot). Commit docs with hooks; do not use --no-verify. Root .husky/ owns hooks, including package-check dispatch and git-lfs wrappers; subprojects opt out with prepare: ":". Root pnpm install wires them up. Docs-only commits run fast doc, path-leak, and personal blocklist checks. Use repo-relative or ~/ paths in tracked content. Doc-check guidance and guard mechanics.

Hooks add Workstream and, when exactly one plan matches, Plan trailers. An optional Issue: <bare-basename> identifies a public issue; omit directories and .md, repeat for multiple issues, and never name a private issue. A nonexistent issue name blocks the commit. Provenance details.

When the human asks to finish or land work, use finish. Auto-deploy runs only on main commits/merges touching shipped paths: beebox/, tap-check/, personal-vibe-check/, patches/, or root pnpm files (development docs under beebox/docs/ and AGENTS.md/CLAUDE.md guidance files excluded; bin/deployed-paths.ts has the rule). It is fired by this checkout's own git hooks when the commit lands, not by GitHub: pushing deploys nothing to the server. A push to GitHub's main does publish the public site (Cloudflare builds beebox.run from it), and a v* tag publishes the container image. Worktree commits do not deploy. Deployment operations.