cartridges

Who a run works for. This folder is the core package and the cartridge data inside the coxswain repository; it ships as part of the one coxswain package. To install Coxswain, see the root README.

Graphs reference abstract roles (plan, build, review_charter). A cartridge binds those roles to real skills, names where writes land, and carries the team's own written conventions. The same graph runs for any team that can fill the contract: swapping trackers, style charters or model providers is an edit to one file, not a rewrite.

What is here

core/                pure substrate: merge, policy, manifest, ledger, work store, intake
cartridges/base/     the contract: roles, write-kind taxonomy, autonomy policy
cartridges/local/    the filesystem-only cartridge every install starts from
cartridges/<name>/   example-team, and the comfort presets local-comfort0 and local-comfort1
providers/           the shipped provider profiles (tier -> model) and catalog.yaml, the model price list
skills-plugins/      the reference `local-skills` plugin and the `coxswain` session plugin
context-templates/   starting points for a team's own context packs
.claude-plugin/      the Claude Code plugin marketplace, named coxswain-cartridges
docs/                design notes and the clean-room rule
tests/               this folder's suite

A workspace's cartridges/base and cartridges/local are links into cartridges/ here, so they move with the checkout's release.

Provider profiles

A provider profile names the runner, maps each tier to a model, and sets the budget for each tier and role. The files in providers/ are the shipped defaults: claude-code.yaml, anthropic-default.yaml and local-oss.yaml. A fresh cox install points the machine profile's provider_profile at <checkout>/src/cartridges/providers/claude-code.yaml.

A profile your team edits is team configuration, not code. Keep it outside the checkout, in the workspace or in <home>/providers/, and point provider_profile in each machine's profile at it. An edited file inside the checkout makes it dirty, and cox upgrade refuses a dirty checkout. Copy catalog.yaml along with the profile: the chair reads model prices from the catalog.yaml beside provider_profile first. cox setup migrate leaves a profile that is already outside the checkout where it is.

Tests

From this folder:

cd src/cartridges && uv run pytest -q

Fixtures are synthetic. The suite leans hardest on the ways autonomy must fail to be granted: streaks that do not transfer across kinds, risks, cartridge hashes or provider profiles, and a single reversal resetting the streak and doubling the bar.

Working with a cartridge

Resolve and validate the local cartridge from this folder:

uv run python -m core.cartridge --team local --json --skills-root skills-plugins

--skills-root checks that every bound skill name resolves to exactly one skill body; pass it once per plugin root.

Start your own team's cartridge in your workspace:

cartridge init my-team --cartridges-dir <workspace>/cartridges

It creates my-team/, its context/ tree, links to base and local, and a cartridge.yaml naming the team. cox install registers the marketplace at <checkout>/src/cartridges and installs local-skills@coxswain-cartridges when claude is on PATH.

The docs site explains the rest: cartridges, team cartridge and policy, including how a write kind earns autonomy.

License

MIT. See LICENSE.