____             _        _             
|  _ \  ___   ___| |_ _ __(_)_ __   __ _ 
| | | |/ _ \ / __| __| '__| | '_ \ / _` |
| |_| | (_) | (__| |_| |  | | | | | (_| |
|____/ \___/ \___|\__|_|  |_|_| |_|\__,_|

  spec-driven · AGENTS.md-native · zero-deps

Spec-driven, AGENTS.md-native framework for multi-agent AI development.

Status: v0.15.1 — released. Read this in Portuguese.

The main path: capture intent once, then turn each request into a scaffolded change that the agent drives through the gates. You give the prompt and approve; the CLI keeps the artifacts honest. (Full per-command flowchart in the flow diagram.)

flowchart TD
    I["doctrina init"] --> N["doctrina intake"]
    N --> P["product.md + specs (EARS)"]
    P --> W["doctrina work 'prompt'"]
    W --> C["doctrina context --concat<br/>(read pack)"]
    C --> E["spec delta → tasks → implement"]
    E --> CK["doctrina change check<br/>(pre-close dry-run)"]
    CK --> AN["doctrina analyze"]
    AN -- "structural gate" --> AP["doctrina change apply"]
    AP --> GATE{"gates green?<br/>verify · coverage · trace · review"}
    GATE -- "red" --> E
    GATE -- "green" --> AR["doctrina change archive → validate"]
    AR --> NX["doctrina next"]
    NX -. "resume the loop" .-> W
    CK -. "doctrina close id...: ADR checkpoint → gates → archive → validate → skill suggest" .-> AR
    STAT["doctrina status / why / watch<br/>(always-on, passive)"] -.-> W

The bottleneck of AI-assisted development is not code generation — it is the reliable transfer of intent and the persistence of context across sessions and agents. Doctrina treats specifications as the single source of truth, keeps architectural decisions as immutable ADRs, and orchestrates work through a single linear coordinator instead of competing parallel agents.

The name comes from the Latin word for doctrine — the foundational text that governs how a body of agents acts.

1. Single ownership of every fact. Specs hold current truth. Changes hold transient deltas that merge into specs and disappear. ADRs hold immutable decisions. No information has two homes. Enforced: the on-disk grammar has one owner (ADR 0021), the command surface one catalog (ADR 0020), and index.json one definition — each with a drift test.
2. Active truth stays small and dense. Files the AI reads on every turn are size-capped to fight the "lost in the middle" effect. Enforced: doctrina context assembles the read pack to fit a token budget rather than measuring it after the fact, degrading decisions to a one-sentence summary before dropping anything (ADR 0022). CI fails when a pack no longer fits.
3. Status, not folder migration. Items are retired by status + link, not by moving files (with the exception of transient changes that archive).
4. Single linear orchestrator by default. Multi-agent parallelism is the wrong default for code writing — it produces conflicting implicit decisions. Subagents are used only for isolated read-only investigation.
5. Value-gated pipeline. The full ceremony runs only when ambiguity costs real time. One-line fixes skip it.
6. Portability over invention. Doctrina builds on the open AGENTS.md standard, on ADRs in the Nygard/MADR format, and on EARS for requirements.

• An AGENTS.md template that follows the open standard, with a CLI-owned command-surface block generated from the installed CLI and regenerated by doctrina upgrade --write (ADR 0015) — agents discover commands through the hub, so the hub can never lag the CLI.
• A .doctrina/ skeleton with product.md, specs/, changes/, decisions/, skills/, templates/, and index.json.
• The doctrina CLI (Node.js, zero runtime dependencies) with 37 commands and 59 operations covering init, intake, adapter, work, prime, spec, change, decision, contract, skill, intent, analyze, clarify, context, show, search, validate, coverage, trace, review, verify, close, doctor, status, why, handoff, constitution, watch, templates, hooks, index, next, metrics, report, completion, and upgrade. The count is checked against the catalog by scripts/check-docs.js, so this line cannot drift.
• Adapters for 12 AGENTS.md-aware agents (Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf, Continue, Amp, Devin, Factory, Jules).
• Eight capability specs and the ADRs 0001–0022 that describe the framework (including ADR 0006, intent provenance; ADR 0018, the exit-code contract; ADR 0021, the one document model; and ADR 0022, context assembly as retrieval), plus on-demand skills capturing its own maintenance procedures.
• Two reference example projects (Python FastAPI greenfield, TypeScript Express brownfield retrofit).
• Bilingual documentation in English and Portuguese.

• A memory/ folder. Deferred until measured pain justifies the complexity. See .doctrina/decisions/0003-defer-memory-folder.md.
• Multi-agent parallel writers. See .doctrina/decisions/0004-single-linear-orchestrator.md.
• A database, vector store, or RAG layer.
• Documentation generators that produce content the humans never read.
• Telemetry, analytics, or network calls. See SECURITY.md.

AGENTS.md                root rules (portable, open standard)
README.md                this file
README.pt.md             Portuguese translation
LICENSE                  MIT
package.json             npm workspaces
.doctrina/               framework artifacts (product, specs, decisions, skills, templates, index)
docs/en /docs/pt         bilingual user-facing documentation
examples/                two reference projects (Python FastAPI, TypeScript Express)
packages/doctrina-cli/   the npm CLI source
scripts/                 synthetic performance benchmark

📖 Documentation site: gcarin1.github.io/Doctrina — bilingual (EN/PT), sidebar navigation, full-text search, served straight from this repository's docs/ folder via GitHub Pages with zero build step. Deployment is automated by .github/workflows/pages.yml, which publishes docs/ on every push to main that touches it. One-time setup: enable Pages once under Settings → Pages → Source → GitHub Actions.

User-facing documentation lives under docs/:

• Getting started — install, init, first feature.
• Workflow — propose → apply → archive.
• CLI reference — every command and flag.
• Adapters — Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Continue.
• Local LLMs — wire Doctrina to LLaMA, Mistral, Qwen, DeepSeek, or any OpenAI-compatible endpoint.
• Multi-agent model — how Doctrina coordinates tools, phases, and humans without parallel writers.
• Skills — on-demand procedural memory: specialised "how to do X" knowledge loaded only when relevant.
• Context engineering — why context shape predicts agent performance more than agent count.
• Gating — when the full pipeline is worth it.
• Brownfield adoption — operational guide for installing Doctrina into an existing codebase.
• Comparison — honest positioning vs Spec Kit, Kiro, OpenSpec, BMAD, SpecWeave.
• Migration — practical mappings from Spec Kit, OpenSpec, BMAD, Kiro, SpecWeave.
• Benchmarks — synthetic numbers for validate and clarify across project sizes.
• Deferred — what we deliberately did not ship at v0.1.0 and why.

Two reference projects live under examples/: a Python FastAPI greenfield demo and a TypeScript Express brownfield retrofit.

Project policy: CONTRIBUTING.md · CHANGELOG.md · SECURITY.md.

• Antipatterns — documented failure modes.
• Validation — empirical A/B protocol to decide if Doctrina is paying for itself.
• Glossary — EARS, ADR, MADR, capability, etc.

Portuguese translations are at docs/pt/.

Doctrina stands on the shoulders of GitHub Spec Kit, OpenSpec, AWS Kiro, BMAD-METHOD, the open AGENTS.md standard, and Michael Nygard's ADR format. Doctrina is a deliberate re-synthesis — not a fork — of their lessons.

MIT. See LICENSE.