Approval System - Agents Squads

Overview

The approval system lets each squad declare what agents can do automatically vs. what requires human sign-off. That declaration lives in plain YAML in SQUAD.md — it’s read by critic agents doing PR review, and (if you run a companion API + Slack app) by an interactive approve/reject flow. The two are independent: the policy is useful as documentation and as a critic-agent gate even if you never wire up Slack.

This is a different mechanism from governance, which protects goals.md/directives.md/SQUAD.md themselves from autonomous edits via native Claude Code permission rules. Approvals gate what an agent does; governance gates what an agent can rewrite.

Four levels of autonomy:

Level	Actions	Human Involvement
`auto`	Safe, reversible operations	None — agent proceeds
`notify`	Worth knowing about	Posted, agent proceeds without waiting
`approve`	Significant but routine	Async approval (Slack)
`confirm`	High-impact decisions	Sync confirmation, escalates to a higher channel

Configuration

Each squad’s SQUAD.md contains an approvals: section:

approvals:
  channel: "#squad-engineering"
  notify: ["@jorge"]         # who gets @-mentioned, independent of the tiers below

  policy:
    auto:
      - memory.update
      - goal.set
      - branch.create
      - issue.create
      - pr.create
      - agent.run.readonly

    notify:
      - release.draft

    approve:
      - pr.merge
      - 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

Notify Actions

Posted to the channel, but the agent proceeds without waiting:

Action	Description
`release.draft`	Create release drafts

Approve Actions

Require async approval via Slack:

Action	Description
`pr.merge`	Merge pull requests
`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

Interactive Slack approve/reject buttons require a running companion API (SQUADS_API_URL) with a Slack app configured — that’s part of the hosted platform, not something the standalone local CLI spins up for you. Without it, squads approval send records a request but nothing decides it. What works standalone: squads add auto-creates a #squad-<name> Slack channel if SLACK_BOT_TOKEN is set, and critic agents can enforce the same policy: tiers directly on a PR without any Slack integration at all.

CLI Approval

# Send an approval request — type is one of: issue, pr, content, run, brief
squads approval send pr --title "Merge feature X" --json '{"repo":"my-org/my-repo","number":123}'

# List pending approvals
squads approval list

# Check status (add --wait to poll until decided)
squads approval check appr_abc123 --wait

squads approval cancel <id> exists in the CLI but isn’t implemented yet server-side — sending it is currently a no-op.

Escalation

Some actions escalate to higher-level channels:

confirm:
  - deploy.production    # Escalate to #company
  - schema.migrate       # Escalate to #company

When an action is in 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

# Autonomy score and confidence metrics, including response times
squads autonomy --period week

Slow approval times indicate policies may be too restrictive.

​Overview

​Configuration

​Action Categories

​Auto Actions

​Notify Actions

​Approve Actions

​Confirm Actions

​Thresholds

​How Thresholds Work

​Approval Flow

​CLI Approval

​Escalation

​Timeout Behavior

​Per-Squad Examples

​Engineering Squad

​Company Squad

​Best Practices

​1. Start Restrictive

​2. Use Thresholds

​3. Clear Channels

​4. Timely Responses

​5. Document Exceptions

​Monitoring Approvals

Overview

Configuration

Action Categories

Auto Actions

Notify Actions

Approve Actions

Confirm Actions

Thresholds

How Thresholds Work

Approval Flow

CLI Approval

Escalation

Timeout Behavior

Per-Squad Examples

Engineering Squad

Company Squad

Best Practices

1. Start Restrictive

2. Use Thresholds

3. Clear Channels

4. Timely Responses

5. Document Exceptions

Monitoring Approvals