doctrina-cli 0.18.0 → 0.21.0

package/src/lib/workspace.js

@@ -0,0 +1,323 @@
+// @ts-check
+import {
+  existsSync, lstatSync, linkSync, mkdirSync, readFileSync, readdirSync,
+  realpathSync, rmdirSync, statSync, symlinkSync, unlinkSync, copyFileSync,
+} from "node:fs";
+import path from "node:path";
+import { isDir, isFile, read, toPosix, write } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+import { openChanges } from "./snapshot.js";
+import { git as runGit, GIT_STATE } from "./git.js";
+import { cdThen } from "./shell.js";
+
+// A WORKSPACE holds the context of several repositories in one place (ADR
+// 0029): which projects exist, what each one is, how they depend on each
+// other, and — for a repository that cannot carry `.doctrina/` — the
+// artifacts themselves. It is a plain directory the human keeps as a private
+// git repository, so the context of a repository nobody may commit to is
+// still versioned, by its owner, somewhere.
+//
+// The CLI never moves the code. A SHADOW project's artifacts live under
+// `<workspace>/projects/<name>/` and are LINKED into the repository, then
+// hidden from that repository's git through `.git/info/exclude` — a file git
+// reads and never commits. Every existing command keeps working unchanged in
+// the repository, because from its working directory `.doctrina/` is simply
+// there.
+
+export {
+  WORKSPACE_FILE, WORKSPACE_SCHEMA, PROJECT_MODES, PROJECT_NAME, EXCLUDE_BEGIN, EXCLUDE_END,
+  blankWorkspace, isWorkspaceDir, readWorkspace, writeWorkspace, doctrinaHome, pointerPath, writePointer,
+  findWorkspace, projectAt, shadowDirOf, artifactRootOf,
+} from "./workspace-locate.js";
+import {
+  EXCLUDE_BEGIN, EXCLUDE_END, isWorkspaceDir, readWorkspace, writeWorkspace, findWorkspace, projectAt,
+  shadowDirOf, artifactRootOf, WORKSPACE_FILE, doctrinaHome, pointerPath, blankWorkspace, writePointer, PROJECT_NAME, PROJECT_MODES, WORKSPACE_SCHEMA, safeReal,
+} from "./workspace-locate.js";
+
+/**
+ * Where a project stands. `missing` when its repository path is gone;
+ * `pending` while it has no spec or its intake is unconverted — the
+ * project still has to be absorbed; `ready` otherwise.
+ */
+const INTAKE_PENDING = "intake not converted";
+// A shadow's folder in the workspace is gone (change 0235): `attach` restores it.
+const SHADOW_GONE = "its shadow folder in the workspace is gone";
+
+/**
+ * The command that moves a pending project on (second audit, change 0233).
+ * `--from-code` starts an absorb and refuses once the inventory is stored —
+ * every surface still named it for a project whose absorb was under way. A
+ * stored, pending intake reprints its playbook with a bare `doctrina intake`.
+ * @param {{ path: string, name?: string }} project
+ * @param {string} reason  projectState's reason
+ */
+export function absorbCommand(project, reason) {
+  if (reason === SHADOW_GONE) return `doctrina workspace attach ${project.name ?? "<name>"}`;
+  return reason === INTAKE_PENDING
+    ? cdThen(project.path, "doctrina intake")
+    : cdThen(project.path, "doctrina intake --from-code");
+}
+
+export function projectState(wsDir, project) {
+  if (!isDir(project.path)) return { state: "missing", reason: `path not found: ${project.path}`, open: [] };
+  const root = artifactRootOf(wsDir, project);
+  const doctrina = path.join(root, ".doctrina");
+  if (project.mode === "shadow" && !isDir(doctrina)) return { state: "pending", reason: SHADOW_GONE, open: [] };
+  if (!isDir(doctrina)) return { state: "pending", reason: "no .doctrina/ yet", open: [] };
+  const intake = path.join(doctrina, "intake.md");
+  if (isFile(intake) && /pending/i.test(listHeader(read(intake), "Status") ?? "")) {
+    return { state: "pending", reason: INTAKE_PENDING, open: openChanges(root) };
+  }
+  const specs = path.join(doctrina, "specs");
+  const count = isDir(specs) ? readdirSync(specs).filter((d) => isFile(path.join(specs, d, "spec.md"))).length : 0;
+  if (count === 0) return { state: "pending", reason: "no capability spec yet", open: openChanges(root) };
+  return { state: "ready", reason: `${count} spec${count === 1 ? "" : "s"}`, open: openChanges(root) };
+}
+
+// ---------------------------------------------------------------------------
+// Links
+// ---------------------------------------------------------------------------
+
+function shadowFiles(shadowDir) {
+  const out = [];
+  const stack = [""];
+  while (stack.length) {
+    const rel = stack.pop();
+    for (const entry of readdirSync(path.join(shadowDir, rel))) {
+      const r = rel ? path.join(rel, entry) : entry;
+      if (r === ".git" || r === ".doctrina") continue;
+      if (isDir(path.join(shadowDir, r))) stack.push(r);
+      else out.push(r);
+    }
+  }
+  return out.sort();
+}
+
+/** True when `at` already resolves to `target` (a symlink, a junction, or a hard link). */
+export function linksTo(at, target) {
+  let st;
+  try {
+    st = lstatSync(at);
+  } catch {
+    return false;
+  }
+  if (st.isSymbolicLink()) return safeReal(at) === safeReal(target);
+  try {
+    const t = statSync(target);
+    return !st.isDirectory() && st.ino === t.ino && st.dev === t.dev && st.ino !== 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What attaching a shadow project would do, entry by entry. `.doctrina/` is
+ * linked as one directory — every command creates files inside it. Every
+ * other file the shadow holds (AGENTS.md, the agent's rule and hooks) is
+ * linked one by one, so a repository that already has a `.cursor/` keeps it.
+ * A path the repository already owns is a conflict, left untouched.
+ * @returns {{ rel: string, kind: "dir"|"file", action: "link"|"ok"|"conflict" }[]}
+ */
+export function linkPlan(shadowDir, repoDir) {
+  const entries = [{ rel: ".doctrina", kind: /** @type {const} */ ("dir") },
+    ...shadowFiles(shadowDir).map((rel) => ({ rel, kind: /** @type {const} */ ("file") }))];
+  return entries.map(({ rel, kind }) => {
+    const at = path.join(repoDir, rel);
+    const target = path.join(shadowDir, rel);
+    let action = /** @type {"link"|"ok"|"conflict"} */ ("link");
+    if (linksTo(at, target)) action = "ok";
+    else if (existsOrLink(at)) action = "conflict";
+    return { rel: toPosix(rel), kind, action };
+  });
+}
+
+function existsOrLink(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create the links a plan calls for. A directory becomes a symlink (a
+ * junction on Windows, which needs no privilege); a file becomes a symlink,
+ * else a hard link, else — last resort — a copy, which `attach` reports
+ * because a copy does not follow the shadow.
+ * @returns {{ rel: string, how: string }[]}
+ */
+export function applyLinks(plan, shadowDir, repoDir) {
+  const done = [];
+  for (const entry of plan) {
+    if (entry.action !== "link") continue;
+    const at = path.join(repoDir, entry.rel);
+    const target = path.join(shadowDir, entry.rel);
+    mkdirSync(path.dirname(at), { recursive: true });
+    if (entry.kind === "dir") {
+      symlinkSync(target, at, "junction");
+      done.push({ rel: entry.rel, how: "linked" });
+      continue;
+    }
+    try {
+      symlinkSync(target, at, "file");
+      done.push({ rel: entry.rel, how: "linked" });
+    } catch {
+      try {
+        linkSync(target, at);
+        done.push({ rel: entry.rel, how: "hard-linked" });
+      } catch {
+        copyFileSync(target, at);
+        done.push({ rel: entry.rel, how: "copied" });
+      }
+    }
+  }
+  return done;
+}
+
+/**
+ * The shadow folder a repository's `.doctrina/` links to, or null when the
+ * repository owns its `.doctrina/` (change 0238).
+ * @param {string} projectRoot
+ */
+export function shadowRootOf(projectRoot) {
+  const link = path.join(projectRoot, ".doctrina");
+  try {
+    if (!lstatSync(link).isSymbolicLink()) return null;
+    return path.dirname(realpathSync(link));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Re-link a shadowed repository after its shadow gained or lost files
+ * (change 0238): a link for each new file, the links to removed files taken
+ * out, and the exclude block rewritten. A command that writes an adapter
+ * file for a shadowed repository writes it in the shadow and calls this —
+ * written in the repository it was a stray, untracked file.
+ * @param {string} projectRoot
+ * @param {Array<{ rel: string, content: string }>} gone  the files the shadow lost, with what they held
+ * @returns {{ linked: string[], unlinked: string[] } | null}  null for a repository that is not a shadow
+ */
+export function relinkShadow(projectRoot, gone = []) {
+  const shadow = shadowRootOf(projectRoot);
+  if (!shadow) return null;
+  const unlinked = [];
+  for (const { rel, content } of gone) {
+    const at = path.join(projectRoot, rel);
+    let st;
+    try {
+      st = lstatSync(at);
+    } catch {
+      continue;
+    }
+    // A symlink to the removed file, or the hard link or copy a platform
+    // without symlinks got instead — still holding what the shadow held.
+    if (st.isSymbolicLink() || (st.isFile() && readFileSync(at, "utf8").replace(/\r\n/g, "\n").trim() === content.replace(/\r\n/g, "\n").trim())) {
+      unlinkSync(at);
+      unlinked.push(toPosix(rel));
+      pruneEmpty(path.dirname(at), projectRoot);
+    }
+  }
+  const plan = linkPlan(shadow, projectRoot);
+  const linked = applyLinks(plan, shadow, projectRoot).map((d) => d.rel);
+  writeExclude(projectRoot, excludeEntries(plan, projectRoot));
+  return { linked, unlinked };
+}
+
+/**
+ * Remove every link the shadow put in the repository — the link, never what
+ * it points at: `fs-ops.remove` follows a directory link and would empty
+ * the shadow, which is why this module does its own unlinking.
+ * @returns {string[]} the paths removed
+ */
+export function removeLinks(shadowDir, repoDir) {
+  const removed = [];
+  for (const entry of linkPlan(shadowDir, repoDir)) {
+    if (entry.action !== "ok") continue;
+    const at = path.join(repoDir, entry.rel);
+    try {
+      unlinkSync(at);
+    } catch {
+      rmdirSync(at);
+    }
+    removed.push(entry.rel);
+    pruneEmpty(path.dirname(at), repoDir);
+  }
+  return removed;
+}
+
+function pruneEmpty(dir, stopAt) {
+  let cur = dir;
+  while (cur.startsWith(stopAt + path.sep)) {
+    try {
+      if (readdirSync(cur).length > 0) return;
+      rmdirSync(cur);
+    } catch {
+      return;
+    }
+    cur = path.dirname(cur);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The repository's local exclude file
+// ---------------------------------------------------------------------------
+
+function git(repoDir, args) {
+  const r = runGit(repoDir, args);
+  return r.state === GIT_STATE.OK ? r.stdout : null;
+}
+
+/** `git init` a new workspace. True when it worked. */
+export function gitInit(dir) {
+  return runGit(dir, ["init", "-q"]).state === GIT_STATE.OK;
+}
+
+/** `.git/info/exclude` for this repository (worktrees included), or null outside git. */
+export function excludePathOf(repoDir) {
+  const out = git(repoDir, ["rev-parse", "--git-path", "info/exclude"]);
+  if (out === null) return null;
+  return path.resolve(repoDir, out.trim());
+}
+
+/** True when the repository tracks anything under `rel`. */
+export function tracksAnything(repoDir, rel) {
+  const out = git(repoDir, ["ls-files", "--", rel]);
+  return out !== null && out.trim() !== "";
+}
+
+/** The patterns that keep a shadow invisible to the repository's git. */
+export function excludeEntries(plan, repoDir) {
+  // No trailing slash on a linked directory: git sees a symlink as a file,
+  // and `/.doctrina/` would match only a real directory.
+  const out = plan.filter((e) => e.action !== "conflict").map((e) => "/" + e.rel);
+  // `index rebuild` exports skills into the repository's own folders; they
+  // belong to the shadow too, unless the repository already keeps skills.
+  for (const dir of [".agents/skills", ".claude/skills"]) {
+    if (!tracksAnything(repoDir, dir)) out.push(`/${dir}/`);
+  }
+  return [...new Set(out)];
+}
+
+/** Replace the managed block of an exclude file's text. */
+export function withExcludeBlock(text, entries) {
+  const lines = String(text ?? "").replace(/\r\n/g, "\n").split("\n");
+  const b = lines.indexOf(EXCLUDE_BEGIN);
+  const e = lines.indexOf(EXCLUDE_END);
+  const kept = b >= 0 && e > b ? [...lines.slice(0, b), ...lines.slice(e + 1)] : lines;
+  while (kept.length > 0 && kept[kept.length - 1] === "") kept.pop();
+  if (entries.length === 0) return kept.length ? kept.join("\n") + "\n" : "";
+  return [...kept, ...(kept.length ? [""] : []), EXCLUDE_BEGIN, ...entries, EXCLUDE_END, ""].join("\n");
+}
+
+/** Write (or with no entries, clear) the managed block. Returns the file, or null outside git. */
+export function writeExclude(repoDir, entries) {
+  const p = excludePathOf(repoDir);
+  if (!p) return null;
+  const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+  mkdirSync(path.dirname(p), { recursive: true });
+  write(p, withExcludeBlock(before, entries), { force: true });
+  return p;
+}

package/templates/AGENTS.md.template

@@ -16,13 +16,17 @@ prompt and approves; do not make them run the CLI or hand-author artifacts.
 - **Bootstrap.** No capability in `.doctrina/specs/`, or an intake still
   `Status: pending`? The specs are not written: run `doctrina intake --text
   "<description>"` and execute the printed playbook in one pass (existing
-  codebase: `doctrina work --from-diff`). After conversion the specs are the
+  code, no specs: `doctrina intake --from-code`). After conversion the specs are the
   only source of truth — never edit `intake.md` to change requirements.
-- **Day-to-day.** Start every session with `doctrina prime` (gates, rules,
-  open work in one read). Turn any request into a change with `doctrina work
-  "<prompt>"` and follow the printed playbook. Preview a close with `doctrina
-  change check <id>`; close with `doctrina close <id>`. Unsure what's next?
-  `doctrina next`. Before compaction or handover: `doctrina handoff`.
+- **Day-to-day.** `doctrina prime` opens the session (gates, rules, open
+  work). A request that changes behaviour is a change opened BEFORE code is
+  edited: `doctrina work "<request>"` — it classifies the lane itself; one
+  change per activity the human asked for. Name the change id in your first
+  sentence to the human. Read with `doctrina context <cap> --for "<task>"
+  --concat` — `prime` is state, not the spec. Project skills are listed
+  where your agent finds skills (`.agents/skills/`, `.claude/skills/`).
+  Close with `doctrina close <id>` and repeat the archive path it prints.
+  Unsure what's next? `doctrina next`. Before handover: `doctrina handoff`.
 
 <!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->
 ## Doctrina command surface (generated — reach for these, don't hand-author)
@@ -43,10 +47,10 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina why` — provenance: intent, proof, ADRs, and history. *When:* you need to justify or trace a capability's existence.
 - `doctrina handoff (before compaction/handover)` — a resume note: open work, task state, next command. *When:* BEFORE compaction or handing over to another session.
 **Change**
-- `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
-- `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
+- `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* diagnosing an incident or a runtime symptom — `work` classifies every other request itself.
+- `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request changes behaviour — BEFORE editing code; it classifies the lane itself.
 - `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
-- `doctrina change new|apply|archive|check|tick|abandon|delta` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
+- `doctrina change new|apply|archive|check|tick|abandon|delta|card` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
 - `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.
 - `doctrina decision new|accept|land|supersede|list|scope` — record, accept, land, scope, and supersede ADRs. *When:* the change decides something a later session must not relitigate.
 - `doctrina skill new|list|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
@@ -60,6 +64,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina verify` — the project's declared typecheck/test/build checks. *When:* the real build gate must run.
 - `doctrina close <id...>` — the whole closing sequence in one attested pass. *When:* a change is implemented and ready to finish.
 - `doctrina doctor` — aggregate diagnostic with per-finding remedies. *When:* something looks wrong and you do not know which gate to ask.
+**Orchestrate** (triggers: `doctrina <command> --help`) — `doctrina workspace init|add|attach|detach|list|tool|guard` · `doctrina delivery new|route|list|status|tick|check|close`
 **Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
 <!-- doctrina:surface:end -->
 
@@ -111,11 +116,9 @@ Finish by running `doctrina validate` and resolving every `error:`.
 
 ## How to read context efficiently
 
-`doctrina context [<capability>] --concat` assembles the read pack in one
-call: this `AGENTS.md` → `product.md` → the capability spec → open changes →
-accepted ADRs. Run it for ANY task; it skips `changes/archive/`. Skills are
-on demand: read the `description:` / `when:` frontmatter in
-`.doctrina/skills/` and load a body only when its trigger fires.
+`doctrina context <cap> --for "<task>" --concat` is the read pack for ANY
+task: `product.md`, the spec, open changes and accepted ADRs, cut to what
+the task is about. `doctrina show <ref>` reads one requirement or ADR.
 
 Keep this file under 150 lines. The scaffold already spends most of them
 and the generated block above grows with the CLI — `doctrina doctor`

package/templates/README.md

@@ -25,6 +25,11 @@ replace. No conditionals, loops, or includes.
 | `{{CONTRACT_NAME}}` | Slug for a new integration contract | required, no default |
 | `{{FRAMEWORK_VERSION}}` | Version of the CLI that scaffolded/stamped the tree | running CLI version |
 | `{{AGENTS_MD_PATH}}` | Path to root `AGENTS.md` from the adapter location | per adapter |
+| `{{DELIVERY_ID}}` | Delivery folder identifier (`NNNN-slug`) | required in `delivery` |
+| `{{DELIVERY_TITLE}}` | The delivery's title | required in `delivery` |
+| `{{DELIVERY_TITLE_ARG}}` | The delivery's title quoted as one shell argument, for a command line | optional in the `delivery` playbook |
+| `{{DELIVERY_REF}}` | The tracker item it comes from | `—` |
+| `{{DELIVERY_PROJECTS}}` | The routed projects, dependencies first | `—` |
 
 CLI authors and template authors share this vocabulary. Adding a token
 requires extending the templates spec at `.doctrina/specs/templates/spec.md`.
@@ -45,9 +50,14 @@ loops in it.
 | `{{CAPABILITY_BLOCK}}` | The pinned capability, the ranked hints, or "no match" | required in `work` |
 | `{{DIFF_MATCHES}}` | Capabilities the working tree touched | empty |
 | `{{STEP3_INTRO}}` | The delta step's opening, pinned or not | required in `work` |
+| `{{FOR}}` | The task, as the read pack's `--for` query (quotes stripped, 80 chars at most) | required in `work` |
 | `{{SHAPE}}` | The spec's measured size — lines, requirements per EARS subsection, criteria | required in `consolidate` |
 | `{{FROM_DIFF_DELTA_NOTE}}` | The backfill caveat on writing the delta | empty |
 | `{{MISSING_SPECS_WARNING}}` | Warning that `.doctrina/specs/` is absent | empty |
+| `{{WORKSPACE_STEP}}` | The closing step naming the workspace a project belongs to | empty, in `absorb` |
+| `{{DELIVERY_FILE}}` | The delivery file, relative to the workspace | required in `delivery` |
+| `{{ROUTING}}` | The routed order, or the projects ranked against the title | required in `delivery` |
+| `{{TOOLS}}` | The tools the workspace declares, with their access | empty, in `delivery` |
 
 A line holding NOTHING but one token whose value is empty is removed rather
 than left blank, which is what lets the optional blocks above be plain tokens.
@@ -98,7 +108,7 @@ adapters/
   claude/.claude/commands/doctrina-*.md.template   native slash commands (core loop)
   codex/README.md
   cursor/.cursor/rules/00-doctrina.mdc.template
-  cursor/.cursor/commands/doctrina-*.md.template   native slash commands (core loop)
+  cursor/.cursor/skills/doctrina-*/SKILL.md.template   the core loop as skills (explicit `/` invocation)
   copilot/.github/copilot-instructions.md.template
   gemini/GEMINI.md.template
   aider/CONVENTIONS.md.template

package/templates/adapters/claude/.claude/settings.json.template

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "doctrina prime --hook claude 2>/dev/null || true" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "doctrina prime --pulse 2>/dev/null || true" }
+        ]
+      }
+    ]
+  }
+}

package/templates/adapters/cursor/.cursor/hooks.json.template

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      { "command": "doctrina prime --hook cursor" }
+    ]
+  }
+}

package/templates/adapters/cursor/.cursor/rules/00-doctrina.mdc.template

@@ -1,16 +1,21 @@
 ---
-description: Doctrina canonical rules — always read AGENTS.md first
+description: Doctrina — the change cycle, every turn; the full rules are in AGENTS.md
 alwaysApply: true
 ---
 
-# Doctrina pointer rule
+# Doctrina
 
-This project uses the open AGENTS.md standard as the single source of
-truth for agent-readable rules. Before answering or editing, read the
-canonical file at `{{AGENTS_MD_PATH}}`.
+The canonical rules and command surface are in `{{AGENTS_MD_PATH}}` — read it
+first. The change cycle applies to every request, whether or not it names
+Doctrina:
 
-The Doctrina framework artifacts (specs, decisions, changes) live under
-`.doctrina/`. Read order is documented in `AGENTS.md`.
+- A request that changes behaviour is a change, opened BEFORE code is
+  edited: `doctrina work "<request>"`. One change per activity asked for.
+- The first sentence to the human names the change id.
+- Read with `doctrina context <cap> --for "<task>" --concat`; `doctrina
+  prime` is the project's state, not the spec.
+- Project skills are in `.agents/skills/` (generated from `.doctrina/skills/`).
+- Finish with `doctrina close <id>` and repeat the archive path it prints.
 
-Do not duplicate rules here. If a rule belongs in AGENTS.md, put it
-there and re-read this project.
+Do not add rules here: this file carries only the cycle, because Cursor's
+per-prompt hook cannot; everything else belongs in AGENTS.md.

package/templates/adapters/cursor/.cursor/{commands/doctrina-context.md.template → skills/doctrina-context/SKILL.md.template}

@@ -1,3 +1,9 @@
+---
+name: doctrina-context
+description: Load the Doctrina read pack for a task, in read order
+disable-model-invocation: true
+---
+
 # /doctrina-context — read pack for {{PROJECT_NAME}}
 
 Assemble the context before doing any work.

package/templates/adapters/cursor/.cursor/{commands/doctrina-next.md.template → skills/doctrina-next/SKILL.md.template}

@@ -1,3 +1,9 @@
+---
+name: doctrina-next
+description: Show and act on the next recommended Doctrina workflow step
+disable-model-invocation: true
+---
+
 # /doctrina-next — next step for {{PROJECT_NAME}}
 
 Decide the next step from the framework's own signals.

package/templates/adapters/cursor/.cursor/{commands/doctrina-status.md.template → skills/doctrina-status/SKILL.md.template}

@@ -1,3 +1,9 @@
+---
+name: doctrina-status
+description: One-glance Doctrina project health and gate status
+disable-model-invocation: true
+---
+
 # /doctrina-status — health of {{PROJECT_NAME}}
 
 Report the project's health and gate status.

package/templates/adapters/cursor/.cursor/{commands/doctrina-why.md.template → skills/doctrina-why/SKILL.md.template}

@@ -1,3 +1,9 @@
+---
+name: doctrina-why
+description: Explain a capability's provenance (intent → proof → ADRs → history)
+disable-model-invocation: true
+---
+
 # /doctrina-why — provenance for {{PROJECT_NAME}}
 
 Explain why a capability exists and is shaped as it is.

package/templates/adapters/cursor/.cursor/{commands/doctrina-work.md.template → skills/doctrina-work/SKILL.md.template}

@@ -1,3 +1,9 @@
+---
+name: doctrina-work
+description: Turn a request into a Doctrina change and drive it through the gates
+disable-model-invocation: true
+---
+
 # /doctrina-work — drive a change for {{PROJECT_NAME}}
 
 Turn the request into a Doctrina change and drive it through the gates.

package/templates/delivery.md.template

@@ -0,0 +1,39 @@
+# Delivery {{DELIVERY_ID}} — {{DELIVERY_TITLE}}
+
+- **Status:** open
+- **Date:** {{DATE}}
+- **Ref:** {{DELIVERY_REF}}
+- **Projects:** {{DELIVERY_PROJECTS}}
+
+<!-- One delivery = one item of work that crosses repositories (a story, a
+     screen, a fix). Each project it touches gets ONE change, opened inside
+     that repository with `doctrina work "<title>" --delivery {{DELIVERY_ID}}`.
+     This file holds what no single repository owns: the story, the sources,
+     the plan across projects, the release and what was watched after it. -->
+
+## Story
+
+<!-- The tracker item, verbatim: title, description, acceptance criteria.
+     Read it through the tracker tool; never paraphrase a criterion. -->
+
+## Sources
+
+<!-- One link per line: documentation pages, design frames, dashboards,
+     queries — each with what it was read for. -->
+
+## Plan
+
+<!-- Per project, in dependency order: what changes and why there. -->
+
+## Release
+
+<!-- How each project reaches its environment, and the proof it did. Every
+     box is a claim `doctrina delivery check` holds you to. -->
+
+- [ ] Every project's change is merged and its pipeline ran green
+- [ ] The delivery was validated in the target environment, evidence linked
+
+## Observability
+
+<!-- What was watched after the release — monitor, dashboard or query, the
+     window, and what it showed. At least one line before the close. -->

package/templates/playbooks/absorb.md.template

@@ -0,0 +1,63 @@
+[[b]]Absorb playbook[[/b]][[g]] — an existing codebase becomes specs; agent-executed (ADR 0005).[[/g]]
+
+The intake holds the code INVENTORY, not a description. Describe what the
+system does TODAY, as the code shows it — never what someone may want it
+to do. Execute in order, in a single linear pass:
+
+1. Read [[c]].doctrina/intake.md[[/c]] (the inventory), then what it points at:
+   the README, the documentation and decisions it lists, the agent
+   instructions already written, and per UNIT its manifest, its entry
+   points, one or two files per candidate area and its tests. Breadth
+   first — do not read the whole repository. Candidate areas are a hint
+   from the folder layout, not capabilities.
+
+2. Fill [[c]].doctrina/product.md[[/c]] with what is observable: what the system
+   is, who uses it, what it does. Every business fact the code cannot tell
+   you (why a rule exists, who the users are, what is out of scope) goes
+   under [[c]]## Open questions[[/c]] for the human — never guess intent. So does
+   every line of the inventory's "What this inventory could not see".
+
+3. One capability per area of behaviour you READ. In a repository of
+   several units, a capability stays inside one unit unless the code
+   itself shares it (a library both import). For each:
+       [[c]]doctrina spec new <capability>[[/c]]
+   then write EARS requirements for the behaviour the code shows, with
+   [[c]]**Implementation:** implemented[[/c]] and [[c]]**Source:**[[/c]] naming the real
+   folders it owns (ADR 0027; `validate` refuses a Source that matches no
+   file). Keep it a BASELINE: a few requirements per area now; the specs
+   grow with every change that touches them.
+
+4. No requirement without the code that does it:
+   - Write behaviour only from code or a test you read — never from a
+     folder name, a comment, a TODO, commented-out code, a disabled flag
+     or a route that answers "not implemented".
+   - Numbers, limits, roles, statuses and messages exactly as the code
+     writes them. A value you did not see is a question, not a default.
+   - Where the docs and the code disagree, the code is what the system
+     does today; the disagreement is an open question.
+   - Existing decisions are recorded, not re-decided:
+     [[c]]doctrina decision new "<title>"[[/c]] citing the document they came from.
+
+5. Acceptance criteria cite the tests that already exist. Mark one
+   [[c]][verified][[/c]] only when a cited test really proves it; everything else
+   stays [[c]][unverified][[/c]] — an honest gap is the point of the absorb.
+
+6. Declare the build gate — [[c]]doctrina verify --init[[/c]] writes the commands
+   the inventory found; confirm each runs what its name says — and own the
+   seams the inventory lists under Interfaces (ports, env names, OpenAPI,
+   protobuf, GraphQL, events) as a contract:
+       [[c]]doctrina contract new <name>[[/c]]
+
+7. Check the facts before the gates. Hand each spec, with its Source, to a
+   reader that did not write it (a reviewer subagent, or a fresh session):
+   for every requirement, find the code that does it; strike what cannot
+   be found, and list what the code does that no requirement says.
+
+8. Gates — fix everything they report:
+       [[c]]doctrina clarify --all[[/c]]
+       [[c]]doctrina validate --fix[[/c]]   (a spec written by hand leaves index.json behind; --fix heals that and reports the rest)
+       [[c]]doctrina coverage[[/c]]
+
+9. Show the human the Open questions, then close the absorb:
+       [[c]]doctrina intake --converted[[/c]]
+{{WORKSPACE_STEP}}