mandate-framework

Mandate Framework

Spec-driven governance for AI coding agents. 🇧🇷 Português: README.pt-BR.md

Mandate is a ready-to-clone framework that gives an AI coding agent (Claude Code as primary executor; Codex/Copilot as reviewers) a mandate: a constitution it reads every session, decisions it may not reopen, a backlog it executes story by story, a small virtual org of role agents with explicit limits, and deterministic guardrails with one verification command that runs the same way locally and in CI.

Its golden rule is its name: the agent acts within its mandate; whatever exceeds it becomes an RFC, and only the decider widens a mandate.

The seven pillars — M.A.N.D.A.T.E.

Method guide — the why behind every file: docs/reference/governance-template.md · PT-BR. Stack-, domain- and tool-agnostic.

Quick start

git clone https://github.com/murilovieir/mandate-framework my-project && cd my-project
rm -rf .git && git init -b main            # start your own history
./scripts/init.sh                          # asks for project name, decider, phase… fills every {{PLACEHOLDER}}
git config core.hooksPath scripts/guardrails/git-hooks
./scripts/guardrails/verify-all.sh         # must end with "VERIFY-ALL: OK"
git add -A && git commit -m "chore: bootstrap governance" -m "Refs: T-001"
git branch develop

Then, in order (template §18):

1. Fill CLAUDE.md §1–§2 and §6 — context, stack table, phases. Write one ADR per stack row (docs/adr/README.md has the template).
2. Adjust governance.env — your sensitive domains and sensitive paths. This is the one thing you can't retrofit after a silent default ships.
3. Record the instruction budget: ./scripts/guardrails/instruction-budget.sh --record.
4. Write your first domain guardrail for your first survival condition (scripts/guardrails/README.md).
5. Plan Unit of Work 01 (docs/backlog/uow-01/_index.md) and execute its first story: "execute T-001".

What's inside

Principles in one breath

Markdown in the repo is the source of truth · every story has a spec · one decider approves RFCs · every fork goes to the Decision Log · delivery and decision are separate axes · a rule without a script is a wish — so every checkable rule has one, run as a warning hook locally and as a merge-blocking check in CI, from the same source.

Requirements

bash, git, python3 (≥ 3.9, standard library only), jq (for the Claude Code hooks). Optional: gh for Issue mirroring.

Author

Created and maintained by Murilo Vieira (@murilovieir).

Mandate was designed and evolved by using it every day and turning each correction into a rule — and, where possible, into a script. The method grew in this order:

1. Constitution read by the agent every session; spec-driven stories (Implementation Contract); ADRs as locked decisions.
2. Decider-gated RFC flow — the agent proposes, never decides.
3. Spec-Driven Development vocabulary; /analyze consistency gate; one-way GitHub Issues mirroring.
4. Virtual org of role agents with bounded mandates; Decision Log v2 (sensitive-default escalation, batch ratification); rigor ladder N0–N3; parallel fan-out.
5. Execute before asserting — the review gate.
6. Deterministic guardrails (hook + CI, one source); two-tier knowledge; bolt sizing; agent evals; machine-readable decision status; verify-all.sh as the single authority; two-hop branching; scale-readiness gates.
7. Mandate Framework v1.0.0 — the seven pillars, packaged as a framework.

What comes next: ROADMAP.md. Contributions: CONTRIBUTING.md.

License

MIT © 2026 Murilo Vieira. Projects bootstrapped with scripts/init.sh keep a copy of the license in docs/guides/MANDATE_LICENSE, which satisfies the notice requirement.

Mandate is an independent project. It is not affiliated with, endorsed by or sponsored by Anthropic (Claude Code), Amazon Web Services (AI-DLC), OpenAI (Codex) or GitHub (Copilot); those names are used only to describe compatibility and comparison. In .github/CODEOWNERS, @{{DECIDER_GITHUB}} is intentional: init.sh replaces it in your project.