Skip to content

Installation

Set up campaigns once you have Architecture Rules installed. A campaign lives in the same architecture.yaml.

Terminal window
pnpm add -D @goodbones/cli # required: check, the ledger commands, the nudge
pnpm add -D @goodbones/oxlint # optional: flags new holdouts in the editor

Both include @goodbones/campaigns and the syntax matcher.

.oxlintrc.json
{
"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.

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.

Terminal window
pnpm exec architecture objectives clear # record every place each objective fires today
pnpm exec architecture check # from now on, the count may only go down

objectives 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/billing

The nudge only appears where something runs it:

  • Before an agent finishes. A stop hook, or a line in CLAUDE.md / AGENTS.md, runs architecture campaigns status --changed --json. It exits non-zero on any verdict other than ok or hotfix, so a hook can block on the exit code.
  • In CI. Run it against the base branch, and check to hold every ledger:
Terminal window
pnpm exec architecture check
pnpm exec architecture campaigns status --changed --base origin/main

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.