nodrail

Playbooks

Preview. Playbooks need @nodrail/cli 0.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, under imports. An import is a catalog module, such as @nodrail/open-reviewed-pr, with its values under with:, or a .yaml file in your repository. A local file is either an ordinary APF rules file or another manifest with its own imports.
  • nodrail.lock.yaml, the lock. nodrail writes 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.yaml is 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 nodrail has.

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.

LabelMeaning
grantedAn allow that wasn't there: the agent may now do this.
revokedAn allow removed: the agent may no longer do this.
tightenedLess is allowed: a deny or a gate added, or an allow narrowed.
loosenedMore is allowed: a deny or a gate removed, or an allow widened.
changedIt changed, but not simply more or less, such as a mix of both.
needs reviewThe 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

ModuleWhat it doesValues
@nodrail/open-reviewed-prA 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-prA separate merger agent may merge only after QA, the checks and a review pass on the current head.repository
@nodrail/triage-issuesA triage agent may read issues, comment and label. It can't close, assign, edit code or open pull requests.repository
@nodrail/dependency-updatesA 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-onlyThe 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

KindWhat it declares
AgentOne 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.
TeamThe agents that work together, the entry agent a session starts as, and the handoffs: who may start whom.
PolicyA rules file of your own, spec: { source: ./policies/x.yaml }. It does nothing until a binding names it.
PolicyBindingWhich 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-pr and @nodrail/merge-reviewed-pr also name dev, 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.yaml and nodrail.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, lock and export change 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, merger or triage are 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. The repo-work starter pack protects the first two; nodrail policy lock compares 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.