specsail 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.

package/README.md

@@ -4,64 +4,76 @@
 
 > **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.
+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
 
-| Stage | Development role | Sailing alias | Responsibility |
+| Skill | 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. |
+| `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 CLI. No runtime dependencies.
+Requires Node.js 20+ for the one-time setup. 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`.
+Then open your coding agent and ask for what you want:
 
-### Use with your coding tool
+> "Let's add user authentication."
 
-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.
+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.
 
-For tools using the Agent Skills convention, you can also install a skill from this repository, for example:
+No commands are required after `init`. The CLI stays available for manual control, CI, and scripting.
 
-```sh
-npx skills add dseija/specsail --skill understand
-```
-
-## The flow
+## How the flow works
 
 ```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`.
+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
+## 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. |
-| `specsail doctor` | Check required files, role skills, and `make verify`. |
+| `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). Interactive workflow use does not.
+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
 
@@ -74,7 +86,7 @@ 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).
+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
 

package/ROADMAP.md

@@ -15,5 +15,4 @@ The first release focuses on a safe, readable baseline. The items below are orde
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A spec-driven AI development crew. Navigate by spec. Deliver with confidence.",
   "license": "MIT",
   "type": "module",

package/scripts/check-content.mjs

@@ -4,12 +4,13 @@ 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", "First Mate"],
-  ship: ["Release", "Bosun"],
+  review: ["Reviewer", "Bosun"],
+  ship: ["Release", "Clerk"],
 };
 
 let errors = 0;
@@ -58,5 +59,22 @@ 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/new-feature.sh

@@ -22,4 +22,4 @@ 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"
+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/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

@@ -13,12 +13,13 @@ 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|first-mate) STAGE=review; TITLE="Reviewer"; CREW="First Mate" ;;
-  ship|bosun) STAGE=ship; TITLE="Release"; CREW="Bosun" ;;
+  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
 

package/skills/acceptance-tests/SKILL.md

@@ -8,6 +8,9 @@ metadata:
 # 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).
 

package/skills/implement/SKILL.md

@@ -8,6 +8,9 @@ metadata:
 # 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.
 

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

@@ -8,6 +8,9 @@ metadata:
 # 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.
 

package/skills/review/SKILL.md

@@ -3,11 +3,14 @@ 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
+  specsail-crew: Bosun
 ---
-# Reviewer — First Mate (review)
+# Reviewer — Bosun (review)
 **Model tier:** frontier, preferably a different model family than the implementer. **Report only, never fix.**
 
+## Conversational mode
+The First Mate (orchestrator) asks the Captain whether to run this review in a second session/model. If the Captain accepts a same-model review, record that caveat at the top of `review.md`. Never claim independent review when the same model implemented and reviewed.
+
 ## 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.
 

package/skills/ship/SKILL.md

@@ -3,11 +3,14 @@ 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
+  specsail-crew: Clerk
 ---
-# Release — Bosun (ship)
+# Release — Clerk (ship)
 **Model tier:** cheap. **Mostly mechanical; the Captain merges.**
 
+## Conversational mode
+The First Mate (orchestrator) runs the mechanical steps and reports the PR link. The Captain reviews the diff and merges; never merge on the Captain's behalf.
+
 ## 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`.
 

package/skills/understand/SKILL.md

@@ -8,6 +8,9 @@ metadata:
 # Product Owner — Scout (understand)
 **Model tier:** frontier. **Interactive with the human.**
 
+## Conversational mode
+The First Mate (orchestrator) may hand you an already-started conversation. Ask the Captain in small batches, most important first, and stop when the request is confirmed; the orchestrator handles the remaining stages.
+
 ## Reads
 `AGENTS.md`, `docs/project.md`, `docs/architecture.md`, the raw request, `specs/<feature>/request.md` (template).
 

