specsail 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable SpecSail changes are recorded here.
 
+## 0.2.1 — 2026-10-22
+
+- Simplify the repository layout: `templates/` now mirrors the installed layout, feature templates live under `templates/specs/`, and maintainer tooling moved to `tools/`.
+- Single-source the installed workflow and runbook from `docs/`; remove the duplicated template copies.
+- Remove the vestigial `tests/` placeholder. No change to `npx specsail init` output or consumer paths.
+
+## 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

@@ -1,19 +1,21 @@
 # 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.
+Ordered by the evidence each item unlocks. Completed work rolls into `CHANGELOG.md` instead of accumulating here.
 
-## Before calling the workflow stable (1.0)
+## Now (0.3.0 candidates)
 
-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.
+1. **`specsail update`** — upgrade `.specsail/` from the version in `.specsail.json`, with a dry-run, a conflict report, and no silent overwrites of consumer edits.
+2. **Run the conversational mode in real projects.** Two feature cycles each in a JavaScript/TypeScript, Python, and Go codebase. Record every point where the human or agent had to reinterpret an instruction, and keep representative cases as evaluation fixtures.
+3. **Publish a tested agent compatibility matrix.** Exercise OpenCode, Claude Code, Codex, Cursor, Copilot, and Gemini CLI against the conversational trigger and skills; distinguish tested tools from tools expected to work by convention.
 
-## Later, based on user demand
+## Next (before 1.0)
 
-- 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.
+4. **Prove the gates.** Add evaluation cases for ambiguous specs, wrong-reason test failures, scope creep, and Captain approvals; verify agents stop instead of guessing, weakening tests, or merging.
+5. **Document support and upgrade policy.** Settle the supported Node range, the bash runner's platform matrix (macOS, Linux, WSL, Git Bash), and what consumers should expect from a minor upgrade.
+
+## Later (demand-driven)
+
+- Windows-native runner for headless execution outside WSL/Git Bash.
+- Opt-in language/framework presets; the core stays stack-neutral.
+- Opt-in agent-specific adapters or commands that never become mandatory.
+- Richer `specsail doctor` checks once `update` defines the installed-file contract.

package/docs/runbook.md

@@ -0,0 +1,40 @@
+# SpecSail runbook
+
+Step-by-step operating guide. The workflow reference in this folder (`workflow.md`) is the concise summary.
+
+## Talk to the First Mate
+
+In a coding agent, ask for the change in normal language: *"let's add user authentication."* The agent reads the SpecSail rules in `AGENTS.md`, starts `.specsail/skills/manage/SKILL.md`, and:
+
+1. Checks `docs/project.md`, `docs/architecture.md`, and the `Makefile` verify target. Missing or starter content is drafted with the Captain's answers first.
+2. Scaffolds `specs/<slug>/` and runs Scout, Navigator, Quartermaster, Hands, Bosun, and Clerk in order.
+3. Stops at each gate: request confirmed, spec approved, tests approved, architecture approved if affected, and merge.
+
+Commands are optional after `npx specsail init`.
+
+## Run a feature manually (optional)
+
+```sh
+npx specsail new <slug> <fix|update|new>
+```
+
+1. **Scout / Product Owner:** clarify the raw request and record it in `request.md`.
+2. **Navigator / Tech Lead, spec mode:** draft `spec.md`. The Captain approves it before any plan is written.
+3. **Navigator / Tech Lead, plan mode:** write `plan.md` and `tasks.md` from the approved spec.
+4. **Quartermaster / QA:** write executable failing tests for only the current phase's approved criteria. The Captain approves them before implementation.
+5. **Hands / Developer:** implement one planned task, run `make verify`, and report scope or spec problems instead of silently expanding.
+6. **Bosun / Reviewer:** independently run verification and review against the spec, tests, plan, and architecture.
+7. **Clerk / Release:** update docs/changelog and prepare the PR. The Captain checks CI and merges.
+
+The Captain may pause at any gate. Agents do not approve specs/tests or merge. See `workflow.md` for task states, FIX routing, gates, and parallel-work rules.
+
+## Gates and review
+
+- **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 the Captain accepts same-model review, the caveat is recorded in `review.md`.
+- **Merge:** the Captain checks CI, protected paths, and docs, then merges.
+
+## Optional headless runner
+
+The installed Bash runner at `.specsail/scripts/run-agent.sh` supports configured Claude, Codex, and OpenCode CLIs plus a custom command. Configure `.specsail/agents.env` from `.specsail/agents.env.example`. Invoke stages by name (`understand`) or alias (`scout`); the orchestrator is `manage` / `first-mate`. It requires Git and Bash; using skills interactively with any coding tool that can read Markdown does not.

