Installation
Set up campaigns once you have Architecture Rules
installed. A campaign lives in
the same architecture.yaml.
Install
Section titled “Install”pnpm add -D @goodbones/cli # required: check, the ledger commands, the nudgepnpm add -D @goodbones/oxlint # optional: flags new holdouts in the editorBoth include @goodbones/campaigns and the syntax matcher.
Enable the editor rule
Section titled “Enable the editor rule”{ "jsPlugins": [{ "name": "architecture", "specifier": "@goodbones/oxlint" }], "rules": { "architecture/campaigns": "error" }}The rule reports a holdout the ledger does not already record. It stays quiet about recorded ones.
Write a campaign and its first ledger
Section titled “Write a campaign and its first ledger”Add a campaigns key to architecture.yaml. Start from the
smallest campaign.
Every match objective needs a probe it fires on, or the policy refuses to load.
pnpm exec architecture objectives clear # record every place each objective fires todaypnpm exec architecture check # from now on, the count may only go downobjectives clear writes one JSON file per objective under .architecture-campaigns/ (the
manifest’s ledger key moves it). Commit that directory. Until it exists, check fails
and names the command to run.
To route ledger changes to the campaign’s owner:
# CODEOWNERS.architecture-campaigns/billing-ddd/ @your-org/billingRun the nudge
Section titled “Run the nudge”The nudge only appears where something runs it:
- Before an agent finishes. A stop hook, or a line in
CLAUDE.md/AGENTS.md, runsarchitecture campaigns status --changed --json. It exits non-zero on any verdict other thanokorhotfix, so a hook can block on the exit code. - In CI. Run it against the base branch, and
checkto hold every ledger:
pnpm exec architecture checkpnpm exec architecture campaigns status --changed --base origin/mainEmbed the loader
Section titled “Embed the loader”Skip this unless you call loadPolicy yourself instead of using the CLI or plugin. Pass the
campaigns extension, then read its state back:
import { campaignsExtension, campaignsOf } from "@goodbones/campaigns";import { loadPolicy } from "@goodbones/core";
const policy = loadPolicy({ // … extensions: [campaignsExtension({ functions, reports })],});
const { campaignRules, ledgers } = campaignsOf(policy);Without the extension, the campaigns and ledger keys are refused as unknown. A campaign
whose scope covers a language with no syntax matcher is refused at load.