shipcraft 2.14.0 → 2.17.0

package/README.md

@@ -54,10 +54,12 @@ Every refusal is three lines: **what happened, why it matters, and the next step
 
 ## Quick start
 
+Installing is two steps: add the package (or the binary), then run `shipcraft init` in the project. Until `init` runs, nothing checks your commits.
+
 ```bash
 # A Node/TypeScript project (macOS): pin Shipcraft in the project, like any dev dependency
-pnpm add -D shipcraft          # or: npm i -D shipcraft
-pnpm exec shipcraft init       # the hooks call this project's install
+pnpm add -D shipcraft          # step 1, or: npm i -D shipcraft
+pnpm exec shipcraft init       # step 2, or: npx -- shipcraft init; the hooks call this project's install
 
 # macOS (Apple silicon or Intel), any language: the latest release, checksum-verified, into ~/.local/bin
 gh repo clone victorassisalves/shipcraft && bash shipcraft/install.sh
@@ -67,18 +69,30 @@ git clone https://github.com/victorassisalves/shipcraft && cd shipcraft
 cargo install --path nucleo
 ```
 
-`install.sh --version <v>` pins a version and `install.sh --uninstall` removes the binary. It needs `gh` logged in.
+`install.sh --version <v>` pins a version and `install.sh --uninstall` removes the binary. It needs `gh` logged in. With the npm install, `shipcraft` is not on your `PATH`: run it through the project (`pnpm exec shipcraft …` or `npx -- shipcraft …`).
 
-Then, in your project:
+With `install.sh` or `cargo install`, step 2 is, in your project (`install.sh` puts the binary in `~/.local/bin`; if that folder is not on your `PATH`, run `export PATH="$HOME/.local/bin:$PATH"` first, or add it to your shell profile):
 
 ```bash
 shipcraft init          # detects the language, writes .shipcraft.toml, wires the hook
-git add .shipcraft.toml && git commit -m "add shipcraft"
 ```
 
