doctrina-cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -18,10 +18,12 @@
     "doctrina": "./src/index.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepack": "node scripts/copy-templates.js"
   },
   "files": [
     "src",
+    "templates",
     "README.md"
   ],
   "engines": {

package/templates/AGENTS.md.template

@@ -0,0 +1,68 @@
+# 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/`.
+
+## 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,64 @@
+# 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
+  templates/.gitkeep
+spec.md.template                           one capability spec
+change/
+  proposal.md.template
+  tasks.md.template
+  design.md.template
+  spec-delta.md.template
+decision.md.template                       one ADR (Nygard/MADR)
+adapters/
+  claude/CLAUDE.md.template
+  codex/README.md
+  cursor/rules/00-doctrina.mdc.template
+```
+
+## 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. |
+
+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.

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

@@ -0,0 +1,16 @@
+---
+description: Doctrina canonical rules — always read AGENTS.md first
+alwaysApply: true
+---
+
+# Doctrina pointer rule
+
+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 here. If a rule belongs in AGENTS.md, put it
+there and re-read this project.

package/templates/adapters/devin/README.md

@@ -0,0 +1,14 @@
+# Cognition Devin adapter
+
+Cognition Devin 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 Devin.
+
+This directory exists so the templates inventory is symmetric
+across supported agents, and so future Devin-specific
+affordances (custom session configs, for example) have an
+obvious home.
+
+If you are reading this because `doctrina init --agent devin`
+did not create any files: that is the intended behaviour.

package/templates/adapters/factory/README.md

@@ -0,0 +1,13 @@
+# Factory AI adapter
+
+Factory AI 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
+Factory.
+
+This directory exists so the templates inventory is symmetric
+across supported agents, and so future Factory-specific
+affordances have an obvious home.
+
+If you are reading this because `doctrina init --agent factory`
+did not create any files: that is the intended behaviour.

package/templates/adapters/gemini/GEMINI.md.template

@@ -0,0 +1,11 @@
+# GEMINI.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 `GEMINI.md` is a thin pointer so Gemini CLI's
+auto-loading picks it up.
+
+See `{{AGENTS_MD_PATH}}` for the operational rules.
+
+The Doctrina framework artifacts (specs, decisions, changes) live
+under `.doctrina/`. Read order is documented in AGENTS.md.

package/templates/adapters/jules/README.md

@@ -0,0 +1,13 @@
+# Google Jules adapter
+
+Google Jules (autonomous coding agent) 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 Jules.
+
+This directory exists so the templates inventory is symmetric
+across supported agents, and so future Jules-specific
+affordances have an obvious home.
+
+If you are reading this because `doctrina init --agent jules`
+did not create any files: that is the intended behaviour.

package/templates/adapters/windsurf/.windsurfrules.template

@@ -0,0 +1,11 @@
+# Windsurf rules — {{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/change/design.md.template

@@ -0,0 +1,24 @@
+# Design — Change {{CHANGE_ID}}
+
+<!--
+Optional, but recommended for any change with non-trivial design choices.
+If this change is mechanical (a renamed field, a typo fix), delete this
+file rather than leaving it empty.
+-->
+
+## Approach
+
+<!-- The chosen approach in one or two paragraphs. -->
+
+## Alternatives considered
+
+<!-- The shortlist of approaches you rejected and why. -->
+
+## Trade-offs and risks
+
+<!-- What this design costs and where it can break. -->
+
+## Decisions to record as ADRs
+
+<!-- List any architectural decisions surfaced by this change that should
+become their own ADR. Empty if none. -->

package/templates/change/proposal.md.template

@@ -0,0 +1,26 @@
+# Change {{CHANGE_ID}} — {{CHANGE_TITLE}}
+
+- **Status:** proposed
+- **Date:** {{DATE}}
+- **Owner:**
+- **Affects specs:**
+
+## Why
+
+<!-- The user-visible or technical reason this change exists. -->
+
+## What
+
+<!-- The shape of the change: artifacts created or modified, specs affected. -->
+
+## Scope boundaries
+
+<!-- Anything adjacent that this change deliberately does NOT touch. -->
+
+## Verification
+
+<!-- How you will know the change is correctly applied. -->
+
+## Open questions
+
+<!-- List unresolved decisions. Empty if none. -->

package/templates/change/spec-delta.md.template

@@ -0,0 +1,20 @@
+# Spec Delta — capability: {{CAPABILITY}}
+
+**Operation:** ADDED | MODIFIED | REMOVED
+**Target spec on apply:** `.doctrina/specs/{{CAPABILITY}}/spec.md`
+
+<!--
+For ADDED: include the full new spec body below. On apply, the body is
+written verbatim to the target path.
+
+For MODIFIED: include only the sections that change, with clear
+before/after markers. On apply, the maintainer merges the delta into the
+existing spec by hand or with the CLI.
+
+For REMOVED: the body may be empty; on apply, the target spec file is
+deleted and the capability is recorded in the change archive only.
+-->
+
+---
+
+<!-- delta body below -->

package/templates/change/tasks.md.template

@@ -0,0 +1,17 @@
+# Tasks — Change {{CHANGE_ID}}
+
+<!--
+Each task is a single checkable item. Keep tasks small (under a few hours
+of work). The change is done when every box is checked, including the
+three closing steps at the bottom.
+-->
+
+- [ ]
+- [ ]
+- [ ]
+
+## Closing steps
+
+- [ ] Apply the change: merge each delta into the corresponding spec.
+- [ ] Archive the change folder to `.doctrina/changes/archive/{{DATE}}-{{CHANGE_ID}}/`.
+- [ ] Update `.doctrina/index.json` with new or modified artifacts.

package/templates/decision.md.template

@@ -0,0 +1,56 @@
+# ADR {{DECISION_NUMBER}} — {{DECISION_TITLE}}
+
+- **Status:** proposed
+- **Date:** {{DATE}}
+- **Deciders:**
+- **Supersedes:** —
+- **Superseded by:** —
+
+## Context
+
+<!--
+The forces at play: business goals, technical constraints, prior
+decisions, options ruled out before deliberation. Reader should
+understand WHY this decision is being made now, not just what was
+chosen.
+-->
+
+## Decision
+
+<!--
+What was decided. Active voice. State the choice plainly. If the
+decision has scope limits, state them.
+-->
+
+## Alternatives considered
+
+<!--
+The shortlist of approaches that were on the table. For each, a sentence
+on why it was not chosen. Even rejected alternatives carry value: they
+prevent the next reader from re-running the same debate.
+-->
+
+1.
+2.
+
+## Consequences
+
+**Positive**
+
+-
+
+**Negative**
+
+-
+
+**Neutral**
+
+-
+
+<!--
+Once this ADR is accepted, do not edit it. To change the decision,
+create a new ADR that supersedes this one and update the "Superseded by"
+header above to point at the new ADR. Status transitions:
+proposed -> accepted | rejected
+accepted -> deprecated | superseded by NNNN
+-->

package/templates/doctrina/index.json.template

@@ -0,0 +1,18 @@
+{
+  "$schema_version": "0.1.0",
+  "project": "{{PROJECT_NAME}}",
+  "framework_version": "0.0.0",
+  "last_updated": "{{DATE}}",
+  "artifacts": {
+    "product": {
+      "path": ".doctrina/product.md",
+      "status": "active",
+      "version": "0.1.0",
+      "last_updated": "{{DATE}}"
+    },
+    "specs": [],
+    "decisions": [],
+    "changes": [],
+    "changes_archive": []
+  }
+}

package/templates/doctrina/product.md.template

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}} — Product
+
+## Vision
+
+<!-- One short paragraph: what this project exists to do, for whom, why now. -->
+
+## Problem
+
+<!-- The specific user pain or technical gap this project addresses. -->
+
+## Target users
+
+<!-- Who benefits. Be specific; avoid "everyone". -->
+
+## Scope
+
+In scope:
+
+-
+
+Out of scope (deferred or rejected):
+
+-
+
+## Non-goals
+
+<!-- Explicit things this project will NOT try to be. -->
+
+## Success criteria
+
+<!-- How you will know this project is working. Prefer measurable signals. -->

package/templates/hooks/pre-commit.sample

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+# Doctrina pre-commit hook.
+# Installed by `doctrina hooks install`. Runs validate and blocks the
+# commit if it exits non-zero. Edit freely after install; the CLI will
+# not overwrite without --force.
+
+doctrina validate

package/templates/hooks/watch.sample

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# Doctrina on-save watcher (sample).
+#
+# Re-runs `doctrina validate` whenever a Markdown file under
+# .doctrina/ or docs/ changes. Pair with `doctrina hooks install` for
+# pre-commit validation; this script gives you the on-save loop too.
+#
+# Requires a path watcher to be installed. Two common choices:
+#
+#   entr      (POSIX, portable)        https://github.com/eradman/entr
+#   fswatch   (macOS / Linux / BSD)    https://github.com/emcrisostomo/fswatch
+#
+# Edit the body below to match your watcher of choice. The CLI does
+# not install or run this script — wire it into your dev setup
+# (a Make target, an npm script, a tmux pane) by hand.
+
+# entr example (default):
+find .doctrina docs -name '*.md' 2>/dev/null | entr -c doctrina validate
+
+# fswatch example (uncomment to use):
+# fswatch -o .doctrina docs | xargs -n1 -I{} doctrina validate

package/templates/skill.md.template

@@ -0,0 +1,49 @@
+---
+name: {{SKILL_NAME}}
+description: <one-sentence summary of what this skill helps the agent do>
+when: <one-sentence trigger — when the agent should load this skill>
+---
+
+# Skill — {{SKILL_NAME}}
+
+## When to use this skill
+
+<!--
+Be specific about the trigger. Examples that DO work:
+- The agent is asked to add or modify a database migration.
+- The agent is reviewing a PR that touches public API surface.
+- The agent is investigating a production incident.
+
+Examples that DON'T work (too vague):
+- "Whenever the agent is coding."
+- "Anytime there is a problem."
+-->
+
+## Procedure
+
+<!--
+Step-by-step. Exact commands beat advice. Verifiable checks beat
+adjectives. Same rules as AGENTS.md.
+-->
+
+1.
+2.
+3.
+
+## Anti-patterns
+
+<!--
+Things this skill exists to prevent. Be concrete: a real failure
+mode you have seen.
+-->
+
+-
+
+## Related material
+
+<!--
+Cross-links to the spec, ADR, or other artifacts that this skill
+references or extends.
+-->
+
+- [Workflow](../../docs/en/workflow.md)

package/templates/spec-bug.md.template

@@ -0,0 +1,40 @@
+# Bug spec — {{CAPABILITY}}
+
+**Capability:** {{CAPABILITY}}
+**Type:** bug
+**Status:** active
+**Last updated:** {{DATE}}
+**Version:** 0.1.0
+
+## Current behaviour
+
+<!--
+What the system does today, exactly. Reproduce the wrong path.
+Include input, observed output, and any error messages.
+-->
+
+## Expected behaviour
+
+<!--
+What it should do instead, exactly. Be specific about inputs and
+outputs that change.
+-->
+
+## Unchanged behaviour
+
+<!--
+What must keep working. The guard-rail that prevents "fix the bug,
+break two adjacent features". Reference the capabilities, flows,
+or files this bug fix must NOT alter.
+-->
+
+## Acceptance criteria
+
+<!-- Observable signals the bug is fixed and the guard-rails hold. -->
+
+1.
+2.
+
+## Out of scope
+
+<!-- Adjacent issues this fix deliberately does not address. -->

package/templates/spec.md.template

@@ -0,0 +1,52 @@
+# Spec — {{CAPABILITY}}
+
+**Capability:** {{CAPABILITY}}
+**Status:** active
+**Last updated:** {{DATE}}
+**Version:** 0.1.0
+
+## Purpose
+
+<!-- One paragraph: what this capability does and why it exists. -->
+
+## Requirements (EARS)
+
+<!--
+Easy Approach to Requirements Syntax. Use one of the five forms per item:
+
+- Ubiquitous:           The system shall <action>.
+- Event-driven:         When <trigger>, the system shall <action>.
+- State-driven:         While <state>, the system shall <action>.
+- Unwanted-behavior:    The system shall not <action> [when <trigger>].
+- Optional:             Where <feature available>, the system may <action>.
+-->
+
+### Ubiquitous
+
+-
+
+### Event-driven
+
+-
+
+### State-driven
+
+-
+
+### Unwanted-behavior (must-not)
+
+-
+
+### Optional
+
+-
+
+## Acceptance criteria
+
+<!-- Concrete, observable signals that the capability is correctly implemented. -->
+
+1.
+
+## Out of scope for this spec
+
+-