specsail 0.0.0-stage → 0.2.0

package/skills/review/SKILL.md

@@ -0,0 +1,35 @@
+---
+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: Bosun
+---
+# 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.
+
+## Writes
+`specs/<feature>/review.md` (only when changes are needed) and the task status in `tasks.md`.
+
+## Checklist (evidence required: file:line)
+1. `make verify` is green (run it; don't trust the report).
+2. Each AC of the task has a passing test that really exercises it (not trivially passing).
+3. Behavior matches the spec, including Out of scope: no scope creep, no missing cases.
+4. Architecture boundaries and invariants respected.
+5. Protected paths untouched (`make check-protected`).
+6. Docs listed in plan.md updated.
+7. Correctness, error handling, security, obvious perf traps in the changed code.
+
+## Outcome
+- No BLOCKER/MAJOR → set `DONE`. NITs may be listed in the report but don't block.
+- Otherwise → write `review.md` from the template (overwrite previous), set `CHANGES_REQUESTED`, increment loops in `tasks.md`.
+- Loops reaches 3 → don't request again; write `blocked.md` summarizing the disagreement and stop.
+
+## Must not
+Edit code or tests; approve without running verify; raise findings without evidence; review style already covered by lint.

package/skills/ship/SKILL.md

@@ -0,0 +1,30 @@
+---
+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: Clerk
+---
+# 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`.
+
+## Writes
+Docs only, in the same PR: changelog entry, README, API docs, architecture/project/module docs where the diff changed reality. Commit prefix `docs:`.
+
+## Process
+1. Confirm every task in the phase is `DONE` and `make verify` is green. If not, stop.
+2. Compare the diff to the docs; update only what became false or incomplete. Keep project.md/architecture.md short.
+3. Add a changelog entry from the spec Objective and ACs (user-facing language).
+4. Run `scripts/open-pr.sh <feature> <phase>`; the PR description links spec.md and lists AC coverage.
+
+## Must not
+Merge; edit code, tests, spec or plan; grow docs with history or status.
+
+## Done when
+PR is open, docs are current, and the human has what they need to merge.

package/skills/understand/SKILL.md

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

package/specs/_templates/blocked.md

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

package/specs/_templates/plan.md

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

package/specs/_templates/request.md

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

package/specs/_templates/review.md

@@ -0,0 +1,18 @@
+# Review: {{SLUG}} / T-?
+Iteration: 1
+Verdict: CHANGES_REQUESTED
+<!-- Written only when changes are needed. If all is good, mark DONE in tasks.md and don't write this file. -->
+
+## AC coverage
+| AC | Test | Result |
+|---|---|---|
+| AC-1 | tests/acceptance/... | pass / missing / weak |
+
+## Findings
+<!-- Every finding needs evidence. Severity: BLOCKER (spec/AC violated, bug, broken invariant) | MAJOR | NIT (not blocking) -->
+1. **[BLOCKER]** `path/file.ext:42` — what is wrong, which AC/invariant it violates, expected fix direction.
+
+## Checked and OK
+- Scope creep: none
+- Protected paths untouched
+- Docs updated: yes

package/specs/_templates/spec.md

@@ -0,0 +1,20 @@
+# Spec: {{SLUG}}
+Status: DRAFT
+<!-- A human changes DRAFT to APPROVED. Agents never do. -->
+
+## Overview
+
+## Objective
+<!-- One or two sentences: what outcome, for whom. -->
+
+## Acceptance criteria
+<!-- IDs are stable. Tests are named by ID. Use domain glossary terms exactly. -->
+
+### AC-1: <short title>
+- **Given**
+- **When**
+- **Then**
+
+## Out of scope
+
+## Open questions

package/specs/_templates/tasks.md

@@ -0,0 +1,7 @@
+# Tasks: {{SLUG}}
+States: TODO → IN_PROGRESS → DEV_DONE → DONE | CHANGES_REQUESTED | BLOCKED
+Only the role named in docs/workflow.md changes a status. Plan.md defines tasks; this file only tracks status.
+
+| Task | Status | Review loops | Notes |
+|---|---|---|---|
+| T-1 | TODO | 0 | |

package/src/cli.js

@@ -0,0 +1,300 @@
+import { access, copyFile, lstat, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+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",
+  new: "NEW FEATURE",
+};
+
+const help = `SpecSail — navigate by spec, deliver with confidence.
+
+Usage:
+  specsail init                      Add SpecSail to the current project
+  specsail new <slug> <fix|update|new>
+                                     Create a feature's request/spec/plan/tasks
+  specsail doctor                    Check the current project's SpecSail setup
+  specsail --version                 Print the installed version
+  specsail --help                    Show this help
+
+The Captain is always human. SpecSail does not approve specs/tests or merge PRs.
+`;
+
+function writeLine(stream, text) {
+  stream(`${text}\n`);
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function lstatIfExists(filePath) {
+  try {
+    return await lstat(filePath);
+  } catch (failure) {
+    if (failure.code === "ENOENT") return undefined;
+    throw failure;
+  }
+}
+
+async function ensureSafeDirectory(projectRoot, directory) {
+  const relative = path.relative(projectRoot, directory);
+  if (relative && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))) {
+    throw new Error(`Refusing to write outside the project: ${directory}`);
+  }
+  let current = projectRoot;
+  for (const segment of relative ? relative.split(path.sep) : []) {
+    current = path.join(current, segment);
+    try {
+      const details = await lstat(current);
+      if (details.isSymbolicLink() || !details.isDirectory()) {
+        throw new Error(`Refusing to write through a symlink or non-directory path: ${current}`);
+      }
+    } catch (failure) {
+      if (failure.code !== "ENOENT") throw failure;
+      await mkdir(current);
+    }
+  }
+}
+
+async function copyTree(source, destination, { suffixes, projectRoot } = {}) {
+  let created = 0;
+  let skipped = 0;
+  const entries = await readdir(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(source, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    if (entry.isDirectory()) {
+      await ensureSafeDirectory(projectRoot, destinationPath);
+      const result = await copyTree(sourcePath, destinationPath, { suffixes, projectRoot });
+      created += result.created;
+      skipped += result.skipped;
+    } else if (entry.isFile() && (!suffixes || suffixes.some((suffix) => entry.name.endsWith(suffix)))) {
+      await ensureSafeDirectory(projectRoot, path.dirname(destinationPath));
+      try {
+        const sourceStat = await stat(sourcePath);
+        await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL);
+        await access(destinationPath, constants.F_OK);
+        if (process.platform !== "win32") await import("node:fs/promises").then(({ chmod }) => chmod(destinationPath, sourceStat.mode));
+        created += 1;
+      } catch (error) {
+        if (error.code === "EEXIST") skipped += 1;
+        else throw error;
+      }
+    }
+  }
+  return { created, skipped };
+}
+
+async function copyFileIfMissing(source, destination, projectRoot) {
+  await ensureSafeDirectory(projectRoot, path.dirname(destination));
+  try {
+    const sourceStat = await stat(source);
+    await copyFile(source, destination, constants.COPYFILE_EXCL);
+    if (process.platform !== "win32") await import("node:fs/promises").then(({ chmod }) => chmod(destination, sourceStat.mode));
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+async function updateManagedBlock(filePath, marker, text, projectRoot) {
+  await ensureSafeDirectory(projectRoot, path.dirname(filePath));
+  let current = "";
+  const details = await lstatIfExists(filePath);
+  if (details) {
+    if (details.isSymbolicLink() || !details.isFile()) throw new Error(`Refusing to modify symlink or non-file: ${filePath}`);
+    current = await readFile(filePath, "utf8");
+  }
+  const [start, end] = marker;
+  const startCount = current.split(start).length - 1;
+  const endCount = current.split(end).length - 1;
+  if (startCount !== endCount || startCount > 1) {
+    throw new Error(`Cannot safely update managed section in ${path.relative(process.cwd(), filePath)}: markers are unbalanced or duplicated.`);
+  }
+  const section = `${start}\n${text.trim()}\n${end}`;
+  if (startCount === 1) {
+    const escapedStart = start.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escapedEnd = end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    current = current.replace(new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`), section);
+  } else {
+    current = `${current.trimEnd()}${current.trim() ? "\n\n" : ""}${section}\n`;
+  }
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, current, "utf8");
+}
+
+async function loadInstalledConfig(configPath) {
+  try {
+    const details = await lstatIfExists(configPath);
+    if (!details) return {};
+    if (details.isSymbolicLink() || !details.isFile()) throw new Error("expected a regular file, not a symlink");
+    const parsed = JSON.parse(await readFile(configPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("expected a JSON object");
+    return parsed;
+  } catch (error) {
+    throw new Error(`Cannot read .specsail.json: ${error.message}`);
+  }
+}
+
+async function init(cwd, output, root) {
+  const configPath = path.join(cwd, ".specsail.json");
+  const config = await loadInstalledConfig(configPath);
+  const operations = [
+    [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")],
+  ];
+  let created = 0;
+  let skipped = 0;
+  for (const [source, destination, options] of operations) {
+    const result = await copyTree(source, destination, { ...options, projectRoot: cwd });
+    created += result.created;
+    skipped += result.skipped;
+  }
+
+  const individualFiles = [
+    [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")],
+    [path.join(root, "templates/docs/architecture/.gitkeep"), path.join(cwd, "docs/architecture/.gitkeep")],
+    [path.join(root, "templates/.github/CODEOWNERS"), path.join(cwd, ".github/CODEOWNERS")],
+    [path.join(root, "templates/.github/workflows/verify.yml"), path.join(cwd, ".github/workflows/verify.yml")],
+  ];
+  for (const [source, destination] of individualFiles) {
+    if (await copyFileIfMissing(source, destination, cwd)) created += 1;
+    else skipped += 1;
+  }
+
+  await updateManagedBlock(
+    path.join(cwd, "AGENTS.md"),
+    ["<!-- specsail:start -->", "<!-- specsail:end -->"],
+    "## 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(
+    path.join(cwd, ".gitignore"),
+    ["# >>> SpecSail >>>", "# <<< SpecSail <<<"],
+    ".specsail/agents.env",
+    cwd,
+  );
+  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: 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;
+}
+
+function validSlug(slug) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
+}
+
+async function newFeature(cwd, args, output) {
+  const [slug, kind, ...extra] = args;
+  if (!slug || !kind || extra.length || !validSlug(slug) || !Object.hasOwn(typeNames, kind)) {
+    throw new Error("Usage: specsail new <lowercase-kebab-slug> <fix|update|new>");
+  }
+  const specsailRoot = path.join(cwd, ".specsail");
+  const templates = path.join(specsailRoot, "templates/specs/_templates");
+  if (!(await exists(templates))) throw new Error("SpecSail is not initialized here. Run `specsail init` first.");
+  const destination = path.join(cwd, "specs", slug);
+  if (await exists(destination)) throw new Error(`specs/${slug} already exists; refusing to overwrite it.`);
+  const entries = ["request.md", "spec.md", "plan.md", "tasks.md"];
+  await ensureSafeDirectory(cwd, path.join(cwd, "specs"));
+  await mkdir(destination, { recursive: true });
+  try {
+    for (const entry of entries) {
+      const source = await readFile(path.join(templates, entry), "utf8");
+      const content = source.replaceAll("{{SLUG}}", slug).replaceAll("{{TYPE}}", typeNames[kind]);
+      await writeFile(path.join(destination, entry), content, { flag: "wx" });
+    }
+  } catch (error) {
+    throw new Error(`Could not scaffold specs/${slug}: ${error.message}. Remove the partial directory before retrying.`);
+  }
+  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;
+}
+
+async function hasGitRepository(cwd) {
+  let current = cwd;
+  while (true) {
+    if (await exists(path.join(current, ".git"))) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+async function doctor(cwd, output, error) {
+  const failures = [];
+  const checks = [
+    [".specsail.json", path.join(cwd, ".specsail.json")],
+    [".specsail/AGENTS.md", path.join(cwd, ".specsail/AGENTS.md")],
+    ["AGENTS.md SpecSail section", path.join(cwd, "AGENTS.md")],
+  ];
+  for (const [label, filePath] of checks) {
+    if (!(await exists(filePath))) failures.push(`Missing ${label}; run specsail init.`);
+  }
+  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.`);
+  }
+  const makefile = path.join(cwd, "Makefile");
+  const makefileContent = await exists(makefile) ? await readFile(makefile, "utf8") : "";
+  if (!/^verify\s*:/m.test(makefileContent)) {
+    failures.push("Makefile must define a verify target. Configure it for this project's stack.");
+  } else if (makefileContent.includes("SPECSAIL_UNCONFIGURED_TEMPLATE")) {
+    failures.push("Makefile still contains the SpecSail starter template. Configure setup, lint, typecheck, test, and accept before relying on make verify.");
+  }
+  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) {
+    for (const failure of failures) writeLine(error, `✗ ${failure}`);
+    return 1;
+  }
+  writeLine(output, "✓ SpecSail files and verify target are present.");
+  return 0;
+}
+
+export async function runCli(args, options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const root = path.resolve(options.packageRoot ?? packageRoot);
+  const output = options.stdout ?? ((text) => process.stdout.write(text));
+  const error = options.stderr ?? ((text) => process.stderr.write(text));
+  const [command, ...rest] = args;
+  try {
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+      writeLine(output, help);
+      return 0;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+      const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+      writeLine(output, manifest.version);
+      return 0;
+    }
+    if (command === "init") return await init(cwd, output, root);
+    if (command === "new") return await newFeature(cwd, rest, output);
+    if (command === "doctor") return await doctor(cwd, output, error);
+    throw new Error(`Unknown command: ${command}. Run specsail --help for usage.`);
+  } catch (failure) {
+    writeLine(error, `Error: ${failure.message}`);
+    return 1;
+  }
+}

