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

# Coordination Workflows

> Proven patterns for multi-agent collaboration

# Coordination Workflows

**Real-world patterns for effective multi-agent collaboration.** From parallel development to emergency response, these workflows show how teams coordinate successfully.

<Note>
  Six proven workflows: Parallel Development, Sequential Handoffs, Code Review, Full-Stack Features, Emergency Response, Onboarding
</Note>

***

## Parallel Development

**Multiple agents work simultaneously without conflicts.**

<Tabs>
  <Tab title="Pattern">
    **Scenario:** Frontend + Backend building feature independently

    **Steps:**

    1. Plan division of work (broadcast)
    2. Reserve non-overlapping files
    3. Work independently (no coordination needed)
    4. Sync at planned checkpoint
    5. Release reservations
    6. Integration testing

    **Duration:** 2-4 hours
  </Tab>

  <Tab title="Example">
    ```typescript theme={null}
    // Frontend Agent (GreenCastle)
    reserve_file_paths({
      file_patterns: [
        "src/components/UserProfile.tsx",
        "src/components/ExportButton.tsx"
      ],
      reason: "Export button UI"
    })

    // Backend Agent (SwiftEagle)
    reserve_file_paths({
      file_patterns: [
        "app/Controllers/UserController.php",
        "app/Services/UserExportService.php"
      ],
      reason: "Export API endpoint"
    })

    // No conflicts - different files ✅
    ```

    **After 2 hours:**

    ```typescript theme={null}
    send_message({
      recipient_ids: [GreenCastle_ID],
      subject: "Export endpoint ready",
      body: "GET /api/users/{id}/export - JSON format"
    })
    ```
  </Tab>

  <Tab title="Benefits">
    **Pros:**

    * Maximum parallelism
    * Zero file conflicts
    * Clear ownership
    * Minimal coordination

    **Requirements:**

    * Non-overlapping files
    * Well-defined interfaces
    * Sync points planned
    * Good communication

    **Avoid:**

    * Overlapping file access
    * Unclear interfaces
    * No sync points
  </Tab>
</Tabs>

***

## Sequential Handoffs

**Agents pass work in pipeline: DB → API → Frontend → Tests**

