# 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--`, 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