Wardens — admin

The CLI is bin/warden.mjs at the plugin root, two directories above this skill's base directory. It's one file with no dependencies and needs Node 18+. Below, warden means node <plugin-root>/bin/warden.mjs.

Where things live

Authority (what the hooks enforce) is only ever in wardens.yaml. Agent files hold prose for the model.

Commands

.claude/wardens.yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/tylerjrbuell/wardens/main/schema/wardens.schema.json
version: 1
mode: warn                      # enforce | warn
# confidence-floor: 0.7         # reports at/above this need `verification`
# ownership-file: tools/ownership.json   # read owned globs from an existing [{glob, owner}] map
never-run:                      # added to the built-ins (git commit/push/tag/rebase, git stash/clean/reset --hard/restore, *publish)
  - terraform apply
# always-run: []                # added to the built-in read-only commands
# ledger: .wardens/ledger.jsonl
# agent-dirs: [.claude/agents]

wardens:                        # keep this section last so `warden new` can append to it
  payments-warden:
    kind: domain                # domain: owns code | specialist: writes only its own reports
    owns:
      - services/payments/**
    run:                        # prefix-matched per shell segment; omit to guard only never-run; ["*"] = anything not in never-run
      - npm test -- services/payments
    expires: 2027-01-31         # optional pilot window
  debrief-scribe:               # bundled agents: override only the keys you need
    owns:
      - docs/debriefs/**

• Bundled agents (debrief-scribe, evidence-warden) are wardens out of the box, with defaults built into the CLI (debrief-scribe owns docs/debriefs/**, evidence-warden owns docs/evidence/**). Declaring them here overrides key by key.
• ownership-file keeps an existing path → owner map as the single source: a warden's authority is its owns plus every glob the map assigns to it, and owner: null rows stay unowned.
• Problems don't disable the guard. An invalid key is reported by doctor, and the rest of the file still loads.

Adopting in a repo

1. Install the plugin (see README) and run warden init. You start in warn mode: the hooks record what they would deny, and block nothing.
2. Map ownership. Pick the 2–4 areas where mistakes are costly and the context isn't obvious: invariants, past incidents, quirks. Don't give a warden a directory that the main thread handles fine on its own.
3. warden new for each, or copy the closest tested example from examples/ at the plugin root. Write each domain primer with things that are true but not obvious from the code: invariants, failure history with anchors, and "never X because Y". Keep it under ~80 lines. doctor checks anchors (path/file.ts:123), so a stale primer fails CI instead of quietly misleading the warden.
4. Commit .claude/wardens.yaml and .claude/agents/. Add warden doctor to CI.
5. After a week, read warden team and warden stats, resize owns/run where the guard denied legitimate work, then set mode: enforce.

Reading the numbers