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
The approval system ensures humans maintain oversight of agent actions. Each squad defines what agents can do automatically vs. what requires human approval.
Three levels of autonomy:
| Level | Actions | Human Involvement |
|---|
auto | Safe, reversible operations | None - agent proceeds |
approve | Significant but routine | Async approval (Slack/GitHub) |
confirm | High-impact decisions | Sync confirmation required |
Configuration
Each squad’s SQUAD.md contains an approvals: section:
approvals:
channel: "#squad-engineering"
notify: ["@jorge"]
policy:
auto:
- memory.update
- goal.set
- branch.create
- issue.create
- pr.create
- agent.run.readonly
approve:
- pr.merge
- release.draft
- trigger.fire
- agent.run.write
confirm:
- deploy.production
- schema.migrate
- secret.rotate
thresholds:
spend_approval: 15.00
bulk_actions: 5
files_changed: 20
Action Categories
Auto Actions
Agents execute immediately without human intervention:
| Action | Description |
|---|
memory.update | Update squad memory files |
goal.set | Set or update squad goals |
branch.create | Create feature branches |
issue.create | Open GitHub issues |
issue.comment | Comment on issues |
pr.create | Create pull requests |
commit.push | Push commits to branches |
build.run | Run build commands |
test.run | Run test suites |
agent.run.readonly | Execute read-only agents |
Approve Actions
Require async approval via Slack or GitHub:
| Action | Description |
|---|
pr.merge | Merge pull requests |
release.draft | Create release drafts |
release.publish | Publish releases |
trigger.fire | Manually fire triggers |
infra.change | Infrastructure modifications |
agent.run.write | Execute write-capable agents |
Confirm Actions
Require synchronous confirmation before proceeding:
| Action | Description |
|---|
deploy.production | Production deployments |
schema.migrate | Database migrations |
secret.rotate | Rotate secrets |
mission.change | Mission statement changes |
org.restructure | Organizational changes |
budget.exceed | Over-budget decisions |
Thresholds
Automatic escalation based on impact:
thresholds:
spend_approval: 15.00 # USD - actions exceeding this need approval
bulk_actions: 5 # Operations affecting >N items
files_changed: 20 # PRs touching >N files
How Thresholds Work
-
Spend Threshold: Agent tracks cumulative spend. When approaching threshold, pauses for approval.
-
Bulk Actions: Creating >5 issues? Closing >5 PRs? Requires approval.
-
Files Changed: Large PRs automatically require squad lead review.
Approval Flow
Slack Approval
Agent: "I need to merge PR #123 (15 files changed)"
↓
Slack message to #squad-engineering:
┌────────────────────────────────────────┐
│ 🔔 Approval Request │
│ │
│ Agent: engineering/issue-solver │
│ Action: pr.merge │
│ Target: PR #123 - Add user auth │
│ Files: 15 (threshold: 20) │
│ │
│ [Approve] [Reject] [View PR] │
└────────────────────────────────────────┘
↓
Human clicks [Approve]
↓
Agent receives approval, proceeds
CLI Approval
# Send approval request
squads approval send pr.merge --target "PR #123"
# Check status
squads approval check approval-abc123
# List pending approvals
squads approval list
# Cancel request
squads approval cancel approval-abc123
Escalation
Some actions escalate to higher-level channels:
confirm:
- deploy.production # Escalate to #company
- schema.migrate # Escalate to #company
confirm, it escalates from the squad channel to the company channel, requiring explicit confirmation before proceeding.
Timeout Behavior
Approvals have configurable timeouts:
| Type | Default Timeout | On Timeout |
|---|
approve | 4 hours | Reminder, then abandon |
confirm | 1 hour | Abandon, create issue |
Per-Squad Examples
Engineering Squad
approvals:
channel: "#engineering"
notify: [] # GitHub watched directly
policy:
auto:
- issue.create
- pr.create
- commit.push
- release.draft
approve:
- pr.merge
- release.publish
confirm:
- deploy.production # → #company
Company Squad
approvals:
channel: "#company"
notify: ["@jorge"]
policy:
auto:
- memory.update
- goal.set
approve:
- sprint.approve
- strategy.update
confirm:
- mission.change
- org.restructure
Best Practices
1. Start Restrictive
Begin with most actions in approve, move to auto as trust builds.
2. Use Thresholds
Don’t make everything require approval. Use thresholds to catch outliers.
3. Clear Channels
Each squad should have a dedicated approval channel. Don’t mix with general chat.
4. Timely Responses
Blocked agents waste compute. Respond to approvals quickly or adjust policies.
5. Document Exceptions
If you approve something unusual, note why in the approval response.
Monitoring Approvals
# View approval statistics
squads approval stats
# See approval response times
squads autonomy --period week
