Doctrine

Doctrine is an evolving, ambitious, pragmatic approach to agentic engineering, expressed as a Rust CLI tool. You might think of it as a harness for your harness.

It promotes engineering rigour, fosters clear understanding, and bounds agent autonomy. Agents adhere to your intent, and you focus your attention on design, not supervision or repair.

Why?

You can build an effective process for small-scale projects in 80 lines of markdown - but agents follow prose instructions unreliably. As project scope and complexity grow, the effectiveness of this approach declines, and new failure modes emerge. Prose is flexible, but unstructured. A prompt, no matter how well considered, can only improve the odds so much.

Doctrine supplements coding agents with the determinism of classical software systems. Workflows are pushed down into finite state machines. Structured data alongside markdown documents allows their traversal as nodes in a graph. Decisions, assumptions, hypotheses, and evidence records make a shared semantic view of your codebase legible. Memories decay over time, and are surfaced when the files they concern are encountered.

Doctrine is designed to work with any model or harness, though specific integrations may vary slightly. Its vendor-agnostic handling of project context, and strict guardrails, make less capable and cheaper models more reliable and reduce the barriers to substitution.

freedom through constraint

Design Goals

Priorities, in order — when two conflict, the higher one wins:

1. Correctness. Work that is wrong is worse than work not done. Lifecycle rules live in the binary, not in a prompt: the CLI refuses an illegal transition, whatever the agent was told. Phases close green; slices close through an audit.
2. Comprehension. You should be able to understand what your agents built and why, months later. Intent, decisions, and evidence are recorded as they happen, cited by durable ids, and linked into one graph you can query.
3. Adaptability. Your process is not ours. Templates, skills, and governance are plain files you own and edit; doctrine works with any model or harness, at any project size.
4. Automation. Once the above hold, hand over more of the loop: parallel workers, prescribed next steps, derived priority.
5. Efficiency. Spend as little as possible of three budgets — complexity, tokens, and human attention. Agents load the context they need, when they need it, instead of a wall of instructions every turn.

Why you might care

• Agents stop drifting. A long design session survives context compaction because its state lives on disk, not in the transcript. The framework tracks where the work stands and what is owed next; the agent spends its judgement on the problem.
• You review design, not wreckage. Scope, design, and plan are agreed before code is written. Review findings sit on a ledger that must be resolved, not in a chat scroll.
• Knowledge compounds. What one session learns, the next one inherits — scoped to the files it concerns, with staleness flagged rather than silently trusted.
• Cheaper models do more. Structure and guardrails carry weight a frontier model would otherwise carry in its head, which makes substitution practical.
• It's just files. TOML and Markdown in your repo, versioned with your code. A single binary, no service, no account, no lock-in.

What's in the box

Area	What it does
Change lifecycle	Every intentional change is a slice: scope → design → plan → phases → audit → reconcile → close. The lifecycle is a state machine; design runs are managed, so an interview resumes cleanly in a fresh context.
Specifications & governance	Product and technical specs, requirements, ADRs, policies, standards, RFCs, and revisions. A boot snapshot puts the binding rules — and who may override them — in front of every agent session.
Epistemic records	Assumptions, decisions, open questions, constraints, evidence, hypotheses, and concepts: the things a project acts on without having proven, tracked from held to settled instead of lost in prose. Useful before anything is concrete enough to build.
Memory	Typed, scoped memories anchored to the code they describe. Surfaced when an agent touches matching files; verified, aged, and flagged when stale. Usable on its own (--only-memory).
Adversarial review	Reviews as a first-class ledger: findings are raised, disposed, verified, or contested turn by turn — across models if you like. Audit uses the same ledger to reconcile what was built against what was designed.
Backlog & priority	Cheap capture of issues, improvements, chores, risks, and ideas. Priority and actionability are derived from the dependency graph and lifecycle state; doctrine next explains its answer. Value can be elicited by pairwise comparison.
Parallel dispatch	Phases run as workers in isolated git worktrees (kernel-confined on Linux). One orchestrator is the sole writer of shared state; progress is crash-resumable; nothing lands on trunk before audit. Orchestration verbs are primitives you can compose.
Exploration	Ranked search over the whole corpus, relation graphs in the terminal, and a local web explorer (doctrine map serve).
Harness independence	Skills install for Claude Code, Codex, pi, and other agents. Per-model prompt supplements resolve on demand, so one project works across harnesses.
Self-measurement	An observation ledger captures process friction as it happens, so the workflow itself can be tuned on evidence.

