Troubleshooting

Cause: the binary isn't on your PATH. cargo install puts binaries in ~/.cargo/bin, which some shells don't add. Fix: run cargo install shipmates again to confirm it succeeded, then check ls ~/.cargo/bin/shipmates and add ~/.cargo/bin to PATH (e.g. echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc and restart).

Cause: the harness name isn't one the CLI knows. Fix: run shipmates targets for the canonical list: claude-code, opencode, antigravity, codex, cursor, github-copilot, windsurf.

Cause: shipmates install writes into the global home directory by default — claude-code files go to ~/.claude/, not the current directory. Fix: pass --local for the current directory, or pin the root with --dir /path/to/project. Verify with ls .claude/agents and ls .claude/skills.

Cause: your harness scans its directories at startup, so a first-time install isn't visible to an already-running session. Fix: restart the harness. If they still don't load, verify the files landed where you expected (see Verify in the install reference) and that skills/<name>/SKILL.md exists — the skill's frontmatter name: must equal its parent directory name.

Cause: you ran the install from a Shipmates checkout that is behind the binary, so shipmates --version and the payload disagreed. Fix: a current binary installs the payload compiled into it from any directory — re-run the install anywhere. To install from a checkout on purpose, ask for it: shipmates install --from-cwd inside the checkout, or SHIPMATES_SRC=/path/to/checkout shipmates install. A directory without crew/ and commands/ is an error rather than a silent fall back, and an ignored checkout in the current directory prints a warning naming the version it was ignored for.

Cause: a file that is not a Shipmates artifact sits at a path the payload writes, so the install stopped before changing anything. Fix: move the named files aside and re-run, or run shipmates install --force to back each one up (a sibling .bak-…) and replace it. A file whose frontmatter name: matches the artifact installed there needs neither: install and shipmates doctor --fix adopt it automatically. Skills of your own that are not payload paths are never touched.

Cause: shipmates before v0.1.16 scanned the whole harness root for unmanaged files and stopped on a package manager's symlink. Fix: upgrade. From v0.1.16 the scan is bounded to the payload's own subtrees, skips symlinks, and never walks node_modules, so a harness root that doubles as your runtime installs cleanly.

Cause: one harness failed; the others installed. The run is not transactional and exits non-zero so the failure is not lost. Fix: read the harness summary at the end of the output — every target reports either the version it installed or why it failed — then fix that cause and re-run just that harness with shipmates install --harness <name>.

Cause: the skill isn't where the harness looks, or its identity broke — the Agent Skills standard requires the frontmatter name: to equal the parent directory name, so skills/ship-issue/SKILL.md must declare name: ship-issue. Fix: check ./.claude/skills/ship-issue/SKILL.md exists and that the harness is pointing at this project's .claude/. Missing → re-run shipmates install. Hand-edited name: → restore it to match the directory.

Cause: the thirteen install as .opencode/commands/<name>.md (flat files, /-invoked) rather than skills, and agents land in .opencode/agents/. If files are missing, the install went to a different root than opencode reads. Fix: confirm .opencode/commands/ship-issue.md and .opencode/agents/sdet.md exist, then restart opencode. Note the payload is format-verified but not runtime-verified — see the harness matrix.

Cause: Codex keeps crew and skills in separate trees. Fix: confirm .codex/agents/sdet.toml exists for crew and .agents/skills/ship-issue/SKILL.md exists for skills, then restart Codex. The payload is format-, golden-digest-, and install-verified, but not runtime-verified; use the Codex quickstart for the optional read-only harden skill check.

Cause: by design. Those four harnesses have no documented native subagent directory, so only the thirteen skills land — the crew is dropped entirely. Fix: not a bug; the workflows themselves are still available via /<command>.

Cause: a command's instructions reference the project-instructions file your harness actually reads — CLAUDE.md on Claude Code, AGENTS.md on most others. An install targeted at the wrong harness gets the wrong dialect. Fix: uninstall the wrong tree and re-run shipmates install --harness <correct-name>. The rendered body tells you which file the harness reads.

Check it: run shipmates doctor (global home and claude-code by default; use --harness, --local, or --dir /path/to/project to select another harness or root). Doctor does not discover harnesses from receipts. It reports, in a plain pass/attention list, whether the harness tree is present, whether expected files are missing, whether installed files are modified or unreadable. Doctor is read-only — it never changes anything until you ask. A missing receipt reports unknown ownership and preserves existing files; an invalid receipt is a problem and --fix refuses repair. Fix it: run shipmates doctor --fix and it repairs receipt-owned files only, backing up replacements under .shipmates-backup/. Receipt-owned legacy commands may be migrated; unowned legacy files remain. --no-migrate requires --fix: use shipmates doctor --fix --no-migrate to restore files while leaving a superseded commands/<name>.md in place. Doctor exits non-zero when a problem remains, so it slots cleanly into a script or CI check.

Cause: the canonical sources (commands/ + crew/) changed, so the fresh payload no longer matches its committed reference digest in tests/payload-digests/<name>.sha256. Those digests are regression fixtures — never hand-edit them. Fix: after an intentional source change, regenerate every target's digest with cargo run -- update --target <name> (per target) or cargo run -- build --target <name> --update, and commit them together with the change.

Cause: on a skill-only harness (codex, cursor, github-copilot, windsurf) the payload emits only the Agent Skills standard's name/description pair — vendor keys like allowed-tools or disable-model-invocation are dropped because a strict parser would reject them. That is deliberate, not a bug. Fix: if the workflow depends on a vendor key, the harness can't express it; that's a reason to prefer a harness that can.

Cause: --harness selects the tree, and the default is claude-code — a forgotten flag installs there. Fix: run shipmates targets to list the names, then reinstall with the correct --harness. If the tree is the right harness but looks stale or partly missing — say after an upgrade — reach for shipmates doctor --fix first: it restores the missing and drifted files (backing up whatever it changes) instead of removing anything. The install receipt records the harness and layout for uninstall, so uninstall does not need a guessed --harness.

Run shipmates uninstall. It defaults to the global home directory and reads <target>/.shipmates/receipts/<harness>.json; one valid receipt permits omitted --harness, while multiple valid receipts require it. Missing or invalid receipts fail closed; no receipt directory is a no-op. It removes only receipt-owned files whose hashes still match. Modified, unreadable, and unmanaged files trigger warnings and remain untouched. Use --local or --dir /path/to/project when the install is not in the global home directory. Do not use rm -rf on the whole harness tree.