specsail 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable SpecSail changes are recorded here.
+
+## 0.2.0 — 2026-10-21
+
+- Add conversational mode: ask your coding agent for a change and the First Mate (`manage`) runs the workflow, bootstrapping project docs and the Makefile first.
+- Add the `manage` orchestrator skill; chat approvals are recorded in artifacts as `Status: APPROVED — Captain (chat), <date>`.
+- Review now asks whether to use a second session/model and records any same-model caveat.
+- Rename crew aliases: Reviewer is now **Bosun** and Release is now **Clerk**. Stage names and commands are unchanged.
+- Publish releases from GitHub Actions with npm trusted publishing and provenance; add `make release` and the release guide.
+
+## 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,93 @@
-# 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.
+
+Start with one sentence. Your agent runs the workflow.
+
+## The crew
+
+| Skill | Development role | Sailing alias | Responsibility |
+|---|---|---|---|
+| `manage` | Orchestrator | **First Mate** | Bootstraps project context, runs the workflow, and stops at every gate. |
+| `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 | **Bosun** | Independently checks behavior, evidence, scope, and invariants. |
+| `ship` | Release | **Clerk** | 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 one-time setup. No runtime dependencies.
+
+```sh
+npx specsail init
+```
+
+Then open your coding agent and ask for what you want:
+
+> "Let's add user authentication."
+
+The First Mate checks `docs/project.md`, `docs/architecture.md`, and the `Makefile`. If they are missing or still starter templates, it interviews you and drafts them. It then scaffolds `specs/<feature>/` and runs Scout → Navigator → Quartermaster → Hands → Bosun → Clerk, asking questions and stopping at each approval gate. You answer in chat; the agent records each decision in the artifact.
+
+No commands are required after `init`. The CLI stays available for manual control, CI, and scripting.
+
+## How the flow works
+
+```text
+request → Captain-approved spec → plan → Captain-approved phase tests
+       → implement one task → independent review → PR → Captain merges
+```
+
+The spec is approved before planning; phase tests are approved before implementation. Bug fixes use a shorter path; trivial changes can use a normal PR and the project's `make verify`.
+
+At every stage the agent may ask you questions. Two gates are always explicit:
+
+1. **Spec approval** — the acceptance criteria are observable and complete.
+2. **Test approval** — the tests fail for the right reason before code is written.
+
+Review independence is also explicit: the First Mate asks whether to open a second session/model. If you accept a same-model review, the caveat is recorded in `review.md`.
+
+## Use with your coding tool
+
+SpecSail does not require a vendor-specific agent integration. Use any tool that reads repository instructions and Markdown — OpenCode, Claude Code, Codex, Cursor, Copilot, Gemini CLI, or anything else. `AGENTS.md` tells the agent to start the workflow; if your tool does not discover skills automatically, it can read the `SKILL.md` files directly.
+
+For tools using the Agent Skills convention, you can also install individual skills from this repository:
+
+```sh
+npx skills add dseija/specsail --skill manage
+```
+
+## Commands (optional)
+
+| 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 manually. |
+| `specsail doctor` | Check required files, crew skills, `make verify`, and the workflow trigger. |
+| `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). The conversational workflow 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), the [release guide](docs/releasing.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,18 @@
+# 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.
+- 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.2.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,80 @@
+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 = {
+  manage: ["Orchestrator", "First Mate"],
+  understand: ["Product Owner", "Scout"],
+  plan: ["Tech Lead", "Navigator"],
+  "acceptance-tests": ["QA", "Quartermaster"],
+  implement: ["Developer", "Hands"],
+  review: ["Reviewer", "Bosun"],
+  ship: ["Release", "Clerk"],
+};
+
+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}`);
+}
+
+const templateAgents = await readFile(path.join(root, "templates/.specsail/AGENTS.md"), "utf8");
+if (!templateAgents.includes(".specsail/skills/manage/SKILL.md")) {
+  fail("the installed AGENTS.md must trigger the conversational workflow via the manage skill");
+}
+const cliSource = await readFile(path.join(root, "src/cli.js"), "utf8");
+if (!cliSource.includes("skills/manage/SKILL.md")) {
+  fail("specsail init must add the conversational workflow trigger to AGENTS.md");
+}
+
+const releaseWorkflow = await readFile(path.join(root, ".github/workflows/release.yml"), "utf8");
+if (!/^\s*id-token:\s*write$/m.test(releaseWorkflow)) fail("release workflow must request the GitHub OIDC token (id-token: write)");
+if (!/^\s*contents:\s*write$/m.test(releaseWorkflow)) fail("release workflow must be allowed to create the GitHub release (contents: write)");
+if (!/tags:\s*\["v\*"\]/.test(releaseWorkflow)) fail("release workflow must run on v* tags");
+if (!releaseWorkflow.includes("--provenance")) fail("release workflow must publish with --provenance");
+if (releaseWorkflow.includes("environment: npm") === false) fail("release workflow must use the npm environment configured as the trusted publisher");
+if (/NODE_AUTH_TOKEN|NPM_TOKEN|secrets\./.test(releaseWorkflow)) fail("release workflow must not use npm tokens or repository secrets");
+
+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: ask your agent to start the SpecSail workflow for $SLUG; the First Mate will continue from the request stage."

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/release.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Bump the version, commit, and push a release tag. The tag starts the release workflow.
+# Usage: scripts/release.sh <x.y.z>
+set -euo pipefail
+VERSION="${1:?usage: release.sh <x.y.z>}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "version must be x.y.z (no leading v)" >&2; exit 1; }
+
+cd "$(git rev-parse --show-toplevel)"
+[ -z "$(git status --porcelain)" ] || { echo "working tree must be clean" >&2; exit 1; }
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+[ "$BRANCH" = "main" ] || { echo "release from main, not $BRANCH" >&2; exit 1; }
+
+git fetch origin main
+[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] || { echo "local main must match origin/main" >&2; exit 1; }
+grep -q "^## $VERSION " CHANGELOG.md || { echo "CHANGELOG.md is missing a '## $VERSION' heading" >&2; exit 1; }
+git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null && { echo "tag v$VERSION already exists" >&2; exit 1; }
+
+make verify
+CURRENT="$(node -p "require('./package.json').version")"
+if [ "$CURRENT" != "$VERSION" ]; then
+  npm version "$VERSION" --no-git-tag-version
+  git add package.json package-lock.json
+  git commit -m "chore: release $VERSION"
+fi
+git tag "v$VERSION"
+git push origin main
+git push origin "v$VERSION"
+
+echo "Pushed v$VERSION. Watch the release workflow with: gh run watch"

package/scripts/run-agent.sh

@@ -0,0 +1,45 @@
+#!/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
+  manage|first-mate) STAGE=manage; TITLE="Orchestrator"; CREW="First Mate" ;;
+  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|bosun) STAGE=review; TITLE="Reviewer"; CREW="Bosun" ;;
+  ship|clerk) STAGE=ship; TITLE="Release"; CREW="Clerk" ;;
+  *) 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,38 @@
+---
+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.
+
+## Conversational mode
+The First Mate (orchestrator) may run you in the same session. Read only the approved spec, glossary, and public interfaces; do not inspect the plan or implementation. Ask the Captain about test placement or harness details instead of reading the plan.
+
+## 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,39 @@
+---
+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.**
+
+## Conversational mode
+The First Mate (orchestrator) may ask you to implement one task at a time in the same session. Keep to that task, run `make verify`, and report scope issues; the orchestrator handles gates and commits only as this skill allows.
+
+## 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/manage/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: manage
+description: Orchestrate the SpecSail workflow from a feature request to a merge-ready PR. Use whenever the user asks to add, change, or fix something non-trivial and expects the crew to run the process conversationally.
+metadata:
+  specsail-title: Orchestrator
+  specsail-crew: First Mate
+---
+# Orchestrator — First Mate (manage)
+**Model tier:** frontier. **You run the ship; the Captain decides.** The human is the Captain and is the only one who approves artifacts or merges. You sequence the stages, ask questions, and report at each gate.
+
+## Reads
+`AGENTS.md`, `.specsail/AGENTS.md`, `docs/project.md`, `docs/architecture.md`, the `Makefile`, `specs/<feature>/**`, and `.specsail/docs/workflow.md`. Before acting as a stage, read that stage's `SKILL.md` and follow it.
+
+## When to start
+The user asked for a non-trivial change ("add authentication", "fix the lockout bug") and there is no finished feature for it. Trivial edits (typo, config, dependency bump) need only a normal change and `make verify`; say so and skip the workflow unless the user wants it.
+
+## 1. Bootstrap the project (once)
+Check for the three things the workflow depends on:
+- `docs/project.md` is filled in, not the starter skeleton.
+- `docs/architecture.md` is filled in.
+- `make verify` runs real project checks (not the `SPECSAIL_UNCONFIGURED_TEMPLATE` starter).
+
+If any are missing or unconfigured, stop and interview the Captain in small batches:
+- What does this project do, for whom, and what is explicitly out of scope?
+- What are the main modules and their boundaries? Which invariants must no PR break?
+- What are the real commands for setup, lint, typecheck, unit/integration tests, and acceptance tests?
+
+Draft the missing files yourself from the answers and the repository. Never invent an invariant, a non-goal, or a command. Show the diff before saving. Configure the `Makefile` targets, run `npx specsail doctor` if available, and commit with `docs:`/`chore:` as appropriate. Only then continue.
+
+## 2. Start the feature
+Ask the Captain for a short kebab-case slug if it is not obvious, and classify it:
+- **FIX**: bug with a reproducible failure.
+- **UPDATE**: an existing behavior changes.
+- **NEW FEATURE**: new behavior.
+
+Scaffold `specs/<slug>/` from `.specsail/templates/specs/_templates/`, or run `npx specsail new <slug> <fix|update|new>` if available. Commit the scaffold with the `spec:` prefix.
+
+## 3. Run the stages
+Each stage is a role lens: read its `SKILL.md`, adopt its reads/writes/must-not rules, and stop where it says to stop. Ask the Captain questions at any stage; never guess an answer that belongs to them.
+
+1. **Scout (`understand`)** — clarify and write `request.md`. Confirm routing and open questions. Gate: Captain confirms the request.
+2. **Navigator (`plan`), spec mode** — write `spec.md` with observable `AC-n` criteria. Gate: Captain approves the spec.
+3. **Navigator, plan mode** — write `plan.md` and `tasks.md` from the approved spec. Gate: architecture decisions, if affected.
+4. **Quartermaster (`acceptance-tests`)** — write failing tests for this phase's ACs only. Gate: Captain approves the tests.
+5. **Hands (`implement`)** — one task at a time, TDD, `make verify` green, status `DEV_DONE`.
+6. **Bosun (`review`)** — independent review. Ask the Captain each time: open a second session/model for an independent review, or accept same-model review. If they accept, record the caveat in `review.md`. Rework up to three times.
+7. **Clerk (`ship`)** — docs, changelog, PR body. The Captain merges.
+
+Do not skip a stage because the change "looks simple" or to save time. For FIX, still write the reproduction AC.
+
+## Gate protocol
+- Present the artifact and ask: **"APPROVE, or what should change?"**
+- Silence, a different topic, or "ok" about something else is not approval. Ask again.
+- On explicit approval, record it in the artifact: `Status: APPROVED — Captain (chat), YYYY-MM-DD`. You are recording the Captain's decision, not making it. If the Captain edits the file directly, keep their wording and do not overwrite it.
+- On changes, revise and return to the same gate. Never approve on the Captain's behalf, never merge, never weaken an acceptance test to get past a gate.
+
+## Resuming
+Read `specs/*/` and `tasks.md`. If one feature is active, say where it is and continue from that stage. If several are active, ask which one. Use the "Where am I?" table in `.specsail/docs/runbook.md` when unsure.
+
+## Mechanical steps you may run
+Scaffolding, stage commits with the required prefixes (`spec:`, `plan:`, `accept:`, `feat:`, `fix:`, `docs:`), `make verify`, `make check-protected`, and placeholder-free PR creation. Do not hand-edit protected artifacts outside their owning stage.
+
+## Must not
+Implement outside the Hands stage; approve specs or tests; merge; invent requirements; skip the independent-review question; let the Captain's chat content be the only record when a file can carry the decision.
+
+## Done when
+The PR is open, docs are current, and the Captain has what they need to merge.
+
+## Escalate when
+The spec is contradictory or untestable, a gate stalls, or review hits three loops. Write `specs/<feature>/blocked.md`, set the task `BLOCKED`, and stop for the Captain.

package/skills/plan/SKILL.md

@@ -0,0 +1,41 @@
+---
+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.
+
+## Conversational mode
+When the First Mate (orchestrator) runs this stage, present the artifact and ask the Captain to approve or request changes. Record their explicit decision as described in `.specsail/skills/manage/SKILL.md`; never infer approval.
+
+## 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.