DECIDERS.md

Why DECIDERS.md?

As AI agents take on more of the work, one question moves to the foreground: who has the right to decide? AGENTS.md tells agents how to act — but nothing declares where human authority begins. DECIDERS.md fills that gap.

It's a Markdown file at the root of your repository that specifies which decisions must remain with an authorized human, which actions an AI may take autonomously, which it may only propose, and which role holds each decision right.

DECIDERS.md is not:

≠ AGENTS.md — instructions for agents

≠ SOUL.md — agent identity

≠ ETHICS.md — agent conscience

≠ FAILSAFE.md — technical shutdowns

Built to not rot

Most governance documents — RACI charts, approval matrices, org charts — go stale the day someone changes jobs. DECIDERS.md is designed not to. You write it once, and it stays true as your team changes.

It binds decisions to roles, not names, and points at a single live source — your CODEOWNERS file, a team page, or an identity-provider group — for who currently fills each role. When a person moves teams, you update that one source, not a scatter of hardcoded names. Write it once; don't rewrite it when your org changes.

Three decision tiers

DECIDERS.md classifies every AI action into one of three tiers based on who may authorize it.

Tier 1 — Autonomous

Routine, low-risk, reversible actions the AI may take without approval. Running tests, formatting code, generating documentation.

Tier 2 — Propose & Approve

Consequential actions the AI may propose but cannot execute until a designated human decider approves. Merging to main, modifying infrastructure, sending external communications.

Tier 3 — Human Only

Actions that must be initiated and executed by a human. Production deployments, access control changes, financial approvals, compliance configuration.

Quick start

Adoption takes one prompt, not a config project. Point a coding agent at your repo:

Prompt your agent

