🚢 Shipmates

Stop being your AI's for-loop. Give it a crew. ⚓

You know the drill: prompt, read the reply, prompt again, sigh, prompt again. You are the control loop — the planner, the reviewer, the nagger. Shipmates hands that job to a crew of specialist subagents and a workflow that actually finishes things.

One command — /shipmates-ship-issue — takes a GitHub issue from "open" to a reviewed, CI-green pull request, on its own: it plans the work, builds it in an isolated worktree, waits for CI to go green, convenes an adversarial review board, loops on the fixes, and hands you a PR to merge. You stay the captain. The shipmates do the twenty steps in between. 🫡

⚓ Get the crew aboard → · one line, no clone — then just /shipmates-ship-issue 42. 🌐 shipmates website → · the crew, the commands, and how /shipmates-ship-issue works.

---

🧭 Meet the crew

Thirteen domain-neutral specialists. They'll work on anything — a game engine, a web app, a CLI — because the standard they hold your work to comes from your repo's README / CLAUDE.md, not from anything hardcoded into the role.

Shipmate	Rank & duty
🏛️ architect	Structure & schema — coupling, boundaries, migration safety, "does this actually fit?"
🔧 senior-engineer	Builds to spec, fixes red CI, clears review defects
🧪 sdet	Runs the real tests/build and reports pass/fail with a proper defect list
🛡️ security-engineer	Threat-models the change — authz, injection, secrets, crypto, vulnerable deps
🚨 site-reliability-engineer	Reliability & failure modes, rollback/deploy safety — and bug root-cause
⚡ performance-engineer	Profiles, benchmarks, and proves the win — measure → optimise → measure
📦 devops-engineer	Build & delivery — reproducibility, pinning, environment parity, does the gate gate?
📋 product-manager	Accepts or rejects against the acceptance criteria and your quality bar
🎛️ ux-ui-designer	Specs & reviews on-screen UI — tokens, responsive layout, focus, a11y
🎨 art-director	Directs & reviews rendered visuals — judges the picture, not the code that drew it
📖 technical-writer	Writes docs from the real code; proves them with a fresh-reader test
📊 data-scientist	Data/model work — metric choice, leakage & validation, reproducibility (domain-gated)

📜 The commands