package/docs/workflow.md

@@ -0,0 +1,56 @@
+# 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. The First Mate (`manage`) runs the workflow conversationally; the other stages are role lenses it adopts.
+
+## Stages and crew
+
+| # | 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 — 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. The Captain approves `spec.md`, approves each phase's acceptance tests, and merges.
+
+## Conversational operation
+
+The Captain starts with a normal request. The First Mate checks `docs/project.md`, `docs/architecture.md`, and the `Makefile` verify target; if any are missing or still starter templates, it bootstraps them with the Captain's answers before starting the feature. It then runs the stages in order. 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 whether to review in a second session/model. If the Captain accepts same-model review, the caveat is recorded in `review.md`.
+
+## Change paths
+
+| Type | Path |
+|---|---|
+| FIX | understand → spec with a reproduction criterion → acceptance test → implement → review → ship. Skip architecture planning unless needed. |
+| FEATURE UPDATE | full flow; skip architecture decisions if `Architecture affected: NO`. |
+| NEW FEATURE | full flow. |
+| Trivial (typo, config, dependency bump) | Normal PR and `make verify`; no feature artifacts. |
+
+## Human gates
+
+1. Confirm the request and resolve or defer its open questions.
+2. Approve `spec.md` before planning.
+3. Approve acceptance tests for the current phase before implementation.
+4. Merge only after CI, review, protected-path, and documentation checks pass.
+
+Architecture decisions require Captain approval when architecture is affected. Agents never approve or merge.
+
+## Task states and done
+
+`TODO → IN_PROGRESS → DEV_DONE → DONE`; rework uses `CHANGES_REQUESTED`; an unresolved issue uses `BLOCKED` and `blocked.md`. Escalate after three review iterations.
+
+Done means `make verify` is green, linked criteria pass, required docs are updated, and the Bosun marks the task `DONE`.
+
+## Parallel work and review
+
+- Define API contracts before parallel multi-app work; use one worktree per independent task/app.
+- Do not parallelize tasks that touch the same module or shared task-status rows.
+- CI is deterministic verification; Bosun review checks behavior and invariants; the Captain merges.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsail",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A spec-driven AI development crew. Navigate by spec. Deliver with confidence.",
   "license": "MIT",
   "type": "module",
@@ -14,18 +14,19 @@
     "bin/",
     "src/",
     "scripts/*.sh",
-    "scripts/check-content.mjs",
     "skills/",
-    "specs/_templates/",
+    "docs/workflow.md",
+    "docs/runbook.md",
     "test/",
     "templates/",
+    "tools/",
     "README.md",
     "ROADMAP.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "lint": "node scripts/check-content.mjs",
+    "lint": "node tools/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",

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/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",
@@ -154,7 +155,7 @@ async function init(cwd, output, root) {
     [path.join(root, "templates/.specsail"), path.join(cwd, ".specsail")],
     [path.join(root, "skills"), path.join(cwd, ".specsail/skills")],
     [path.join(root, "scripts"), path.join(cwd, ".specsail/scripts"), { suffixes: [".sh"] }],
-    [path.join(root, "specs/_templates"), path.join(cwd, ".specsail/templates/specs/_templates")],
+    [path.join(root, "templates/specs/_templates"), path.join(cwd, ".specsail/templates/specs/_templates")],
   ];
   let created = 0;
   let skipped = 0;
