coord/CLAUDE.md

# CLAUDE.md — coord maintainer and agent guide

This is the complete instruction source for agents working on `coord`. Read [`README.md`](README.md)
for the user workflow and [`DESIGN.md`](DESIGN.md) for the architecture, isolation boundary, and
proved failure modes.

## Repository and VCS

This is a **Jujutsu (`jj`) repository with a colocated Git backend**. Use `jj` for status, diffs,
history, descriptions, commits, bookmarks, rebases, and pushes. Do not use `git add`, `git commit`,
`git rebase`, or Git history mutation merely because `.git/` exists.

Useful commands:

```sh
jj st
jj diff
jj log
jj describe -m "type: concise change"
jj new
jj bookmark set master -r @
jj git push
```

Never force-push or rewrite published changes. A remote is not part of a fresh checkout of this
standalone repository; inspect configuration before proposing publication.

## Purpose and source map

- `coord` — command parser and coordinator operations.
- `store.py` — SQLite schema, identities, leases, messaging, and audit records.
- `workspace.py` — independent Jujutsu clones, lifecycle, integration evidence, tmux, and cleanup.
- `hook.py` — pre-write lease enforcement and context delivery.
- `session.py` — harness lifecycle registration, heartbeat, and termination.
- `install` — preflighted vendoring, compatibility shims, hook merge, and skill installation.
- `VERSION` — semantic source/install release identifier exposed by both entry points.
- `skills/coord/` — canonical concise skill installed into both harness discovery locations.
- `tests/` — behavioral installer, CLI, documentation, and packaging tests.
- `DESIGN.md` — architectural rationale and security boundaries.

The standalone files above are authoritative. Installed `.coord/` copies and `.claude/coord/`
compatibility shims in consumer repositories are generated artifacts, not alternate sources.

## Invariants

Preserve these properties in every change:

1. `.coord/` is the canonical installed runtime. `.claude/coord/` remains a compatible shim for
   existing sessions, including argv, cwd, environment, exit status, and module imports.
2. `skills/coord/SKILL.md` is the repository skill source. Install byte-identical skill trees at
   `.coord/skills/coord/`, `.agents/skills/coord/`, and `.claude/skills/coord/`; do not embed
   repository-specific policy in the generic skill.
3. A project ID is explicit on first install, immutable thereafter, and shared by clones of one
   logical project. Never silently generate or replace it.
4. Runtime SQLite state stays outside repositories. Install, upgrade, check, and cleanup must not
   copy, delete, reset, or rewrite unrelated state.
5. Finish all fallible source reads, project-ID checks, wrapper generation, skill reads, and hook
   JSON validation before the first target replacement. Invalid input must leave the target
   untouched.
6. Replace only exact known coord hook endpoints. Preserve unrelated hooks, JSON keys, agent
   instructions, skills, and repository files.
7. Writes use a complete write loop, fsync, and atomic replacement. Do not leave partial files.
8. Full opaque IDs remain canonical evidence. Exact five-word handles may resolve identities;
   prefixes and display-only shortened VCS IDs never carry authority.
9. Managed writable work defaults to independent colocated `jj git clone` instances. Each gets a
   unique jj workspace name, described working-copy change, and namespaced agent bookmark. A
   native `jj workspace` is opt-in because it shares an operation log and object store.
10. Workspace deletion never guesses. Require registry/on-disk ownership agreement, clean state,
    gate evidence, integration evidence where needed, and exact confirmation.
11. Tmux names are presentation only. Create concise `<task>-<sid4>` names, but inspect and mutate
    sessions, windows, and panes only through recorded immutable tmux IDs.
12. `batch` accepts only the low-risk allowlist, inherits one already-resolved identity, executes
    ordinary handlers sequentially, stops on failure, and performs no hidden rollback.
13. Hooks fail open when coordinator infrastructure cannot load, but a positively recognized
    conflicting write fails closed. Do not claim shell-command parsing or security isolation the
    hook does not provide.
14. Publishing, integration, activation, deployment, and other external side effects require
    explicit resource scopes and authoritative before/after evidence. Acquisition snapshots and
    freezes the exact candidate commit; only the recorded owner may release it. Never force.

## Change workflow

Before editing, run `hostname` and `jj st`. Preserve unrelated working-copy changes. In a shared
consumer repository, use its installed coord policy and an isolated managed clone; do not develop
the standalone source by editing a vendored copy.

When changing runtime behavior:

1. Update the authoritative module.
2. Add a behavioral regression test that observes the property, not merely a source string.
3. Run the focused test and the full standard-library suite.
4. If the installed interface or model changes, update README, DESIGN, and the coord skill.

When changing installation or packaging:

1. Keep `CORE_FILES` and `SKILL_FILES` explicit.
2. Build the entire install plan before the first replacement.
3. Test fresh install, legacy migration, invalid-input no-write behavior, drift detection, hook
   preservation, compatibility entry points, and identical dual-harness skills.
4. Confirm the installer vendors docs under `.coord/` without overwriting target-root `AGENTS.md`
   or `CLAUDE.md`.
5. Bump `VERSION` for every shipped installed change: major for incompatibility, minor for new
   backward-compatible behavior, and patch for compatible fixes. Drift checks remain content
   based rather than trusting the version marker alone.

When changing the skill:

1. Keep the frontmatter trigger description specific and the body concise.
2. Put detailed architecture in DESIGN rather than duplicating it into model context.
3. Regenerate `agents/openai.yaml` when its UI text becomes stale.
4. Run the skill validator and the packaging tests.

## Validation

Run:

```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
./coord --help
./coord work --help
./install --help
jj st
```

Tests must use temporary directories and an explicit `COORD_DB`; never exercise cleanup against
an operator’s real registry. If a required external binary such as `jj` or `tmux` is unavailable,
report that portion as unverified rather than implying it passed.

## Documentation ownership

- README: installation, common operations, state locations, compatibility, and development entry.
- CLAUDE: complete maintainer/agent rules and validation contract.
- AGENTS: short high-risk front-load that points here.
- DESIGN: implementation-independent rationale, boundaries, and threat model.
- Skill: minimal operational procedure loaded into model context.

Update or remove stale statements rather than appending contradictory history. Historical names
retained for compatibility must be labelled as such.