templates

Imported from Pawper/sipnship-plugin (templates/AGENTS.md). Install upstream with npx skills add Pawper/sipnship-plugin --skill templates. Copyright stays with the author.

PROJECT_NAME

This file is the copy of CLAUDE.md for tools that read AGENTS.md. Keep the two the same; when you change one, change the other in the same commit.

One line on what this project is. Replace every CAPITALIZED placeholder.

Many agents work here at once. Each kind of thing has one home, every rule has something that enforces it, and nothing is appended to a shared page.

Stack

• Issues and board: GitHub. CI: GitHub Actions. Agent runtime: Claude Code.
• One-file test command: TEST_COMMAND path/to/file. Generated pages: STATUS.md.
• Specs: by hand in specs/<feature>/. Work folder: WORK_FOLDER, backed up to BACKUP_LOCATION. Worktrees: WORKTREE_DIR.
• Dates are the owner's local day, TIMEZONE (an IANA name such as America/Los_Angeles). gh output, runner logs and date -u are UTC; convert before writing a date anywhere, including a memory note.

Homes

Rules

• File the issue first, with a State label. Work in an isolated worktree. Never force-push. Never delete; move aside.
• Nothing is appended to a shared page. A PR names its spec in its body (Spec: specs/<feature>) and changes the spec only when the design changed; it changes SETUP.md only when a person must do a setup step; it changes a feature's status stub only when that feature's state changes; it adds no task to any file, because tasks are issues.
• Tests prove the change and run per file. The full suite is the gate on main, not on the PR.
• Everything a person sees is calm and plain, never a developer note: no issue numbers, fields or migrations in user-facing text.
• GitHub gives the hour 5,000 GraphQL points, shared by every agent and the queue, and gh issue, gh pr, gh project and gh search all spend them; a secondary limit on concurrent GraphQL calls trips earlier still. The session brief prints the budget as one line, and sh scripts/gh-budget.sh prints it on demand. File issues with sh scripts/issue-open.sh "TITLE" .scratch/body.md state:ready, open pull requests with sh scripts/pr-open.sh, read checks with sh scripts/pr-checks.sh N, and read one issue or pull request with gh api repos/{owner}/{repo}/issues/N: all REST, which has its own budget. One queue process at a time; no loop of your own around it; when the budget is low or a call is refused for its rate limit, wait for the reset the line names, never retry at once, and never poll. The board scripts need GraphQL and belong to the coordinator.
• Every date written here is the owner's local day, named in the Stack section above; the session brief prints today. A UTC timestamp from gh or a runner log is converted first, or an evening's work is dated tomorrow.
• Report what was not done and why, not only what was. Say which commands were refused.
• No wait loops; bounded commands; stop every shell when done.
• The plugin's scripts live at the path the session brief prints on its "Plugin:" line. $CLAUDE_PLUGIN_ROOT is set for hooks but empty in the Bash tool, so use that path in commands.
• At session start, reply from the session brief. Never run one network call per branch, worktree or issue in the foreground; one call for the whole board is sh "$CLAUDE_PLUGIN_ROOT/hooks/scripts/board-now.sh". Count long lists, do not print them.
• A clean folder is part of done. Before you report finished or open a pull request, git status shows nothing outside .scratch/. Commit the files, or list them in the pull request as deliberately left out.
• One scratch folder, .scratch/, which git ignores. Probe scripts, screenshots and notes go there and nowhere else, so any other untracked file means real work. Stage with git add -A; git add .scratch fails because the folder is ignored, and that is right.
• Images and build output never go in a worktree. They belong in the work folder outside the repository. The production build runs in CI's app job on every pull request that touches the app; to build by hand, build in the batch worktree or a copy under .scratch/, never in a task's worktree.
• A screen uses a token or a type role by name, never a literal colour, size or font; the look lives in design/tokens.json and is generated into every platform (node scripts/design/generate.mjs). A type role is the unit: a screen says type-rowClaim or DesignType.RowClaim, and the size lives in the tokens. A colour chosen by data is a core rule, with fixtures; a colour chosen by design is a token.
• A fix to shared code gets its own issue and its own pull request. Never patch shared code to get your own build through and ship only your part.
• Stop what you started. Any server or watcher you started from a worktree ends before you finish. Never stop a build daemon (gradlew --stop, nx reset): it is shared by every build on the machine, including a self-hosted runner's job in flight.
• Never move a branch from outside its worktree, never add a detached worktree, and never close a pull request without a comment saying why or what replaced it; sh scripts/worktrees.sh close PR "reason" does the whole ending.
• Open a pull request with sh scripts/pr-open.sh "TITLE" .scratch/body.md and read its checks with sh scripts/pr-checks.sh N; both use REST. The body follows .github/pull_request_template.md: Closes #N, Spec: specs/<feature>, and, only when a check asks, Parity: #<open issue> or Parity: none, <reason>, or Design: <reason>, written exactly so. gh pr create and gh pr checks go through GraphQL, whose secondary limit trips first when many agents work at once.
• A new worktree needs its packages before its first test: run the install (npm ci in each package with a lockfile) right after git worktree add. A first test run without it writes outside the repository.
• Merge only through the queue: sh scripts/ci/merge-queue.sh --drain merges everything green, --serial PR one pull request. A direct gh pr merge is refused.
• A decision is one file in docs/decisions/, made with sh scripts/decisions.sh new "what was decided", never a row appended to a table in the brief; sh scripts/decisions.sh list prints them all. A brief that still holds a decisions table is moved once with sh scripts/decisions.sh split.
• Never take a running number in a shared place. A task, a setup step or a note is named by its issue number ("#123"), which never collides. A file that must keep its order, such as a migration, takes its number from sh scripts/next-number.sh migration, which checks main and every open pull request.
• A change that adds a migration merges after the migration has run: run it, mark its line Done in the manual on the same branch, then queue it.
• To act in another folder, use git -C PATH ... rather than cd PATH && git ...; a cd inside a chained command asks for approval every time.
• Worktrees live in one folder, WORKTREE_DIR, and go when their pull request merges. The merge queue removes them; sh scripts/worktrees.sh prune --apply clears a backlog. It is the one cleanup allowed, because the branch keeps the work.

What enforces each rule

Two rules have no mechanical check and are reviewed by hand: report what was not done and which commands were refused, and stop every shell when done.

Not on GitHub?

These files were written for GitHub, Actions and gh. If this project uses something else, say so once, keep every rule, and swap the tool: the tracker's issue with a State field, its board grouped by State, its CI with the same jobs, its CLI in the scripts. The pure parts of every script are tool-free.

The hooks come from the sipnship plugin, SipNShip's free local part. If a hook refuses a command, do what its message says; do not look for a way around it.

Commands

• Build the status page: sh status/build.sh
• Check it is current: sh status/check.sh
• Run one test file: TEST_COMMAND path/to/file
• Classify a change: sh scripts/ci/classify.sh
• Regenerate the design tables from design/tokens.json: node scripts/design/generate.mjs (--check in CI); record a cross-platform screen comparison: sh scripts/design/screens.sh compare NAME
• Open the owner console: node "$CLAUDE_PLUGIN_ROOT/console/cli.js" console; check its config: node "$CLAUDE_PLUGIN_ROOT/console/cli.js" console --check. Adding a service means adding an entry to console/services.json.
• Where every open issue and pull request really stands: /project-status. Light readers summarize bodies and comments, only for items that changed; you keep one line per item. Do not read the item files yourself.
• Propose the next round: /project-drive. It reads the board and the checks, proposes, and does nothing until a person approves in the session or on the issue labeled drive. Config in .claude/project-drive.json.