Maintainer Gate Blueprint is a Frontier Infra project for making multi-agent software projects safer to maintain.
It gives maintainers a reusable operating model for:
- structured issue intake
- stricter PR intake
- slice and worktree discipline
- machine-checkable handoff packets
- clean dev/release-lane reconstruction
- operator validation before promotion to
main - separate handling for public-docs and multi-repo work
- automated patrol loops (Bug Patrol + Feature Patrol on separate machines)
- PR quality gates (CI → Code Review → Email → Merge)
- incident response and health monitoring
- changelog and version management
This is for projects where multiple agents, humans, or automation threads are working in parallel and maintainers need a reliable way to prevent regressions, merge the right work, and promote changes safely.
Who this is for. You're a maintainer (often a team of one) running AI coding agents — Claude Code, Codex, or similar — against a real codebase, sometimes several agents at once on several machines.
Why it exists. Agents move fast and sound confident whether or not the work is real. Left alone, they work from dirty trees, reuse stale branch names, mix unrelated changes, claim "done" without proof, and merge regressions you find in production. The problem isn't any one agent — it's that nothing in the repo forces the workflow to be safe.
What it is. A directory of operating rules (ops/), a handful of scripts,
and CI/hook wiring that get stamped into your repo by an installer. Agents read
the rules at the start of every session; the scripts and gates enforce the
critical ones even when an agent doesn't read anything.
How it works. Three layers, weakest to strongest:
- Rules agents read — runbooks and rules in
ops/(claim your slice, batch your fixes, escalate features, report with receipts). - Machine checks — handoff packets and PR intake validated by scripts in CI, so "the paperwork is right" is checked by code, not trust.
- Deterministic gates — a PreToolUse hook that blocks destructive prod-DB commands and a CI gate that flags cross-tenant data leaks. These run whether or not the agent cooperates.
Work flows one way: implementation branch → PR → quality gates (CI → review →
notification) → operator validation → main. Nothing lands on main on an
agent's word alone.
In fast-moving repos, the failure mode is predictable:
- agents work from dirty trees
- branch names stop being trustworthy
- handoffs are vague
- docs changes get mixed into product changes
- regressions are discovered after merge
- maintainers end up reconstructing intent from chat instead of source-of-truth artifacts
Maintainer Gate Blueprint fixes that by making the workflow explicit, repeatable, and machine-checkable.
The blueprint includes:
- reusable
ops/structure with 10 runbooks and 4 rules - deterministic gates — a prod-DB PreToolUse hook and a tenant-isolation CI check that enforce policy in code, whether or not the agent reads a runbook
- maintainer runbooks (merge gate, handoff, dev workflow)
- operator truth/evidence contract for agent honesty, blocker escalation, and receipts-backed completion
- DevOps automation runbooks (patrol loops, PR workflow, incident response, daily digest, changelog)
- slice registry and journal conventions
- PR and issue templates
- CI intake checks
- scripts:
check-handoff.mjs,check-pr-intake.mjs,check-ci-health.sh,send-pr-email.sh,send-escalation-email.sh, gate engines + hook installer - a task prompt footer for agent tasks and threadmaster handoffs
- greenfield and brownfield adoption playbooks
- an installer that stamps the blueprint into a target repo from a simple manifest
maintainer-gate-blueprint/
├── bin/
│ └── apply-blueprint.mjs
├── examples/
│ └── project.manifest.json
├── playbooks/
│ ├── greenfield-adoption.md
│ └── brownfield-adoption.md
├── prompts/
│ └── task-footer.md
├── templates/
│ ├── .github/
│ │ ├── workflows/ci.yml
│ │ ├── pull_request_template.md
│ │ └── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml
│ │ └── feature_request.yml
│ ├── ops/
│ │ ├── README.md
│ │ ├── runbooks/
│ │ │ ├── patrol.md # Bug + Feature patrol loops
│ │ │ ├── pr-workflow.md # PR + quality gates + email
│ │ │ ├── incident-response.md # Site down? Start here
│ │ │ ├── daily-digest.md # Morning summary report
│ │ │ ├── loop-contract.md # Phase 0 sync for all loops
│ │ │ ├── changelog.md # Version management
│ │ │ ├── dev-workflow.md # Day-to-day development + release lane
│ │ │ ├── gates.md # Deterministic enforcement gates
│ │ │ ├── maintainer-gate.md # Merge validation
│ │ │ └── threadmaster-handoff.md # Handoff packets
│ │ ├── gates/
│ │ │ └── gates.config.json # Gate policy (stamped from manifest)
│ │ ├── rules/
│ │ │ ├── agent-coordination.md # Claim → work → sync
│ │ │ ├── branching.md
│ │ │ ├── never-do.md
│ │ │ └── operator-truth-and-evidence.md
│ │ ├── projects/
│ │ │ └── ACTIVE.md
│ │ ├── handoffs/ # Threadmaster handoff packets land here
│ │ ├── slices/
│ │ └── log/
│ └── scripts/
├── package.json
└── README.md
- Copy a project manifest from
examples/project.manifest.json. - Fill in repo-specific paths, branch names, role names, and CI commands.
- Run the installer to stamp the templates into the target repo.
- Review the generated files and tighten any project-specific rules.
- Roll the stricter gates out in phases if the repo is brownfield.
The blueprint enforces a few non-negotiable ideas:
- Use commit/file truth, not branch-name truth.
- Do not merge directly from an implementation slice to
main. - Reconstruct changes in a clean dev/release lane first.
- Require operator or human validation before promotion.
- If work spans multiple repos, use separate slices and separate handoff packets.
This blueprint is meant for:
- maintainers managing multiple AI agent sessions
- teams using Codex, Claude Code, or similar autonomous contributors
- repos with release-sensitive install, runtime, infra, or docs surfaces
- projects that need stronger merge hygiene without inventing process from scratch
cp examples/project.manifest.json /tmp/my-project-blueprint.json
# edit the manifest
node bin/apply-blueprint.mjs /tmp/my-project-blueprint.jsonPoint any AI agent (Claude Code, Codex, etc.) at this repo and give it this instruction:
Apply the Maintainer Gate Blueprint from
/path/to/Maintainer-Gate-Blueprintto this repo. Readplaybooks/ai-agent-setup.mdfor the full step-by-step process, then create a manifest and run the installer.
The agent setup guide covers:
- How to auto-detect manifest values from the target repo
- Greenfield vs brownfield adoption path selection
- Post-install verification and customization
- Patrol loop setup for multi-machine automation
- Branch protection configuration
See playbooks/ai-agent-setup.md for the complete instructions.
The installer replaces {{PLACEHOLDER}} tokens in template files using the
manifest JSON values.
| Token | Purpose | Example |
|---|---|---|
PROJECT_NAME |
Display name | "MyProject" |
REPO_NAME |
Repository identifier | "my-project" |
REPO_ROOT_PATH |
Absolute path to repo | "/Users/you/code/my-project" |
DOCS_REPO_PATH |
Path to docs repo | "/Users/you/code/my-project-docs" |
DOCS_SITE_URL |
Public docs URL | "https://docs.myproject.io" |
ISSUE_TRACKER_NAME |
Issue tracking system | "Linear" |
ISSUE_TRACKER_NOTE |
Custom integration note | "Check before significant work..." |
THREADMASTER_ROLE |
Release/merge owner | "Threadmaster" |
OPERATOR_ROLE |
Validation/approval role | "operator" |
DEV_BRANCH |
Integration branch | "develop" |
MAIN_BRANCH |
Production branch | "main" |
| Token | Purpose | Example |
|---|---|---|
DEV_WORKSPACE_PATH |
Active dev workspace | "/Users/you/code/my-project" |
DEVELOP_CLEAN_PATH |
Clean integration workspace | "/Users/you/code/my-project-develop-clean" |
TRUNK_CLEAN_PATH |
Clean trunk workspace | "/Users/you/code/my-project-main-clean" |
| Token | Purpose | Example |
|---|---|---|
PACKAGE_MANAGER_INSTALL_COMMAND |
Install deps | "npm install" |
CI_BUILD_COMMAND |
Build command | "npm run build" |
CI_CHECK_COMMAND |
Lint/check | "npm run lint" |
CI_TEST_COMMAND |
Test command | "npm test" |
CI_PROTOCOL_COMMAND |
Schema validation | "npm run check:types" |
CI_DASHBOARD_COMMAND |
Dashboard build | "npm run build:dashboard" |
RUNTIME_VERSION |
Node/runtime version | "22.x" |
| Token | Purpose | Example |
|---|---|---|
GH_ORG |
GitHub organization | "my-org" |
SITE_URL |
Production site URL | "https://myproject.io" |
NOTIFICATION_EMAIL |
Alert/PR email recipient | "owner@example.com" |
AUTOMATION_MAC_NAME |
Bug Patrol machine name | "Automation Mac" |
AUTOMATION_MAC_SESSION |
Bug Patrol tmux session | "patrol" |
PRIMARY_MAC_NAME |
Feature Patrol machine name | "Primary Mac" |
PRIMARY_MAC_SESSION |
Feature Patrol tmux session | "dev" |
Policy for the gate engines (see templates/ops/runbooks/gates.md), stamped
into ops/gates/gates.config.json:
| Token | Purpose | Example |
|---|---|---|
GATE_PROD_DB_HOST_PATTERNS |
Hosts treated as production | "prod,railway.app" |
GATE_DESTRUCTIVE_DB_PATTERNS |
Commands the prod-DB hook blocks | "prisma db push,--accept-data-loss" |
GATE_PROD_DB_BLOCK_ON_UNKNOWN |
Fail closed when prod-ness unknown | "false" |
GATE_TENANT_SCOPE_KEY |
Tenant scope column | "organizationId" |
GATE_TENANT_SCAN_GLOBS |
Directories the CI gate scans | "app/api,lib/services" |
GATE_TENANT_ALLOWLIST_GLOBS |
Intentionally-global paths | "app/api/auth,app/api/admin" |
GATE_TENANT_MODE |
report or fail |
"report" |
The installer writes:
ops/— operational hub with 10 runbooks, 4 rules, gate policy, tracking docs.github/— PR template, issue templates, CI workflowscripts/—check-handoff.mjs,check-pr-intake.mjs
It does not overwrite files outside the blueprint surface.
| Category | Runbooks | Purpose |
|---|---|---|
| Automation | patrol, loop-contract, daily-digest | Continuous monitoring loops |
| Quality | pr-workflow, maintainer-gate, changelog | PR gates, merge validation, versioning |
| Enforcement | gates (+ scripts/gate-*.mjs) |
Deterministic prod-DB and tenant-isolation gates |
| Operations | dev-workflow | Day-to-day development and release lane |
| Incident | incident-response | Outage triage |
| Handoff | threadmaster-handoff | Machine-checkable handoff packets |
| Coordination & Trust | rules: agent-coordination, operator-truth-and-evidence | Claim/sync discipline, evidence-backed reporting |
The blueprint governs the repo: how work flows from an agent's branch to
main. Proctor governs the
session: it makes an agent's "done" a verified fact instead of a claim, by
reading what the agent's tools actually did and blocking session end until the
contract's checks pass.
They enforce the same doctrine at two altitudes. The blueprint's
ops/rules/operator-truth-and-evidence.md is the prose contract — receipts,
no silent workarounds, no pseudocode-as-done. Proctor is the harness that
enforces that contract mechanically, the way the blueprint's deterministic
gates enforce prod-DB and tenant-isolation policy. Run both and every layer of
the failure mode is covered: the session can't end on a false claim (Proctor),
the paperwork can't lie (intake checks), and the dangerous commands can't run
(gates).
There is no code coupling — install each independently.
- For greenfield repos, apply the full blueprint early.
- For brownfield repos, use
playbooks/brownfield-adoption.mdand phase the rollout so CI and branch protection do not freeze delivery.
See:
playbooks/greenfield-adoption.mdplaybooks/brownfield-adoption.md
Use the prompt footer in prompts/task-footer.md when instructing agents. It
covers everyday tasks, research/planning-only requests, and threadmaster
handoffs in one footer.
After applying the blueprint in a target repo:
- run the generated handoff checker against a sample packet
- run the PR intake checker against a sample event payload
- confirm the repo-specific CI commands in
.github/workflows/ci.yml - wire the required checks into branch protection
This blueprint is intentionally opinionated about merge safety.
It is not a release manager by itself. It creates the process surface so a maintainer or Threadmaster can safely intake, reconstruct, validate, and promote work.
Maintainer Gate Blueprint is a Frontier Infra project — the repo-governance tier of an open stack for the agent web (declare: AVL · prove: AAR · behave: ADL + Proctor · operate: The Machine). Built from real maintainer workflow hardening in a multi-agent production codebase, with early sponsorship from ArgentOS.
MIT