doctrina-cli 0.1.0 → 0.2.0

package/src/lib/diff.js

@@ -0,0 +1,103 @@
+// Minimal line diff (LCS-based) for `change diff`. Specs are capped at a
+// few hundred lines, so the O(n*m) table is fine and keeps us at zero deps.
+
+export function diffLines(aText, bText) {
+  const a = splitLines(aText);
+  const b = splitLines(bText);
+  const n = a.length;
+  const m = b.length;
+
+  // LCS length table.
+  const table = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      table[i][j] = a[i] === b[j]
+        ? table[i + 1][j + 1] + 1
+        : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+
+  // Backtrack into a flat op list.
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "same", text: a[i] });
+      i += 1;
+      j += 1;
+    } else if (table[i + 1][j] >= table[i][j + 1]) {
+      ops.push({ type: "del", text: a[i] });
+      i += 1;
+    } else {
+      ops.push({ type: "add", text: b[j] });
+      j += 1;
+    }
+  }
+  while (i < n) ops.push({ type: "del", text: a[i++] });
+  while (j < m) ops.push({ type: "add", text: b[j++] });
+  return ops;
+}
+
+// Render ops as unified-style hunks with `context` lines around changes.
+export function formatUnified(ops, { context = 3, aLabel = "a", bLabel = "b" } = {}) {
+  const out = [`--- ${aLabel}`, `+++ ${bLabel}`];
+  const hunks = collectHunks(ops, context);
+  let aLine = 1;
+  let bLine = 1;
+  let cursor = 0;
+  for (const [start, end] of hunks) {
+    // Advance line counters across the skipped region.
+    for (; cursor < start; cursor++) {
+      if (ops[cursor].type !== "add") aLine += 1;
+      if (ops[cursor].type !== "del") bLine += 1;
+    }
+    let aLen = 0;
+    let bLen = 0;
+    for (let k = start; k < end; k++) {
+      if (ops[k].type !== "add") aLen += 1;
+      if (ops[k].type !== "del") bLen += 1;
+    }
+    out.push(`@@ -${aLine},${aLen} +${bLine},${bLen} @@`);
+    for (; cursor < end; cursor++) {
+      const op = ops[cursor];
+      const prefix = op.type === "add" ? "+" : op.type === "del" ? "-" : " ";
+      out.push(prefix + op.text);
+      if (op.type !== "add") aLine += 1;
+      if (op.type !== "del") bLine += 1;
+    }
+  }
+  if (hunks.length === 0) out.push("(no differences)");
+  return out.join("\n");
+}
+
+function collectHunks(ops, context) {
+  // Indices of changed ops.
+  const changed = [];
+  for (let k = 0; k < ops.length; k++) {
+    if (ops[k].type !== "same") changed.push(k);
+  }
+  if (changed.length === 0) return [];
+  const hunks = [];
+  let start = Math.max(0, changed[0] - context);
+  let end = Math.min(ops.length, changed[0] + context + 1);
+  for (let c = 1; c < changed.length; c++) {
+    const k = changed[c];
+    if (k - context <= end) {
+      end = Math.min(ops.length, k + context + 1);
+    } else {
+      hunks.push([start, end]);
+      start = Math.max(0, k - context);
+      end = Math.min(ops.length, k + context + 1);
+    }
+  }
+  hunks.push([start, end]);
+  return hunks;
+}
+
+function splitLines(text) {
+  const lines = text.split("\n");
+  // Drop a single trailing empty line produced by a final newline.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}

package/src/lib/ears.js

@@ -0,0 +1,108 @@
+// Structural EARS checks for capability specs. The clarify command catches
+// word-level smells; this catches grammar-shape problems per EARS section.
+// All findings are warnings: specs evolve, validation should not block.
+
+const SECTION_RULES = [
+  {
+    match: /^###\s+Ubiquitous/i,
+    name: "Ubiquitous",
+    check(req) {
+      if (/^when\b/i.test(req)) return "event-shaped requirement (starts with \"When\") — move to ### Event-driven";
+      if (/^while\b/i.test(req)) return "state-shaped requirement (starts with \"While\") — move to ### State-driven";
+      if (/^where\b/i.test(req)) return "optional-shaped requirement (starts with \"Where\") — move to ### Optional";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" — ubiquitous form is \"The system shall ...\"";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Event-driven/i,
+    name: "Event-driven",
+    check(req) {
+      if (!/^when\b/i.test(req)) return "expected \"When <trigger>, the system shall ...\"";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" after the When-trigger";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+State-driven/i,
+    name: "State-driven",
+    check(req) {
+      if (!/^while\b/i.test(req)) return "expected \"While <state>, the system shall ...\"";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" after the While-state";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Unwanted/i,
+    name: "Unwanted-behavior",
+    check(req) {
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" — unwanted-behavior form is \"The system shall not ...\"";
+      if (!/\b(not|no|never)\b/i.test(req)) return "missing a negation — unwanted-behavior requirements forbid something";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Optional/i,
+    name: "Optional",
+    check(req) {
+      if (!/^where\b/i.test(req)) return "expected \"Where <feature is present>, the system may ...\"";
+      if (!/\bmay\b/i.test(req)) return "missing \"may\" — optional requirements use may, not shall";
+      return null;
+    },
+  },
+];
+
+// Check one spec text. Returns [{ line, message }]. Only applies to specs
+// that declare a "## Requirements (EARS)" section; bug-shape specs and
+// free-form specs are skipped entirely.
+export function checkEars(text) {
+  const lines = text.split("\n");
+  const findings = [];
+
+  let inRequirements = false;
+  let rule = null;
+  let req = null; // { line, text }
+
+  const flush = () => {
+    if (req && rule) {
+      const message = rule.check(req.text.trim());
+      if (message) findings.push({ line: req.line, message: `${rule.name}: ${message}` });
+    }
+    req = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (/^##\s+Requirements \(EARS\)/i.test(line)) {
+      inRequirements = true;
+      continue;
+    }
+    if (!inRequirements) continue;
+    if (/^##\s+/.test(line)) {
+      // Left the Requirements section.
+      flush();
+      break;
+    }
+    if (/^###\s+/.test(line)) {
+      flush();
+      rule = SECTION_RULES.find((r) => r.match.test(line)) ?? null;
+      continue;
+    }
+    if (/^-\s+/.test(line)) {
+      flush();
+      req = { line: i + 1, text: line.replace(/^-\s+/, "") };
+      continue;
+    }
+    // Continuation of the current bullet (indented text or nested bullet).
+    if (req && /^\s+\S/.test(line)) {
+      req.text += " " + line.trim();
+    }
+  }
+  flush();
+  return findings;
+}
+
+export function isEarsSpec(text) {
+  return /^##\s+Requirements \(EARS\)/im.test(text);
+}

package/src/lib/fs-ops.js

@@ -73,3 +73,15 @@ export function lineCount(p) {
   if (text.length === 0) return 0;
   return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 }
+
+// Normalise a path to forward slashes for display and comparison. CLI
+// output is part of the contract (tests, docs, agents parse it), so it
+// must not change shape between platforms.
+export function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+// path.relative with stable, platform-independent forward slashes.
+export function relPath(from, to) {
+  return toPosix(path.relative(from, to));
+}

package/src/lib/scan.js

@@ -0,0 +1,185 @@
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { parseFrontmatter } from "../commands/skill.js";
+import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
+
+// Parse a spec-style header line: **Name:** value
+export function specHeader(text, name) {
+  const m = text.match(new RegExp(`^\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+// Parse an ADR/proposal-style header line: - **Name:** value
+export function listHeader(text, name) {
+  const m = text.match(new RegExp(`^-\\s+\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+function dirEntries(dir) {
+  if (!isDir(dir)) return [];
+  return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
+}
+
+// Regenerate the index object from the artifacts on disk. The files are
+// the source of truth; fields with no on-disk source (project name,
+// framework_version, product metadata) are carried over from `current`.
+export function deriveIndex(projectRoot, current) {
+  const dot = path.join(projectRoot, ".doctrina");
+  const date = today();
+  const cur = current?.artifacts ?? {};
+
+  const out = {
+    $schema_version: current?.$schema_version ?? "0.1.0",
+    project: current?.project ?? path.basename(projectRoot),
+    framework_version: current?.framework_version ?? "0.0.0",
+    last_updated: current?.last_updated ?? date,
+    artifacts: {
+      product: cur.product ?? {
+        path: ".doctrina/product.md",
+        status: "active",
+        version: "0.1.0",
+        last_updated: date,
+      },
+      specs: [],
+      decisions: [],
+      changes: [],
+      changes_archive: [],
+      skills: [],
+    },
+  };
+
+  // Specs — headers inside each spec.md win over the previous index.
+  const specsDir = path.join(dot, "specs");
+  for (const cap of dirEntries(specsDir)) {
+    const p = path.join(specsDir, cap, "spec.md");
+    if (!isFile(p)) continue;
+    const text = read(p);
+    const prev = (cur.specs ?? []).find((s) => s.id === cap);
+    out.artifacts.specs.push({
+      id: cap,
+      path: `.doctrina/specs/${cap}/spec.md`,
+      status: specHeader(text, "Status") ?? prev?.status ?? "active",
+      version: specHeader(text, "Version") ?? prev?.version ?? "0.1.0",
+      last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
+    });
+  }
+
+  // Decisions — NNNN-slug.md files; Status/Date headers win.
+  const adrDir = path.join(dot, "decisions");
+  for (const f of walk(adrDir)) {
+    const base = path.basename(f);
+    const m = base.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f);
+    const prev = (cur.decisions ?? []).find((d) => d.id === m[1]);
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    const entry = {
+      id: m[1],
+      path: `.doctrina/decisions/${base}`,
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? base,
+      status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
+      date: listHeader(text, "Date") ?? prev?.date ?? date,
+    };
+    const supersedes = listHeader(text, "Supersedes");
+    if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
+    const supersededBy = listHeader(text, "Superseded by");
+    if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+    out.artifacts.decisions.push(entry);
+  }
+
+  // Open changes — every directory except archive/.
+  const changesDir = path.join(dot, "changes");
+  for (const id of dirEntries(changesDir)) {
+    if (id === "archive") continue;
+    if (!isDir(path.join(changesDir, id))) continue;
+    const prev = (cur.changes ?? []).find((c) => c.id === id);
+    const proposalPath = path.join(changesDir, id, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    out.artifacts.changes.push({
+      id,
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? id,
+      path: `.doctrina/changes/${id}`,
+      status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
+      opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
+    });
+  }
+
+  // Archived changes — folder name carries the applied date and id.
+  const archiveDir = path.join(changesDir, "archive");
+  for (const name of dirEntries(archiveDir)) {
+    const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+    if (!m || !isDir(path.join(archiveDir, name))) continue;
+    const prev = (cur.changes_archive ?? []).find((c) => c.path?.endsWith(name));
+    const proposalPath = path.join(archiveDir, name, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    const specsAffected = [];
+    for (const deltaPath of walk(path.join(archiveDir, name, "specs"))) {
+      if (!deltaPath.endsWith("delta.md")) continue;
+      const text = read(deltaPath);
+      const capability = parseCapabilityFromDelta(text, deltaPath);
+      if (capability) {
+        specsAffected.push({ capability, operation: parseOperation(text) ?? "MODIFIED" });
+      }
+    }
+    out.artifacts.changes_archive.push({
+      id: m[2],
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? m[2],
+      path: `.doctrina/changes/archive/${name}`,
+      status: "applied",
+      applied: m[1],
+      specs_affected: specsAffected,
+    });
+  }
+
+  // Skills — frontmatter description wins.
+  const skillsDir = path.join(dot, "skills");
+  for (const f of walk(skillsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const prev = (cur.skills ?? []).find((s) => s.id === id);
+    out.artifacts.skills.push({
+      id,
+      path: `.doctrina/skills/${id}.md`,
+      description: parseFrontmatter(read(f), "description")
+        ?? prev?.description ?? "<edit me — one-sentence summary>",
+      last_updated: prev?.last_updated ?? date,
+    });
+  }
+
+  return out;
+}
+
+// Deterministic stringify (sorted keys) so two indexes compare by content,
+// not by key insertion order.
+export function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+
+// Content equality ignoring the root last_updated timestamp. Absent
+// artifact categories compare equal to empty ones so pre-skills indexes
+// are not flagged for a purely structural difference.
+export function indexesMatch(a, b) {
+  if (!a || !b) return false;
+  const normalize = (x) => {
+    const clone = { ...x };
+    delete clone.last_updated;
+    const arts = { ...(clone.artifacts ?? {}) };
+    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills"]) {
+      arts[cat] = arts[cat] ?? [];
+    }
+    clone.artifacts = arts;
+    return clone;
+  };
+  return stableStringify(normalize(a)) === stableStringify(normalize(b));
+}

package/src/lib/templates.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { read, walk, write } from "./fs-ops.js";
+import { read, toPosix, walk, write } from "./fs-ops.js";
 
 // Resolve the path to the .doctrina/templates/ directory shipped with this
 // package. The package layout is:
@@ -59,7 +59,7 @@ export function loadTemplateTree(templatesDir, subdir) {
   const root = path.join(templatesDir, subdir);
   const files = walk(root);
   return files.map((templatePath) => {
-    const relativePath = path.relative(root, templatePath);
+    const relativePath = toPosix(path.relative(root, templatePath));
     const body = templatePath.endsWith(".gitkeep") ? "" : read(templatePath);
     return { templatePath, relativePath, body };
   });

package/templates/AGENTS.md.template

@@ -0,0 +1,83 @@
+# AGENTS.md — {{PROJECT_NAME}}
+
+Operational source of truth for AI coding agents working in this
+repository. Follows the open AGENTS.md standard.
+
+## What this repo is
+
+{{PROJECT_DESCRIPTION}}
+
+This repository uses the Doctrina framework for spec-driven, AGENTS.md
+native multi-agent development. The full framework artifacts live under
+`.doctrina/`.
+
+## Working from intent
+
+- **Bootstrap.** If `.doctrina/intake.md` exists with `Status: pending`,
+  the specs have not been written yet. Before anything else, run
+  `doctrina intake` and execute the printed bootstrap playbook in one
+  linear pass: fill `product.md`, derive capabilities, author one EARS
+  spec each, run the quality gates (`doctrina clarify --all`,
+  `doctrina validate`), then flip the intake to `Status: converted`. Ask
+  the user only when the intake is genuinely ambiguous. After conversion
+  the specs are the only source of truth — never edit `intake.md` to
+  change requirements.
+- **Day-to-day.** Turn a brief request into a scaffolded change with
+  `doctrina work "<prompt>"`, then follow the printed work playbook
+  (spec delta → tasks → implement → analyze → apply → archive → validate).
+
+## Stack and tooling
+
+<!-- Replace with the project's actual stack. Keep this section short. -->
+- Runtime:
+- Package manager:
+- Test runner:
+- Linter / formatter:
+
+## Commands
+
+<!-- Use exact, copy-pasteable commands. Avoid prose. -->
+```
+# install
+# build
+# test
+# lint
+```
+
+## Repository structure
+
+<!-- Outline the top-level directories an agent needs to know about. -->
+
+## Conventions and boundaries
+
+- Specs in `.doctrina/specs/<capability>/spec.md` are the current truth.
+- ADRs in `.doctrina/decisions/` are immutable; supersede instead of edit.
+- Active change proposals live in `.doctrina/changes/<id>/`.
+- Archived changes in `.doctrina/changes/archive/` are out of the default
+  read path; consult only when explicitly debugging history.
+
+## How to read context efficiently
+
+1. Read this `AGENTS.md`.
+2. Read `.doctrina/product.md`.
+3. Read the relevant `.doctrina/specs/<capability>/spec.md`.
+4. Read any open `.doctrina/changes/<id>/`.
+5. Read `.doctrina/decisions/` filtered by `Status: accepted`.
+6. If the task matches a skill in `.doctrina/skills/`, load the
+   relevant skill on demand (read its `description:` / `when:`
+   frontmatter; load the full body only when the trigger fires).
+
+Keep this file under 150 lines. Density beats prose. Use exact commands.
+
+## Definition of done
+
+A change is done when:
+- All tasks in the change's `tasks.md` are checked.
+- Deltas have been merged into affected spec files.
+- The change folder has been moved to `.doctrina/changes/archive/`.
+- Any architectural decisions are recorded as ADRs with `Status: accepted`.
+- `.doctrina/index.json` has been updated.
+
+## What never goes in this file
+
+Tutorials, project history, secrets, generated content, session notes.

package/templates/README.md

@@ -0,0 +1,85 @@
+# Doctrina templates
+
+Canonical scaffolds consumed by the `doctrina` CLI.
+
+## Placeholder syntax
+
+Templates use `{{TOKEN}}` — double curly braces around an uppercase,
+digit, and underscore token. Substitution is a single global string
+replace. No conditionals, loops, or includes.
+
+## Canonical tokens
+
+| Token | Meaning | Default if not supplied |
+|-------|---------|-------------------------|
+| `{{PROJECT_NAME}}` | Human-readable project name | basename of target directory |
+| `{{PROJECT_DESCRIPTION}}` | One-sentence description | empty string |
+| `{{DATE}}` | YYYY-MM-DD of init or artifact creation | system date |
+| `{{CAPABILITY}}` | Slug for a new capability spec | required, no default |
+| `{{CHANGE_ID}}` | Change folder identifier | required, no default |
+| `{{CHANGE_TITLE}}` | Short change title | required, no default |
+| `{{DECISION_NUMBER}}` | Zero-padded ADR number (e.g. `0007`) | next available |
+| `{{DECISION_TITLE}}` | ADR title | required, no default |
+| `{{DECISION_SLUG}}` | kebab-case slug derived from `{{DECISION_TITLE}}` | derived |
+| `{{AGENTS_MD_PATH}}` | Path to root `AGENTS.md` from the adapter location | per adapter |
+
+CLI authors and template authors share this vocabulary. Adding a token
+requires extending the templates spec at `.doctrina/specs/templates/spec.md`.
+
+## Inventory (v0)
+
+```
+README.md                                  this file
+AGENTS.md.template                         root rules for the target repo
+doctrina/                                  the .doctrina/ skeleton
+  product.md.template
+  index.json.template
+  specs/.gitkeep
+  changes/.gitkeep
+  changes/archive/.gitkeep
+  decisions/.gitkeep
+  skills/.gitkeep
+  templates/.gitkeep
+spec.md.template                           one capability spec (EARS)
+spec-bug.md.template                       bug-shape capability spec
+skill.md.template                          one on-demand skill
+change/
+  proposal.md.template
+  tasks.md.template
+  design.md.template
+  spec-delta.md.template
+decision.md.template                       one ADR (Nygard/MADR)
+hooks/
+  pre-commit.sample                        installed by `doctrina hooks install`
+  watch.sample                             on-save validation wrapper (manual wiring)
+adapters/
+  claude/CLAUDE.md.template
+  codex/README.md
+  cursor/.cursor/rules/00-doctrina.mdc.template
+  copilot/.github/copilot-instructions.md.template
+  gemini/GEMINI.md.template
+  aider/CONVENTIONS.md.template
+  windsurf/.windsurfrules.template
+  continue/.continue/rules/00-doctrina.md.template
+  amp/README.md
+  devin/README.md
+  factory/README.md
+  jules/README.md
+```
+
+## Adapter strategy
+
+| Agent | What gets installed | Why |
+|-------|--------------------|-----|
+| `claude` | `CLAUDE.md` at project root with `@AGENTS.md` import | Claude Code reads `CLAUDE.md` natively and supports `@file` includes. |
+| `codex` | nothing | OpenAI Codex CLI reads `AGENTS.md` natively; an adapter file would only add drift surface. |
+| `cursor` | `.cursor/rules/00-doctrina.mdc` with `alwaysApply: true` | Cursor's `.mdc` rules live in a dedicated directory; the file is a thin pointer. |
+| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot's repository-level custom instructions path. |
+| `gemini` | `GEMINI.md` at project root | Gemini CLI's native context file. |
+| `aider` | `CONVENTIONS.md` at project root | Aider reads CONVENTIONS.md as cached read-only context. |
+| `windsurf` | `.windsurfrules` at project root | Windsurf's rules file convention. |
+| `continue` | `.continue/rules/00-doctrina.md` | Continue.dev's rules directory. |
+| `amp` / `devin` / `factory` / `jules` | nothing | AGENTS.md-native (same posture as `codex`); the directory marks the support contract and gives future per-agent affordances a home. |
+
+Adapter files stay under 30 lines so they cannot meaningfully drift from
+`AGENTS.md` and so they do not pay a noticeable per-turn token tax.

package/templates/adapters/aider/CONVENTIONS.md.template

@@ -0,0 +1,11 @@
+# CONVENTIONS.md — {{PROJECT_NAME}}
+
+Aider reads this file as read-only context (CONVENTIONS.md is
+loaded automatically and cached). This project routes all
+operational rules through the open AGENTS.md standard.
+
+See `{{AGENTS_MD_PATH}}` for the canonical operational source of
+truth. The Doctrina framework artifacts (specs, decisions,
+changes) live under `.doctrina/`.
+
+Read order is documented in AGENTS.md.

package/templates/adapters/amp/README.md

@@ -0,0 +1,13 @@
+# Sourcegraph Amp adapter
+
+Sourcegraph Amp reads `AGENTS.md` natively as part of its
+support for the open AGENTS.md standard (per the Linux
+Foundation's December 2025 announcement). No adapter file is
+installed for Amp.
+
+This directory exists so the templates inventory is symmetric
+across supported agents, and so future Amp-specific affordances
+have an obvious home.
+
+If you are reading this because `doctrina init --agent amp` did
+not create any files: that is the intended behaviour.

package/templates/adapters/claude/CLAUDE.md.template

@@ -0,0 +1,11 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+This project uses the open AGENTS.md standard as the single source of
+truth for agent-readable rules. The canonical file is at the repository
+root; this `CLAUDE.md` is a thin pointer so Claude Code's auto-loading
+picks it up.
+
+@{{AGENTS_MD_PATH}}
+
+The Doctrina framework artifacts (specs, decisions, changes) live under
+`.doctrina/`. Read order is documented in `AGENTS.md`.

package/templates/adapters/codex/README.md

@@ -0,0 +1,12 @@
+# Codex CLI adapter
+
+OpenAI Codex CLI reads `AGENTS.md` natively (Codex is one of the
+reference implementations of the open AGENTS.md standard). No adapter
+file is installed for Codex.
+
+This directory exists so the templates inventory is symmetric across
+supported agents, and so future Codex-specific affordances (for example
+custom subagent definitions) have an obvious home.
+
+If you are reading this because `doctrina init --agent codex` did not
+create any files: that is the intended behaviour.

package/templates/adapters/continue/.continue/rules/00-doctrina.md.template

@@ -0,0 +1,11 @@
+# Doctrina pointer — {{PROJECT_NAME}}
+
+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 Doctrina framework artifacts (specs, decisions, changes) live
+under `.doctrina/`. Read order is documented in AGENTS.md.
+
+Do not duplicate rules in this file. If a rule belongs in AGENTS.md,
+put it there.

package/templates/adapters/copilot/.github/copilot-instructions.md.template

@@ -0,0 +1,11 @@
+# Copilot instructions — {{PROJECT_NAME}}
+
+This repository uses the open AGENTS.md standard as the single source
+of truth for agent-readable rules. Before suggesting code or
+completions, consult the canonical file at `{{AGENTS_MD_PATH}}`.
+
+The Doctrina framework artifacts (specs, decisions, changes) live
+under `.doctrina/`. Read order is documented in AGENTS.md.
+
+Do not duplicate rules here. If a rule belongs in AGENTS.md, put it
+there.