doctrine-agents 1.0.2

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 flows as code. Compile them to AGENTS.md.

Doctrine is a typed DSL and compiler for reusable agent instructions, workflows, reviews, skills, and I/O contracts. Instead of hand-editing giant AGENTS.md files, you author small .prompt files and compile deterministic runtime artifacts that current coding-agent tools can already read today.

Why teams reach for Doctrine:

• one shared rule changes once
• 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

Doctrine and Rally

• Use Doctrine when you want to author and validate the flow.
• Use Rally when you want to run that flow with repo-local state, resumability, and strict turn routing.
• The split is deliberate: Doctrine is the authoring layer, Rally is the runtime layer.

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

Source checkout is still the full setup path for contributor proof, the example corpus, and emit_flow.

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

Want the packaged compiler instead of a source checkout?

python -m pip install doctrine-agents

git clone https://github.com/aelaguiz/doctrine.git
cd doctrine
uv sync
npm ci
make check

Want a smaller first proof?

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

Want generated output right away?

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, and JSON-schema-backed contracts
• imports, readable refs, interpolation, enums, and workflow law
• emit_docs, emit_flow, and emit_skill
• manifest-backed verification through examples/106_review_split_final_output_json_schema_partial
• 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
• docs/LANGUAGE_REFERENCE.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.