Playbooks
Preview. Playbooks need
@nodrail/cli0.1.0 or later. Modules with gates need APF engine feature level 3: see Runs, gates and budgets (preview).
A playbook is a policy for one way of working, packaged so a repository can add it by name: "a publisher agent may open a draft pull request once QA and review passed", or "a triage agent may label issues and nothing else". You add it with nodrail, give it your values, review what it permits, and commit the result. Your agents follow it once you activate an export of it.
Everything on this page works offline, with no account. It needs the nodrail command line.
npm i -g @nodrail/cli
Projects, modules and the lock
A repository's policy is described by two files at its root. Commit both.
nodrail.yaml, the manifest. It lists what the policy is made of, in order, underimports. An import is a catalog module, such as@nodrail/open-reviewed-pr, with its values underwith:, or a.yamlfile in your repository. A local file is either an ordinary APF rules file or another manifest with its ownimports.nodrail.lock.yaml, the lock.nodrailwrites it. It records the exact version of each catalog module, the SHA-256 of every file, the values each module was given, the import graph and order, the digest of the effective policy, and the effective policy last reviewed.
A module is a set of APF files with a name and a version, plus the values it needs, such as your repository. The catalog of modules ships inside @nodrail/cli, so adding one downloads nothing.
kind: nodrail.project/v1
imports:
- ref: "@nodrail/open-reviewed-pr"
with:
repository: acme/widgets
- ref: ./policies/team.yaml
The effective policy is every imported file compiled together, in order, into one APF file. That file is what an agent's hook or adapter reads.
Quickstart
This adds @nodrail/open-reviewed-pr to a repository. Run each command at the repository's root.
1. Add the module.
nodrail add @nodrail/open-reviewed-pr
Added @nodrail/open-reviewed-pr@1.0.0
Changed: nodrail.yaml, nodrail.lock.yaml
@nodrail/open-reviewed-pr: configuration required. Set with.repository in nodrail.yaml.
Permissions: pending until every module has its values.
The module is in nodrail.yaml but not in effect: it needs a value. add lists its rules below this, so you can read them first.
2. Give it your repository. In nodrail.yaml, set the value as owner/name:
with:
repository: acme/widgets
3. Lock and review.
nodrail policy lock
Updated nodrail.lock.yaml
Permissions:
3 permission changes.
Agent github
github.pr.merge
repository (any)
tightened rule no-merge "Keep merge outside the publisher role": added (deny)
github.pr.open
repository exact "acme/widgets"
granted rule open-draft "Open a reviewed draft": added (allow)
where draft eq true
where targetScope eq "candidate"
tightened gate reviewed-draft "Require QA, checks and review on the candidate": added: deny until qa: pass since dev; gatekeeper: pass since dev; reviewer: ship since dev
Effective policy:
…
Read the permissions first, then the lines of the effective policy that changed. See Reading the review.
4. Commit both files.
git add nodrail.yaml nodrail.lock.yaml
git commit -m "Let the publisher open reviewed draft pull requests"
Reviewers see the same change in the pull request: the manifest, and the lock with the reviewed policy in it.
5. Export.
nodrail policy export --frozen > effective.apf.yaml
The export is one ordinary APF file. Check it like any other with nodrail policy validate effective.apf.yaml.
6. Activate it. Until now nothing governs an agent. Adding a module installs no hook and runs nothing. Agents follow the policy once you point an enforcement point at the export. See Activate an export.
What the lock checks
nodrail policy export --frozen reads only what was locked. Before it prints anything it checks, offline:
nodrail.yamlis the file that was locked;- each local file has the hash the lock recorded, and nothing was added to or dropped from the imports;
- each catalog module is the locked version, and every one of its files has the locked hash;
- every module has its values;
- the import order and the effective policy are the ones locked;
- the lock wasn't made by a newer engine level than this
nodrailhas.
When anything differs, it prints nothing on stdout, gives the reason on stderr and exits with 1:
nodrail: policies/team.yaml changed since it was locked. Run `nodrail policy lock` to review it.
So an export always matches the policy someone reviewed and committed. To change the policy, edit the files, run nodrail policy lock, read the review and commit again.
Versions
nodrail add @nodrail/open-reviewed-pr takes the catalog's version. nodrail add @nodrail/open-reviewed-pr@1.0.0 asks for that exact version; a version the catalog doesn't have is refused, and nothing changes. Once locked, a module stays at its version.
If a module's files at the locked version don't match the hashes in the lock, lock and export --frozen both stop:
nodrail: @nodrail/open-reviewed-pr@1.0.0 doesn't match nodrail.lock.yaml (policies/open.yaml). The installed package was changed; reinstall nodrail, or ask for another version with `nodrail add @nodrail/open-reviewed-pr@<version>`.
That is an error, never an update. The same version must always mean the same files.
Reading the review
nodrail add and nodrail policy lock print what the change does to permissions since the policy last reviewed, grouped by agent, then operation, then resource. Each change has one label.
| Label | Meaning |
|---|---|
granted | An allow that wasn't there: the agent may now do this. |
revoked | An allow removed: the agent may no longer do this. |
tightened | Less is allowed: a deny or a gate added, or an allow narrowed. |
loosened | More is allowed: a deny or a gate removed, or an allow widened. |
changed | It changed, but not simply more or less, such as a mix of both. |
needs review | The tool can't tell whether it is more or less. Read both versions. |
A ! before the label marks a change that weakens a deny or a gate, and the count at the top says how many there are. Read those first.
3 permission changes, 1 marked ! weaken a deny, a gate or a budget.
…
! loosened gate review-first "Review first": …
After the permissions, Effective policy: shows the lines of the exported file that changed, with + and -.
Use it in CI
Pin the nodrail version you lock with, and build the export from the committed files only. A shell redirect empties the target file before nodrail runs, so export to a temporary file and replace the deployed file only on success:
set -e
nodrail policy export --frozen > effective.apf.yaml.tmp
nodrail policy validate effective.apf.yaml.tmp
mv effective.apf.yaml.tmp effective.apf.yaml
A pull request that changes nodrail.yaml or a local file without running nodrail policy lock fails here, with the reason. To check expected decisions too, run nodrail policy test against the export with a cases file.
The catalog
| Module | What it does | Values |
|---|---|---|
@nodrail/open-reviewed-pr | A publisher agent (github) may open draft pull requests after QA, a gatekeeper and a reviewer accept the current candidate. Merging stays denied. Also named @nodrail/pr_policy.yaml. | repository |
@nodrail/merge-reviewed-pr | A separate merger agent may merge only after QA, the checks and a review pass on the current head. | repository |
@nodrail/triage-issues | A triage agent may read issues, comment and label. It can't close, assign, edit code or open pull requests. | repository |
@nodrail/dependency-updates | A deps agent may write lockfiles and refresh them with scripts off. Changes to package.json, commits and pushes wait for a person. It may open a draft pull request after the checks pass, and can't merge or force-push. | repository |
@nodrail/read-only | The read-only starter pack as a module. | None |
repository is one exact repository, as owner/name. A wildcard or a path is refused.
A module that has values to give is reported as configuration required until it has them, and export --frozen refuses until then.
Compose with your own files
Add your own rules files next to modules:
nodrail add ./policies/team.yaml
Imports compile in the order nodrail.yaml lists them, and add appends to the end. Order matters in one way only: a later file can change an entry from an earlier file with override. It doesn't change precedence. Deny still wins over review, and review over allow, whatever the order.
Names must be unique across every imported file. Redefining a module's rule or gate without override is an error, so a local file can't quietly weaken it.
Example: one more reviewer
To make @nodrail/open-reviewed-pr also wait for a security agent, save this as policies/security.yaml:
# Opening also waits for a security review of the same candidate.
- required_engine_version: 3
- gate: Require QA, checks and review on the candidate
requires:
- { agent: security, verdict: pass, since: [dev] }
override: { requires: append }
The gate's name is the module's own. override: { requires: append } adds the requirement to the module's three. Add the file after the module and review the change:
nodrail add ./policies/security.yaml
Added ./policies/security.yaml
Changed: nodrail.yaml, nodrail.lock.yaml
Permissions:
1 permission change.
Agent github
github.pr.open
repository exact "acme/widgets"
needs review gate reviewed-draft "Require QA, checks and review on the candidate": requires security: pass since dev
security's commands no longer count as changing the work for the other requirements
The same override can replace a field, such as otherwise, or append to a rule's condition or tags. A replacement can weaken a module's deny or gate: the review marks it !. See Layering files for every form.
Give the roles to your agents (preview)
A module's rules name roles, such as github or qa, not your agents. To run a playbook with your own agents, declare them as resources and bind the module's roles to them. nodrail.yaml points at the resources:
kind: nodrail.project/v1
runtime: claude-code
resources: ./resources
imports:
- ref: "@nodrail/open-reviewed-pr"
with:
repository: acme/widgets
resources is a file, a folder of .yaml files, or a list of both. Each document in them is one resource:
apiVersion: apf.nodrail.com/v1alpha1
kind: Agent
metadata: { name: publisher }
spec:
description: Opens the draft pull request once the candidate is checked.
instructions: ./agents/publisher.md
skills: [./skills/release-notes]
---
apiVersion: apf.nodrail.com/v1alpha1
kind: Team
metadata: { name: release }
spec:
entry: lead
members: [lead, publisher, tester, gate, critic, builder]
handoffs:
- { from: lead, to: publisher }
---
apiVersion: apf.nodrail.com/v1alpha1
kind: PolicyBinding
metadata: { name: open-prs }
spec:
policy: "@nodrail/open-reviewed-pr"
roles:
github: publisher
qa: tester
gatekeeper: gate
reviewer: critic
dev: builder
| Kind | What it declares |
|---|---|
Agent | One agent: its name, description, instructions (a Markdown file), skills (folders with a SKILL.md) and model. Paths start with ./ and are read from the resource's file. |
Team | The agents that work together, the entry agent a session starts as, and the handoffs: who may start whom. |
Policy | A rules file of your own, spec: { source: ./policies/x.yaml }. It does nothing until a binding names it. |
PolicyBinding | Which agent plays each role a module or Policy names. |
A binding renames the roles everywhere the policy names an agent: a rule's agent, a gate's requires and since, a budget's step_agent, and a kind: agent resource, such as which agents a role may start. The lock covers the resource files like any other, so a changed binding stops export --frozen until it is reviewed and locked again.
lock refuses a binding when:
- the policy names an agent that no role maps and no team member is called.
@nodrail/open-reviewed-prand@nodrail/merge-reviewed-pralso namedev, the agent whose later work resets the checkers' verdicts; map it too. - a role it maps is one the policy never names, which is usually a typo.
- two roles go to one agent, which would let that agent vouch for its own work.
- a role goes to an agent that isn't on the team.
The team adds rules of its own to the effective policy, after everything else:
- each member may start the members it hands off to, and no other member, itself included. The team's handoffs are the only way work moves between its agents. Agents that aren't on the team, such as a host's built-in ones, are left to the rest of the policy.
- no agent may write, edit, patch or delete the setup:
.claude,.codex,.agents,.nodrail,nodrail.yamlandnodrail.lock.yaml. An agent that could rewrite an agent definition could make itself that agent.
Both are denies, and deny wins, so no other file can widen them.
runtime (claude-code or codex) and start are for setting up the host. nodrail plan shows what would be set up, without changing anything, and nodrail apply sets it up. Claude Code only, for now. Only the root nodrail.yaml may declare them, and a module nobody binds compiles exactly as before.
Activate an export
Agents follow a playbook only through an enforcement point that reads the export. Which one depends on the calls the playbook covers.
File and shell rules work with the local Claude Code hook today. That covers @nodrail/read-only and the file part of @nodrail/dependency-updates. Point the hook from Try APF locally at the export:
nodrail policy hook effective.apf.yaml
nodrail-policy hook effective.apf.yaml does the same. The hook blocks any call no rule covers, so the export needs rules for every shell and file call your agent makes. Import those with the module, such as your own rules file or @nodrail/read-only, rather than loading a second file next to the export.
GitHub rules describe calls with tool github, operations such as pr.open, pr.merge or issues.comment, and resource kind repository with the id owner/name, as in the APF guide. They take effect only where an adapter maps your agents' GitHub calls to those names and supplies the run evidence the gates need: which candidate or head is being acted on, and the verdicts of QA, the checks and review for it. The local Claude Code hook doesn't map GitHub calls. An agent's own GitHub credentials don't go through these rules at all, so the merge and triage modules deny those agents the shell, where gh and git push would run. See Runs, gates and budgets (preview) for the evidence a gate reads.
Limits
- Nothing runs until you activate an export.
add,lockandexportchange files and print text. They install no hook and govern no agent. - A module is only as good as its enforcement point. A GitHub module's guarantees cover the calls that go through a trusted adapter, with evidence that adapter supplies. Calls that bypass it aren't seen.
- Agent names are reported, not authenticated.
github,mergerortriageare the names your integration gives the caller. Read the security model before relying on them. - Gates need engine level 3, which is a preview. Receipts are self-reported: a gate proves a step reported a verdict, not that the work was good.
- With the local hook, checkers vouch for themselves. The hook judges a subagent's call as the subagent Claude Code or Codex says made it, and the session's other calls as its
--agent. A verdict, though, is whatever the checker's last message said. The modules stop the gated roles (github,merger,deps) from starting their own checkers, but a guarantee that QA, the checks and review really ran on the candidate needs an adapter that collects that evidence on the host, outside the agent's reach. - Protect the policy itself. Agents shouldn't be able to edit
nodrail.yaml,nodrail.lock.yaml, the files they import, the resources and the agent definitions they set up, or the exported policy. Therepo-workstarter pack protects the first two;nodrail policy lockcompares with the lock as last committed in git, so a change an agent made and locked shows up in the review. - The lock covers files, not people. It proves the export matches what was committed. Who may change
nodrail.yaml, the lock and the deployed export is up to your repository's review rules. Keep them out of the agent's reach. - The catalog comes with
nodrail. The modules you can add are the ones bundled in your installed version. There is no registry, and nothing is downloaded.