Command	What it does
/shipmates-ship-issue <n>...	Drives GitHub issue #n — or several at once, bundled into one PR — from open → reviewed, CI-green PR (→ merged, opt-in), with the whole crew
/shipmates-ship-epic <n>	Ships an epic's unchecked stories in dependency-ordered waves — independent units fan out concurrently; gate stories pause for sign-off; failures pause with state
/shipmates-fix-bug <n>	Fixes a bug the honest way — reproduce as a failing test first, root-cause, minimal fix, red→green proof
/shipmates-report-bug [symptom] [apply]	Files a structured bug report on saman-mb/shipmates from a live run — preview by default; apply creates the issue
/shipmates-plan-epics <brief>	Turns a brief (or several) into GitHub epics + linked, labelled user stories, authored in parallel
/shipmates-consolidate-issues [filter] [apply]	Reviews every open issue against git history — merges duplicates into their survivors, closes what's done or stale, migrates legacy ones, bundles the rest by theme so they ship together
/shipmates-harden <surface>	Threat-models a surface and ranks every finding — read-only by default; remediation on a branch, opt-in
/shipmates-spike <question>	De-risks a decision — prototypes the options in parallel, judges them, records the pick as an ADR
/shipmates-migrate <from→to>	Sweeps a mechanical migration across the codebase — every call site, verified, no remnants left
/shipmates-document <target>	Writes docs from the real code, gated on a fresh reader actually completing the steps
/shipmates-release [version]	Cuts a release — changelog from what merged, CI-green tag, SRE rollback pre-flight, opt-in publish
/shipmates-polish <target>	Iterates a visual/UI/output artifact to a specialist's sign-off — render → critique → fix loop
/shipmates-pr-review <pr>	Runs the board against a PR the crew didn't author — read-only, it reports and never repairs
`/shipmates-qa <pr	issue

Where a command writes. Anything that changes your repo does it on its own branch, in its own worktree, and hands you a pull request — your checkout is left as you left it. /shipmates-report-bug and the opt-in file-bugs token of /shipmates-upgrade write to the upstream Shipmates repo, not your project. /shipmates-release is one exception: the release commit has to land on the branch being tagged, so it commits, pushes and tags straight in your checkout instead of an unmerged side branch. /shipmates-auto-trunk is the second exception: it intentionally commits directly to the default branch when you opt into mode=run. /shipmates-pr-review and the default report mode of /shipmates-harden, /shipmates-consolidate-issues, /shipmates-deslop and /shipmates-upgrade write nothing at all. Writing straight into the working tree is opt-in (MODE=edit-in-place); so are merging (MERGE_MODE=auto) and publishing (PUBLISH_MODE=auto).

There's deliberately no code-reviewer. Review is split by discipline instead of pooled into one generalist: architect takes structure, sdet takes verification, product-manager takes acceptance, security-engineer takes threat modelling, devops-engineer takes delivery. Line-level craft — naming, dead code, error handling — is senior-engineer's as it builds and architect's on review. If you're arriving from another agent pack that ships a code-reviewer, reach for one of those instead: an unresolved role name silently falls back to a generic agent rather than erroring.

More crew and more commands are on the way. ⛵

---

🧰 The tools

Beyond the crew and the commands there's a third kind of resource: tools. A command is something you invoke with a slash. A tool is something the crew reach for on their own, implicitly, when the intent of your prompt calls for it — never typed, never a slash command.

Tool	What it does
shipmates-termgif	Renders a polished animated terminal demo GIF of a workflow run from a small JSON spec
shipmates-social-card	Renders a 1280×640 social / Open Graph share card from a small JSON spec
shipmates-pixelart	Renders pixel-art icons — static PNG or animated GIF — the way the shipmates logo is made
shipmates-diagram	Renders a curated diagram — a flow/pipeline/state machine or a sequence of actors and messages — as a committed SVG, deterministic PNG, or animated GIF
shipmates-svgflow	Deprecated alias for shipmates-diagram — svgflow's flow diagram is now a kind of it
shipmates-badge	Renders a shields-style status badge as an offline, committed SVG
shipmates-sparkline	Renders a short number series as a tiny inline SVG trend chart
shipmates-scrub	Redacts secrets and PII from a log or paste before it's shared
shipmates-fixtures	Generates deterministic fake test data from a small JSON schema

Tools ship with a plain shipmates install. Use --with-tools none for crew + commands only, or --with-tools <name> for a subset. Add them with --with-tools (below), or run install in a terminal and pick from the list. Each tool maps to its harness's own native tool surface: a genuine code tool on opencode (.opencode/tools/<name>.ts), and an agent-invoked Agent Skill everywhere else — on Claude Code pinned agent-only with user-invocable: false, so it never appears as a slash command. Defined once in toolbox/<name>/, exactly like the crew and commands.

More tools are on the way. ⛵

---

⚓ Come aboard (install)

shipmates is a single Rust binary. Grab it any way you like:

macOS / Linux (Homebrew):

brew install saman-mb/tap/shipmates

Anywhere (Cargo):

cargo install shipmates

Binary Installer (cargo-dist):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/saman-mb/shipmates/releases/download/vX.Y.Z/shipmates-installer.sh | sh

Then install the crew. By default it drops into your global home directory. When --harness is omitted, shipmates install reports any detected harnesses as a hint, then prompts in a terminal (Enter = claude-code) or installs claude-code only when non-interactive — pass --harness NAME or --harness all to opt in. Global steering lands in home instruction files only on a global / $HOME install (not on --local / --dir). Use --local for the current directory, or --dir to target a specific project:

shipmates install                           # prompt / default claude-code; tools on a global target
shipmates install --harness claude-code     # the proven target
shipmates install --harness opencode        # live run recorded (partial); see harness_matrix
shipmates install --harness codex
shipmates install --harness claude-code --local
shipmates install --harness claude-code --dir /path/to/project
shipmates update                            # refresh every installed harness in place
shipmates update --harness claude-code      # refresh one harness; keeps its tools

Tools ship with a plain install. Pass --with-tools none for crew + commands only, or name specific tools to install a subset:

shipmates install --harness claude-code              # crew + commands + all tools
shipmates install --harness claude-code --with-tools termgif,scrub  # subset
shipmates install --harness claude-code --with-tools none  # crew-only
shipmates install --harness opencode --with-tools all      # same as omitting the flag

After you upgrade the shipmates binary (Homebrew / cargo), refresh an existing install with shipmates update — it overwrites payload files to match the new binary, keeps previously installed tools, and prints an upgrade summary. Payload digest regeneration for contributors stays on cargo run -- build --target <name> --update.

Which harnesses can you install? shipmates targets lists them — today all of:

claude-code      .claude/          agents + skills
opencode         .opencode/        agents + commands
antigravity      .agents/          agents + skills   (agy — the successor to the retired Gemini CLI)
codex            .codex/ + .agents/  crew (TOML) at .codex/agents, skills at .agents/skills
cursor           .cursor/          skills only (first-party tree; slash picker reads it)
github-copilot   .github/ + .agents/  crew (.agent.md) at .github/agents, skills at .agents/skills
pi               .pi/              crew (.md) at .pi/agents, skills at .pi/skills, crew switch at .pi/extensions/shipmates-crew/index.ts
grok-build       .grok/            agents + skills
devin            .devin/           agents + skills   (Devin CLI / Devin Desktop — formerly Windsurf)

Every harness compiles the same canonical crew and commands. Eight receive the thirteen specialists as agents; cursor ships the nineteen commands as skills only. Pi's crew resolve through the third-party pi-subagents extension — core pi documents no subagent schema of its own — so a pi install without that extension resolves no crew. Pi reads its crew from the nearest ancestor directory carrying .pi/ or .agents/, so install into your project: a home-directory install only takes effect when no nearer ancestor carries either. Three harnesses (codex, antigravity, github-copilot) read the open Agent Skills location .agents/skills/, so their skills are rendered once, in a neutral dialect, and shared there — one source of truth, byte-identical, so a multi-harness repo gets a single copy instead of colliding ones. Their crew still land in each harness's own native format. cursor reads that open tree too, but only its first-party .cursor/skills/ reaches the slash-command picker, so its skills ship there and nowhere else — one copy, never two. claude-code keeps its own .claude/skills/, and devin its .devin/skills/. pi and grok-build keep their own native skill trees (.pi/skills/ and .grok/skills/): their commands ship native guards (disable-model-invocation: true, tool scoping, and /skill: command routing on Pi), which the neutral dialect the shared tree carries does not express.

opencode quickstart

Install opencode's native payload into a project, then inspect its two load paths:

shipmates install --harness opencode --dir /path/to/project --with-tools none
cd /path/to/project
ls .opencode/agents .opencode/commands
opencode agent list
opencode run --command shipmates-harden --format json \
  "Review this project in report mode. Do not modify files."

The agent list should include all thirteen Shipmates roles. The report-mode command is a narrow manual probe; keep --auto disabled. Deterministic CI install-fidelity tests check all thirteen installed agents and commands, the exact opencode golden payload, and the translated report-only /shipmates-harden order. They do not use model credentials and do not claim that opencode runtime behavior is fully verified. A captain-attested live run is recorded as runtime_verified.status = partial (#497); those CI smokes do not fill the unknown cells or promote past partial. Full crew resolution, argument passing, permission enforcement, and parallel board execution are not separately recorded for opencode, and the flagship tickets #31 and #32 are closed — this stands as attestation, not a Tier-A /shipmates-ship-issue proof.

One caveat worth knowing before you pick Codex: it documents no per-agent tool allowlist, so its crew inherit whatever the session can do rather than the least-privilege set every other target enforces. Each harness records its evidence, and the date it was checked, in tools/harness_matrix.json. Each harness install writes a receipt at <target>/.shipmates/receipts/<harness>.json. It records Shipmates version, harness, layout, and every file Shipmates owns with its SHA-256 hash. Reinstalling the same payload skips unchanged files and creates backups only for changed files. Files outside the receipt are unmanaged: Shipmates warns and leaves them alone — the scan covers the payload's own subtrees and does not walk harness runtime dirs (sessions, plugins, synced).

A file already sitting at a path the payload writes is decided by what it says it is. One whose frontmatter names the artifact installed there is a Shipmates file that fell out of ownership: install and doctor --fix adopt it — back it up, write the current payload, claim it in the receipt. Anything else is yours, so install stops and names shipmates install --force, which backs each one up and replaces it. Install preflights one harness and rolls back payload changes if payload or receipt publication fails; --harness all is not globally atomic — a failed harness leaves the others installed, prints a per-harness summary, and exits non-zero.

Which payload gets installed. A released shipmates installs the crew and commands compiled into the binary, whatever directory you run it from. Running cargo run -- install inside a Shipmates checkout uses that checkout — the contributor loop. To install from any other source tree, ask for it explicitly with --from-cwd, or point SHIPMATES_SRC=/path/to/checkout at one; either way a directory without crew/ and commands/ is an error, never a quiet fall back to the embed. Pass the same flag to uninstall and doctor so they recognise the payload you installed.

shipmates uninstall reads that receipt. It defaults to the global home directory; use --local or --dir /path/to/project for another root. With exactly one valid receipt, --harness is optional; multiple valid receipts require --harness. An explicit missing or invalid receipt fails closed, and an invalid sibling receipt also blocks discovery. No receipt directory means nothing to uninstall. It removes only receipt-owned, unchanged files and preserves unmanaged files. Modified or unreadable files retain the receipt. The receipt is the ownership record — never remove a whole harness tree to uninstall.

Check an install with shipmates doctor. Run shipmates doctor for a read-only health report against the global home directory and the claude-code harness by default. Pass --harness to check another harness, or use --local / --dir /path/to/project for another root; doctor does not discover harnesses from receipts. It checks the harness tree, receipt ownership, missing files, modified or unreadable files, agent tool vocabulary resolution, shared-tree dialect isolation, user-scope global steering status, and an old commands/<name>.md layout shadowing a skill. A missing receipt warns that ownership is unknown; existing files stay untouched and only genuinely missing payload files may be restored. An invalid receipt is a problem, and doctor --fix refuses ownership-based repair. doctor --fix repairs receipt-owned files only, backing up existing files it replaces or migrates under .shipmates-backup/ first. A plain install also migrates a receipt-owned superseded command layout and identity rename (polish and shipmates-polish → shipmates-polish) as it writes; pass --no-migrate to leave old files in place. For doctor, --no-migrate is valid only with --fix: shipmates doctor --fix --no-migrate restores files without migrating old command names.

Codex quickstart. From a Shipmates checkout, run this layout/install smoke. It creates a temporary sandbox, checks the Codex golden digest, installs the payload, and diagnoses the receipt-backed install:

bash tests/test_codex_smoke.sh

With an authenticated local Codex CLI, add CODEX_SMOKE=1 to run the optional read-only shipmates-harden skill headlessly in that temporary sandbox:

CODEX_SMOKE=1 bash tests/test_codex_smoke.sh

The CI smoke is deliberately layout/install-only; neither path is itself the runtime proof — Codex is partial on a captain-attested live run (2026-09-20, #510 close), and its granular cells stay unknown until separately logged. See the Codex quickstart.

Why opencode gets commands/ and not skills/. opencode has both, and they are not the same thing: its skills are model-invoked — it loads one on demand through a native skill tool — and disable-model-invocation is not a frontmatter key a SKILL.md recognises there, so declaring it would be silently dropped. The nineteen create worktrees, push branches and open pull requests, so shipping them as skills would let the model start one unprompted. commands/ is /-invoked only, which keeps user-invoked-only structural rather than dependent on a key the target ignores.

Least privilege still holds, by inversion. opencode's defaults are permissive — effectively "*": "allow" — so listing the tools a role needs would grant nothing. Each generated agent emits a "*": deny catch-all first and its specific allows after; opencode resolves permissions last-match-wins, so the ordering is the mechanism. The result is marginally stronger than Claude's allowlist: a tool a wildcard denies is hidden from the model rather than refused at call time.

⚠️ Runtime status is per harness in tools/harness_matrix.json → runtime_verified. Claude Code is full (crew, arguments, /shipmates-ship-issue end to end). opencode, Antigravity, Cursor, Pi and Codex CLI have captain-attested live runs (partial — Pi crew_resolve/command_e2e are no per #525, closed 2026-09-21; other granular cells may still be unknown). GitHub Copilot, Grok Build and Devin remain format/digest-verified only — Copilot is the crew-bearing target still without a live run. The opencode flagship tickets #31 and #32 are closed.

🔁 First time a skills/ or agents/ dir got created? Restart your harness so it spots them.

The exporter foundation

Portability work starts from the canonical commands/ and crew/ sources: full persona/workflow bodies, semantic crew capabilities, and harness-neutral prose that names abstract locations (agent-files/*.md, Harness-Session) and {{arguments}} instead of any harness's dialect. A per-harness render layer rewrites that prose into each harness's real dialect — where its agents live, what its session metadata is called, which project-instructions file it reads (CLAUDE.md, AGENTS.md), and how a role is spawned — and an adapter emits the harness's frontmatter shape. The published site is generated from the rendered Claude Code payload, never the neutral source.

Build, check, or regenerate the reference digests:

cargo run -- build --target claude-code --out /tmp/shipmates-build
cargo run -- check --target claude-code
cargo run -- build --target claude-code --update   # regenerate reference digests

tools/capability_registry.json is the semantic-to-harness tool map — including the scopes map each adapter uses to honour role-level refinements. art-director declares web-scopes: search once, and gets WebSearch without WebFetch on Claude Code and websearch: allow without webfetch on opencode. tools/manifest.json declares every implemented target; an unknown target is refused on that declared status, not on a hardcoded name in the exporter.

🚀 Weigh anchor (use it)

/shipmates-ship-issue 42

Then go get a coffee ☕. It plans, spins up a worktree, builds, waits for CI to go green, convenes the board, loops on fixes, and hands you a reviewed PR. By default it stops at the PR for you to merge — set MERGE_MODE=auto if you want it fully hands-off in a repo where that's fair game.

---

🛠️ How the voyage works

/shipmates-ship-issue isn't a clever prompt — it runs a structured workflow with explicit quality gates:

1. Plan 🗺️ — a planner reads the issue + your docs → build plan, acceptance criteria, validation plan, and flags for which specialists this story needs.
2. Design specs ✏️ (only if needed) — for UI / visual / architecture-heavy stories, the right specialist writes a spec the builders must build to.
3. Isolate 📦 — all work in a throwaway git worktree; your base branch never breaks.
4. Build 🔨 — parallel senior-engineer builders with non-overlapping file ownership.
5. Self-check → CI gate 🚦 — the SDET runs the tests; then CI must go green on the pushed PR before anything moves on. Red? It reads the logs and fixes — bounded to a few rounds.
6. Acceptance board ⚖️ — product-manager + sdet (+ gated ux-ui-designer / art-director / architect) review the pushed PR head, independently and adversarially.
7. Remediate 🔁 — any rejection loops back to a fixer, then re-selects the board from that delta: failers sit again, prior ACCEPTs carry unless the delta can invalidate them, and a seat the delta newly trips may join. Bounded, then escalates.
8. Deliver 🏁 — disposes non-blocking nits absorb-first (fix cheap ones in the same PR; file only capped/batched leftovers), names a /shipmates-harden follow-up if the change touched a security-relevant surface (this board doesn't threat-model), and opens (or, opt-in, merges) the PR.

The tricks that make the loop hold together:

• 🎯 Explicit gates over wishful thinking. Stages converge on checkable work and green CI.
• 📦 An isolated sandbox. Autonomy is only safe when the blast radius is zero.
• 🚦 Objective gates over vibes. Green CI beats "looks done to me."
• 👥 Reviewers can't grade their own homework. A fresh agent reviews the PR — never the builder.
• ⏱️ Bounded loops. Retry N, then tap the human. A loop with no cap just spins.
• 🎟️ Capture, don't block. Nits become tickets, not roadblocks.

🧭 Examples — putting the crew to work

Ship a single ticket, hands-off to a reviewed PR:

/shipmates-ship-issue 142

The planner reads issue #142 and your README; a senior-engineer builds it in a worktree; CI has to go green; then a product-manager and sdet review the pushed PR — a ux-ui-designer or art-director joins automatically if the story is UI or art. Fixes loop until they pass, and you get a reviewed PR to merge.

Ship it fully autonomously (merge included), where that's acceptable:

MERGE_MODE=auto /shipmates-ship-issue 142      # or just say "auto-merge" in the prompt

Turn a one-line brief into a tracked backlog:

/shipmates-plan-epics "User accounts: signup, login, password reset, and a profile page"

A product-manager scopes it into an epic, drafts INVEST user stories with acceptance criteria, and files them as linked, labelled GitHub issues — ready to hand to /shipmates-ship-issue one at a time.

Break a big vision into several epics at once (fan-out):

/shipmates-plan-epics ./docs/product-brief.md

When the brief spans multiple epics, one product-manager subagent per epic drafts its stories in parallel, then everything is created and cross-linked.

Preview a backlog without creating anything:

/shipmates-plan-epics "checkout + payments + order history"  — dry run

Polish a UI screen until it's actually right:

/shipmates-polish the settings screen

The ux-ui-designer reviews the rendered screen (not the code), lists concrete fixes, a senior-engineer applies them, it re-renders, and the loop repeats until the designer signs off — or hands you the outstanding notes after a few rounds. It never writes to your checkout: it decides where the polish should land, not where you happen to be standing. Already inside a worktree — the one /shipmates-ship-issue left behind, say — it stays put and reuses it, refusing if the tree is dirty. On a feature branch whose PR is already open, it works in a detached worktree and pushes back onto that branch, so the polish joins the PR you already have instead of opening a second one. Otherwise it cuts a polish/<slug> branch from HEAD and opens a PR of its own.

Polish rendered art the same way:

/shipmates-polish the title-screen background — reviewer: art-director

Same loop, but the art-director judges the actual render — palette, composition, contrast — round after round until it meets the bar.

Fix a bug — proven, not just patched:

/shipmates-fix-bug 213

A failing regression test is written first to reproduce #213; a senior-engineer root-causes and fixes it; the test flips red→green while the suite stays green; a fresh reviewer confirms it's the root cause, not the symptom. You get a PR with the proof attached.

Threat-model and harden a surface:

/shipmates-harden the auth + session flow

The security-engineer walks it with STRIDE / OWASP and ranks findings by severity with the exploit path. That pass is read-only — it reports, it doesn't touch your tree. Ask for the fixes (MODE=pr) and a senior-engineer remediates the blockers on a branch, re-reviewing until nothing Critical/High is left open, then hands you a CI-gated PR.

De-risk a decision before committing to it:

/shipmates-spike "job queue: Redis vs Postgres vs SQS"

Engineers prototype each option in parallel as throwaways, an architect judges them against your real constraints (weighing reversibility), and you get a recommendation recorded as an ADR — not a hunch.

Sweep a migration across the whole codebase:

/shipmates-migrate "moment.js → date-fns"

Every call site is inventoried, transformed in isolation, verified, and the run only closes when a re-grep for the old pattern comes back empty and the suite is green. Nothing left half-migrated.

Write docs that actually work:

/shipmates-document the getting-started guide

The technical-writer drafts from the real code, then a fresh agent follows the steps against the repo like a newcomer — the docs ship only once that reader reaches the result. No drift, no dead ends.

Cut a release safely:

/shipmates-release minor

The changelog is assembled from what actually merged, the version is bumped, CI must be green on the exact tagged commit, and the site-reliability-engineer checks rollback + migration safety before it's tagged.

Chain them — scope the work, ship a story, polish its UI:

/shipmates-plan-epics "settings redesign"     # → creates the epic + stories
/shipmates-ship-epic 42                       # → ships every story in epic #42 (or pauses at gates)
/shipmates-ship-issue next epic 42            # → ships the next unchecked story in epic #42 only
/shipmates-polish the settings screen         # → iterates the visuals to sign-off

Run that third step from the worktree /shipmates-ship-issue left behind (../<repo>--issue-148), so the polish lands on the same branch. Started from your base branch, /shipmates-polish would begin from a baseline that doesn't contain the new screen yet.

🗂️ Scopes & precedence

In Claude Code, both ~/.claude/ (global, every project) and <repo>/.claude/ (that project only) are loaded. The two halves of the crew then resolve a name clash in opposite directions:

• Subagents — the project copy wins. <repo>/.claude/agents/architect.md overrides ~/.claude/agents/architect.md, so any repo can specialise a crew member without touching the shared copy.
• Skills — the personal copy wins. ~/.claude/skills/shipmates-ship-issue/SKILL.md overrides <repo>/.claude/skills/shipmates-ship-issue/SKILL.md. If you have installed globally and into a project (via --dir), the global command is the one that runs — uninstall the one you don't want rather than editing the loser.

A skill also beats a legacy .claude/commands/<name>.md of the same name.

Other harnesses resolve clashes on their own rules, so read this as a Claude Code fact, not a universal one.

🎒 What you'll need

• A supported harness (Claude Code is the proven one; the others build and are format-verified)
• git + an authenticated gh CLI, for the GitHub flow
• A repo with CI (strongly recommended — the green-CI gate is what makes autonomy trustworthy)

💡 Why it's built this way

• Agents are generic; your project supplies the bar. No role name-drops a stack or product — it enforces whatever your README/CLAUDE.md says. That's what makes the crew reusable everywhere.
• A loop is only as smart as its ground-truth signal. Tests and CI are solid gates; taste isn't — so the visual specialists flat-out flag "needs a human visual pass" when they can't render.

🌊 On the horizon

Where each harness stands. Every target's payload is compiled and digest-checked in CI; the question is whether it's been run.

• Runtime-verified (full) — Claude Code: the full crew and all 19 commands, with crew resolve, argument passing, and /shipmates-ship-issue proven end to end.
• Live run (partial) — opencode, Antigravity CLI, Cursor, Pi and Codex CLI: captain-attested live runs recorded in tools/harness_matrix.json under runtime_verified (2026-09-18, #497; Codex 2026-09-20, #510 close / #46). Granular cells (crew_resolve, argument_passing, command_e2e) stay unknown where they were not separately logged — attestation is not Tier-A proof. Pi's crew_resolve and command_e2e are no (#525, closed 2026-09-21 and recorded via #535); argument_passing is still unknown.
• Builds, not runtime-verified (none) — GitHub Copilot, Grok Build and Devin build from shipmates install --harness <name>, and each payload's format was verified against that harness's parsing source and first-party docs, but no live run is recorded. Copilot is the one crew-bearing target still without a live run (#41). The Gemini CLI is retired — the Antigravity CLI (agy) is its successor and reads .agents/, so that is the target Shipmates builds for.

Crew vs skills (payload shape, independent of runtime status). opencode, Antigravity, Codex CLI, GitHub Copilot, Pi and Grok Build get the full crew + all 19 commands (Pi's crew land at .pi/agents/ and resolve through the third-party pi-subagents extension; Grok Build's land at .grok/agents/); Cursor ships the 19 skills only.

Why that's credible: the crew's system prompts name no harness, and the nineteen commands ship in the Agent Skills open-standard shape rather than a Claude-specific one — so most of a port is mapping frontmatter fields and rendering dialect tokens, not rewriting the crew. The opencode adapter is the first test of that claim: it reused every persona and workflow body unchanged, and the work that remained was path mapping and translating Claude's tool allowlist into opencode's permission map.

The crew also keeps signing on (a data-engineer, an ml-engineer, a mobile-engineer…) and new commands keep shipping. Want a role or a workflow aboard? Open an issue — ideas and PRs very welcome.

❓ FAQ

What is Shipmates? A ready-made crew of subagents and command workflows. Instead of you playing planner–builder–reviewer in a loop, a board of specialist AI agents does it — the flagship /shipmates-ship-issue takes a GitHub issue all the way to a reviewed, CI-green pull request. It ships for nine harnesses — Claude Code, opencode, Antigravity CLI, Codex, Cursor, GitHub Copilot, Pi, Grok Build, and Devin; see on the horizon for where each harness stands.

What are Claude Code subagents and skills? Subagents are focused AI agents defined in .claude/agents/*.md; skills are reusable workflows defined in .claude/skills/<name>/SKILL.md and invoked as commands, like /shipmates-ship-issue. Shipmates ships 13 agents and 19 commands you drop into a repo's .claude/ with shipmates install (or .opencode/ for opencode, .codex/ for codex, and so on). See install.

Is this an official Anthropic project? No. Shipmates is an independent, MIT-licensed community project that builds on Claude Code's public subagent and skill features. "Claude" and "Claude Code" are trademarks of Anthropic.

How is it different from just prompting Claude Code? A raw prompt drifts; Shipmates combines an isolated worktree, a mandatory green-CI workflow gate, fresh review, and explicit acceptance criteria so an autonomous run converges instead of wandering. Stage judgment and reviewer acceptance remain orchestrator responsibilities. See how the voyage works.

Which languages and frameworks does it work with? Any. The agents are domain-neutral — they enforce the standard in your repo's README / CLAUDE.md, so the same crew works on a game engine, a web app, or a CLI.

Do I have to configure each agent? No. Install once, then /shipmates-ship-issue 42. The crew picks up your project's quality bar automatically; a project-level .claude/agents/ definition overrides the global one when you want to specialise a crew member. Skills go the other way — see scopes & precedence.

🤝 Contributing

See CONTRIBUTING.md. The one hard rule: keep agent roles domain-neutral so they sail on anyone's project.

📄 License

MIT — take it, fork it, crew up. 🚢