specsail 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable SpecSail changes are recorded here.
+
+## 0.1.0 — 2026-10-20
+
+- First public release of the SpecSail methodology and Node.js CLI.
+- Add the Captain-led crew: Scout, Navigator, Quartermaster, Hands, First Mate, and Bosun.
+- Add merge-safe project initialization, feature scaffolding, and setup diagnostics.
+- Include stack-neutral templates, portable Markdown skills, and optional Bash helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Seija
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# SpecSail
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A spec-driven AI development crew.**
+
+> **Navigate by spec. Deliver with confidence.**
+
+SpecSail gives developers a repeatable, human-led way to work with AI coding agents: capture the request, approve the spec, plan the work, approve tests, implement one task at a time, review independently, and ship. The durable artifacts live in your repository—not in chat history.
+
+## The crew
+
+| Stage | Development role | Sailing alias | Responsibility |
+|---|---|---|---|
+| Understand | Product Owner | **Scout** | Clarifies the request and records routing, constraints, and open questions. |
+| Plan | Tech Lead | **Navigator** | Writes the spec, then the technical plan and thin tasks. |
+| Acceptance tests | QA | **Quartermaster** | Encodes approved criteria as observable tests before implementation. |
+| Implement | Developer | **Hands** | Implements one planned task and runs project verification. |
+| Review | Reviewer | **First Mate** | Independently checks behavior, evidence, scope, and invariants. |
+| Ship | Release | **Bosun** | Updates release docs and prepares the pull request. |
+
+The **Captain is always human**: the Captain resolves questions, approves the spec, approves phase acceptance tests, and merges. Agents can prepare a gate; they cannot pass it.
+
+## Quick start
+
+Requires Node.js 20+ for the CLI. No runtime dependencies.
+
+```sh
+npx specsail init
+npx specsail doctor
+npx specsail new password-reset new
+```
+
+`init` adds the kit without replacing existing project files. It installs skills and scripts under `.specsail/`, adds a marked section to `AGENTS.md`, and creates project templates only when the destination does not already exist. It writes the installed version to `.specsail.json`.
+
+Then fill in `docs/project.md` and `docs/architecture.md`, configure the generated `Makefile` targets for your stack, and add your Captain/team to `.github/CODEOWNERS`. Start the crew by reading `.specsail/docs/runbook.md`.
+
+### Use with your coding tool
+
+SpecSail does not require a vendor-specific agent integration. Use any coding tool that can read repository instructions and Markdown files; follow the stage's `SKILL.md` directly if your tool does not discover skills automatically. The optional Bash headless runner supports Claude, Codex, and OpenCode CLIs, but it is not required.
+
+For tools using the Agent Skills convention, you can also install a skill from this repository, for example:
+
+```sh
+npx skills add dseija/specsail --skill understand
+```
+
+## The flow
+
+```text
+request → Captain-approved spec → plan → Captain-approved phase tests
+       → implement one task → independent review → PR → Captain merges
+```
+
+The plan is approved before acceptance tests are written. Tests are approved per phase before implementation starts. Bug fixes can use a shorter path; trivial changes can use a normal PR and the project's `make verify`.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `specsail init` | Add SpecSail files without overwriting existing project files. |
+| `specsail new <slug> <fix\|update\|new>` | Scaffold request, spec, plan, and task artifacts. |
+| `specsail doctor` | Check required files, role skills, and `make verify`. |
+| `specsail --version` | Print the installed version. |
+
+Optional scripts in `.specsail/scripts/` create phase branches, run configured CLIs, check protected-path commit prefixes, and open a PR. They require Git and Bash (macOS, Linux, WSL, or Git Bash). Interactive workflow use does not.
+
+## Stack-neutral by design
+
+SpecSail does not select a language, framework, CI provider, test runner, or model. The project owner wires `make setup`, `make lint`, `make typecheck`, `make test`, and `make accept` to the real project. The generated targets fail loudly until configured; they do not pretend generic checks are sufficient.
+
+## Development
+
+```sh
+make setup
+make verify
+```
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md), the [workflow reference](docs/workflow.md), the [runbook](docs/runbook.md), and the [roadmap](ROADMAP.md).
+
+## Open source
+
+MIT licensed. Contributions and issue reports are welcome. See [CHANGELOG.md](CHANGELOG.md) for release notes.