@@ -165,6 +166,8 @@ async function init(cwd, output, root) {
   }
 
   const individualFiles = [
+    [path.join(root, "docs/workflow.md"), path.join(cwd, ".specsail/docs/workflow.md")],
+    [path.join(root, "docs/runbook.md"), path.join(cwd, ".specsail/docs/runbook.md")],
     [path.join(root, "templates/Makefile"), path.join(cwd, "Makefile")],
     [path.join(root, "templates/docs/project.md"), path.join(cwd, "docs/project.md")],
     [path.join(root, "templates/docs/architecture.md"), path.join(cwd, "docs/architecture.md")],
@@ -180,7 +183,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 +195,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 +225,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 +249,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 +263,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/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,15 @@ 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, ".specsail/docs/workflow.md"), "utf8"), /SpecSail workflow reference/);
+  assert.match(await readFile(path.join(cwd, ".specsail/docs/runbook.md"), "utf8"), /SpecSail runbook/);
+  assert.match(await readFile(path.join(cwd, ".specsail/templates/specs/_templates/spec.md"), "utf8"), /Status: DRAFT/);
+  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 +99,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\./);
+});

package/{scripts → tools}/check-content.mjs

@@ -1,15 +1,17 @@
 import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
 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", "First Mate"],
-  ship: ["Release", "Bosun"],
+  review: ["Reviewer", "Bosun"],
+  ship: ["Release", "Clerk"],
 };
 
 let errors = 0;
@@ -53,10 +55,39 @@ for (const term of ["Navigate by spec. Deliver with confidence.", "The **Captain
   if (!readme.includes(term)) fail(`README.md must document: ${term}`);
 }
 
-const templateFiles = await readdir(path.join(root, "specs/_templates"));
+const templateFiles = await readdir(path.join(root, "templates/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 (!templateFiles.includes(name)) fail(`missing feature scaffold template templates/specs/_templates/${name}`);
 }
 
+const methodologyDocs = ["workflow.md", "runbook.md"];
+for (const name of methodologyDocs) {
+  try {
+    await readFile(path.join(root, "docs", name), "utf8");
+  } catch {
+    fail(`missing canonical methodology doc docs/${name}`);
+  }
+  if (existsSync(path.join(root, "templates/.specsail/docs", name))) {
+    fail(`templates/.specsail/docs/${name} duplicates docs/${name}; keep a single source`);
+  }
+}
+
+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/tools/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: tools/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/templates/.specsail/docs/runbook.md

@@ -1,30 +0,0 @@
-# SpecSail runbook
-
-Step-by-step operating guide. `.specsail/docs/workflow.md` is the concise reference.
-
-## Start a feature
-
-```sh
-./.specsail/scripts/start-phase.sh <slug> 1
-./.specsail/scripts/new-feature.sh <slug> <fix|update|new>
-```
-
-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.
-
-## Run the crew
-
-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.
-
-For later phases, create the phase branch with `start-phase.sh <slug> <phase>`, then write and approve that phase's acceptance tests before implementation.
-
-## Optional headless runner
-
-The Bash runner supports configured Claude, Codex, and OpenCode CLIs, plus a custom command. Copy `.specsail/agents.env.example` to `.specsail/agents.env` to configure it. The runner is optional; any coding tool that can read the project instructions and Markdown skills can follow the workflow interactively. Keep each agent's tool permissions and writable paths minimal.
-
-The scripts require Git and Bash (macOS, Linux, WSL, or Git Bash). The Markdown workflow and Node-based `specsail` commands do not depend on a particular application language or coding agent.

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

@@ -1,47 +0,0 @@
-# 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.
-
-## Stages and crew
-
-| # | Stage / skill | Development role — crew alias | Reads | Writes |
-|---|---|---|---|---|
-| 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 |
-
-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.
-
-## Change paths
-
-| Type | Path |
-|---|---|
-| FIX | understand → spec with a reproduction criterion → acceptance test → implement → review → ship. Skip architecture planning unless needed. |
-| FEATURE UPDATE | full flow; plan skips architecture decisions if `Architecture affected: NO`. |
-| NEW FEATURE | full flow. |
-| Trivial (typo, config, dependency bump) | Normal PR and `make verify`; no feature artifacts. |
-
-## 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`.
-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.
-
-Architecture decisions require Captain approval when the plan says architecture is affected. Merge is always a human decision.
-
-## Task states and done
-
-`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`.
-
-## 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.