Create a DECIDERS.md at the root of this repository, following the
DECIDERS.md standard (https://deciders.md).

1. Find the deciders from what this org already has — don't ask me to
   list people. Read whichever exist: CODEOWNERS, MAINTAINERS/OWNERS
   files, GitHub teams and branch-protection reviewers, and CI/CD deploy
   permissions. Derive the ROLES that hold authority and the single
   source that records who currently fills each.
2. Sort this repo's AI-eligible actions into three tiers by risk and
   reversibility: Tier 1 Autonomous (routine, reversible), Tier 2
   Propose & Approve (needs a role's sign-off), Tier 3 Human Only
   (never AI-initiated — prod deploys, access control, secrets, billing,
   security/compliance, public comms). Bind each Tier 2/3 entry to a
   ROLE, not a person. Keep the Tier-3 gate intact.
3. Write a Core-conformant DECIDERS.md: Governance Statement, Decision
   Categories, and a role-based Decider Registry pointing at the sources
   from step 1.
4. Then ask me ONLY what you couldn't infer — usually: who owns
   production deploys, the escalation channel, and any action that must
   never be delegated to an AI.

It reads your CODEOWNERS, teams, and CI config to build the decider list, then asks only what it can't infer. Prefer to start by hand? Copy the template:

        DECIDERS.md
        
      
# DECIDERS.md

## Governance Statement

This project uses AI agents for development and operations.
All consequential decisions require approval from an authorized
human decider. Routine, low-risk, reversible actions may be
performed autonomously within the boundaries defined below.

## Decision Categories

### Tier 1 — Autonomous
- Running test suites and linters
- Creating and updating draft pull requests
- Generating documentation from code
- Formatting and refactoring within established patterns

### Tier 2 — Propose and Approve
- Merging to main              Role: Tech Lead
- Modifying CI/CD config        Role: DevOps Lead
- Updating dependencies         Role: Tech Lead
- External notifications        Role: Product Owner

### Tier 3 — Human Only
- Production deployments        Role: Release Owner
- Access control changes        Role: Security Lead
- Financial approvals           Role: Finance Owner

## Decider Registry

| Role          | Who holds it (single source)     |
| Tech Lead     | CODEOWNERS → @org/tech-leads     |
| Release Owner | CODEOWNERS → @org/release-owners |
| Security Lead | IdP group `security-approvers`   |

## Escalation Policy

Ladder: primary role → backup → emergency → system holds.
Channels and timeouts live in your runbook, not here.

## Delegation Rules

A role holder may delegate to a named backup for a set period.
Tier 3 decisions may not be delegated to AI systems.

Where it fits

The AI convention ecosystem has organized into distinct layers. DECIDERS.md fills the governance layer that no other convention addresses.

How agents act

AGENTS.md

How actions travel

MCP · HTTP · CLI

Where human authority begins
DECIDERS.md

Who agents are

SOUL.md

What agents believe

ETHICS.md

What agents can do

SKILL.md

When agents break

FAILSAFE.md

DECIDERS.md is transport-agnostic — it governs the decision whether the action arrives over MCP, an HTTP API, a CLI, or a UI. Transport is a neighbor, not the governance layer: a tool may propose, but Tier 2 and Tier 3 still pass through the human gate.

How to use DECIDERS.md

Add DECIDERS.md

Create a DECIDERS.md file at the root of your repository, alongside your AGENTS.md.

Define your tiers

Classify actions into autonomous, propose-and-approve, and human-only categories based on risk and reversibility.

Bind rights to roles

Assign each consequential decision to a role, then point that role at the one place your org already records who holds it — CODEOWNERS, a team page, or an IdP group. Every role must resolve to an accountable human; never an automated system. Bind to roles, not names, so the file doesn't rot when people change jobs.

Set escalation policy

Define the escalation ladder and what an agent does while a decision is pending. Keep volatile parameters — channels, timeouts, on-call rotations — in your runbook, referenced rather than inlined.

FAQ

Does this mean humans approve every action?

No. Tier 1 actions are explicitly autonomous. DECIDERS.md defines the boundary between autonomous and human-authorized actions. It doesn't require human approval for everything.

Are there required fields?

A Core file needs three things: a Governance Statement, Decision Categories, and a role-based Decider Registry. A Full file adds an Escalation Policy, Delegation Rules, and a Review & Change History. Beyond that it's standard Markdown — adapt it to your governance needs.

How do I create one?

Fastest is to let a coding agent scaffold it — use the prompt in Quick start. It reads the role sources your org already has (CODEOWNERS, teams, CI config) to build the decider list, then asks only what it can't infer. To start by hand instead, copy the template:

curl -o DECIDERS.md \
  https://raw.githubusercontent.com/decidersmd/deciders.md/main/TEMPLATE.md

How do I migrate an existing approval matrix or RACI?

Map each row to a tier by risk and reversibility: routine/reversible → Tier 1, needs sign-off → Tier 2, human-only → Tier 3. Replace every hardcoded name with the role, and record who holds each role once in CODEOWNERS (or a team page / IdP group). The matrix becomes a role-based Decider Registry that no longer rots on reorg.

What happens when someone changes roles?

Nothing in the file changes. DECIDERS.md binds decisions to roles, not names, and points at a single live source — CODEOWNERS, a team page, or an identity-provider group — for who holds each role. You update that one source; every DECIDERS.md that points at it stays correct. That's the whole design: write it once, and it stays true as your team changes.

Do I still name real people?

Every role must resolve to an accountable human — never an automated system, never a diffuse "whole team." But the names live in your single source of truth, not hardcoded across the file. Hardcoding names is the anti-pattern that makes governance docs rot.

How does this relate to AGENTS.md?

They're complementary. AGENTS.md tells agents how to work in your project. DECIDERS.md tells the organization which decisions require human authority. One is operational. The other is governance.

Can I update it later?

Absolutely. Treat DECIDERS.md as a living governance document. Review it on a cadence and when team structure changes. The specification also makes a stability promise, so the standard won't move under you: changes are additive, and the Tier-3 human gate is permanent.

Who created this?

DECIDERS.md is an open standard, offered as a complement to AGENTS.md. Its escalation policy was informed by publicly documented human-in-the-loop safety primitives (throttling, escalation, and stop/kill patterns). Contributions and critique are welcome on GitHub.