AGENTS.md — Doctrina

Operational source of truth for AI coding agents working in this repository. Follows the open AGENTS.md standard. This repo BUILDS the Doctrina framework and uses it on itself; its artifacts live in .doctrina/.

Working from intent (you drive; the human stays passive)

You — the AI agent — run the Doctrina commands. The human gives a brief 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 (fill product.md, derive capabilities, one EARS spec each, clarify --all + validate, then flip the intake to converted). Existing 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. 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 command surface (generated — reach for these, don't hand-author)

Every command, with the moment you reach for it. The CLI scaffolds from canonical templates and syncs index.json. Flags: doctrina <cmd> --help. Bootstrap

• doctrina init — scaffold AGENTS.md and .doctrina/. When: starting a project that has no AGENTS.md yet.
• doctrina intake — store the intent and print the bootstrap playbook. When: you have a full project description and no specs yet.
• doctrina adapter list|add|remove — install/remove agent adapters (additive). When: adding or removing an agent's pointer files. Orient
• doctrina prime (session start) — gates, open work and next steps in one read (--rules for the full standing rules). When: at the START of every session.
• doctrina context [<cap>] --for "<task>" --concat — the read pack, assembled to fit a token budget. When: before working on any task, to load the right files.
• doctrina show — point-read a single artifact by reference. When: you need one requirement, criterion, or ADR, not a file.
• doctrina search — search the artifact tree, grouped by category. When: you do not know which artifact mentions a term.
• doctrina status — index, coverage, trace, and artifact counts. When: you need the health of the tree at a glance.
• doctrina next — the recommended next workflow action. When: you finished something and do not know what follows.
• 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: 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|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.
• doctrina intent add|list — append and list product intent anchors. When: new product intent appears after the intake. Gate
• doctrina clarify --all (--lang pt|en) — smell-test Markdown for ambiguity. When: before applying, or before opening a PR.
• doctrina validate (--fix) — schema, structure, EARS, and index drift. When: after any artifact edit, and before considering work done.
• doctrina coverage --strict — acceptance criteria against cited evidence. When: before claiming a capability is proven.
• doctrina trace --strict — intent provenance across the tree. When: checking that product intent still maps to capabilities.
• doctrina review — conformance of your changes vs specs/ADRs/contracts. When: before handing work back, to self-review it.
• 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

What changed in 0.21.0

• At a workspace root, next, handoff, status, validate, context, doctor and metrics answer for the workspace; never doctrina init there or in a shadowed repository's clone — the commands name doctrina workspace attach instead.
• A task card carries the delta, the delivery's story and every binding decision, global ones included: as an executor, stop and report when the story or the task contradicts one; a card on placeholder tasks means the planner writes them first (doctrina work --resume <id>).
• Run the command lines the CLI prints as printed: paths and titles are quoted for the shell, and tracker text stays data.
• Cursor: the core loop is skills in .cursor/skills/doctrina-*/; run doctrina upgrade --write to move an older install. With a tool declared the guard fails closed — a refused call means fix the install or ask the human.
• Absorb: after writing specs by hand run doctrina validate --fix; a stored code inventory resumes with a bare doctrina intake, never --from-code again.

Stack

Node.js (ESM, zero runtime dependencies), npm workspaces, node:test.

Commands

npm install
npm test --workspace=doctrina-cli
node packages/doctrina-cli/src/index.js verify   # the real build gate
node scripts/check-docs.js                       # docs shape and accuracy

Repository structure

The CLI is packages/doctrina-cli/ (src/commands/ render, src/lib/ decides — ADR 0025); docs are docs/en/ + docs/pt/, kept in parity.

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.

Artifact invariants (verbatim — doctrina validate enforces these)

Scaffold with the CLI; do not hand-author from memory. If you must:

• Metadata headers come in two forms — do not mix them up:
  • ADRs, change proposals, and the intake use list items: - **Status:** accepted, - **Date:** 2026-06-13.
  • Specs use bare bold (no leading - ): **Status:** active, **Version:** 0.1.0. Match the template for the artifact you are writing.
• ADR filename must be NNNN-slug.md — four digits, e.g. 0001-jwt-algorithm.md. ADR-001-...md or 1-...md is invisible to doctrina decision accept, the index, and the orphan check.
• Change folder at .doctrina/changes/<id>/ must contain a file named exactly proposal.md (not change.md, not README.md). tasks.md and design.md are optional siblings.
• Spec lives at .doctrina/specs/<capability>/spec.md and its **Version:** header must equal the version recorded for it in .doctrina/index.json.
• Every artifact on disk must be registered in .doctrina/index.json, and every path in index.json must exist on disk. Update the index in the same change that adds or moves a file.

Always finish by running doctrina validate and resolving every error: before considering work done.

How to read context efficiently

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; changes/archive/ is history. doctrina show <ref> reads one requirement or ADR.

Keep this file under 150 lines; doctrina doctor reports what is left, and the generated block above grows with the CLI. Use exact commands.

Definition of done

doctrina close <id> is the definition: tasks checked, deltas merged into specs, gates green, ADRs recorded and accepted, change archived, index updated. If close refuses, the change is not done.

What never goes in this file

Tutorials, project history, secrets, generated content, session notes.