package/ROADMAP.md

@@ -0,0 +1,19 @@
+# SpecSail roadmap
+
+The first release focuses on a safe, readable baseline. The items below are ordered by the evidence and safety they unlock; they are proposals, not promises.
+
+## Before calling the workflow stable (1.0)
+
+1. **Run cross-stack pilots.** Complete at least two real feature cycles in each of a JavaScript/TypeScript, Python, and Go project. Record where the human or agent had to reinterpret instructions; keep representative cases as regression/evaluation fixtures.
+2. **Validate agent compatibility.** Exercise the same stages with multiple coding tools using their native instruction discovery and with manual `AGENTS.md`/`SKILL.md` references. Publish a tested matrix; distinguish tested tools from tools that should work by convention.
+3. **Harden initialization.** Add a dry-run mode and explicit conflict report; test interrupted initialization, existing agent instructions, symlinked paths, and Windows filesystem behavior.
+4. **Prove the gates.** Add evaluation cases where agents encounter ambiguous specs, failing tests, scope changes, and the Captain approval gates; verify they stop instead of guessing, weakening tests, or merging.
+5. **Document release/support policy.** Use pilot feedback to settle supported Node versions, upgrade expectations, and the optional runner's platform support before declaring 1.0 stability.
+
+## Later, based on user demand
+
+- Add a conflict-aware `specsail update` that previews changes and never overwrites local edits.
+- Add opt-in agent-specific adapters or commands only when they improve the universal Markdown workflow without making them mandatory.
+- Consider a Windows-native runner if users need headless execution outside WSL or Git Bash.
+- Automate release notes and npm publishing with GitHub Actions trusted publishing/provenance after the maintainer account is configured.
+- Consider language/framework presets as separately maintained opt-ins; the core remains stack-neutral.