package/src/cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const stageRoles = ["understand", "plan", "acceptance-tests", "implement", "review", "ship"];
+const skillRoles = ["manage", ...stageRoles];
 const typeNames = {
   fix: "FIX",
   update: "FEATURE UPDATE",
@@ -180,7 +181,7 @@ async function init(cwd, output, root) {
   await updateManagedBlock(
     path.join(cwd, "AGENTS.md"),
     ["<!-- specsail:start -->", "<!-- specsail:end -->"],
-    "## SpecSail\n\nThis project uses SpecSail, a Captain-led, spec-driven development workflow. Read .specsail/AGENTS.md for project workflow rules. For the assigned stage, read the matching skill in .specsail/skills/<stage>/SKILL.md. The human Captain approves specs and acceptance tests and merges pull requests; agents must not take those gates.",
+    "## SpecSail\n\nThis project uses SpecSail, a Captain-led, spec-driven development workflow. When the user asks for a non-trivial feature, fix, or update, start the workflow before writing code: read .specsail/skills/manage/SKILL.md and follow it. The First Mate orchestrates the crew; the human Captain answers questions, approves specs and acceptance tests, and merges. Commands are optional. Read .specsail/AGENTS.md for the crew and rules.",
     cwd,
   );
   await updateManagedBlock(
@@ -192,7 +193,7 @@ async function init(cwd, output, root) {
   config.version = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")).version;
   await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
   writeLine(output, `SpecSail initialized (${config.version}). Added ${created} file(s); left ${skipped} existing file(s) unchanged.`);
-  writeLine(output, "Next: fill docs/project.md and docs/architecture.md, configure Makefile, then run specsail doctor.");
+  writeLine(output, "Next: open your coding agent and ask for a change. The First Mate will check the project docs and Makefile, ask what is missing, and start the workflow.");
   return 0;
 }
 
@@ -222,7 +223,7 @@ async function newFeature(cwd, args, output) {
   } catch (error) {
     throw new Error(`Could not scaffold specs/${slug}: ${error.message}. Remove the partial directory before retrying.`);
   }
-  writeLine(output, `Created specs/${slug}/. Next: run ".specsail/scripts/run-agent.sh understand ${slug}" with your agent, or read the Scout skill.`);
+  writeLine(output, `Created specs/${slug}/. Next: ask your agent to start the SpecSail workflow for ${slug}; the First Mate will continue from the request stage.`);
   return 0;
 }
 
@@ -246,7 +247,7 @@ async function doctor(cwd, output, error) {
   for (const [label, filePath] of checks) {
     if (!(await exists(filePath))) failures.push(`Missing ${label}; run specsail init.`);
   }
-  for (const stage of stageRoles) {
+  for (const stage of skillRoles) {
     const skill = path.join(cwd, ".specsail/skills", stage, "SKILL.md");
     if (!(await exists(skill))) failures.push(`Missing ${path.relative(cwd, skill)}; run specsail init.`);
   }
@@ -260,6 +261,8 @@ async function doctor(cwd, output, error) {
   const agents = await exists(path.join(cwd, "AGENTS.md")) ? await readFile(path.join(cwd, "AGENTS.md"), "utf8") : "";
   if (!agents.includes("<!-- specsail:start -->") || !agents.includes("<!-- specsail:end -->")) {
     failures.push("AGENTS.md is missing the SpecSail managed section; run specsail init.");
+  } else if (!agents.includes("skills/manage/SKILL.md")) {
+    failures.push("AGENTS.md does not start the conversational workflow; update the SpecSail section or run specsail init again.");
   }
   if (!(await hasGitRepository(cwd))) writeLine(error, "Warning: no .git directory found. Initialize version control before starting a feature.");
   if (failures.length) {

package/templates/.specsail/AGENTS.md

@@ -2,18 +2,29 @@
 
 This project follows the SpecSail workflow. The human is the **Captain** and is the only person who approves specs, approves acceptance tests, or merges pull requests. Agents must stop at those gates and ask the Captain to act.
 
+## Conversational mode
+
+When the user asks for a non-trivial change, fix, or feature, run the workflow instead of writing code immediately:
+
+1. Read `.specsail/skills/manage/SKILL.md` and follow it.
+2. If `docs/project.md`, `docs/architecture.md`, or the `Makefile` verify target are missing or unconfigured, bootstrap them with the Captain's answers first.
+3. Run the stages in order and stop at each gate. Chat approvals are recorded in the artifact with the Captain's name and date.
+
+The user does not need to run commands. `npx specsail init/new/doctor` and `.specsail/scripts/*` are optional shortcuts.
+
 ## Crew and skills
 
-| Stage | Development role | Crew name | Skill |
+| Skill | Development role | Crew alias | Purpose |
 |---|---|---|---|
-| Understand | Product Owner | Scout | `.specsail/skills/understand/SKILL.md` |
-| Plan | Tech Lead | Navigator | `.specsail/skills/plan/SKILL.md` |
-| Acceptance tests | QA | Quartermaster | `.specsail/skills/acceptance-tests/SKILL.md` |
-| Implement | Developer | Hands | `.specsail/skills/implement/SKILL.md` |
-| Review | Reviewer | First Mate | `.specsail/skills/review/SKILL.md` |
-| Ship | Release | Bosun | `.specsail/skills/ship/SKILL.md` |
+| `manage` | Orchestrator | First Mate | Runs the workflow, bootstraps the project, sequences stages and gates. |
+| `understand` | Product Owner | Scout | Turns the request into `request.md`. |
+| `plan` | Tech Lead | Navigator | Writes `spec.md`, then `plan.md` and `tasks.md`. |
+| `acceptance-tests` | QA | Quartermaster | Writes failing acceptance tests from approved criteria. |
+| `implement` | Developer | Hands | Implements one planned task. |
+| `review` | Reviewer | Bosun | Reviews independently with evidence. |
+| `ship` | Release | Clerk | Updates docs, changelog, and opens the PR. |
 
-Use the stage name in files and commands. The crew name is a human-friendly alias. If an agent tool cannot load skills automatically, tell it to read this file and the relevant `SKILL.md` directly.
+The Captain is a human, not an agent. If an agent tool cannot load skills automatically, tell it to read `.specsail/skills/<skill>/SKILL.md` directly.
 
 ## Workflow
 
@@ -24,7 +35,7 @@ Use the stage name in files and commands. The crew name is a human-friendly alia
 - Protected files are approved `spec.md`, `plan.md`, and `tests/acceptance/**`. Only the owning stage may edit them; commits use `spec:`, `plan:`, or `accept:` prefixes.
 - If the request/spec is ambiguous or an acceptance criterion is unworkable, write `specs/<feature>/blocked.md` and stop. Never silently reinterpret an approved spec or weaken a test.
 - Implement one planned task at a time. Do not broaden scope. Run `make verify` before marking a task `DEV_DONE`.
-- Review must be independent of implementation and report evidence; it does not fix code. The Captain merges.
+- Review is independent of implementation and reports evidence; it does not fix code. The Captain merges.
 - Update docs in the same PR as the code change.
 
 See `.specsail/docs/workflow.md` for stage definitions and `.specsail/docs/runbook.md` for operating steps.

package/templates/.specsail/docs/runbook.md

@@ -2,24 +2,38 @@
 
 Step-by-step operating guide. `.specsail/docs/workflow.md` is the concise reference.
 
-## Start a feature
+## Talk to the First Mate
+
+In your coding agent, ask for the change in normal language: *"let's add user authentication"* or *"fix the login lockout bug."* The agent reads `.specsail/skills/manage/SKILL.md` and starts the workflow:
+
+1. Checks `docs/project.md`, `docs/architecture.md`, and the `Makefile` verify target. If they are missing or still starter templates, it interviews you and drafts them.
+2. Scaffolds `specs/<slug>/`, asks any questions, and runs Scout, Navigator, Quartermaster, Hands, Bosun, and Clerk in order.
+3. Stops at each gate: request confirmed, spec approved, tests approved, architecture approved when affected, and merge. Approve in chat; the agent records the decision with your name and date.
+
+Commands are optional. Use them if you prefer manual control, CI, or scripting.
+
+## Run stages manually (optional)
 
 ```sh
 ./.specsail/scripts/start-phase.sh <slug> 1
 ./.specsail/scripts/new-feature.sh <slug> <fix|update|new>
+./.specsail/scripts/run-agent.sh scout <slug>
+./.specsail/scripts/run-agent.sh navigator <slug>
+./.specsail/scripts/run-agent.sh quartermaster <slug> "AC-1,AC-2"
+./.specsail/scripts/run-agent.sh hands <slug> T-1
+./.specsail/scripts/run-agent.sh bosun <slug> T-1
+./.specsail/scripts/run-agent.sh clerk <slug>
+./.specsail/scripts/open-pr.sh <slug> 1
 ```
 
-If you prefer not to create a branch yet, run only `new-feature.sh`. Trivial changes can use a normal PR and `make verify` without feature artifacts.
+Stage names also work: `understand`, `plan`, `acceptance-tests`, `implement`, `review`, `ship`. The orchestrator is `manage` / `first-mate`.
 
-## Run the crew
+## Gates and review
 
-1. **Scout / Product Owner:** `./.specsail/scripts/run-agent.sh understand <slug>`. Give it the raw request, answer its questions, and confirm the routing. Exit when the request is complete and open questions are resolved or explicitly deferred.
-2. **Navigator / Tech Lead, spec mode:** run `./.specsail/scripts/run-agent.sh plan <slug>`. The Captain reviews every acceptance criterion and sets `Status: APPROVED` in `spec.md`.
-3. **Navigator / Tech Lead, plan mode:** run the same command again after approval. Check every criterion maps to tasks and each task has a verification command. The Captain reviews architecture decisions when architecture is affected.
-4. **Quartermaster / QA:** `./.specsail/scripts/run-agent.sh acceptance-tests <slug> "AC-1,AC-2"`. The Captain checks tests fail for the intended missing behavior and approves them before implementation.
-5. **Hands / Developer:** `./.specsail/scripts/run-agent.sh implement <slug> T-1`. One task per run. Check scope and protected paths.
-6. **First Mate / Reviewer:** `./.specsail/scripts/run-agent.sh review <slug> T-1`. Use a different model family than the implementer. Rework findings up to three times, then escalate.
-7. **Bosun / Release:** `./.specsail/scripts/run-agent.sh ship <slug>`, then `./.specsail/scripts/open-pr.sh <slug> 1`. The Captain checks CI and merges.
+- **Spec:** the Captain reviews every acceptance criterion and approves before planning.
+- **Tests:** the Captain checks the phase's tests fail for the right reason before implementation.
+- **Review:** the First Mate asks whether to use a second session/model. If you accept same-model review, the caveat is recorded in `review.md`.
+- **Merge:** the Captain checks CI, protected paths, and docs, then merges.
 
 For later phases, create the phase branch with `start-phase.sh <slug> <phase>`, then write and approve that phase's acceptance tests before implementation.
 

package/templates/.specsail/docs/workflow.md

@@ -1,21 +1,30 @@
 # SpecSail workflow reference
 
-SpecSail uses durable Markdown artifacts to carry intent between stages. The Captain is the human who owns the approval and merge gates.
+SpecSail uses durable Markdown artifacts to carry intent between stages. The Captain is the human who owns the approval and merge gates. The First Mate (`manage`) runs the workflow conversationally; the other stages are role lenses it adopts.
 
 ## Stages and crew
 
-| # | Stage / skill | Development role — crew alias | Reads | Writes |
+| # | Skill | Development role — crew alias | Reads | Writes |
 |---|---|---|---|---|
+| 0 | manage | Orchestrator — First Mate | project docs, Makefile, feature state | bootstrap docs, sequencing, gate records |
 | 1 | understand | Product Owner — Scout | project, architecture, request | `request.md` |
 | 2a | plan (spec mode) | Tech Lead — Navigator | project, architecture, request | `spec.md` |
 | 2b | plan (plan mode) | Tech Lead — Navigator | approved spec, module docs | `plan.md`, `tasks.md` |
 | 3 | acceptance-tests | QA — Quartermaster | approved spec, glossary, public interfaces | `tests/acceptance/<feature>/**` |
 | 4 | implement | Developer — Hands | spec, plan, tasks, review, module docs | code, unit tests, task status |
-| 5 | review | Reviewer — First Mate | spec, plan, tasks, diff, invariants | review report, task status |
-| 6 | ship | Release — Bosun | spec, plan, tasks, diff | docs, changelog, PR |
+| 5 | review | Reviewer — Bosun | spec, plan, tasks, diff, invariants | review report, task status |
+| 6 | ship | Release — Clerk | spec, plan, tasks, diff | docs, changelog, PR |
 
 The human Captain is not an agent role. Agents may prepare work for a gate, but only the Captain approves `spec.md`, approves each phase's acceptance tests, and merges.
 
+## Conversational operation
+
+The Captain starts with a normal request ("let's add user authentication"). The First Mate checks project context, bootstraps missing docs/Makefile settings with the Captain's answers, scaffolds the feature, then runs the stages in order. The Captain answers questions and approves artifacts in chat; commands are optional.
+
+**Recording approvals:** on explicit approval, the agent records `Status: APPROVED — Captain (chat), YYYY-MM-DD` in the artifact. The Captain's decision is the approval; the file is the evidence. Silence is not approval.
+
+**Review independence:** the First Mate asks the Captain whether to review in a second session/model. If the Captain accepts a same-model review, the caveat is recorded in `review.md`.
+
 ## Change paths
 
 | Type | Path |
@@ -28,7 +37,7 @@ The human Captain is not an agent role. Agents may prepare work for a gate, but
 ## Human gates
 
 1. Confirm the request and resolve or explicitly defer open questions.
-2. Review and approve `spec.md` before planning by setting `Status: APPROVED`.
+2. Review and approve `spec.md` before planning.
 3. Review and approve acceptance tests for the current phase before implementation.
 4. Merge only after CI is green, review is done, protected paths are clean, and docs are current.
 
@@ -38,10 +47,10 @@ Architecture decisions require Captain approval when the plan says architecture
 
 `TODO → IN_PROGRESS → DEV_DONE → DONE`; rework uses `CHANGES_REQUESTED`; an unresolved issue uses `BLOCKED` plus `blocked.md`. After three review iterations, stop and escalate to the Captain.
 
-A task is done when `make verify` is green, linked acceptance criteria pass, required docs are updated, and the First Mate marks it `DONE`.
+A task is done when `make verify` is green, linked acceptance criteria pass, required docs are updated, and the Bosun marks it `DONE`.
 
 ## Parallel work and review
 
 - Define API contracts before parallel multi-app work; independent tasks may use separate worktrees.
 - Do not parallelize tasks that touch the same module or shared task-status rows.
-- CI is deterministic verification; First Mate review checks behavior and invariants; the Captain merges.
+- CI is deterministic verification; Bosun review checks behavior and invariants; the Captain merges.

package/test/acceptance/cli.acceptance.test.js

@@ -6,6 +6,7 @@ import { test } from "node:test";
 import { runCli } from "../../src/cli.js";
 
 const packageRoot = new URL("../../", import.meta.url).pathname;
+const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
 
 async function temporaryProject() {
   return mkdtemp(path.join(os.tmpdir(), "specsail-test-"));
@@ -40,8 +41,12 @@ test("init preserves project-owned files, installs the crew, and is repeatable",
   assert.equal(await readFile(path.join(cwd, "docs/project.md"), "utf8"), "# My existing project\n");
   assert.match(await readFile(path.join(cwd, "AGENTS.md"), "utf8"), /<!-- specsail:start -->/);
   assert.match(await readFile(path.join(cwd, ".specsail/skills/understand/SKILL.md"), "utf8"), /Scout/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/manage/SKILL.md"), "utf8"), /First Mate/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/review/SKILL.md"), "utf8"), /Bosun/);
+  assert.match(await readFile(path.join(cwd, ".specsail/skills/ship/SKILL.md"), "utf8"), /Clerk/);
+  assert.match(await readFile(path.join(cwd, "AGENTS.md"), "utf8"), /skills\/manage\/SKILL\.md/);
   assert.match(await readFile(path.join(cwd, ".gitignore"), "utf8"), /\.specsail\/agents\.env/);
-  assert.deepEqual(JSON.parse(await readFile(path.join(cwd, ".specsail.json"), "utf8")), { version: "0.1.0", localSetting: true });
+  assert.deepEqual(JSON.parse(await readFile(path.join(cwd, ".specsail.json"), "utf8")), { version: manifest.version, localSetting: true });
 
   const second = streams();
   assert.equal(await runCli(["init"], { cwd, ...second.options }), 0);
@@ -91,6 +96,19 @@ test("doctor verifies the kit and the project's verify command", async (context)
   assert.match(afterConfig.stdout(), /files and verify target are present/);
 });
 
+test("doctor flags an AGENTS.md that does not start the conversational workflow", async (context) => {
+  const cwd = await temporaryProject();
+  context.after(() => rm(cwd, { recursive: true, force: true }));
+  const initialized = streams();
+  assert.equal(await runCli(["init"], { cwd, ...initialized.options }), 0);
+  await writeFile(path.join(cwd, "Makefile"), "verify:\n\t@echo configured\n", "utf8");
+  const agentsPath = path.join(cwd, "AGENTS.md");
+  await writeFile(agentsPath, (await readFile(agentsPath, "utf8")).replace("skills/manage/SKILL.md", "AGENTS.md"), "utf8");
+  const result = streams();
+  assert.equal(await runCli(["doctor"], { cwd, ...result.options }), 1);
+  assert.match(result.stderr(), /does not start the conversational workflow/);
+});
+
 test("init refuses to write through a symlinked SpecSail directory", async (context) => {
   const cwd = await temporaryProject();
   const outside = await temporaryProject();

package/test/cli.test.js

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
 import { test } from "node:test";
 import { runCli } from "../src/cli.js";
 
 const root = new URL("../", import.meta.url).pathname;
+const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 
 test("help and version are available without initializing a project", async () => {
   let stdout = "";
@@ -11,7 +13,7 @@ test("help and version are available without initializing a project", async () =
   assert.equal(await runCli(["--help"], options), 0);
   assert.match(stdout, /Captain is always human/);
   assert.equal(await runCli(["--version"], options), 0);
-  assert.match(stdout, /0\.1\.0/);
+  assert.match(stdout, new RegExp(manifest.version.replaceAll(".", "\\.")));
   assert.equal(stderr, "");
 });
 

package/test/release.test.js

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { test } from "node:test";
+
+const workflowPath = new URL("../.github/workflows/release.yml", import.meta.url);
+const shipped = existsSync(workflowPath);
+
+test("release workflow publishes with OIDC and provenance", { skip: !shipped && "release workflow is not included in the published tarball" }, async () => {
+  const workflow = await readFile(workflowPath, "utf8");
+  assert.match(workflow, /^on:\s*\n\s*push:\s*\n\s*tags:\s*\["v\*"\]/m);
+  assert.match(workflow, /^\s*id-token:\s*write$/m);
+  assert.match(workflow, /^\s*contents:\s*write$/m);
+  assert.match(workflow, /^\s*environment:\s*npm$/m);
+  assert.match(workflow, /npm publish --access public --provenance/);
+  assert.doesNotMatch(workflow, /NODE_AUTH_TOKEN|NPM_TOKEN|secrets\./);
+});