The separation is deliberate throughout: structured, queryable data in TOML; prose in Markdown; disposable runtime state in a gitignored directory, apart from the artifacts worth keeping.

Non-Goals

• SaaS integration (in core)
• Windows support (for now)
• Integrated TUI (for now)

Installation

TL'DR:

curl -sL https://install.doctrinal.systems | sh

Prebuilt binary (macOS + Linux, no Rust toolchain) — recommended:

# latest release (rolling):
curl -fsSL https://raw.githubusercontent.com/davidlee/doctrine/main/install.sh | sh

# or pin to a release tag for reproducibility:
curl -fsSL https://raw.githubusercontent.com/davidlee/doctrine/v0.8.1/install.sh | sh

Installs to ~/.local/bin (override with DOCTRINE_BIN_DIR); choose a version with DOCTRINE_VERSION. The script checksum-verifies what it downloads — read it before piping to a shell. macOS arm64 + x86_64; Linux x86_64 + aarch64 (static musl — runs on any distro regardless of glibc version).

Or with cargo binstall (prebuilt, no compile):

cargo binstall doctrine

Or cargo install (compiles from source; needs a Rust toolchain — may hit the -liconv link error on some macOS toolchains, which the prebuilt paths above sidestep):

cargo install doctrine

Then bootstrap a project:

cd my_project || mkdir my_project

doctrine install                  # prompts to confirm; or use --dry-run | --yes

claude 
> Let's design a feature: ...

or install from source (customise templates / skills):

gh repo clone davidlee/doctrine && cd doctrine

# optional: 
# customise install/templates and/or plugins/skills
# they'll get bundled into the binary for installation

cargo install --path .

or use it as a nix flake:

inputs.doctrine.url = "github:davidlee/doctrine";
# ...
doctrine = inputs.doctrine.packages.${system}.doctrine;

to install skills for other agents:

doctrine install --agent codex    # or pi / universal: all read .agents/skills from the embed

Host dependencies

doctrine install registers the doctrine MCP server with each detected harness. The Codex registration is user-level: install runs codex mcp add doctrine -- <absolute path of the doctrine on your PATH> serve --mcp, writing ~/.codex/config.toml (or $CODEX_HOME/config.toml), so it applies to every project on the machine. Interactive codex starts MCP servers from a long-lived daemon whose PATH is frozen, so a PATH-dependent command fails there; an absolute path works, and a machine path does not belong in a file that client projects commit.

Two things follow:

• install asks a separate question before changing that user entry (default No, asked only when the entry would change), and -y grants it; declining changes nothing in either codex config;
• codex mcp add replaces the whole entry, so the prompt lists any keys the write would drop.

An old doctrine-written project-level [mcp_servers.doctrine] entry is removed under the same consent, because codex prefers the project layer. A project entry whose command contains a path separator — or a url transport — is a deliberate override: left untouched and reported. A PATH-dependent foreign project entry is warned about and leaves install incomplete. Codex has a per-folder trust prompt before it loads project config; the user-level entry does not depend on it.

The codex CLI is a declared dependency of the codex harness: with no codex on PATH, install prints the codex mcp add line to run yourself. A codex session already running keeps its old MCP config until restarted.

Post-Install Setup

mkdir my-project && cd my-project
git init 
mkdir .claude 

# also run this after a new doctrine version:
doctrine install -y

# commit with the git add / git commit command install prints

Memory-only use

Use Doctrine's memory system with your preferred tooling for the rest:

cd my-project
doctrine install --agent claude --only-memory -y 

# doctrine memory help
# doctrine memory record --type pattern "red/green/refactor TDD" --glob "src/lib/**/*" --summary "..."
# doctrine memory list

Usage

# start up your harness of choice 
claude

# it'll route through doctrine when it needs to
> I've got a markdown file @here.md with a task description. Take a look and let's shape it up.

Many / most of the CLI surface is really for agents. Once you have some content, you might find some of these useful:

doctrine --help
doctrine slice list 
doctrine status
doctrine next
doctrine backlog list
doctrine <kind> paths <ID>
doctrine search ...
doctrine memory find ...

Doctrine ships with self-documenting agent memories.