package/bin/specsail.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "specsail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A spec-driven AI development crew. Navigate by spec. Deliver with confidence.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "specsail": "bin/specsail.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/*.sh",
+    "scripts/check-content.mjs",
+    "skills/",
+    "specs/_templates/",
+    "test/",
+    "templates/",
+    "README.md",
+    "ROADMAP.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "lint": "node scripts/check-content.mjs",
+    "typecheck": "node --check bin/specsail.js && node --check src/cli.js",
+    "test": "node --test test/*.test.js",
+    "accept": "node --test test/acceptance/*.test.js",
+    "verify": "npm run lint && npm run typecheck && npm test && npm run accept",
+    "prepublishOnly": "npm run verify"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dseija/specsail.git"
+  },
+  "homepage": "https://github.com/dseija/specsail#readme",
+  "bugs": {
+    "url": "https://github.com/dseija/specsail/issues"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "ai-agents",
+    "agent-skills",
+    "methodology",
+    "development-workflow"
+  ]
+}

package/scripts/check-content.mjs

@@ -0,0 +1,62 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const roles = {
+  understand: ["Product Owner", "Scout"],
+  plan: ["Tech Lead", "Navigator"],
+  "acceptance-tests": ["QA", "Quartermaster"],
+  implement: ["Developer", "Hands"],
+  review: ["Reviewer", "First Mate"],
+  ship: ["Release", "Bosun"],
+};
+
+let errors = 0;
+function fail(message) {
+  console.error(`✗ ${message}`);
+  errors += 1;
+}
+
+const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+if (manifest.name !== "specsail") fail("package name must be specsail");
+if (!/^\d+\.\d+\.\d+$/.test(manifest.version)) fail("package version must be a stable x.y.z version");
+if (manifest.engines?.node !== ">=20") fail("package must declare Node.js >=20");
+if (manifest.bin?.specsail !== "bin/specsail.js") fail("the specsail binary path must use the normalized bin/specsail.js form");
+if (Object.keys(manifest.dependencies ?? {}).length > 0) fail("the CLI should not add runtime dependencies");
+
+for (const [stage, [title, crew]] of Object.entries(roles)) {
+  const skillPath = path.join(root, "skills", stage, "SKILL.md");
+  let content;
+  try {
+    content = await readFile(skillPath, "utf8");
+  } catch {
+    fail(`missing skill ${path.relative(root, skillPath)}`);
+    continue;
+  }
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!frontmatter) {
+    fail(`${stage}/SKILL.md is missing YAML frontmatter`);
+    continue;
+  }
+  const fields = frontmatter[1];
+  if (!new RegExp(`^name: ${stage.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m").test(fields)) {
+    fail(`${stage}/SKILL.md name must match its directory`);
+  }
+  if (!fields.includes(`specsail-title: ${title}`)) fail(`${stage}/SKILL.md must identify the ${title} role`);
+  if (!fields.includes(`specsail-crew: ${crew}`)) fail(`${stage}/SKILL.md must identify the ${crew} crew alias`);
+  if (!content.includes(`${title} — ${crew}`)) fail(`${stage}/SKILL.md heading must show ${title} — ${crew}`);
+}
+
+const readme = await readFile(path.join(root, "README.md"), "utf8");
+for (const term of ["Navigate by spec. Deliver with confidence.", "The **Captain is always human**", ...Object.values(roles).flat()]) {
+  if (!readme.includes(term)) fail(`README.md must document: ${term}`);
+}
+
+const templateFiles = await readdir(path.join(root, "specs/_templates"));
+for (const name of ["request.md", "spec.md", "plan.md", "tasks.md"]) {
+  if (!templateFiles.includes(name)) fail(`missing feature scaffold template specs/_templates/${name}`);
+}
+
+if (errors) process.exitCode = 1;
+else console.log("✓ content, crew metadata, and package invariants are valid");

package/scripts/check-protected-paths.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Fail if protected files changed in a commit that isn't prefixed spec:/accept:/plan:.
+# Usage: scripts/check-protected-paths.sh [base-ref]   (default origin/main)
+# Backstop for fake prefixes: CODEOWNERS review on the same paths.
+set -euo pipefail
+BASE="${1:-origin/main}"
+PROTECTED='^(tests/acceptance/|specs/[^/]+/(spec|plan)\.md$)'
+ALLOWED='^(spec|accept|plan)(\(.+\))?!?:'
+fail=0
+for c in $(git rev-list --no-merges "$BASE"..HEAD); do
+  subj="$(git log -1 --format=%s "$c")"
+  hits="$(git diff-tree --no-commit-id --name-only -r "$c" | grep -E "$PROTECTED" || true)"
+  if [ -n "$hits" ] && ! printf '%s' "$subj" | grep -Eq "$ALLOWED"; then
+    echo "Protected paths changed in ${c:0:8} ('$subj'):"
+    printf '%s\n' "$hits" | sed 's/^/  /'
+    fail=1
+  fi
+done
+[ "$fail" -eq 0 ] && echo "Protected paths OK"
+exit "$fail"

package/scripts/new-feature.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Scaffold specs/<slug>/ from templates.
+# Usage: scripts/new-feature.sh <slug> <fix|update|new>
+set -euo pipefail
+SLUG="${1:?usage: new-feature.sh <slug> <fix|update|new>}"
+KIND="${2:?usage: new-feature.sh <slug> <fix|update|new>}"
+[[ "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo "slug must be lowercase kebab-case" >&2; exit 1; }
+case "$KIND" in
+  fix) TYPE="FIX" ;;
+  update) TYPE="FEATURE UPDATE" ;;
+  new) TYPE="NEW FEATURE" ;;
+  *) echo "type must be fix|update|new" >&2; exit 1 ;;
+esac
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SPECSAIL_DIR="${SPECSAIL_HOME:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+cd "$(git rev-parse --show-toplevel)"
+DIR="specs/$SLUG"
+[ -e "$DIR" ] && { echo "$DIR already exists" >&2; exit 1; }
+TEMPLATES="$SPECSAIL_DIR/templates/specs/_templates"
+[ -d "$TEMPLATES" ] || TEMPLATES="$SPECSAIL_DIR/specs/_templates"
+mkdir -p "$DIR"
+for f in request spec plan tasks; do
+  sed "s/{{SLUG}}/$SLUG/g; s/{{TYPE}}/$TYPE/g" "$TEMPLATES/$f.md" > "$DIR/$f.md"
+done
+echo "Created $DIR. Commit scaffolds with a spec: prefix. Next: .specsail/scripts/run-agent.sh scout $SLUG"

package/scripts/open-pr.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Verify, then open the PR for a phase. Usage: scripts/open-pr.sh <feature> <phase-number>
+set -euo pipefail
+SLUG="${1:?feature}"; N="${2:?phase number}"
+[[ "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo "feature slug must be lowercase kebab-case" >&2; exit 1; }
+[[ "$N" =~ ^[1-9][0-9]*$ ]] || { echo "phase must be a positive integer" >&2; exit 1; }
+cd "$(git rev-parse --show-toplevel)"
+make verify
+BODY="Spec: specs/$SLUG/spec.md
+Plan: specs/$SLUG/plan.md (phase $N)
+
+Task status:
+$(cat "specs/$SLUG/tasks.md")"
+git push -u origin HEAD
+gh pr create --title "$SLUG: phase $N" --body "$BODY"

package/scripts/run-agent.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Run one stage headlessly with whichever CLI/model is configured for it.
+# Usage: scripts/run-agent.sh <stage-or-crew-alias> <feature> [task-id]
+# Config: .specsail/agents.env (see .specsail/agents.env.example)
+set -euo pipefail
+ROLE="${1:?usage: run-agent.sh <stage-or-crew-alias> <feature> [task-id]}"
+FEATURE="${2:?feature slug}"
+TASK="${3:-}"
+[[ "$FEATURE" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo "feature slug must be lowercase kebab-case" >&2; exit 1; }
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SPECSAIL_DIR="${SPECSAIL_HOME:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+cd "$(git rev-parse --show-toplevel)"
+[ -f "$SPECSAIL_DIR/agents.env" ] && . "$SPECSAIL_DIR/agents.env"
+
+case "$ROLE" in
+  understand|scout) STAGE=understand; TITLE="Product Owner"; CREW="Scout" ;;
+  plan|navigator) STAGE=plan; TITLE="Tech Lead"; CREW="Navigator" ;;
+  acceptance-tests|quartermaster) STAGE=acceptance-tests; TITLE="QA"; CREW="Quartermaster" ;;
+  implement|hands) STAGE=implement; TITLE="Developer"; CREW="Hands" ;;
+  review|first-mate) STAGE=review; TITLE="Reviewer"; CREW="First Mate" ;;
+  ship|bosun) STAGE=ship; TITLE="Release"; CREW="Bosun" ;;
+  *) echo "Unknown stage or crew alias '$ROLE'." >&2; exit 1 ;;
+esac
+
+SKILL="$SPECSAIL_DIR/skills/$STAGE/SKILL.md"
+[ -f "$SKILL" ] || { echo "No skill for stage '$STAGE' ($SKILL)" >&2; exit 1; }
+
+KEY="$(printf '%s' "$STAGE" | tr 'a-z-' 'A-Z_')"
+CLI_VAR="AGENT_CLI_$KEY"; MODEL_VAR="AGENT_MODEL_$KEY"
+CLI="${!CLI_VAR:-${AGENT_CLI:-claude}}"
+MODEL="${!MODEL_VAR:-}"
+
+PROMPT="You are the $TITLE ($CREW) agent for the $STAGE stage. Read AGENTS.md, $SPECSAIL_DIR/AGENTS.md, and $SKILL, then do your job for specs/$FEATURE/. The human is the Captain: never approve specs/tests or merge. Follow your Must-not and Escalate rules strictly."
+[ -n "$TASK" ] && PROMPT="$PROMPT Task: $TASK. Work on this task only."
+
+# NOTE: headless runs need tool permissions configured in each tool (allowed
+# commands, writable paths). Keep them minimal per role.
+case "$CLI" in
+  claude)   exec claude -p ${MODEL:+--model "$MODEL"} "$PROMPT" ;;
+  codex)    exec codex exec ${MODEL:+-m "$MODEL"} "$PROMPT" ;;
+  opencode) exec opencode run ${MODEL:+-m "$MODEL"} "$PROMPT" ;;
+  custom)   : "${AGENT_CUSTOM_CMD:?set AGENT_CUSTOM_CMD}"; exec $AGENT_CUSTOM_CMD "$PROMPT" ;;
+  *) echo "Unsupported CLI '$CLI'. Edit scripts/run-agent.sh to add it." >&2; exit 1 ;;
+esac

package/scripts/start-phase.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Create the branch for a phase. Usage: scripts/start-phase.sh <feature> <phase-number> [base]
+set -euo pipefail
+SLUG="${1:?feature}"; N="${2:?phase number}"; BASE="${3:-main}"
+[[ "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo "feature slug must be lowercase kebab-case" >&2; exit 1; }
+[[ "$N" =~ ^[1-9][0-9]*$ ]] || { echo "phase must be a positive integer" >&2; exit 1; }
+git fetch origin "$BASE" 2>/dev/null || true
+git checkout -b "$SLUG/phase-$N" "origin/$BASE" 2>/dev/null || git checkout -b "$SLUG/phase-$N" "$BASE"
+echo "On branch $SLUG/phase-$N"

package/skills/acceptance-tests/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: acceptance-tests
+description: Turn approved spec acceptance criteria into executable failing acceptance tests. Use once per phase, before implementation.
+metadata:
+  specsail-title: QA
+  specsail-crew: Quartermaster
+---
+# QA — Quartermaster (acceptance-tests)
+**Model tier:** frontier. **Isolated context: you do not see the plan or the implementation.** The Captain approves the tests before implementation begins.
+
+## Reads
+`AGENTS.md`, `specs/<feature>/spec.md` (must be APPROVED), glossary in `docs/project.md`, existing test harness/fixtures and public interfaces (only to write tests that run).
+
+## Writes
+`tests/acceptance/<feature>/**` only. Commit prefix `accept:`.
+
+## Scope
+If the task argument lists AC IDs (e.g. `AC-1,AC-2`), write tests only for those. Otherwise write them for all ACs. This keeps `main` green when a feature ships in several phases.
+
+## Process
+1. One test per AC at minimum. Name it with the ID (e.g. `test_AC1_...` / `it("AC-1: ...")`).
+2. Test observable behavior through public interfaces (API, UI, CLI), not internals.
+3. Run `make accept`. Every new test must FAIL for the right reason (missing behavior), not for imports, syntax, setup or typos. Report each failure message.
+4. Keep tests deterministic: no sleeps, no network, no shared state.
+
+## Must not
+- Read `plan.md` or implementation code beyond public interfaces.
+- Edit `spec.md` or production code.
+- Write a test that can't fail, or one that mocks the behavior under test.
+
+## Done when
+Every AC has a test, all fail for the right reason, and the report lists AC → test → failure message.
+
+## Escalate when
+An AC can't be tested as written. Write `blocked.md` quoting the AC.

package/skills/implement/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: implement
+description: Implement exactly one task from plan.md so its acceptance tests pass. Use per task, also for CHANGES_REQUESTED rework.
+metadata:
+  specsail-title: Developer
+  specsail-crew: Hands
+---
+# Developer — Hands (implement)
+**Model tier:** mid/cheap. **One task per run.**
+
+## Reads
+`AGENTS.md`, `specs/<feature>/spec.md`, `plan.md` (your task only), `tasks.md`, `review.md` (if status is CHANGES_REQUESTED), `docs/architecture/<module>.md` for your module.
+
+## Writes
+Production code, unit/integration tests, docs listed in plan.md "Docs to update", your task's row in `tasks.md`.
+
+## Process
+1. Pick the first `TODO` or `CHANGES_REQUESTED` task. Set `IN_PROGRESS`.
+2. If reworking: address every BLOCKER and MAJOR finding in review.md; mention how you handled NITs.
+3. TDD for unit-level logic: red, green, refactor. Make the linked acceptance tests pass.
+4. Run `make verify`. Fix until green.
+5. Update docs the plan lists. Commit (`feat:`/`fix:`/`docs:`). Set `DEV_DONE`.
+6. Report: what changed, AC → test status, anything out of scope you noticed.
+
+## Must not
+- Edit `tests/acceptance/**`, `spec.md`, `plan.md`.
+- Delete, skip, loosen or special-case a failing test.
+- Touch modules outside the task's scope or refactor unrelated code.
+- Mark DEV_DONE while `make verify` is red.
+
+## Done when
+`make verify` is green, linked ACs pass, docs updated, status `DEV_DONE`.
+
+## Escalate when
+- The spec/AC seems wrong, ambiguous or conflicting → write `blocked.md`, set `BLOCKED`, stop.
+- 3 failed attempts at the same failure → write `blocked.md` with what you tried.

package/skills/plan/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: plan
+description: Write spec.md (and then plan.md + tasks.md once spec is approved). Use after request.md is confirmed.
+metadata:
+  specsail-title: Tech Lead
+  specsail-crew: Navigator
+---
+# Tech Lead — Navigator (plan)
+**Model tier:** frontier. **Two modes, chosen by state. Stop at the end of each mode.** The human is the Captain; agents never approve artifacts.
+
+## Reads
+`AGENTS.md`, `docs/project.md`, `docs/architecture.md`, `specs/<feature>/request.md`; in plan mode also the approved `spec.md` and `docs/architecture/<module>.md` for modules in request.md.
+
+## Mode A: spec (when spec.md is missing or `Status: DRAFT`)
+Writes `spec.md`: Overview, Objective, Acceptance criteria, Out of scope.
+- Acceptance criteria are Given/When/Then, with stable IDs `AC-1`, `AC-2`, ...
+- Each AC is observable behavior, testable without knowing the implementation.
+- Use glossary terms exactly. Put anything uncertain under "Open questions", not in an AC.
+- FIX type: AC-1 must be the reproduction of the bug.
+- Stop. The Captain reviews and approves the spec by setting `Status: APPROVED` before mode B. Acceptance tests are written and approved later, after the plan, by the Quartermaster.
+
+## Mode B: plan (when spec.md is `Status: APPROVED`)
+Writes `plan.md` and `tasks.md`.
+- Tasks are thin vertical slices, grouped in phases. Each lists: AC IDs, scope, verification command.
+- Do not create tasks for branches or PRs (scripted).
+- Multi-app: define the API contract first, then per-app tasks that can run in parallel.
+- Include "Docs to update" and "Risks and mitigations".
+- Architecture decisions only if request.md says Architecture affected = YES; create ADRs for significant ones.
+- Every AC must be covered by at least one task.
+
+## Must not
+Edit an APPROVED spec; write tests or code; set `Status: APPROVED`.
+
+## Done when
+Mode A: spec complete and every AC testable. Mode B: every AC mapped to a task, every task has a verify command.
+
+## Escalate when
+An AC is untestable, contradictory, or requires an architecture change the request didn't flag.

package/skills/review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: review
+description: Review a task's or phase's diff against spec and plan. Use after a task reaches DEV_DONE.
+metadata:
+  specsail-title: Reviewer
+  specsail-crew: First Mate
+---
+# Reviewer — First Mate (review)
+**Model tier:** frontier, preferably a different model family than the implementer. **Report only, never fix.**
+
+## Reads
+`AGENTS.md`, `specs/<feature>/spec.md`, `plan.md`, `tasks.md`, the diff against the base branch, `docs/architecture.md` (invariants + boundaries), module doc for touched modules.
+
+## Writes
+`specs/<feature>/review.md` (only when changes are needed) and the task status in `tasks.md`.
+
+## Checklist (evidence required: file:line)
+1. `make verify` is green (run it; don't trust the report).
+2. Each AC of the task has a passing test that really exercises it (not trivially passing).
+3. Behavior matches the spec, including Out of scope: no scope creep, no missing cases.
+4. Architecture boundaries and invariants respected.
+5. Protected paths untouched (`make check-protected`).
+6. Docs listed in plan.md updated.
+7. Correctness, error handling, security, obvious perf traps in the changed code.
+
+## Outcome
+- No BLOCKER/MAJOR → set `DONE`. NITs may be listed in the report but don't block.
+- Otherwise → write `review.md` from the template (overwrite previous), set `CHANGES_REQUESTED`, increment loops in `tasks.md`.
+- Loops reaches 3 → don't request again; write `blocked.md` summarizing the disagreement and stop.
+
+## Must not
+Edit code or tests; approve without running verify; raise findings without evidence; review style already covered by lint.

package/skills/ship/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ship
+description: Prepare a phase for merge: docs, changelog, PR description. Use after all tasks of a phase are DONE. Prefer scripts for anything mechanical.
+metadata:
+  specsail-title: Release
+  specsail-crew: Bosun
+---
+# Release — Bosun (ship)
+**Model tier:** cheap. **Mostly mechanical; the Captain merges.**
+
+## Reads
+`AGENTS.md`, `specs/<feature>/spec.md`, `plan.md`, `tasks.md`, the phase diff, current README / API docs / changelog / `docs/project.md` / `docs/architecture.md`.
+
+## Writes
+Docs only, in the same PR: changelog entry, README, API docs, architecture/project/module docs where the diff changed reality. Commit prefix `docs:`.
+
+## Process
+1. Confirm every task in the phase is `DONE` and `make verify` is green. If not, stop.
+2. Compare the diff to the docs; update only what became false or incomplete. Keep project.md/architecture.md short.
+3. Add a changelog entry from the spec Objective and ACs (user-facing language).
+4. Run `scripts/open-pr.sh <feature> <phase>`; the PR description links spec.md and lists AC coverage.
+
+## Must not
+Merge; edit code, tests, spec or plan; grow docs with history or status.
+
+## Done when
+PR is open, docs are current, and the human has what they need to merge.

package/skills/understand/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: understand
+description: Turn a raw request into specs/<feature>/request.md. Use at the start of any feature, update or fix.
+metadata:
+  specsail-title: Product Owner
+  specsail-crew: Scout
+---
+# Product Owner — Scout (understand)
+**Model tier:** frontier. **Interactive with the human.**
+
+## Reads
+`AGENTS.md`, `docs/project.md`, `docs/architecture.md`, the raw request, `specs/<feature>/request.md` (template).
+
+## Writes
+`specs/<feature>/request.md` only.
+
+## Process
+1. Read the docs, then the request. Look at code only to confirm which modules are involved.
+2. Interrogate the human before writing: ask about goal, users, edge cases, constraints. Ask in small batches, most important first.
+3. Fill the template. Decide Type and Routing flags honestly; they select the path (see `docs/workflow.md`).
+4. List unresolved questions under "Open questions".
+
+## Must not
+- Write spec, plan, tests or code.
+- Guess an answer to an open question; ask.
+- Invent modules; use names from the project.md repo map.
+
+## Done when
+Every template field is filled, Open questions is empty or explicitly deferred by the human, and the human confirmed the request.
+
+## Escalate when
+The request conflicts with a non-goal or invariant in project.md/architecture.md. Say so and stop.

package/specs/_templates/blocked.md

@@ -0,0 +1,15 @@
+# Blocked: {{SLUG}} / T-?
+Raised by: <role>
+Date:
+
+## What I was trying to do
+
+## Why I can't proceed
+<!-- Quote the spec line / AC ID that is ambiguous, contradictory or impossible. -->
+
+## Options I see
+1.
+2.
+
+## Recommendation
+<!-- A human resolves this and, if needed, updates spec.md. -->

package/specs/_templates/plan.md

@@ -0,0 +1,23 @@
+# Plan: {{SLUG}}
+<!-- Branch and PR creation are scripted (scripts/start-phase.sh, scripts/open-pr.sh). Don't list them as tasks. -->
+
+## Overview
+
+## Architecture decisions
+<!-- Omit if request.md says Architecture affected: NO. Link or create ADRs for significant ones. -->
+
+## API contract
+<!-- Multi-app only: define first. Endpoints, payloads, errors. -->
+
+## Phases
+
+### Phase 1: <name>
+- **T-1** <title>
+  - AC: AC-1
+  - Scope: <modules/files>
+  - Verify: `make verify` + <specific command>
+
+## Docs to update (same PR)
+<!-- README, API docs, changelog, architecture.md, project.md, module docs. -->
+
+## Risks and mitigations

package/specs/_templates/request.md

@@ -0,0 +1,19 @@
+# Request: {{SLUG}}
+Type: {{TYPE}}
+
+## Overview
+<!-- What is being asked and why, in 3-6 lines. -->
+
+## Routing
+| Question | Answer |
+|---|---|
+| Architecture affected | YES / NO |
+| API affected | YES / NO |
+| UI/UX affected | YES / NO |
+| Apps involved | BACKEND / FRONTEND / MOBILE |
+| Modules involved | <names matching docs/project.md repo map> |
+
+## Constraints and risks
+
+## Open questions
+<!-- Must be empty (or answered) before moving to spec. -->