package/templates/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Replace @OWNER with the GitHub handle/team that acts as Captain.
+/tests/acceptance/   @OWNER
+/specs/*/spec.md     @OWNER
+/specs/*/plan.md     @OWNER
+/AGENTS.md           @OWNER
+/.specsail/          @OWNER

package/templates/.github/workflows/verify.yml

@@ -0,0 +1,18 @@
+name: verify
+on:
+  pull_request:
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Set up Node.js (for SpecSail CLI)
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20
+      # Add your stack's setup action here if make setup needs it.
+      - run: make setup
+      - run: make verify
+      - run: make check-protected BASE=origin/${{ github.base_ref }}

package/templates/.specsail/AGENTS.md

@@ -0,0 +1,41 @@
+# SpecSail project rules
+
+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
+
+| Skill | Development role | Crew alias | Purpose |
+|---|---|---|---|
+| `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. |
+
+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
+
+`request → approved spec → plan → approved acceptance tests (per phase) → implement one task → review → ship`
+
+- Read `docs/project.md` and `docs/architecture.md` before scoping project work. Add module documentation under `docs/architecture/` when needed.
+- Feature artifacts live in `specs/<feature>/`; templates are in `.specsail/templates/specs/_templates/`.
+- 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 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/agents.env.example

@@ -0,0 +1,15 @@
+# Copy to .specsail/agents.env (gitignored). Read by .specsail/scripts/run-agent.sh.
+# CLI options: claude | codex | opencode | custom
+AGENT_CLI=claude
+# AGENT_CUSTOM_CMD="pi -p"      # used when a role's CLI is "custom"; prompt is appended as last arg
+
+# Per-stage overrides. You may invoke a stage by either its name or crew alias.
+# Tier guidance: frontier for understand/plan/acceptance-tests/review, mid/cheap for implement.
+# Use a DIFFERENT model family for review.
+AGENT_MODEL_UNDERSTAND=
+AGENT_MODEL_PLAN=
+AGENT_MODEL_ACCEPTANCE_TESTS=
+AGENT_MODEL_IMPLEMENT=
+AGENT_MODEL_REVIEW=
+AGENT_CLI_REVIEW=codex
+AGENT_MODEL_SHIP=

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

@@ -0,0 +1,44 @@
+# 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.