Skip to main content

​
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

FieldRequiredDescription
idYesUnique identifier (e.g., SEC-001, MY-001)
nameYesHuman-readable title
descriptionYesWhat the rule enforces
severityYesblocker or warning
exceptionsNoPaths or patterns that bypass this rule

​
Severity Levels

LevelMeaningPR Action
blockerMust fix before mergeRequest Changes
warningShould fix, can proceedComment 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

  1. Fetch PR: gh pr view —json files,body,title
  2. Check each policy in your policy_file
  3. Output review:
If violations found: gh pr review —request-changes —body “

​
Policy Review: ❌ Changes Requested

PolicyViolation
PREFIX-XXXDescription
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:
PrefixCategoryExample Rules
SEC-*SecurityNo hardcoded secrets, input validation
CODE-*Code QualityNo any types, error handling required
API-*API StandardsVersioning, deprecation notices
DOC-*DocumentationREADME required, help text
OPS-*OperationsHealth checks, logging
ORG-*GovernancePR 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

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

# List all policies across squads
squads permissions show my-squad

# Validate policies before execution
squads permissions check my-squad