Agent Instructions for Shipshape

This repository contains the Shipshape skill package. These instructions are for agents editing this repository, not for projects using Shipshape.

Agents using Shipshape should treat this entire repository as Captain/human-owned material, like assets/** in an adopting project: edit it only when explicitly asked, and do not treat it as disposable implementation or verification.

Scope

Shipshape is distributed as skill files:

Editing rules

• Keep repository guidance separate from downstream Shipshape usage guidance.
• Put public positioning in README.md.
• The README slogan is "Specifications are durable. Code is disposable. Agents are replaceable." It is a slogan, not doctrine. Keep it punchy. Do not rewrite it to match skill wording; the skills carry the precise three-layer doctrine.
• Put shared workflow rules in skills/shipshape/SKILL.md.
• Put role-specific rules in the matching role skill.
• Keep all role skills consistent with the Articles of Agreement in skills/shipshape/SKILL.md.
• Role skills are structured as jobs. A role's work divides into jobs. A job is entered by dispatch or by completion of the preceding job, and discovers work through exactly one retrieval: one question asked of one source, yielding one worklist. A job polices the quality of its own retrieval and of its own writes. Proof runs are execution, not retrieval. Incidental findings surfaced by a job's own work route by the Blocker policy; a duty that hunts through a second retrieval is a defect.
• A role duty MUST belong to a job, name its trigger in the role's walkthrough, read only evidence its job's retrieval or execution puts in front of it, and load no more context than its decision needs. Mechanize, move, or delete a duty that fails any of these.
• shipshape.md is a structural map: names, relations, and pointers only. A normative sentence in it is a defect. Update it with any rename it references; tests/map.sh checks the names against the skills.
• Bump the version in .plugin/plugin.json with any doctrine change, skill content included, not only a plugin-layer change to .plugin/, agents/, hooks/, commands/, assets/, or shipshape.md. A plugin-channel install's update tooling was observed gating on this version field rather than skill content hash; an unbumped skills-only change risks silent staleness for every plugin-channel consumer.
• Enforcement claims are per-runtime. Claim a mechanism for a runtime only after live-fire verification on that runtime; name unverified runtimes unsupported for enforcement.
• Skills alone MUST fully instruct agents. The plugin layer (.plugin/, agents/, hooks/, rules/) only mechanizes or restates what skill text already states. Every plugin artifact cites the skill text it enforces. Adding behaviour to the plugin layer that the skills do not state is a violation; fix the skill first, then mechanize it. Deleting the plugin layer must lose nothing but enforcement.
• Use Shipshape Controlled English in skill files: short sentences, precise subjects, RFC 2119 terms where useful, and Canadian spelling such as behaviour. Use artifact, not artefact.
• The README Ship of Theseus section is the only text with relaxed Controlled English rules, for literary effect. Every other file follows Controlled English in full, including the punctuation rules: no em dashes and no parenthetical asides.
• Do not add project-specific assumptions from Jolly, Saleor, or other adopters to shared Shipshape rules.
• Do not create binding repository artifacts such as roadmaps, memory banks, decision logs, constitutions, or task lists unless the user explicitly asks.
• Do not update installed global skills or downstream project copies unless the user explicitly asks.
• Do not commit or push unless the user explicitly asks.

Plugin format

The repository is vendor-neutral. It carries no runtime-specific support. Downstream runtimes and installers add their own vendor layers; Shipshape ships only the generic minimum.

The core is skill-only, which is the widely portable form. Install it with npx skills add, which works across most agent runtimes. The optional plugin layer follows the vendor-neutral open-plugin specification. That format is experimental and its adoption is uncertain, so treat it as early-adopter support and keep it generic.

• Docs: https://open-plugins.com/
• Spec: https://github.com/vercel-labs/open-plugin-spec
• Installer: https://www.npmjs.com/package/plugins, run as npx plugins add dmytri/shipshape

Rules that follow:

• Keep every plugin artifact vendor-neutral. Use no runtime-specific variable, path, directory, or manifest anywhere in the repository.
• The manifest lives at .plugin/plugin.json, the spec-required path and the installer's source of truth. Component directories such as skills/, agents/, hooks/, and commands/ live at the plugin root, never inside .plugin/.
• Do not add a vendor manifest at a .<vendor>-plugin/plugin.json path. On install, npx plugins add copies .plugin/ to each vendor directory, generates the vendor marketplace file, and registers the plugin in the runtime settings. That translation is downstream, not in this repository.
• hooks/hooks.json uses the neutral ${PLUGIN_ROOT}. The installer rewrites it to each runtime's own plugin-root variable at install time. Do not hardcode a runtime-specific variable.

Commit attribution

Do not add agent-specific authorship, committer identity, or Co-authored-by trailers for coding agents. Commits should use Dmytri Kleiner <dev@dmytri.to> unless the maintainer explicitly instructs otherwise.

Validation

Before reporting a documentation change as complete:

• run diagnostics for changed Markdown files when available;
• search for stale names or project-specific leakage when relevant;
• check git diff for accidental duplication or unrelated edits.