doctrine-agents 2.0.0

Typed DSL and compiler for reusable AI agent instructions and workflows that compile to AGENTS.md.

Doctrine

Docs · Versioning · Changelog · Rally · VS Code extension

Write agent workflows in a code-like DSL. Compile them to portable instructions.

Doctrine is a typed DSL and compiler for agent instructions, workflows, reviews, skills, and I/O contracts that coding agents are actually good at writing and maintaining. Instead of hand-editing giant AGENTS.md files, letting coding agents generate markdown sprawl, or locking yourself into a proprietary Python agent framework, you author small .prompt files and compile deterministic runtime artifacts that current coding-agent tools can already read today.

If Rally is how you run the workflow, Doctrine is how you author it. Rally gets attention through strong, stable workflow execution. Doctrine is the reason those workflows stay coherent under the hood.

Why teams reach for Doctrine:

• instructions read like code instead of text sludge
• coding agents can change shared rules without duplicating markdown
• compile-time failures catch drift before runtime
• humans can review source and emitted runtime side by side
• flow diagrams, verification, and editor support ship today
• output stays portable across current agent tools and harnesses

Runtime boundary

Doctrine is the authoring and compile layer. It turns typed .prompt source into deterministic runtime Markdown such as AGENTS.md. That output is meant for the agent runtime that fits your stack. Doctrine does not try to be the runtime, scheduler, or state store.

If you want the split in one glance:

• Use Doctrine when you want to author and validate the flow.
• Use Rally when you want to run a strong, stable workflow with repo-local state, resumability, and strict turn routing.
• The split is deliberate: Doctrine is how you author it. Rally is how you run it.

Why Doctrine exists

Serious agent systems drift fast when the source of truth is copied Markdown:

• shared sections get duplicated and then edited out of sync
• one policy fix turns into search-and-hope edits
• large prompt trees become hard to review
• runtime Markdown is the delivery format, not the right authoring surface

Doctrine turns that into a language and compiler problem.

Quick example

workflow SharedTurn: "How To Take A Turn"
    "Read the current brief before you act."
    "Leave one honest handoff and stop."

skill RepoSearchSkill: "repo-search"
    purpose: "Find the right repo surface for the current job."

abstract agent ReviewRole:
    read_first: SharedTurn

agent BriefReviewer[ReviewRole]:
    role: "Core job: review the current brief and route the same issue honestly."

    inherit read_first

    skills: "Skills"
        can_run: "Can Run"
            skill search: RepoSearchSkill
                requirement: Advisory

That compiles to runtime Markdown:

Core job: review the current brief and route the same issue honestly.

## How To Take A Turn

Read the current brief before you act.
Leave one honest handoff and stop.

## Skills

### Can Run

#### repo-search

Quickstart

Want the Doctrine skill from this repo?

npx skills add .

Run that from the Doctrine repo root. That one line installs the checked-in agent-linter skill from this repo. If the CLI asks where to install it, pick the agent you use.

Want a no-prompt Codex install?

npx skills add . -g -a codex -y

When Doctrine is installed from a package index, the distribution name is doctrine-agents. The Python module name stays doctrine.

Want the packaged compiler?

python -m pip install doctrine-agents

Need the example corpus, repo proof, or emit_flow?

git clone https://github.com/aelaguiz/doctrine.git
cd doctrine
make setup

Use CONTRIBUTING.md for the full source-checkout proof path. make setup owns the repo bootstrap commands. Use docs/VERSIONING.md for release rules and CHANGELOG.md for the public release record.

Want a smaller first proof from a source checkout?

uv run --locked python -m doctrine.verify_corpus --manifest examples/01_hello_world/cases.toml

Want generated output right away from a source checkout?

uv run --locked python -m doctrine.emit_docs --target example_07_handoffs
uv run --locked python -m doctrine.emit_flow --target example_73_flow_visualizer_showcase

What ships today

• concrete and abstract agent declarations
• reusable and inherited workflow declarations
• first-class review and abstract review declarations
• typed skills, inputs, outputs, direct output[...] inheritance, output schema, and generated schema contracts
• imports, directory-backed runtime packages, readable refs, interpolation, enums, and workflow law
• emit_docs, emit_flow, emit_skill, and structured-output schema validation helpers
• manifest-backed verification through examples/115_runtime_agent_packages
• a repo-local VS Code extension for .prompt files

Workflow visualizer

The checked-in showcase above comes from examples/73_flow_visualizer_showcase. It proves that Doctrine can emit human-readable runtime docs and compiler-owned flow diagrams from the same source graph.

Read next

• docs/README.md
• docs/VERSIONING.md
• CHANGELOG.md
• docs/WHY_DOCTRINE.md
• PRINCIPLES.md
• docs/LANGUAGE_REFERENCE.md
• docs/AUTHORING_PATTERNS.md
• docs/EMIT_GUIDE.md
• examples/README.md
• editors/vscode/README.md
• CONTRIBUTING.md

Questions and contributions

• Use Discussions for questions and design talk.
• Use Issues for clear bugs or scoped proposals.
• See CONTRIBUTING.md for setup and proof commands.
• See SUPPORT.md for help paths, SECURITY.md for private vulnerability reports, and CODE_OF_CONDUCT.md for collaboration rules.

If this direction is useful, star the repo and watch releases.