coord/CLAUDE.md

CLAUDE.md — coord maintainer and agent guide

This is the complete instruction source for agents working on coord. Read README.md for the user workflow and 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:

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:

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.