Issues live in the GitHub Issues of this repo. See docs/agents/issue-tracker.md.
The five canonical triage labels. See docs/agents/triage-labels.md.
Single-context: GLOSSARY.md at the root, ADRs in docs/adr/, specs in docs/spec/. See docs/agents/domain.md.
Before writing UI in apps/desktop, read apps/desktop/DESIGN.md and the "Rules for components" in apps/desktop/README.md. DESIGN.md records design decisions and tokens, never UI copy: the copy lives in the code, and its rules in the README. Style only with the tokens in apps/desktop/src/styles/tokens.css, which DESIGN.md documents; when a design needs a value no token holds, add the token to tokens.css and document it in DESIGN.md. Our components take no className or style: give them a closed, typed prop or variant instead. pnpm check rejects type errors, arbitrary values, a class that reads a CSS variable (w-(--x)), raw colours, unknown classes, inline styles and a className or style on our components; fix the code, never the guard. It misses alpha modifiers, rounded-full and leading-none, so avoid those yourself (see "What the checks catch" in the README). Ultracite (oxlint and oxfmt) lints and formats the frontend: run pnpm fix in apps/desktop before you commit.
UI primitives come from shadcn/ui: add one with pnpm dlx shadcn@latest add <name> into apps/desktop/src/components/ui/ and adapt it as the README's "Rules for components" say (tokens, no className, cva() variants, our icons); write a component in src/components/ only when shadcn has no equivalent.
Keep the Help Center up to date. Whenever there's a new feature or a change in functionality, update the relevant user-facing documentation in docs/help-center. Keep the language clear, structured, and concise. Use an imperative tone.
Mintlify publishes every file under docs/help-center, so treat anything you add there as public.
Mintlify spellchecks the pages a PR changes. When it flags a product term, add the term to docs/help-center/styles/config/vocabularies/agentx/accept.txt.
The CLI's tests drive real git, and starting a process is what they spend their time on, several times more on macOS than on Linux. Test each behavior once, at the cheapest level that shows it:
- End to end (through the harness, with a real home and git): one happy path per command or flag family, and one case per distinct user-visible refusal or warning, that is, a different message or exit code. Not one case per input that reaches the same branch.
- Unit tests for the edge cases of a pure function (names, URLs, paths, selections, overlap rules, refusal order, formatting), as a table over that function.
- Crash recovery at every journal boundary is tested once, without git, in
internal/home. A command's own recovery test checks the steps it journals and stops it at no more than two boundaries. - Fixtures: refusals that change nothing share one home, and a test builds only what it uses.
- Assertions: check the fact that matters (the exit code, a distinctive substring, an event field). One test pins an exact output or a long hint; the others check a substring.
- Parallelism: call
t.Parallel()unless the test usest.Setenvort.Chdir, swaps a package variable, or measures time.
Before adding a test, find the one that already covers the path, and extend it instead.
Test what the product does: its happy paths, and a limited set of known non-happy paths (a refusal, a failure, a conflict, a stale event). Write no test or assertion for a thing the product was never meant to have or do, such as a button a row never had or a command nothing runs. When a change removes something, delete its test; don't assert it is gone. Assert that something is gone only when that is the main effect of the action under test, such as a dialog that closes on Cancel. This applies to the CLI's tests and to the desktop app's tests in apps/desktop/e2e.
Follow the conventional commit format. GitHub uses the first commit message as the PR title, and we squash-merge PRs, so the PR title becomes the commit on main.
The type decides the release notes section: feat for something new, change for a change to how an existing feature behaves, fix for a bug fix. See "Release notes" in CONTRIBUTING.md.
For PR descriptions, follow the PR skill in .agents/skills/pr/SKILL.md.
Write commit descriptions in an imperative style. Focus on how the change affects users, what changed and why, and describe the implementation only where it's needed to understand the change.
- Name branches after the change in product terms, such as
feat/source-removed-drift.
- Never use em dashes (
—); instead, use en dashes (–) or hyphens (-). - State what is true, and stop. Don't add a negation that repeats it, such as "runs on Macs with Apple silicon, not on Intel Macs".
This repository is public. See docs/agents/domain.md for what must never appear in it.