Guardrails reference

Guardrails are quality gates that every agent must pass before creating a PR. They are defined as YAML files in .cate/guardrails/ and configured through the Guardrail command during setup. Re-run the Guardrail command at any time to add, change, or remove gates.

File format

Each guardrail category gets its own YAML file at .cate/guardrails/<category>.yml:

name: testing
required: true
description: 'Unit and integration tests must pass'

gates:
  - name: 'unit-tests'
    command: 'npm test'
    pass-condition: 'exit-code-zero'
    description: 'Run the full test suite'
    run: 'before-pr'

Fields

Top-level

Field	Type	Description
name	string	Category name
required	boolean	If true, all gates in this category must pass before a PR is created. If false, failures are reported but don’t block the PR.
description	string	What this category checks

Gate fields

Field	Type	Description
name	string	Gate name, used in reporting and error messages
command	string	Shell command to run
pass-condition	string	How to determine success. Currently only "exit-code-zero".
description	string	What this specific gate checks
run	string	When to run: "before-pr", "before-commit", or "in-review"

Categories

Testing (mandatory)

At least one testing gate must exist. Agents will not start working until a testing gate is defined.

name: testing
required: true
description: 'All tests must pass before creating a PR'

gates:
  - name: 'unit-tests'
    command: 'npm test'
    pass-condition: 'exit-code-zero'
    description: 'Run unit and integration tests'
    run: 'before-pr'

  - name: 'coverage'
    command: 'npm test -- --coverage --coverageThreshold="{\"global\":{\"lines\":80}}"'
    pass-condition: 'exit-code-zero'
    description: 'Enforce 80% line coverage'
    run: 'before-pr'

Formatting and linting

name: formatting
required: true
description: 'Code must be properly formatted and lint-free'

gates:
  - name: 'prettier'
    command: 'npx prettier --check .'
    pass-condition: 'exit-code-zero'
    description: 'Check code formatting'
    run: 'before-pr'

  - name: 'eslint'
    command: 'npx eslint .'
    pass-condition: 'exit-code-zero'
    description: 'Check for lint errors'
    run: 'before-pr'

Static analysis and security

name: security
required: false
description: 'Security and dependency vulnerability checks'

gates:
  - name: 'audit'
    command: 'npm audit --production'
    pass-condition: 'exit-code-zero'
    description: 'Check for known vulnerabilities in production dependencies'
    run: 'before-pr'

Build verification

name: build
required: true
description: 'Project must build successfully'

gates:
  - name: 'build'
    command: 'npm run build'
    pass-condition: 'exit-code-zero'
    description: 'Full production build'
    run: 'before-pr'

Examples by stack

Java / Gradle

testing.yml

name: testing
required: true
description: 'Gradle tests must pass'

gates:
  - name: 'test'
    command: './gradlew test'
    pass-condition: 'exit-code-zero'
    description: 'Run JUnit tests via Gradle'
    run: 'before-pr'

  - name: 'spotless'
    command: './gradlew spotlessCheck'
    pass-condition: 'exit-code-zero'
    description: 'Check code formatting with Spotless'
    run: 'before-pr'

Python / pytest

testing.yml

name: testing
required: true
description: 'pytest must pass with 80% coverage'

gates:
  - name: 'pytest'
    command: 'pytest --cov=src --cov-fail-under=80'
    pass-condition: 'exit-code-zero'
    description: 'Run tests with coverage threshold'
    run: 'before-pr'

  - name: 'black'
    command: 'black --check .'
    pass-condition: 'exit-code-zero'
    description: 'Check formatting with Black'
    run: 'before-pr'

Rust / Cargo

testing.yml

name: testing
required: true
description: 'Cargo tests and clippy must pass'

gates:
  - name: 'test'
    command: 'cargo test'
    pass-condition: 'exit-code-zero'
    description: 'Run all tests'
    run: 'before-pr'

  - name: 'clippy'
    command: 'cargo clippy -- -D warnings'
    pass-condition: 'exit-code-zero'
    description: 'Run clippy with warnings as errors'
    run: 'before-pr'

  - name: 'fmt'
    command: 'cargo fmt --check'
    pass-condition: 'exit-code-zero'
    description: 'Check formatting with rustfmt'
    run: 'before-pr'

How agents use guardrails

Every agent that produces code — work tasks, bug fixes, collaboration sessions — reads all .yml files in .cate/guardrails/ and executes each gate’s command before creating a PR. Gates run twice: once during implementation (for fast feedback) and once fresh before PR creation (to catch regressions from upstream sync). If a required gate fails, the agent fixes the issue and re-runs until it passes.

Reviewing agents do not run guardrails locally. Guardrails are the implementing agent’s responsibility.