AGENTS.md git:20260812.8e0d9fdB

Immutable. This exact content is served forever at /api/v1/blob/71dca8c9bcaa8e68.

<!-- Generated by scripts/sync-mirrors.sh from the canonical sources — do not edit. -->

# Repository Instructions

Assistant configuration is canonical under `.claude/`. Codex discovers this
repository's skills from `.agents/skills/` (generated). Regenerate every
surface with `scripts/sync-mirrors.sh`; verify with `--check`.

## Mandatory workflow: issue → worktree → pull request

All work goes through a GitHub issue and a pull request. Never commit to
`main` directly.

1. **File an issue first** — run the `gh-issue-push` skill. It enumerates
   every file the change touches before drafting, so nothing is missed.
   (Beads repositories use `bd-issue-push` instead.)
2. **Pop it into a worktree** — run the `gh-issue-pop` skill. All
   implementation happens inside the worktree at `../gh-<number>-<slug>`,
   never in the main checkout, which stays on `main`.
3. **Do the work** — run the `do-work` skill inside the worktree, once per
   sub-issue, until the epic is complete. It detects the tracker (GitHub
   issues or beads) and works either.
4. **Open the PR** — the pop skill's final phase opens it, records the actual
   lines of code against the estimate, and closes the issue on merge.

One issue per logical change; small fixes still need an issue. The only
exceptions are an emergency hotfix authorized in-session and `exp/*`
experiment branches, which never merge to `main`.

## Skills and commands

Codex discovers both from `.agents/skills/`.

Command workflows (14), each carrying its full workflow inline: align-specs, bd-issue-pop, bd-issue-push, bd-issue-show, bootstrap, do-work, exp-start, exp-stop, gh-issue-pop, gh-issue-push, gh-issue-show, gh-release-push, make-work, test-clone.

Python-backed skills run in a pixi environment that ships beside them:
run `.agents/scripts/ensure-env.sh` once per machine, then invoke scripts
with `pixi run --manifest-path .agents/pixi.toml python <script>`.

## Conventions

These are summaries; the canonical rule files hold the detail.

- **Documentation Standards** — Distilled from `docs/constitutions/design.yaml`. See `.claude/rules/documentation-standards.md`.
- **Git Workflow** — All work goes through issues and pull requests. See `.claude/rules/git-workflow.md`.
- **Pixi for Python** — We use pixi (https://pixi.sh/) to manage Python environments and dependencies. See `.claude/rules/pixi-python.md`.
- **README Format** — README files are the public interface of a repository. See `.claude/rules/readme-format.md`.
- **Response Style** — Default to cliffnotes. See `.claude/rules/response-style.md`.

Before committing, run the repository's consistency check if it defines
one, and commit after each round of edits rather than accumulating them.