agentgem: Instructions file for Claude Code

CLAUDE.md

Concurrent sessions

Use git worktrees to isolate concurrent sessions. When more than one agent or session may be working in this repo at the same time, create a dedicated worktree per session instead of sharing the main checkout. Always branch off the freshly fetched origin/main, never the local main (see below):

git fetch origin
git worktree add ../agentgem-worktrees/<task> -b <task> origin/main

Always nest worktrees under the sibling agentgem-worktrees/ directory — one subdirectory per task — rather than scattering flat agentgem-<task> siblings next to the repo. Keeping them in one container makes the checkout list legible and the cleanup sweep easy. This keeps each session's branch, working tree, and build artifacts (dist/, tsconfig.tsbuildinfo) separate, avoiding cross-session interference. Remove the worktree when the work is merged or abandoned:

git worktree remove ../agentgem-worktrees/<task>

Integration: keep local main a clean mirror

Worktrees isolate each session's working tree — that part is automatic. The thing that actually bites is a divergent local main: with many concurrent worktrees, main drifts if it's committed to directly or left stale, and ends up both ahead of and behind origin/main (not fast-forwardable) — and it's often checked out in another worktree (e.g. ../agentgem-worktrees/run) you must not disturb. Keep main clean and a PR is the default integration path; a direct local merge is the exception. The PR route runs CI (test (24)) before anything lands, never touches the main checkout, and serializes safely when several sessions integrate at once — worth the round-trip as the default.

• Never commit directly to main. Treat it as a read-only mirror of origin/main — only ever fast-forward it (git fetch && git checkout main && git merge --ff-only origin/main). Do all work on feature branches. Direct commits are what make main diverge "ahead" and stop fast-forwarding.
• Branch off freshly-fetched origin/main, not local main, so your diff is against the real trunk.
• Finish with a PR (default): push the branch and open a PR; let CI gate it and merge once green (gh run watch <run-id> --exit-status then gh pr merge --rebase --delete-branch). See PR lifecycle below for the gating facts and the verify-each-commit-landed check — the PR path is where the dropped-commit trap lives, so follow it.
• Local merge (the exception) — only for a trivial change you deliberately want to skip CI/review on, and when main isn't checked out in another worktree: in the one checkout that holds main, git fetch then sync down (git merge --ff-only origin/main — local only, no push; it just advances local main up to the remote), git merge <branch> (new commits, now ahead of the remote), run tests, then push up (git push — the step that publishes to origin/main). The ff-only sync and the push move in opposite directions; only the push leaves your machine.
• Before finishing, confirm your branch is ahead of origin/main only (not built on a stale/divergent local main).