objectstack CLAUDE.md

CLAUDE.md

AGENTS.md is the source of truth for working in this repo — read it. Its Prime Directives are binding. Do not rely on this file alone; the four rules that must never be missed are inlined here because missing any one of them wastes or corrupts other agents' work.

⛔ Claim the issue before you write any code

Assign the issue to yourself (gh issue edit <n> --add-assignee @me, or issue_write with assignees) as the first action of the task — before the worktree, before the first read. Several agents work this repo at once and an unassigned issue reads as an open invitation: two that start on it burn the same hours twice, then race to land conflicting shapes. Already assigned to someone else? It is taken — pick another or ask; never reassign it. File findings unassigned when only recording; assign at the moment you start.

All agents share one GitHub identity, so the assignee field can't tell you whether a claim is yours — a claim is assign plus a claim comment with your session ID and branch (claude/issue-<n>-<slug>), and before writing code you must re-read the comments: an earlier claim with a different session ID means it's taken, whatever the assignee says. (Skipping that read is how one issue got implemented twice in one morning.)

⛔ Worktree-first — before your FIRST file edit (AGENTS.md Prime Directive #11)

This repo — and every sibling repo you touch (objectui, cloud) — is edited by multiple agents at once. The shared primary checkout has its HEAD switched and its tree reset under you, silently clobbering uncommitted work. A feature branch on the shared checkout is NOT enough — it still gets switched under you. You MUST be in a dedicated per-task worktree:

git fetch origin main && git worktree add --no-track ../<repo>-<task> -b <branch> origin/main && cd ../<repo>-<task> && pnpm install

Then make all edits there. This applies per repo: if a task spans framework and objectui, create a worktree in each. Two PreToolUse hooks enforce this, and both check the target file's own repo (so sibling repos are covered): guard-main-checkout.sh blocks Edit/Write/NotebookEdit, and guard-main-checkout-bash.sh blocks the same write as a Bash command (>/>>, sed -i, perl -i, tee, cp, mv, rm, touch) — reads are never blocked, and anything it cannot parse confidently is allowed through, so the rule still outranks the hook. Non-task exception (both hooks, one switch): OS_ALLOW_MAIN_EDITS=1. Follow the rule because it's correct, not because the hook fires.