-A cycle:
+Either way, `init` ends with the files to commit (`shipcraft: ready. Commit …`): `.shipcraft.toml`, `.shipcraft/`, and the hook manager's file and `AGENTS.md`/`CLAUDE.md` when it wrote them. Commit all of them, plus `package.json` and its lockfile with the npm install:
+
+```bash
+git add .shipcraft.toml .shipcraft    # plus every other file init listed (AGENTS.md, CLAUDE.md, the hook manager's file),
+                                      # and package.json with pnpm-lock.yaml or package-lock.json
+git commit -m "add shipcraft"
+```
+
+Git does not commit hooks: every other clone installs the dependencies and runs `init` once (or the hook manager's install). Until then nothing runs at its commits, and CI is the backstop.
+
+A cycle (with the npm install, run each `shipcraft` command through the project's install, from the repository root: `pnpm exec shipcraft red` or `npx -- shipcraft red`; `git` stays as is):
 
 ```bash
+# work on a branch: `shipcraft pr` refuses the default branch
+git switch -c invoice-rounding
+
 # RED: write the failing tests, then lock them
 shipcraft red
 git add -A && git commit -m "red: invoice rounding"
@@ -86,15 +100,21 @@ git add -A && git commit -m "red: invoice rounding"
 # GREEN: write the code; commit as often as you like
 git commit -am "fix rounding"      # the lock closes on the first fully green commit
 
-# open the PR: CI and review run, and their statuses are published
+# open the PR (needs a GitHub remote named origin and gh logged in): CI runs, then the review
+# when an agent is configured (init turns review off if it finds no codex, claude or gemini),
+# and their statuses are published
 shipcraft pr --title "Invoice rounding"
 
-# merge only when both are green
+# merge only when CI is green and the review approved (or is off)
 shipcraft merge 42
 ```
 
 `shipcraft status` shows the open locks and how protected the repository really is.
 
+Without a GitHub remote, the cycle still works up to the commits: `red`, the hook and `shipcraft ci --base <ref>` run locally; `pr` and `merge` need GitHub.
+
+Upgrading: with the npm install, `pnpm add -DE shipcraft@latest` (or `npm i -D --save-exact shipcraft@latest`) and commit `package.json` with the lockfile; every clone then gets the same version. To go back, pin the previous one exactly: `pnpm add -DE shipcraft@<version>`, and commit both files again. With `install.sh`, run it again, or `install.sh --version <version>`. A version older than the config's `shipcraft_min` refuses to run: going back past it also means lowering `shipcraft_min` in `.shipcraft.toml`, with no lock open. Release notes say which version to go back to when a release changes something you may want to undo.
+
 ## Commands
 
 | Command | What it does |
@@ -149,6 +169,8 @@ Two rules keep the config honest:
 - **The config is part of the lock.** It can't change while a lock is open.
 - **A PR is judged by the config on the base branch,** not by its own. A PR can't switch off its own review.
 
+**Adding a package with a new suite.** Once the base branch has a `.shipcraft.toml`, a `[[suite]]` added in the same PR as its first tests doesn't run in CI, and `shipcraft ci` refuses its locked cases as missing. Bring the suite first, in a PR of its own: the package, its `[[suite]]` entry and one passing test. Once that's merged, rebase and write the RED. `shipcraft red` warns when changed test files match no suite's globs, or when the lock has cases in a suite the base doesn't have.
+
 A layer that is switched off is labeled "off in .shipcraft.toml" on every PR, so nobody mistakes it for a check that ran.
 
 ## The layers
@@ -175,7 +197,9 @@ Every rule in Shipcraft has to pay for itself. It ships with the metric that jus
 Agents don't need a plugin, an MCP server or a skill. They find Shipcraft the same way they find every other project constraint:
 
 - `git commit` runs the hook, and refusals say exactly what to do next;
-- `shipcraft init` writes a short block in `AGENTS.md` that tells agents to run `shipcraft red` after writing tests. In our trials (four runs per arm, a small sample) this took agents from 0/4 to 4/4 running `shipcraft red` before the first commit.
+- `shipcraft init` writes a short block in `AGENTS.md` that tells agents the cycle: write the failing test and stub, run `shipcraft red`, commit the tests with the lock, then implement. In our trials (four runs per arm, a small sample) the earlier block took agents from 0/4 to 4/4 running `shipcraft red` before the first commit.
+- Since 2.17, the block also asks for the RED and the GREEN in separate sessions (a subagent per phase in Claude Code, a new `codex exec` per phase in Codex), and `init` adds an import of it to `CLAUDE.md` when Claude Code is installed or the file exists, since Claude Code reads `CLAUDE.md`. `init` upgrades a block it wrote earlier and keeps one you edited; while `AGENTS.md` holds an edited or older block, `CLAUDE.md` is left alone and `init` says so.
+- `shipcraft --version` and `shipcraft --help` say when the repository has no `.shipcraft.toml` yet, so an agent that checks the install is told to run `init`.
 
 Give the RED and the GREEN to different sessions. They can be the same model; separate context is what matters.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipcraft",
-  "version": "2.14.0",
+  "version": "2.17.0",
   "description": "A seatbelt for test-driven development with coding agents: locks the tests at RED so GREEN cannot quietly undo them.",
   "license": "Apache-2.0",
   "repository": { "type": "git", "url": "git+https://github.com/victorassisalves/shipcraft.git" },
@@ -10,7 +10,7 @@
   "files": ["bin/shipcraft.js", "LICENSE", "README.md"],
   "engines": { "node": ">=18" },
   "optionalDependencies": {
-    "shipcraft-darwin-arm64": "2.14.0",
-    "shipcraft-darwin-x64": "2.14.0"
+    "shipcraft-darwin-arm64": "2.17.0",
+    "shipcraft-darwin-x64": "2.17.0"
   }
 }