Guardrails YAML

Guardrails are quality gates that every agent must pass before creating a PR. They are defined as YAML files in .cate/guardrails/. To set up or modify your project’s guardrails, see Set guardrails. This page is the YAML schema reference.

How agents use guardrails

Every agent that produces code — work tasks, bug fixes — 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.

Pair agents do not run guardrails automatically, but you can ask them to at any point during the session.

Categories

• Testing (mandatory) — Unit tests, integration tests, coverage thresholds. At least one testing gate must exist. Agents will not start working until a testing gate is defined.
• Formatting and linting — Code style enforcement (Prettier, ESLint, Black, rustfmt, etc.)
• Static analysis and security — Dependency audits, vulnerability scanning, static analyzers
• Build verification — Full production build must succeed

Examples by stack

Node / npm

testing.yml

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.yml

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'

security.yml

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.yml

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'

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"

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"