# AGENTS.md — notes for Codex and other repository agents

**Full project instructions live in [`CLAUDE.md`](CLAUDE.md); read it first.** It is the source of
truth for the file map, invariants, change workflow, and validation contract. Read
[`DESIGN.md`](DESIGN.md) before changing isolation, identity, leases, cleanup, tmux, or hooks.

## This is a Jujutsu repository

The repository uses **Jujutsu (`jj`) with a colocated Git backend**. Use `jj` for status, diffs,
history, commits, bookmarks, rewriting, and pushes. Do not use Git history commands just because
`.git/` exists. Never force-push or rewrite published work.

Run these before editing:

```sh
hostname
jj st
```

## Do not regress packaging or safety

- Edit standalone sources, never a consumer repository’s vendored `.coord/` copy.
- `.coord/` is canonical; `.claude/coord/` is compatibility only.
- Keep the canonical skill in `skills/coord/` and install identical copies for Codex and Claude.
- Preflight every source, identity, wrapper, skill, and JSON input before replacing target files.
- Preserve unrelated hooks, skills, settings, `AGENTS.md`, and `CLAUDE.md` in target repositories.
- Keep runtime SQLite state outside repositories and preserve immutable project IDs.
- Use independent `jj git clone --colocate` instances for concurrent writable work.
- Keep agent bookmarks namespaced; only the integration owner moves shared bookmarks.
- Treat full IDs as authority; short names and five-word handles are presentation/resolution aids.
- Never guess during workspace cleanup or target tmux objects by their names.

Validate with:

```sh
python3 -m unittest discover -s tests -v
python3 -m py_compile coord hook.py install session.py store.py workspace.py
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/coord
```