specsail 0.0.0-stage → 0.1.0

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,297 @@
+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 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. 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.",
+    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: fill docs/project.md and docs/architecture.md, configure Makefile, then run specsail doctor.");
+  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: run ".specsail/scripts/run-agent.sh understand ${slug}" with your agent, or read the Scout skill.`);
+  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 stageRoles) {
+    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.");
+  }
+  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,30 @@
+# 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.
+
+## Crew and skills
+
+| Stage | Development role | Crew name | Skill |
+|---|---|---|---|
+| 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` |
+
+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.
+
+## 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 must be independent of implementation and report 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,30 @@
+# 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

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

package/templates/Makefile

@@ -0,0 +1,19 @@
+# SPECSAIL_UNCONFIGURED_TEMPLATE: replace these recipes with your project's real checks.
+.PHONY: setup lint typecheck test accept verify check-protected
+
+# Configure these commands for your project before using the workflow.
+setup:
+	@echo "Configure setup for this project's stack"; exit 1
+lint:
+	@echo "Configure lint for this project's stack"; exit 1
+typecheck:
+	@echo "Configure typecheck for this project's stack (or use a no-op if not applicable)"; exit 1
+test:
+	@echo "Configure unit/integration tests; exclude tests/acceptance/**"; exit 1
+accept:
+	@echo "Configure acceptance tests from tests/acceptance/**"; exit 1
+
+verify: lint typecheck test accept
+
+check-protected:
+	@.specsail/scripts/check-protected-paths.sh $${BASE:-origin/main}

package/templates/docs/architecture.md

@@ -0,0 +1,15 @@
+# Architecture
+
+<!-- Complete for the consuming project. Keep the overview short; use docs/architecture/<module>.md for module detail. -->
+
+## System context
+
+## Module boundaries and allowed dependencies
+
+## Critical data flows
+
+## Cross-cutting concerns
+
+## Invariants
+
+## Key decisions

package/templates/docs/project.md

@@ -0,0 +1,19 @@
+# Project
+
+<!-- Complete this file for the consuming project. Keep details that agents cannot reliably infer from the code. -->
+
+## What it is / who uses it
+
+## Non-goals
+
+## Glossary
+| Term | Meaning |
+|---|---|
+
+## Tech stack
+
+## Repo map
+
+## Invariants and gotchas
+
+## Pointers