Workflows

Understanding typical workflows and how sessions progress through their lifecycle

Agent Orchestrator orchestrates end-to-end workflows from issue assignment to PR merge. Understanding these workflows helps you configure reactions and anticipate agent behavior.

Standard Workflow: Spawn → Work → PR → CI → Review → Merge

This is the most common workflow for feature development:

Auto-Reaction Workflows

Reactions automate common interventions, reducing human toil.

CI Failure Auto-Fix

Trigger: ci.failing event
Config key: ci-failed
Default: Enabled with 2 retries

Configuration

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: |
      CI checks failed. Review the logs and fix the issue:
      
      {ci_logs}
    retries: 2
    escalateAfter: 30m

Flow:

1. Lifecycle Manager detects ci_failed status
2. SCM fetches CI check details
3. Runtime sends failure logs to agent
4. Agent analyzes logs, fixes issue, pushes commit
5. Lifecycle Manager detects PR updated → pr_open
6. If CI fails again, repeat (up to retries times)
7. If all retries exhausted, escalate to human

The agent sees actual CI logs and error messages, not just “tests failed.” This gives it enough context to diagnose and fix most issues autonomously.

Review Comments Auto-Response

Trigger: review.changes_requested event
Config key: changes-requested
Default: Enabled with escalation

Configuration

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    message: |
      Review feedback received:
      
      {review_comments}
      
      Please address these comments and push updates.
    retries: 1
    escalateAfter: 1h

Flow:

1. Lifecycle Manager detects changes_requested status
2. SCM fetches review comments (including line numbers, file paths)
3. Runtime sends comments to agent
4. Agent reads feedback, updates code, pushes commits
5. Lifecycle Manager detects PR updated → pr_open
6. PR goes back to review
7. If unresolved after 1 hour, escalate to human

Automated Review Comments (Bug Bots)

Trigger: automated_review.found event
Config key: bugbot-comments
Default: Enabled

Configuration

reactions:
  bugbot-comments:
    auto: true
    action: send-to-agent
    message: |
      Automated review feedback from {bot_name}:
      
      {bot_comments}
      
      Please address these issues.

Flow:

1. SCM detects automated comments (bots, linters, security scanners)
2. Event: automated_review.found
3. Runtime sends bot feedback to agent
4. Agent fixes issues flagged by bots
5. Agent pushes fixes

Supported bots:

• GitHub CodeQL
• Dependabot
• ESLint bot
• Security scanners

Agent Stuck Detection

Trigger: Agent idle beyond readyThresholdMs (default: 5 min)
Config key: agent-stuck
Default: Notify after 10 min

Configuration

readyThresholdMs: 300000  # 5 minutes

reactions:
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m
    message: |
      Agent {session_id} has been idle for {duration}.
      
      Check if it needs input or guidance.

Flow:

1. Lifecycle Manager polls sessions every 30s
2. Agent plugin detects idle activity (last action > 5 min ago)
3. If idle for 10 minutes total, event: session.stuck
4. Notifier sends urgent notification
5. Human attaches to session or sends guidance

Agent Needs Input

Trigger: Agent waiting for user response
Config key: agent-needs-input
Default: Immediate notification

Configuration

reactions:
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
    message: |
      Agent {session_id} is waiting for your input.

Flow:

1. Agent plugin detects waiting_input activity state
2. Lifecycle Manager updates status to needs_input
3. Event: session.needs_input
4. Notifier delivers urgent notification
5. Human responds: ao send session-1 "Yes, proceed"
6. Runtime delivers message to agent

Merge Conflict Detection

Trigger: PR has merge conflicts
Config key: merge-conflicts
Default: Send to agent

Configuration

reactions:
  merge-conflicts:
    auto: true
    action: send-to-agent
    message: |
      Your PR has merge conflicts with {base_branch}.
      
      Please resolve the conflicts and push updates.

Flow:

1. SCM checks merge readiness
2. If noConflicts: false, event: merge.conflicts
3. Runtime notifies agent
4. Agent pulls base branch, resolves conflicts, pushes

Multi-Project Workflows

Orchestrate work across multiple repositories.

Cross-Repo Feature Development

Scenario: Feature requires changes to backend and frontend.

Parallel Issue Batch

Scenario: Clear backlog of 10 similar issues.

for issue in 120 121 122 123 124 125 126 127 128 129; do
  ao spawn my-project $issue
done

Result:

• 10 agents work in parallel
• Each in its own worktree + tmux session
• Each creates its own PR
• Auto-reactions handle CI/review for all
• You review and merge when ready

Monitor:

ao status
# Or open dashboard: ao dashboard

Custom Workflows

Exploration Workflow (No Issue)

Sometimes you want an agent to explore without a specific issue:

ao spawn my-project "Explore performance optimization opportunities"

What happens:

• No issue ID → agent gets free-form prompt
• Agent explores codebase
• Agent may or may not create PR
• Session ends in done state (not merged)

Orchestrator-Managed Workflow

For complex workflows, spawn an orchestrator agent that manages other agents:

ao start                        # Start orchestrator agent

The orchestrator agent:

• Monitors project state
• Spawns child agents for issues
• Coordinates multi-agent workflows
• Makes decisions about priorities
• Reports summary to human

Experimental: Orchestrator agents are a powerful pattern but require careful prompt engineering and monitoring.

Review-Only Workflow

Agent reviews code without making changes:

ao spawn my-project --agent reviewer "Review PR #456 for security issues"

Flow:

1. Agent fetches PR diff
2. Agent analyzes code
3. Agent posts review comments
4. Session ends (no commits, no new PR)

Incremental Workflow

Agent works on large task incrementally:

ao spawn my-project 123 "Step 1: Add database schema"

After first PR merges:

ao spawn my-project 123 "Step 2: Implement API endpoints"

Each session creates a separate PR, building on previous work.

Workflow Best Practices

Reaction Configuration

Start conservative:

reactions:
  ci-failed:
    auto: true          # Safe: CI failures are objective
    retries: 2
  
  changes-requested:
    auto: false         # Start with notify-only
    action: notify
  
  approved-and-green:
    auto: false         # Always review before merge
    action: notify

Graduate to aggressive:

After you trust the system:

reactions:
  changes-requested:
    auto: true          # Let agent address simple feedback
    escalateAfter: 1h
  
  approved-and-green:
    auto: true          # Auto-merge routine PRs

Notification Routing

Route notifications by priority:

notificationRouting:
  urgent: [desktop, slack]      # Agent stuck/needs input
  action: [desktop]             # Merge ready, decision needed
  warning: [slack]              # CI failures (may auto-fix)
  info: []                      # Don't notify for progress updates

Session Monitoring

Use the dashboard for overview:

ao dashboard

Use CLI for quick checks:

ao status                       # All sessions
ao status my-project            # One project

Set up notification channels:

• Desktop: Immediate attention (urgent/action)
• Slack: Team visibility (action/warning)
• Webhook: Integration with your tools (all priorities)

Agent Selection

General purpose: claude-code (default)

• Best for most tasks
• Session resume support
• Good at following complex instructions

Fast iteration: codex

• Quick responses
• Good for small fixes

Interactive: aider

• Git-aware
• Good at incremental changes

Custom: Write your own agent plugin

Workspace Strategy

Most cases: worktree (default)

• Shares git history
• Fast and efficient
• Agents see each other’s commits

Complete isolation: clone

• Separate git state
• Higher disk usage
• Use when agents might interfere

Cleanup Cadence

Clean up regularly to free resources:

ao cleanup --confirm             # All projects
ao cleanup my-project --confirm  # One project

When to clean:

• After PRs merge
• After issues close
• Weekly for stale sessions

What to preserve:

• Sessions in pr_open (may need revival)
• Sessions in needs_input (waiting for you)
• Sessions with unresolved work

Troubleshooting Workflows

Agent Not Creating PR

Symptoms: Session stuck in working, no PR detected.

Causes:

1. Agent hasn’t finished work yet (check activity)
2. Agent lacks GitHub permissions (gh auth login)
3. Workspace hooks not set up (PR not written to metadata)

Solutions:

ao send session-1 "Please create a pull request now"
# Or attach and check: ao attach session-1

CI Keeps Failing

Symptoms: Session cycles pr_open → ci_failed repeatedly.

Causes:

1. Flaky tests (non-deterministic failures)
2. Agent misunderstanding failure logs
3. Retries exhausted

Solutions:

ao send session-1 "The test failure is due to [specific issue]. Please fix [specific thing]."
# Or disable auto-reaction and fix manually

Review Comments Not Addressed

Symptoms: Session stays in changes_requested.

Causes:

1. Comments require human judgment
2. Agent doesn’t understand feedback
3. Escalation threshold not reached

Solutions:

ao send session-1 "The reviewer wants you to [clarification]. Please make that change."
# Or attach and help: ao attach session-1

Agent Stuck

Symptoms: Session in stuck state, no activity.

Causes:

1. Agent waiting for external resource
2. Agent confused about next step
3. Agent process died

Solutions:

ao attach session-1              # Check what agent is doing
ao send session-1 "Please continue with [next step]"
# Or restore if dead: ao session restore session-1

Next Steps

Sessions

Deep dive into session lifecycle and management

Reactions

Configure automatic reactions for your workflows

Monitoring

Set up monitoring and notifications