Agent Policies

Overview

Policies are codified rules that govern agent behavior. Define them in your squad’s SQUAD.md file, and critic agents automatically enforce them on PRs, issues, and agent actions. Why policies matter:

Prevent mistakes before they reach production
Maintain consistency across agents
Build trust through predictable behavior
Enable compliance and auditability

How Policies Work

You define policies
    ↓
Critic agents read them
    ↓
On PR/Issue events, critics review
    ↓
Violations → Request Changes
Clean → Approve

Defining Policies

Add a policies: section to your squad’s SQUAD.md:

## Policies

Enforced by: `my-squad-critic`

### My Policies (PREFIX-*)

```yaml
policies:
  - id: PREFIX-001
    name: Descriptive Name
    description: What this rule enforces
    severity: blocker  # or warning

  - id: PREFIX-002
    name: Another Rule
    description: Explanation of the rule
    exceptions: ["test files", "scripts/"]
    severity: warning

Policy Fields

Field	Required	Description
`id`	Yes	Unique identifier (e.g., `SEC-001`, `MY-001`)
`name`	Yes	Human-readable title
`description`	Yes	What the rule enforces
`severity`	Yes	`blocker` or `warning`
`exceptions`	No	Paths or patterns that bypass this rule

Severity Levels

Level	Meaning	PR Action
`blocker`	Must fix before merge	Request Changes
`warning`	Should fix, can proceed	Comment only

Creating Critic Agents

Critic agents review work against your policies. Create one in your squad:

---
name: my-squad-critic
squad: my-squad
role: Review PRs for policy compliance
model: claude-haiku-3.5
trigger: event
event: pr_opened
policy_file: .agents/squads/my-squad/SQUAD.md#policies
budget:
  per_run: 0.10
  daily: 2.00
---

# Agent: My Squad Critic

## Purpose

Review PRs for compliance with squad policies.

## Instructions

You are my-squad-critic. Review for policy violations.

Process

Fetch PR: gh pr view —json files,body,title
Check each policy in your policy_file
Output review:

If violations found: gh pr review —request-changes —body “

Policy Review: ❌ Changes Requested

Policy	Violation
PREFIX-XXX	Description

Action Required: Fix before merge. ” If clean: gh pr review —approve —body “

Policy Review: ✅ Approved

No policy violations found. “

Common Policy Categories

Organize policies by domain. Use consistent prefixes:

Prefix	Category	Example Rules
`SEC-*`	Security	No hardcoded secrets, input validation
`CODE-*`	Code Quality	No `any` types, error handling required
`API-*`	API Standards	Versioning, deprecation notices
`DOC-*`	Documentation	README required, help text
`OPS-*`	Operations	Health checks, logging
`ORG-*`	Governance	PR requirements, review rules

Example: Security Policies

policies:
  - id: SEC-001
    name: No Hardcoded Secrets
    description: No API keys, passwords, or tokens in code
    severity: blocker

  - id: SEC-002
    name: Input Validation
    description: All user input must be validated
    severity: blocker

  - id: SEC-003
    name: Parameterized Queries
    description: SQL must use parameterized statements
    severity: blocker

  - id: SEC-004
    name: Dependency Audit
    description: No known vulnerabilities in dependencies
    severity: blocker

Example: Code Quality Policies

policies:
  - id: CODE-001
    name: TypeScript Strict Mode
    description: No 'any' types, strict: true in tsconfig
    severity: blocker

  - id: CODE-002
    name: Error Handling
    description: Async functions must have try/catch
    severity: warning

  - id: CODE-003
    name: Test Coverage
    description: New code requires tests
    exceptions: ["types/", "index.ts"]
    severity: warning

Example: Governance Policies

policies:
  - id: ORG-001
    name: PR Description Required
    description: PRs must have description explaining changes
    severity: warning

  - id: ORG-002
    name: Issue Reference
    description: PRs should reference an issue (Closes #N)
    exceptions: ["docs/", "typo"]
    severity: warning

  - id: ORG-003
    name: Human Review Required
    description: All PRs require human approval before merge
    severity: blocker

Triggering Policy Reviews

Automatic (Recommended)

Set up a smart trigger to run critics on PR events:

# In SQUAD.md triggers section
triggers:
  - name: policy-review
    agent: my-squad-critic
    condition: |
      SELECT EXISTS (
        SELECT 1 FROM squads.events
        WHERE source = 'github'
          AND event_type = 'pull_request'
          AND data->>'action' = 'opened'
          AND created_at > NOW() - INTERVAL '5 minutes'
      )
    cooldown: 5 minutes
    priority: 1

Manual

# Run critic on specific PR
squads run my-squad/my-squad-critic

Handling Violations

Blocker Violations

PR cannot merge until fixed:

## Policy Review: ❌ Changes Requested

| Policy | Violation |
|--------|-----------|
| SEC-001 | Hardcoded API key in src/config.ts:42 |

**Action Required**: Remove secret, use environment variable.

Warning Violations

PR can merge, but should address:

## Policy Review: ⚠️ Approved with Warnings

| Policy | Note |
|--------|------|
| CODE-002 | Missing error handling in utils.ts:78 |

Consider addressing in follow-up PR.

Exceptions

Some files or patterns can bypass specific policies:

- id: CODE-003
  name: Test Coverage
  description: New code requires tests
  exceptions: ["types/", "*.d.ts", "scripts/"]
  severity: warning

When an exception applies, critics note it:

CODE-003 would apply, but exempted: changes only in `types/`

Multiple Critics

For comprehensive coverage, use multiple specialized critics:

# In SQUAD.md triggers
triggers:
  - name: pr-review-all
    agent: pr-critic-orchestrator
    condition: pr_opened
    context:
      critics:
        - security-critic      # SEC-* policies
        - code-quality-critic  # CODE-* policies
        - docs-critic          # DOC-* policies

The orchestrator spawns all critics in parallel, each reviewing against their domain policies.

Best Practices

1. Start Small

Begin with 5-10 critical policies. Add more as needed.

2. Use Blockers Sparingly

Only blocker for things that absolutely cannot ship. Most rules should be warning.

3. Document Exceptions

Every exception should have a clear reason:

exceptions: ["test/"]  # Test files may use mocks

4. Review and Evolve

Policies that always pass or always fail need adjustment.

5. Make Policies Actionable

Bad: “Code should be good” Good: “Functions over 50 lines must be split”

Checking Policy Coverage

Policies are plain markdown tables in SQUAD.md — there’s no separate lookup command, grep the file directly:

grep -A 20 "## Policies" .agents/squads/my-squad/SQUAD.md

Enforcement happens when the critic agent actually runs against a PR — run it manually to check coverage on demand:

squads run my-squad/my-squad-critic

Get Started

Core Concepts

Configuration

Building Agents

Governance

Production

Resources

API

Overview

How Policies Work

Defining Policies

Policy Fields

Severity Levels

Creating Critic Agents

Process

Policy Review: ❌ Changes Requested

Policy Review: ✅ Approved

Common Policy Categories

Example: Security Policies

Example: Code Quality Policies

Example: Governance Policies

Triggering Policy Reviews

Automatic (Recommended)

Manual

Handling Violations

Blocker Violations

Warning Violations

Exceptions

Multiple Critics

Best Practices

1. Start Small

2. Use Blockers Sparingly

3. Document Exceptions

4. Review and Evolve

5. Make Policies Actionable

Checking Policy Coverage

​Overview

​How Policies Work

​Defining Policies

​Policy Fields

​Severity Levels

​Creating Critic Agents

​Process

​Policy Review: ❌ Changes Requested

​Policy Review: ✅ Approved

​Common Policy Categories

​Example: Security Policies

​Example: Code Quality Policies

​Example: Governance Policies

​Triggering Policy Reviews

​Automatic (Recommended)

​Manual

​Handling Violations

​Blocker Violations

​Warning Violations

​Exceptions

​Multiple Critics

​Best Practices

​1. Start Small

​2. Use Blockers Sparingly

​3. Document Exceptions

​4. Review and Evolve

​5. Make Policies Actionable

​Checking Policy Coverage

Overview

How Policies Work

Defining Policies

Policy Fields

Severity Levels

Creating Critic Agents

Process

Policy Review: ❌ Changes Requested

Policy Review: ✅ Approved

Common Policy Categories

Example: Security Policies

Example: Code Quality Policies

Example: Governance Policies

Triggering Policy Reviews

Automatic (Recommended)

Manual

Handling Violations

Blocker Violations

Warning Violations

Exceptions

Multiple Critics

Best Practices

1. Start Small

2. Use Blockers Sparingly

3. Document Exceptions

4. Review and Evolve

5. Make Policies Actionable

Checking Policy Coverage