You can view them yourself with doctrine onboard.

The agent should be able to steer while you get used to the default workflow.

Hack

templates:

nvim .doctrine/templates

skills:

rm .claude/skills/code-review # remove symlink
cp -r .doctrine/skills/code-review/ .claude/skills/

nvim .claude/skills/code-review/SKILL.md
git add -f .claude/skills/code-review/SKILL.md

doctrine install # skips existing non-symlinks

or:

gh repo fork davidlee/doctrine --clone
cd doctrine
nvim doctrine/plugins/review
git commit -m "feat: review like a pirate" && git push
cargo install --path .             # build with your edits

# in your projects
doctrine install --agent claude --yes # from binary, or
doctrine install --agent universal --yes # for pi / codex / other .agents/skills harnesses

License

This repository is multi-licensed:

• Rust source code, application code, and compiled binaries are licensed under GPL-3.0-only.
• Files under plugins/ are licensed under MIT.
• Files under install/ are licensed under MIT, including templates and config.toml.

Where a file contains an SPDX license identifier or a directory contains its own LICENSE file, that more specific notice controls.

Acknowledgements

The /worktree skill's directory-selection and safety-verification patterns are adapted from superpowers:using-git-worktrees by Jesse Vincent (MIT).

Specifications

Product and technical specifications — the durable, agent-readable intent behind Doctrine's capabilities. Regenerate this list with just readme-index.

Product Specifications

• PRD-001 — Slices — active
• PRD-002 — Specifications — active
• PRD-003 — Skills — active
• PRD-004 — Memory — active
• PRD-005 — Reservation & Leasing — active
• PRD-006 — Install — active
• PRD-007 — Boot & Governance — active
• PRD-008 — ADRs — active
• PRD-009 — Backlog — active
• PRD-010 — Epistemic and Governance Records — active
• PRD-011 — Graph-Derived Priority and Actionability — active
• PRD-012 — Technical Specifications —

Technical Specifications

• SPEC-001 — Graph-Derived Priority Engine — active
• SPEC-002 — Requirement Reconciliation Engine — active
• SPEC-003 — Doctrine — active
• SPEC-004 — Entity engine — active
• SPEC-005 — ADR entity surface — active
• SPEC-006 — Spec composition machinery — active
• SPEC-007 — Memory engine — active
• SPEC-008 — Id lifecycle — active
• SPEC-009 — Install & distribution — active
• SPEC-010 — Skills distribution — active
• SPEC-011 — Boot snapshot — active
• SPEC-012 — Dispatch & worktree —

Request for Comments

• RFC-001 — Thesis: graph value is gated on consumption surfaces — open
• RFC-002 — Consumption surfaces program: estimate, value, and scoring outward pipeline — open
• RFC-003 — Relation model: durable structural shape vs contextual role-intent — resolved
• RFC-004 — Path-intent selector: role-stamped selector+intent primitive — resolved
• RFC-005 — Dispatch funnel integrity: hazard survey and correctness posture — open
• RFC-006 — Auto-merge non-FF trunk at integrate: reversing the FF-only posture — resolved
• RFC-007 — Actionability: legibility and correctness — open
• RFC-008 — Actionability gating: association vs graph-effect — resolved
• RFC-009 — Epistemic records as the human-facing relational substrate for design ambiguity — open
• RFC-010 — Skill improvement sweep — resolved
• RFC-011 — Dispatch Token Efficiency —

Architecture Decision Records

• ADR-001 — Module layering: leaf ← engine ← command, no cycles — accepted
• ADR-002 — Global orientation memory class: repo-empty, unanchored, evergreen — accepted
• ADR-003 — Canonical change loop: slice-first, observe, reconcile, close — accepted
• ADR-004 — Relations stored outbound-only; reciprocity is derived — accepted
• ADR-005 — Shipped knowledge is tiered by access pattern; skills route, reference docs explain — accepted
• ADR-006 — Worktree posture: policy-agnostic framework, orchestrator-sole-writer dispatch — accepted
• ADR-007 — Adversarial review as a first-class kind with turn-based ledger coordination — accepted
• ADR-008 — Project-local jail build isolation and worker confinement for parallel dispatch — accepted
• ADR-009 — Slice lifecycle state machine and conduct axis — accepted
• ADR-010 — Relation modelling: unify the contract and write seam, keep storage bespoke — accepted
• —