shipshape AGENTS.md

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:

Path	Purpose
skills/shipshape/SKILL.md	Shared workflow rules and project setup templates
skills/captain/SKILL.md	Captain role skill
skills/qm/SKILL.md	Quartermaster role skill
skills/crew/SKILL.md	Crew Mate role skill
skills/boatswain/SKILL.md	Boatswain role skill
skills/shipwright/SKILL.md	Shipwright role skill
skills/shipwright/templates.md	Fitting-out scaffold templates: RIGGING.md, AGENTS.md, README block
.plugin/plugin.json	Vendor-neutral plugin manifest
agents/	Role agents for context isolation (thin adapters over role skills)
hooks/	Custody enforcement hooks (mechanize Article text only)
commands/	Plugin slash commands (derived-state reporting and install diagnostics, no doctrine)
rules/	Open-plugin rule files (.mdc): cited role checklists restating skill text, no added doctrine
CAPTAIN.md	Captain-only non-binding notes for this repository's own Shipshape work
assets/logo.svg	Plugin logo
tests/	Hook behaviour, map drift, style, doctrine-home, and bulkhead conformance tests
README.md	Public project positioning and usage overview
llms.txt	Agent-facing index of canonical files (pointers only, no doctrine)
shipshape.md	Structural orientation map (names, relations, pointers; non-normative)
skills.sh.json	skills.sh registry metadata
AGENTS.md	Repository-local agent instructions

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.