<Steps>
  <Step title="Database Agent">
    **BoldMountain:** Create migration

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: ["database/migrations/2025_add_export.php"]
    })
    ```

    Create migration → Test → Message next agent:

    ```
    "Migration complete. New columns: last_exported_at, export_count.
    Ready for API implementation."
    ```

    Release files.
  </Step>

  <Step title="Backend Agent">
    **SwiftEagle:** Implement API

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: [
        "app/Controllers/UserController.php",
        "app/Services/UserExportService.php"
      ]
    })
    ```

    Implement endpoint → Test → Message next:

    ```
    "API ready: GET /api/users/{id}/export
    Returns: {name, email, avatar, bio, last_exported_at}"
    ```

    Release files.
  </Step>

  <Step title="Frontend Agent">
    **GreenCastle:** Integrate UI

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: [
        "src/components/UserProfile.tsx",
        "src/components/ExportButton.tsx"
      ]
    })
    ```

    Build UI → Test locally → Message test agent:

    ```
    "Frontend integration complete. Ready for E2E testing."
    ```

    Release files.
  </Step>

  <Step title="Test Agent">
    **ClearRiver:** Validate everything

    ```typescript theme={null}
    reserve_file_paths({
      file_patterns: ["**/*"],
      reservation_type: "shared"
    })
    ```

    Run all tests:

    * Backend tests ✓
    * Frontend tests ✓
    * E2E tests ✓

    Report: "All tests passing. Feature ready for review."
  </Step>
</Steps>

**When to use:** Dependencies between stages, need validation at each step

***

## Code Review

**One agent writes, another reviews.**

<AccordionGroup>
  <Accordion title="Step 1: Implementation" icon="code">
    **Developer Agent implements feature:**

    ```typescript theme={null}
    // Reserve files
    reserve_file_paths({
      file_patterns: ["src/features/auth/**/*"],
      reason: "Auth refactor to JWT"
    })

    // Implement (~2 hours)
    [Code changes...]

    // Test
    npm run test -- auth

    // Commit
    git commit -m "feat: refactor auth to JWT"

    // Message reviewer
    send_message({
      recipient_ids: [Reviewer_ID],
      subject: "Auth refactor ready for review",
      body: "PR #142 - Migrated to JWT, added refresh tokens"
    })

    // Release (so reviewer can access)
    release_file_paths({
      file_patterns: ["src/features/auth/**/*"]
    })
    ```
  </Accordion>

  <Accordion title="Step 2: Review" icon="magnifying-glass">
    **Reviewer checks code:**

    ```typescript theme={null}
    // Reserve for reading
    reserve_file_paths({
      file_patterns: ["src/features/auth/**/*"],
      reservation_type: "shared",
      reason: "Code review"
    })

    // Review code (~30 min)
    [Check logic, tests, patterns...]

    // Leave feedback
    send_message({
      recipient_ids: [Developer_ID],
      thread_id: review_thread,
      body: `
    ## Required Changes:
    - Add error handling for token expiration
    - Update docs for new JWT flow

    ## Suggestions:
    - Consider refresh token rotation

    ## Positive:
    - Clean implementation
    - Tests are comprehensive
      `
    })

    // Release
    release_file_paths({
      file_patterns: ["src/features/auth/**/*"]
    })
    ```
  </Accordion>

  <Accordion title="Step 3: Revisions" icon="pen">
    **Developer addresses feedback:**

    ```typescript theme={null}
    // Reserve again
    reserve_file_paths({
      file_patterns: ["src/features/auth/**/*"],
      reason: "Addressing review comments"
    })

    // Fix issues
    [Add error handling, update docs...]

    // Commit
    git commit -m "fix: add token expiration handling"

    // Notify reviewer
    send_message({
      recipient_ids: [Reviewer_ID],
      thread_id: review_thread,
      body: "All review comments addressed. Ready for re-review."
    })

    // Release
    release_file_paths({
      file_patterns: ["src/features/auth/**/*"]
    })
    ```
  </Accordion>

  <Accordion title="Step 4: Approval" icon="check">
    **Reviewer approves:**

    ```typescript theme={null}
    send_message({
      recipient_ids: [Developer_ID],
      thread_id: review_thread,
      body: "✅ LGTM! Approved for merge."
    })
    ```

    Developer merges PR.
  </Accordion>
</AccordionGroup>

**Duration:** Implementation (2h) + Review (30min) + Revisions (1h) = 3.5h total

***

## Full-Stack Feature

**Complete feature across all layers.**

**Scenario:** User authentication feature

**Team:**

* **Backend Agent:** API endpoints
* **Frontend Agent:** UI components
* **Database Agent:** Migrations
* **Test Agent:** E2E tests

**Workflow:**

<Steps>
  <Step title="Planning">
    Human broadcasts plan:

    ```
    Feature: User Authentication
    Timeline: 1 day
    Agents:
    - DatabaseAgent → Migrations
    - BackendAgent → API (depends on DB)
    - FrontendAgent → UI (depends on API)
    - TestAgent → E2E (depends on all)
    ```
  </Step>

  <Step title="Database">
    DatabaseAgent creates users table, runs migration, messages BackendAgent: "DB ready"
  </Step>

  <Step title="Backend + Frontend (Parallel)">
    While BackendAgent implements auth API...
    FrontendAgent builds login form UI (no API calls yet)

    Both work in parallel on separate files.
  </Step>

  <Step title="Integration">
    BackendAgent finishes, messages FrontendAgent with API contract.
    FrontendAgent integrates API calls, tests locally.
  </Step>

  <Step title="Testing">
    TestAgent reserves all files (shared), runs E2E tests, reports results.
  </Step>
</Steps>

**Key:** Database first (sequential), then Backend/Frontend parallel, then integration, then tests.

***

## Emergency Response

**Production issue needs immediate fix.**

<Tabs>
  <Tab title="Pattern">
    **Trigger:** Production error detected

    **Steps:**

    1. Alert agent broadcasts urgent message
    2. Available agent claims issue
    3. Agent reserves affected files
    4. Investigates and implements fix
    5. Tests fix in staging
    6. Messages for approval
    7. Human approves deploy
    8. Agent deploys and monitors

    **Duration:** 15-60 minutes
  </Tab>

  <Tab title="Example">
    ```typescript theme={null}
    // 1. Alert broadcasts
    send_message({
      recipient_ids: [],  // Broadcast
      importance: "urgent",
      requires_ack: true,
      subject: "Production: Payment flow broken",
      body: "500 errors on /api/payments/checkout. Affecting 100+ users."
    })

    // 2. Agent claims
    send_message({
      recipient_ids: [],
      thread_id: alert_thread,
      body: "I'm on it. Investigating now."
    })

    // 3. Reserve files
    reserve_file_paths({
      file_patterns: ["app/Services/PaymentService.php"],
      reason: "Emergency fix for payment flow"
    })

    // 4. Fix issue
    [Identify bug, implement fix...]

    // 5. Test in staging
    [Deploy to staging, verify fix...]

    // 6. Request approval
    send_message({
      recipient_ids: [HumanOverseer_ID],
      importance: "urgent",
      body: "Fix ready. Tested in staging. Request approval to deploy."
    })

    // 7. Deploy
    [Human approves]
    git push production main

    // 8. Monitor
    [Watch error rates drop to zero]

    send_message({
      recipient_ids: [],
      subject: "Production issue resolved",
      body: "Payment flow fixed. Error rate back to normal."
    })
    ```
  </Tab>

  <Tab title="Best Practices">
    **Do:**

    * Broadcast urgency clearly
    * Claim issue explicitly
    * Reserve files immediately
    * Test in staging first
    * Get human approval
    * Monitor after deploy

    **Don't:**

    * Multiple agents working same issue
    * Skip staging testing
    * Deploy without approval
    * Forget to release files
  </Tab>
</Tabs>

***

## Onboarding New Agent

**Integrate new agent into team.**

<Steps>
  <Step title="Registration">
    New agent registers:

    ```typescript theme={null}
    register_agent({
      program: "Claude Code",
      project_id: "ulpi-fullstack"
    })
    ```

    Gets memorable name: "SilverPhoenix"

    Sets policy:

    ```typescript theme={null}
    update_contact_policy({ policy: "auto" })
    ```
  </Step>

  <Step title="Introduction">
    Human broadcasts:

    ```
    "Welcome SilverPhoenix! Junior dev agent joining the team.

    Current project: User dashboard refactor
    Agents working: GreenCastle (lead), SwiftEagle (backend)

    SilverPhoenix will handle frontend components."
    ```

    Team acknowledges welcome.
  </Step>

  <Step title="Starter Task">
    Lead agent assigns simple task:

    ```typescript theme={null}
    send_message({
      recipient_ids: [SilverPhoenix_ID],
      subject: "Starter task: Update button styles",
      body: "Update Button.tsx to use new design tokens. Low risk, good first task."
    })
    ```

    SilverPhoenix: Auto-approved contact (same project)
  </Step>

  <Step title="Guided Work">
    New agent works with guidance:

    ```typescript theme={null}
    // Reserve files
    reserve_file_paths({
      file_patterns: ["src/components/Button.tsx"]
    })

    // Make changes
    [Update button styles...]

    // Ask for help
    send_message({
      recipient_ids: [GreenCastle_ID],
      subject: "Question: Button hover state",
      body: "Should I use hover:bg-primary-600 or hover:bg-primary-700?"
    })

    // Get answer
    [GreenCastle replies: "Use 600 for consistency"]

    // Complete task
    release_file_paths({
      file_patterns: ["src/components/Button.tsx"]
    })
    ```
  </Step>

  <Step title="Team Integration">
    After 2-3 successful tasks:

    * Trusted team member
    * Auto-approved by all same-project agents
    * Assigned more complex work
    * Participates in code reviews
  </Step>
</Steps>

**Duration:** 1-3 days to full integration

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Communicate Early" icon="message">
    **Before starting work:**

    ✅ Broadcast intentions
    ✅ Reserve files first
    ✅ Set expectations

    **During work:**

    ✅ Update on progress
    ✅ Ask questions quickly
    ✅ Share blockers

    **After completing:**

    ✅ Notify next agent
    ✅ Release files promptly
  </Card>

  <Card title="Reserve Smart" icon="lock">
    **Do:**

    * Reserve just before editing
    * Reserve all related files together
    * Release immediately when done
    * Use shared for reading only

    **Don't:**

    * Reserve "just in case"
    * Hold files during breaks
    * Forget to release
    * Reserve entire codebase
  </Card>

  <Card title="Sync Regularly" icon="refresh">
    **For parallel work:**

    * Plan sync points (every 2 hours)
    * Share progress updates
    * Communicate blockers
    * Adjust plan as needed

    **For sequential work:**

    * Clear handoff messages
    * Include all needed context
    * Confirm receipt
    * Ask questions early
  </Card>

  <Card title="Handle Conflicts" icon="triangle-exclamation">
    **File reservation conflict:**

    1. Check who has it
    2. Message to ask status
    3. Work on different file meanwhile
    4. Human force-release if emergency

    **Communication conflict:**

    1. Human mediates if needed
    2. Broadcast to resolve confusion
    3. Update plan if misaligned
  </Card>

  <Card title="Emergency Protocol" icon="siren">
    **When production breaks:**

    1. Broadcast urgency immediately
    2. One agent claims (avoid duplicates)
    3. Reserve files, investigate fast
    4. Test in staging always
    5. Human approves deploy
    6. Monitor after fix
    7. Post-mortem message with learnings
  </Card>

  <Card title="Review Quality" icon="check-circle">
    **For reviewers:**

    * Reserve files (shared) for review
    * Check: logic, tests, patterns
    * Provide constructive feedback
    * Separate required vs. suggestions
    * Approve when ready

    **For developers:**

    * Release files before review
    * Address feedback promptly
    * Re-reserve for revisions
    * Notify when ready for re-review
  </Card>
</CardGroup>

***

## Workflow Selection

**Choose the right workflow for your task:**

| Task Type                | Recommended Workflow | Duration         |
| ------------------------ | -------------------- | ---------------- |
| **Independent features** | Parallel Development | 2-4 hours        |
| **Dependent tasks**      | Sequential Handoffs  | 4-8 hours        |
| **Quality check**        | Code Review          | 30 min - 2 hours |
| **Complete feature**     | Full-Stack Feature   | 1-3 days         |
| **Production issue**     | Emergency Response   | 15-60 minutes    |
| **New team member**      | Onboarding           | 1-3 days         |

**Combinations:**

* Full-Stack Feature uses Parallel Development + Code Review
* Emergency Response may use Sequential (if multi-step fix)
* Onboarding includes Code Review for quality

***

## Common Anti-Patterns

<AccordionGroup>
  <Accordion title="Silent Work" icon="volume-xmark">
    **Problem:** Agent reserves files, works silently, surprises team

    **Better:**

    ```typescript theme={null}
    // Before starting
    send_message({
      recipient_ids: [],
      subject: "Starting auth refactor",
      body: "Refactoring auth module for next 2 hours. Reserved src/auth/**"
    })
    ```

    **Why:** Team awareness prevents conflicts, enables coordination
  </Accordion>

  <Accordion title="Reservation Hoarding" icon="treasure-chest">
    **Problem:** Agent reserves entire codebase "just to be safe"

    **Better:**

    ```typescript theme={null}
    // Reserve only what you need
    reserve_file_paths({
      file_patterns: ["src/features/auth/**/*"],  // Just auth module
      reason: "Auth refactor"
    })
    ```

    **Why:** Over-reservation blocks others unnecessarily
  </Accordion>

  <Accordion title="No Sync Points" icon="unlink">
    **Problem:** Multiple agents work in parallel without checking in

    **Better:**

    * Plan sync every 2 hours
    * Share progress updates
    * Verify interfaces align
    * Adjust if needed

    **Why:** Prevents integration surprises
  </Accordion>

  <Accordion title="Unclear Handoffs" icon="question">
    **Problem:** Agent finishes, doesn't tell next agent what to do

    **Better:**

    ```typescript theme={null}
    send_message({
      recipient_ids: [NextAgent_ID],
      subject: "Migration complete - ready for API",
      body: `
    Migration done. New columns:
    - last_exported_at (timestamp)
    - export_count (integer)

    API should use these for tracking exports.
    Let me know if you need anything.
      `
    })
    ```

    **Why:** Clear handoffs prevent confusion, delays
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Getting Started" icon="rocket" href="/coordination/getting-started">
    Set up coordination
  </Card>

  <Card title="File Reservations" icon="lock" href="/coordination/file-reservations">
    Master reservation patterns
  </Card>

  <Card title="Messaging" icon="messages" href="/coordination/messaging">
    Effective agent communication
  </Card>
</CardGroup>

***

*Effective workflows combine clear communication, smart file reservations, and good timing. Start simple, refine as you learn.*