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