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

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

<Steps>
  ### Human: Spawn Session

  ```bash theme={null}
  ao spawn my-project 123
  ```

  **What happens:**

  * Tracker fetches issue details
  * Workspace creates git worktree + feature branch
  * Runtime creates tmux session
  * Agent launches with issue context
  * Session status: `spawning` → `working`

  ### Agent: Work on Task

  Agent autonomously:

  * Reads relevant code
  * Writes implementation
  * Runs tests
  * Makes commits

  **Lifecycle state:** `working`
  **Activity state:** `active` / `ready`

  ### Agent: Create Pull Request

  When work is complete, agent:

  * Pushes branch to remote
  * Opens PR with `gh pr create`
  * Writes PR URL to metadata (via workspace hooks)

  **Lifecycle state:** `working` → `pr_open`
  **Event emitted:** `pr.created`

  ### CI: Run Checks

  GitHub Actions (or other CI) runs tests.

  **Two paths:**

  **Path A: CI Passes**

  * Session status: `pr_open` → `review_pending`
  * Event: `ci.passing`
  * Agent remains idle

  **Path B: CI Fails**

  * Session status: `pr_open` → `ci_failed`
  * Event: `ci.failing`
  * **Auto-reaction triggered** (if configured)

  ### Reaction: Auto-Fix CI Failure

  If `ci-failed.auto: true`:

  1. SCM fetches CI logs
  2. Runtime sends logs to agent
  3. Agent analyzes failure
  4. Agent fixes code
  5. Agent pushes new commit
  6. CI runs again

  **Session status:** `ci_failed` → `pr_open`
  **Event:** `ci.fix_sent`

  If fix fails after retries:

  * Event: `ci.fix_failed`
  * **Human notified** via escalation

  ### Human: Review PR

  Reviewer examines code.

  **Three outcomes:**

  **Outcome A: Approved**

  * Session status: `review_pending` → `approved`
  * Event: `review.approved`
  * Check merge readiness

  **Outcome B: Changes Requested**

  * Session status: `review_pending` → `changes_requested`
  * Event: `review.changes_requested`
  * **Auto-reaction triggered** (if configured)

  **Outcome C: Just Comments**

  * Session stays: `review_pending`
  * Comments can be forwarded to agent (reaction config)

  ### Reaction: Address Review Comments

  If `changes-requested.auto: true`:

  1. SCM fetches review comments
  2. Runtime sends comments to agent
  3. Agent addresses feedback
  4. Agent pushes new commits
  5. PR updates, back to review

  **Session status:** `changes_requested` → `pr_open`
  **Event:** `review.comments_sent`

  If agent can't resolve:

  * **Human notified** after threshold

  ### Check: Merge Readiness

  When PR is approved + CI passes:

  * Session status: `approved` → `mergeable`
  * Event: `merge.ready`

  **Check criteria:**

  * ✅ Review approved
  * ✅ CI passing
  * ✅ No merge conflicts
  * ✅ Branch up to date

  ### Human: Merge PR

  If `approved-and-green.auto: false` (default):

  * **Human gets notification**
  * Human reviews and clicks merge

  If `approved-and-green.auto: true`:

  * **Automatic merge** via SCM plugin

  **Session status:** `mergeable` → `merged`
  **Event:** `merge.completed`

  ### Cleanup

  After merge:

  ```bash theme={null}
  ao cleanup my-project --confirm
  ```

  **What happens:**

  * Runtime terminated
  * Workspace (worktree) deleted
  * Metadata moved to `archive/`
</Steps>

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

<Accordion title="Configuration">
  ```yaml theme={null}
  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
  ```
</Accordion>

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

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

### Review Comments Auto-Response

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

<Accordion title="Configuration">
  ```yaml theme={null}
  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
  ```
</Accordion>

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

<Accordion title="Configuration">
  ```yaml theme={null}
  reactions:
    bugbot-comments:
      auto: true
      action: send-to-agent
      message: |
        Automated review feedback from {bot_name}:
        
        {bot_comments}
        
        Please address these issues.
  ```
</Accordion>

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

<Accordion title="Configuration">
  ```yaml theme={null}
  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.
  ```
</Accordion>

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

<Accordion title="Configuration">
  ```yaml theme={null}
  reactions:
    agent-needs-input:
      auto: true
      action: notify
      priority: urgent
      message: |
        Agent {session_id} is waiting for your input.
  ```
</Accordion>

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

<Accordion title="Configuration">
  ```yaml theme={null}
  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.
  ```
</Accordion>

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

<Steps>
  ### Spawn Backend Session

  ```bash theme={null}
  ao spawn backend 123
  ```

  Agent works on backend API.

  ### Spawn Frontend Session

  ```bash theme={null}
  ao spawn frontend 123
  ```

  Agent works on frontend UI.

  ### Monitor Both Sessions

  ```bash theme={null}
  ao status
  ```

  Dashboard shows both sessions in progress.

  ### Coordinate Merges

  When both PRs are approved:

  1. Merge backend first
  2. Merge frontend after (depends on backend)

  Or configure to wait for both:

  ```yaml theme={null}
  reactions:
    approved-and-green:
      auto: false
      action: notify
      includeSummary: true
  ```

  You get a summary of all ready PRs.
</Steps>

### Parallel Issue Batch

**Scenario:** Clear backlog of 10 similar issues.

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

```bash theme={null}
ao status
# Or open dashboard: ao dashboard
```

## Custom Workflows

### Exploration Workflow (No Issue)

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

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

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

<Warning>
  **Experimental:** Orchestrator agents are a powerful pattern but require careful prompt engineering and monitoring.
</Warning>

### Review-Only Workflow

Agent reviews code without making changes:

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

```bash theme={null}
ao spawn my-project 123 "Step 1: Add database schema"
```

After first PR merges:

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

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

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

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

```bash theme={null}
ao dashboard
```

**Use CLI for quick checks:**

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

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

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

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

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

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

<Card title="Sessions" icon="clock" href="/concepts/sessions">
  Deep dive into session lifecycle and management
</Card>

<Card title="Reactions" icon="bolt" href="/guides/reactions">
  Configure automatic reactions for your workflows
</Card>

<Card title="Monitoring" icon="chart" href="/guides/monitoring">
  Set up monitoring and notifications
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.