specsail 0.2.0 → 0.2.1

package/CHANGELOG.md

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

package/ROADMAP.md

@@ -1,18 +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.
-- 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/{templates/.specsail/docs → docs}/workflow.md

@@ -15,42 +15,42 @@ SpecSail uses durable Markdown artifacts to carry intent between stages. The Cap
 | 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.
+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 ("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.
+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 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`.
+**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; plan skips architecture decisions if `Architecture affected: NO`. |
+| 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 explicitly defer open questions.
-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.
+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 the plan says architecture is affected. Merge is always a human decision.
+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` plus `blocked.md`. After three review iterations, stop and escalate to the Captain.
+`TODO → IN_PROGRESS → DEV_DONE → DONE`; rework uses `CHANGES_REQUESTED`; an unresolved issue uses `BLOCKED` and `blocked.md`. Escalate after three review iterations.
 
-A task is done when `make verify` is green, linked acceptance criteria pass, required docs are updated, and the Bosun marks it `DONE`.
+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; independent tasks may use separate worktrees.
+- 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.2.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/src/cli.js

@@ -155,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;
@@ -166,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")],

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

@@ -44,6 +44,9 @@ test("init preserves project-owned files, installs the crew, and is repeatable",
   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: manifest.version, localSetting: true });

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

@@ -1,4 +1,5 @@
 import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -54,9 +55,21 @@ 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");

package/{scripts → tools}/release.sh

@@ -1,6 +1,6 @@
 #!/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>
+# 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; }

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

@@ -1,44 +0,0 @@
-# SpecSail runbook
-
-Step-by-step operating guide. `.specsail/docs/workflow.md` is the concise reference.
-
-## 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
-```
-
-Stage names also work: `understand`, `plan`, `acceptance-tests`, `implement`, `review`, `ship`. The orchestrator is `manage` / `first-mate`.
-
-## 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 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.
-
-## 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.