Rules for AI agents working in this repo. Read this file first.
This is a starting template. Delete what does not apply, and make every rule specific to how you actually work. Generic rules get ignored; yours will not.
One short paragraph: what this project does and who it is for. Then a pointer to the few files worth reading first, so the agent does not try to load the whole tree.
| Area | Start here |
|---|---|
| Main entry point | path/to/main |
| Core logic | path/to/... |
| Config / constants | path/to/... |
Ignore unless debugging build/packaging: build/, dist/, node_modules/.
Prefer the issue tracker over rereading the code for intent and status. The code says what exists; the issues say why, what is unfinished, and what was already decided.
- Every feature or non-trivial fix gets an issue before work starts.
- The issue body is a living document: summary, motivation, acceptance criteria, decisions.
- Progress goes in comments, so anyone (or any agent) can continue from the issue alone.
- Find work with
gh issue list, not by scrolling files.
All implementation happens in a git worktree, never on main in the primary checkout.
- Primary checkout stays on the default branch, used only for pull, status, cleanup.
- Every feature gets its own worktree, its own branch tied to the issue, its own PR.
- One issue, one worktree, one branch, one PR.
git fetch origin
git worktree add ../project-<slug> -b issue-<N>-<slug> origin/main
cd ../project-<slug>Why: an agent commits wherever it happens to be standing. Keep that place off main.
A commit marks a mature, tested unit of work, not "after every file" and not "only when asked."
A change is ready to commit when it:
- Does one clear thing (one concern, one step).
- Has been tested in the way that change actually calls for.
- Is stable, you would not immediately amend it, and debug leftovers are gone.
- Can be read on its own, without the next unfinished change to make sense.
Keep commits atomic, one logical change each. If the message needs "and" three times, it is really three commits. The message explains why, not which files moved.
The constraints that are easy to break when moving fast. Replace these with yours.
- Never delete data destructively (drop a database, empty a table). Migrate instead.
- No new network calls in an offline/privacy-sensitive tool.
- If a change has a desktop and a mobile side, change both or scope one in an issue.
- Never commit secrets. Never force-push
main. Do not commit build artifacts.
- Read this file.
gh issue list/gh issue view <N>to load intent and acceptance criteria.- No issue yet? Create one, then proceed.
- Create a worktree for that issue.
- Implement only what the acceptance criteria require.
- Comment on the issue with progress, blockers, and decisions.
- Commit in small atomic pieces once each unit is mature; open a PR when the criteria are met.