A Workshop 42 tool

Guardrails
for AI-built code.

Config-driven checks that stop coding agents from padding, weakening or bypassing your tests, docs and architecture.

npm i -D @ws42ca/guardrails

⚠ TEST-5W Weak assertions (heuristic) (1)
    test/receipt.test.ts:4  "ORDER-01 formats the receipt total":
    only tautological assertions (toBeTruthy).
    Assert the exact value.
    fix: Assert on the observable result (returned value,
         written data, response status).
✖ TEST-7 No test weakening (1)
    test/receipt.test.ts:4  "ORDER-01 formats the receipt total"
    lost 1 expect() call(s). Restore them.
    fix: Restore the test/assertion/threshold. Deleting
         base-branch tests needs the tests-removed-approved
         label from a code owner.
FAIL: 1 blocking, 1 warnings, 0 known (diff vs main)
Real output, wrapped to fit: an agent swapped an exact assertion for toBeTruthy to get a green build. Guardrails blocks the pull request.

Agents optimise
for green.

Left alone, a coding agent will delete the failing test, loosen an assertion, special-case the expected value, add a package that does not exist or write a new doc for every task. Guardrails blocks those shortcuts in CI and inside the agent’s own editor.

What it checks.

49 rules. One config file per project.

Tests

Honest tests

Every test maps to a spec ID, risky specs must have a test and every test must assert something. Deleting tests, removing expects and loosening matchers is blocked on pull requests, and new tests must fail on the base branch.

Anti-cheating

No test-gaming

Product code that detects the test runner, exits early, overloads equality or hard-codes expected values is blocked. Agents stop and flag a conflict instead of bending a test, and a human has to answer before merge.

Architecture

Boundaries that hold

Declared import boundaries, production reachability, duplication on new code, restricted strings and no fixtures in production code. Existing violations go in a baseline that can only shrink.

Supply chain

Real dependencies only

New packages must exist on the npm registry, be old enough and downloaded enough, and carry no high or critical advisory. That catches package names an agent made up.

Hooks

Locked inside the editor

Hooks for Claude Code, Gemini CLI, Antigravity and Codex deny edits to the config, the baseline, CI files and spec-tagged tests, so the rules are not one edit away from off.

Journeys

Tests tied to real tasks

Critical user journeys are plain-language tasks a human approves. Approved journeys need an end-to-end test, and the CLI can generate and run those tests with Playwright.

  • 49 rules
  • 4 agent hosts
  • 1 config file
  • MIT licence

Quick start.

Node 20 or newer.

Install it as a dev dependency, scaffold the files, record the baseline and run the checks. init never overwrites an existing file unless you pass --force.

It writes guardrails.config.json, AGENTS.md with one-line CLAUDE.md and GEMINI.md pointers, CODEOWNERS, a starter GitHub Actions workflow and the agent hook and MCP files.

Full CLI reference on npm ↗

Install and first run
npm i -D @ws42ca/guardrails

# scaffold config, AGENTS.md, CODEOWNERS, CI workflow and agent hooks
npx guardrails init --owner @your-github-handle --base main

# record today's violations; the baseline can only shrink from here
npx guardrails baseline

# run the checks (exit code 1 means a blocking finding)
npx guardrails check

# on a branch, also run the diff rules
npx guardrails check --base origin/main --fails-on-base

One config file

Describe the behaviours you promise (specs), how strict each part of the code is (tiers) and which layers may not touch. Unknown keys are an error, so a typo cannot quietly turn a rule off.

guardrails.config.json
{
  "version": 1,
  "baseBranch": "main",
  "sourceRoots": ["src"],
  "tiers": {
    "T1": ["src/payments/**"],
    "T3": ["src/**"]
  },
  "specs": {
    "items": {
      "ORDER-01": {
        "tier": "T1",
        "behaviour": "A paid order sends a receipt email"
      }
    }
  },
  "architecture": {
    "entries": ["src/main.ts"],
    "forbidden": [
      { "name": "ui-not-db", "from": ["src/ui/**"], "to": ["src/db/**"],
        "message": "Go through the service layer" }
    ]
  }
}

Journeys, not just tests.

Critical user journeys (CUJs).

A journey is a short, plain-language task a real visitor does, such as “sends an enquiry through the contact form and sees a confirmation”. Unit tests can all pass while that form is broken.

  • Humans own them. Agents can draft journeys, but only a person approves one.
  • Approved journeys gate. An approved P0 journey needs exactly one end-to-end test titled with its ID.
  • Executable. A declarative run list becomes Playwright tests you can run against a local preview, a staging site or production.
  • Safe by default. Steps time out after 10 seconds, and requests other than GET and HEAD are aborted unless you mock them.
guardrails.config.json (journeys)
{
  "journeys": {
    "items": {
      "CUJ-CHECKOUT": {
        "title": "Visitor buys a product and sees a confirmation",
        "priority": "P0",
        "steps": [
          "Open the shop", "Add an item", "Pay", "See the confirmation"
        ],
        "specs": ["ORDER-01"],
        "routes": ["/shop"],
        "run": [
          { "goto": "/shop" },
          { "click": { "role": "button", "name": "Add to cart" } },
          { "expectText": "Order confirmed" }
        ]
      }
    }
  }
}
Approve, generate, run
# a human approves; agents can only draft
npx guardrails journeys approve CUJ-CHECKOUT

# turn journeys into Playwright tests and run them
npx guardrails journeys scaffold
npx guardrails journeys generate-tests
npx guardrails journeys run --base-url http://localhost:4321

In CI.

The same checks, with the base branch.

Run the checks on every pull request with the base branch so the diff rules apply: no test weakening, new tests fail on base and new dependencies are verified. The job writes a Markdown report to the run summary.

  • Pull request labels such as guardrails:tests-removed-approved, guardrails:journeys-approved and guardrails:config-approved let a code owner approve a specific exception.
  • Mutation testing with Stryker is opt in and runs on the files you changed.
  • Change-scoped runs with guardrails affected keep pull requests fast.
.github/workflows/guardrails.yml
name: Guardrails
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  push:
    branches: [main]

jobs:
  guardrails:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - name: guardrails
        env:
          GUARDRAILS_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
        run: |
          ARGS=""
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            ARGS="--base origin/${{ github.base_ref }} --fails-on-base"
          fi
          npx guardrails report --format markdown $ARGS >> "$GITHUB_STEP_SUMMARY" || true
          npx guardrails check $ARGS

Built for agents.

Hooks, an MCP server and a skill.

The MCP server lets an agent list specs, validate a test before writing it, run the checks, see surviving mutants and flag a conflict. It can read journeys but has no tool to approve one.

It works with Claude Code, Gemini CLI, Antigravity and Codex. A skill file in the package tells an agent how to work under the rules.

Claude Code
claude mcp add guardrails --scope project -- \
  npx -y -p @ws42ca/guardrails guardrails-mcp
Gemini CLI, Antigravity: MCP config
{
  "mcpServers": {
    "guardrails": {
      "command": "npx",
      "args": ["-y", "-p", "@ws42ca/guardrails", "guardrails-mcp"],
      "cwd": "."
    }
  }
}
Codex: .codex/config.toml
[mcp_servers.guardrails]
command = "npx"
args = ["--no-install", "guardrails-mcp"]

[shell_environment_policy.set]
GUARDRAILS_AGENT = "codex"

Try it on your next agent branch.

MIT licensed · Node 20+ · npm package @ws42ca/guardrails