> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Policies

> Define and enforce governance rules for your AI agents

## 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`:

````yaml theme={null}
## 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:

```yaml theme={null}
---
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 {number} --json files,body,title

2. Check each policy in your policy\_file

3. Output review:

If violations found:
gh pr review {number} --request-changes --body "

## Policy Review: ❌ Changes Requested

| Policy     | Violation   |
| ---------- | ----------- |
| PREFIX-XXX | Description |

**Action Required**: Fix before merge.
"

If clean:
gh pr review {number} --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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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:

```yaml theme={null}
# 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

```bash theme={null}
# Run critic on specific PR
squads run my-squad/my-squad-critic
```

***

## Handling Violations

### Blocker Violations

PR cannot merge until fixed:

```markdown theme={null}
## 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:

```markdown theme={null}
## 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:

```yaml theme={null}
- 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:

```markdown theme={null}
CODE-003 would apply, but exempted: changes only in `types/`
```

***

## Multiple Critics

For comprehensive coverage, use multiple specialized critics:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
squads run my-squad/my-squad-critic
```