AGENTS.md git:20260725.d478789B

Immutable. This exact content is served forever at /api/v1/blob/3eb315f5a0dbb038.

<!-- 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

Reusable skills and one command skill per canonical command are discovered
from `.agents/skills/`. Command skills carry the complete workflow inline.

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>`. API keys
(`SERPAPI_KEY`, `ANTHROPIC_API_KEY`, `OPENALEX_MAILTO`) come from the
environment, not from pixi.

## Conventions

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

- **Git** — issue and PR for every change; work in worktrees; never commit to
  `main`. See `.claude/rules/git-workflow.md`.
- **Python** — environments are managed with pixi, never bare pip or
  virtualenv. See `.claude/rules/pixi-python.md`.
- **Documentation** — specifications are the source of truth and code serves
  them; YAML for structured documents, markdown for prose; active voice;
  observe the forbidden-terms list. See
  `.claude/rules/documentation-standards.md`.
- **READMEs** — written as a technical brief: title, thesis, diagram, scope,
  then build instructions last. See `.claude/rules/readme-format.md`.
- **Document types** — pick the right external form (concept paper, RFC,
  specification, invention disclosure) from
  `.claude/rules/technical-document-types.md`.

Before committing, run the repository's consistency check if one exists
(`mage audit` or `mage analyze`), and commit after each round of edits rather
than accumulating changes.