coven AGENTS.md

AGENTS.md — coven

Guidance for AI agents (Codex, Claude Code, Hermes, and any Coven familiar) opening pull requests against this repo. Humans: your canonical guide is CONTRIBUTING.md — this is the agent-specific layer on top.

Read first: README.md for what this repo is, and CONTRIBUTING.md for the full contribution bar (including the "Contributor First 10 Minutes" checkout path).

---

What this repo is (one line)

Coven is a small, boring Rust authority layer with TypeScript integration packages around it. The development loop must keep that boundary clear: core logic stays in Rust; the npm packages are thin integration surface.

Check, enter a worktree, then claim it

Multiple agent sessions (Codex, Claude Code, familiars) frequently run against the same checkout at once, each in its own worktree. Worktrees keep git operations from racing, but they do not stop two sessions from independently building the same issue — which has happened repeatedly, producing duplicate PRs that a session then has to close. Before you touch code:

1. Check what's already taken. Duplication hides behind divergent branch names — one issue once spawned fix/output-polish, fix/311-output-polish, and fix/output-polish-311 — so branch names alone won't tell you. Check both the shared claim registry and open PRs:

   coven claim status          # active claims, shared across every worktree of this repo
   gh pr list --state open     # is there already a PR for this issue?
   

   If the issue is claimed or already has a PR, pick different work or coordinate.

2. Create or enter the task worktree. The automatic fallback identity is worktree-scoped, so enter the worktree before acquiring the claim:

   git fetch origin main
   git worktree add -b <branch> /tmp/coven-<branch-slug> origin/main
   cd /tmp/coven-<branch-slug>
   

3. Claim it with a shared, issue-keyed token — not your working branch name, which no other session can predict:

   coven claim acquire issue-<N>     # e.g. issue-311; a TTL-bounded lock
   

   Claims live in the repo's shared --git-common-dir/agent-claims/, so every worktree and session sees them. For long tasks, extend the TTL with coven claim heartbeat issue-<N>.