A local-first control room for a team of AI agents: a chat-style inbox, decision and action cards, projects and drafts, backed by a file-based message protocol. This file is the short orientation for AI coding agents. The rules live in one place each, so read these before your first change: CONTRIBUTING.md (rules), DEVELOPMENT.md (workflow), README.md and INSTALL.md (setup), Testing and evals and UI components.
packages/deck: the React Router web app, with vitest unit tests and Playwright journeys.packages/base: the agent protocol (packages/base/docs/protocol.md), persona templates and theinboxCLI. It never imports frompackages/deck;pnpm check:boundariesenforces that..specs/<issue-number>-<slug>/: one SPEC per ticket, written first and updated as the work happens.scripts/: the root gates (leak, licence, lib-version) andsetup.sh. The dash check ispackages/deck/scripts/check-dashes.mjs.
- Start from a GitHub issue.
start-issue(skill) creates the branch and the SPEC skeleton. - Write or update the SPEC in the same pull request as the code. Never keep a spec only in a chat, a ticket comment or a wiki.
- Keep changes small and focused, follow the patterns in the files you touch, and add tests for core behaviour and for anything that can lose data or leak.
- Before pushing, run the checks listed in CONTRIBUTING.md ("Checks a pull request must pass"). Commit first: two suites assert the tree is clean.
- Branch off
main, keep each pull request to one change, and title commitstype(scope): summary (#issue). Never push tomain.
- Test core behaviour, meaningful regressions and safeguards against unexpected spend, data loss or leaks. Skip exhaustive low-risk edge cases and implementation details unless they are part of the contract.
- Test shell scripts in subprocesses with temporary fixtures, fake homes and
stubs. For Nudges, use synthetic requests and fake cron dependencies, never
a real crontab. If tmux is needed, use a private fixture socket, never the
real
agentssession or the user's tmux. Do not run live agents for tests. - The eval workflow is proposed, not implemented: use synthetic fixtures, check outputs and side effects deterministically first, and use a fixed rubric for model grading only where judgement is needed. Keep live evals opt-in and agree limits first.
- Feature components live in
packages/deck/app/components/, with shared primitives in itsui/subdirectory. Reuse existing components before adding new ones and follow the semantic tokens inpackages/deck/app/app.css. See the UI components guide.
- No internal material (names, hosts, paths, ticket ids, addresses) in the
repository.
pnpm check:leaksenforces it. - ASCII only, no em-dashes or en-dashes anywhere in the tree: U+2014 is the field
separator in the message protocol.
pnpm -C packages/deck check:dashesenforces it. - Sign off every commit (
git commit -s); an unsigned commit fails the DCO gate. - Agents: do not push to
main, force-push a shared branch, merge your own pull request, or create a release unless a maintainer asked you to in the issue or pull request.