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

# Multi-Agent Coordination

> How multiple AI agents coordinate work using sudocode MCP tools

When multiple agents work on the same project, sudocode's dependency system and status management enable seamless coordination without conflicts.

## Core Coordination Mechanisms

### Status-Based Work Discovery

The `ready` command is the foundation of multi-agent coordination. It automatically filters out work that's already claimed or blocked.

```
Agent A: ready()
→ Returns: [i-abc123, i-def456, i-ghi789]

Agent A: upsert_issue(issue_id: "i-abc123", status: "in_progress")
→ Agent A claims i-abc123

Agent B: ready()
→ Returns: [i-def456, i-ghi789]  // i-abc123 excluded - it's in_progress
```

**Why this works:**

* Issues with `status: in_progress` are automatically excluded from `ready()`
* Issues blocked by open dependencies are automatically excluded
* Agents only see work that's truly available to claim

### Dependency-Based Ordering

Use `blocks` and `depends-on` relationships to enforce execution order across agents.

<Steps>
  <Step title="Define dependencies">
    ```
    i-migration (database schema)
      blocks →
    i-api (API endpoints using new schema)
      blocks →
    i-frontend (UI using new API)
    ```
  </Step>

  <Step title="Agents work in order">
    ```
    Agent A: ready()
    → Returns: [i-migration]  // Only unblocked work

    Agent A: Claims i-migration, completes it, closes it

    Agent B: ready()
    → Returns: [i-api]  // Automatically unblocked when i-migration closed

    Agent B: Claims i-api, completes it, closes it

    Agent C: ready()
    → Returns: [i-frontend]  // Automatically unblocked
    ```
  </Step>
</Steps>

**Automatic unblocking:**

* When a blocker is closed, blocked issues automatically become ready
* No manual coordination needed - the dependency graph handles it

## Parallel Independent Work

Multiple agents can work simultaneously on unrelated issues without coordination.

<CodeGroup>
  ```json Agent A theme={null}
  // Agent A checks for work
  { "tool": "ready" }
  → [i-auth, i-payments, i-notifications]

  // Agent A claims authentication work
  {
    "tool": "upsert_issue",
    "parameters": {
      "issue_id": "i-auth",
      "status": "in_progress"
    }
  }
  ```

  ```json Agent B theme={null}
  // Agent B checks for work (same time as Agent A)
  { "tool": "ready" }
  → [i-auth, i-payments, i-notifications]

  // Agent B claims payments work
  {
    "tool": "upsert_issue",
    "parameters": {
      "issue_id": "i-payments",
      "status": "in_progress"
    }
  }
  ```

  ```json Agent C theme={null}
  // Agent C checks for work (after A and B claimed work)
  { "tool": "ready" }
  → [i-notifications]  // Only remaining unblocked work

  // Agent C claims notifications
  {
    "tool": "upsert_issue",
    "parameters": {
      "issue_id": "i-notifications",
      "status": "in_progress"
    }
  }
  ```
</CodeGroup>

**Best practices for parallel work:**

* Keep issues focused and independent
* Avoid creating issues that touch the same files
* Use tags to indicate which subsystem/module the issue affects
* Break down large features into smaller, parallel-friendly tasks

## Sequential Dependencies

When work must happen in order, use dependencies to coordinate handoffs between agents.

### Example: Feature with Dependencies

```mermaid theme={null}
graph TD
    A[i-types: Define TypeScript types] --> B[i-backend: Implement API]
    A --> C[i-validation: Add input validation]
    B --> D[i-frontend: Build UI]
    C --> D
    D --> E[i-tests: Integration tests]

    style A fill:#10B981
    style B fill:#6B9AFF
    style C fill:#6B9AFF
    style D fill:#9CA3AF
    style E fill:#9CA3AF
```

**Workflow:**

<Steps>
  <Step title="Agent A completes foundation">
    ```
    Agent A: Claims and completes i-types (TypeScript definitions)
    Agent A: upsert_issue(issue_id: "i-types", status: "closed")

    → This unblocks both i-backend and i-validation
    ```
  </Step>

  <Step title="Agents B and C work in parallel">
    ```
    Agent B: ready()
    → Returns: [i-backend, i-validation, ...]

    Agent B: Claims i-backend

    Agent C: ready()
    → Returns: [i-validation, ...]

    Agent C: Claims i-validation

    → Both agents work simultaneously on different parts
    ```
  </Step>

  <Step title="Agent D waits for both">
    ```
    Agent D: ready()
    → Returns: []  // i-frontend still blocked

    Agent B: Closes i-backend
    Agent C: Closes i-validation

    Agent D: ready()
    → Returns: [i-frontend]  // Now unblocked!
    ```
  </Step>
</Steps>

## Discovery Coordination

When an agent discovers new work during implementation, they create issues for other agents to pick up.

<Steps>
  <Step title="Agent discovers missing work">
    ```
    Agent A is working on i-oauth

    Agent A: "While implementing OAuth, I discovered we need Redis
    configured for token storage."
    ```
  </Step>

  <Step title="Agent creates blocker issue">
    ```json theme={null}
    {
      "tool": "upsert_issue",
      "parameters": {
        "title": "Configure Redis for OAuth token storage",
        "description": "Set up Redis instance for storing OAuth tokens.\n\nDiscovered while working on [[i-oauth]]",
        "priority": 0,
        "tags": ["redis", "infrastructure", "blocker"]
      }
    }
    ```

    Returns: `{ "id": "i-redis" }`
  </Step>

  <Step title="Agent links relationships">
    ```json theme={null}
    // Mark as blocking
    {
      "tool": "link",
      "parameters": {
        "from_id": "i-redis",
        "to_id": "i-oauth",
        "type": "blocks"
      }
    }

    // Track provenance
    {
      "tool": "link",
      "parameters": {
        "from_id": "i-redis",
        "to_id": "i-oauth",
        "type": "discovered-from"
      }
    }
    ```
  </Step>

  <Step title="Agent updates status">
    ```json theme={null}
    {
      "tool": "upsert_issue",
      "parameters": {
        "issue_id": "i-oauth",
        "status": "blocked"
      }
    }
    ```
  </Step>

  <Step title="Another agent picks up blocker">
    ```
    Agent B: ready()
    → Returns: [i-redis, ...]

    Agent B: Claims i-redis, implements Redis setup, closes issue

    → i-oauth automatically unblocked

    Agent A or Agent C: ready()
    → Returns: [i-oauth, ...]
    ```
  </Step>
</Steps>

**Discovery patterns:**

* Use `discovered-from` to track which issue led to discovery
* Set high priority (P0-P1) on critical blockers
* Include context in description: "Discovered while working on \[\[i-xyz]]"
* The discovering agent can work on the blocker themselves or leave it for others

## Communication via Feedback

Agents leave notes for downstream agents using the feedback system.

### Feedback to Issues

When an agent needs to communicate with another agent about an issue:

```json theme={null}
{
  "tool": "add_feedback",
  "parameters": {
    "issue_id": "i-current",
    "to_id": "i-downstream",
    "type": "comment",
    "content": "Note for whoever works on [[i-downstream]]:\n\nI've implemented the authentication middleware in `auth.ts`. The session tokens are stored in Redis with a 24-hour TTL. Make sure to handle token refresh before the TTL expires."
  }
}
```

**When to use issue-to-issue feedback:**

* Handoff notes between sequential work
* Important context for downstream implementation
* Warnings about edge cases discovered
* Recommendations for implementation approach

### Feedback to Specs

When implementing, agents provide feedback on specs to improve clarity:

```json theme={null}
{
  "tool": "add_feedback",
  "parameters": {
    "issue_id": "i-current",
    "to_id": "s-auth-spec",
    "type": "request",
    "content": "The spec doesn't specify token refresh interval. Recommend:\n- Access tokens: 15 minutes\n- Refresh tokens: 7 days\n\nProceeding with these values, but please update spec if different values are needed.",
    "line": 42
  }
}
```

Downstream agents can review feedback on specs to learn from previous implementations.

## Preventing Conflicts

### File-Level Organization

Break work to minimize file conflicts:

<Accordion title="Good: Separate files">
  ```
  i-user-model: Implement User model in models/user.ts
  i-auth-model: Implement Auth model in models/auth.ts
  i-payment-model: Implement Payment model in models/payment.ts

  → 3 agents can work in parallel, no conflicts
  ```
</Accordion>

<Accordion title="Bad: Same file">
  ```
  i-add-validation: Add validation to utils.ts
  i-add-formatting: Add formatting to utils.ts
  i-add-parsing: Add parsing to utils.ts

  → Agents will conflict on utils.ts
  ```

  **Better approach:**

  ```
  i-utils-refactor: Split utils.ts into validation.ts, formatting.ts, parsing.ts
    blocks →
  i-add-validation: Add validation to validation.ts
  i-add-formatting: Add formatting to formatting.ts
  i-add-parsing: Add parsing to parsing.ts
  ```
</Accordion>

### Scope-Based Breakdown

Organize issues by scope/module/subsystem:

```
Backend Team:
- i-api-endpoints (src/api/)
- i-database-schema (src/models/)
- i-business-logic (src/services/)

Frontend Team:
- i-ui-components (src/components/)
- i-state-management (src/store/)
- i-routing (src/routes/)

→ Backend and frontend agents work in parallel without conflicts
```

## CI/CD Integration

### Pre-Commit Checks

Agents verify work before closing issues:

```
Agent completes i-feature:

1. Run tests: npm test
2. Run linter: npm run lint
3. Run type check: npm run type-check
4. If all pass → close issue
5. If any fail → fix issues or mark as blocked
```

### Atomic Issue Completion

Each issue should represent a complete, mergeable unit:

<Check>
  **Complete issue criteria:**

  * All tests passing
  * Code follows style guidelines
  * No type errors
  * Documentation updated
  * Related issues updated
</Check>

### Multi-Agent CI Workflow

```mermaid theme={null}
graph LR
    A[Agent A: Closes i-backend] --> B[CI: Run tests]
    B --> C{Tests pass?}
    C -->|Yes| D[Unblock i-frontend]
    C -->|No| E[Reopen i-backend]
    D --> F[Agent B: Claims i-frontend]
```

## Best Practices

<AccordionGroup>
  <Accordion title="Check ready() frequently">
    Status changes as other agents work. Check `ready()` to see newly unblocked work:

    ```
    Agent: ready()
    → [i-abc]

    // 5 minutes later, another agent closed a blocker

    Agent: ready()
    → [i-abc, i-xyz]  // i-xyz newly unblocked!
    ```
  </Accordion>

  <Accordion title="Update status immediately">
    Update status as soon as you claim or complete work:

    **Good:**

    ```
    Agent A: ready() → [i-abc, i-def]
    Agent A: upsert_issue(i-abc, status: in_progress)  // Immediate
    Agent A: [starts work]
    ```

    **Bad:**

    ```
    Agent A: ready() → [i-abc, i-def]
    Agent A: [starts work]
    Agent B: ready() → [i-abc, i-def]  // Agent B sees i-abc!
    Agent B: upsert_issue(i-abc, status: in_progress)
    Agent A: upsert_issue(i-abc, status: in_progress)  // Conflict!
    ```
  </Accordion>

  <Accordion title="Create focused, claimable issues">
    Break work into discrete units that one agent can complete:

    **Too large:**

    ```
    i-implement-auth: Implement entire authentication system
    → Multiple agents want to work on this, but it's one issue
    ```

    **Better:**

    ```
    i-auth-types: Define authentication TypeScript types
    i-auth-service: Implement AuthService class
    i-auth-middleware: Add authentication middleware
    i-auth-routes: Create authentication routes
    → 4 agents can work in parallel
    ```
  </Accordion>

  <Accordion title="Use priority to guide work selection">
    Agents should prefer high-priority work:

    ```
    Agent: ready()
    → [i-critical (P0), i-feature (P2), i-nice-to-have (P3)]

    Agent: Claims i-critical first (highest priority)
    ```

    Set priorities to guide agent behavior:

    * P0: Critical blockers, production issues
    * P1: Important features, high-value work
    * P2: Standard features, improvements
    * P3: Nice-to-haves, low-priority tasks
  </Accordion>
</AccordionGroup>

## Real-World Scenario

**Project:** Building OAuth 2.0 authentication system with 3 agents

<Steps>
  <Step title="Planning agent breaks down spec">
    ```
    Agent A: show_spec("s-oauth")
    Agent A: Creates 5 implementation issues with dependencies:

    i-config (P0) - OAuth provider setup
      blocks → i-tokens (P1) - Token exchange
      blocks → i-flow (P1) - Auth flow
    i-tokens blocks → i-refresh (P2) - Token refresh
    i-flow blocks → i-security (P1) - Security hardening

    Agent A: Links all issues to s-oauth with "implements"
    ```
  </Step>

  <Step title="Agents claim initial work">
    ```
    Agent B: ready() → [i-config]
    Agent B: Claims i-config

    Agent C: ready() → []  // Nothing else ready yet
    Agent C: Waits...
    ```
  </Step>

  <Step title="Agent B completes foundation">
    ```
    Agent B: Implements OAuth config
    Agent B: upsert_issue(i-config, status: closed)

    → Unblocks i-tokens and i-flow
    ```
  </Step>

  <Step title="Parallel work begins">
    ```
    Agent C: ready() → [i-tokens, i-flow]
    Agent C: Claims i-tokens

    Agent D: ready() → [i-flow]
    Agent D: Claims i-flow

    → Both work in parallel
    ```
  </Step>

  <Step title="Agent C discovers blocker">
    ```
    Agent C: "Need Redis for token storage"
    Agent C: Creates i-redis (P0)
    Agent C: link(i-redis blocks i-tokens)
    Agent C: upsert_issue(i-tokens, status: blocked)
    ```
  </Step>

  <Step title="Agent B picks up blocker">
    ```
    Agent B: ready() → [i-redis]
    Agent B: Claims i-redis, implements, closes

    → Unblocks i-tokens
    ```
  </Step>

  <Step title="Completion">
    ```
    Agent C: ready() → [i-tokens]
    Agent C: Claims i-tokens, completes it

    Agent D: Completes i-flow

    → Unblocks i-refresh and i-security

    Agent C: Claims i-refresh
    Agent D: Claims i-security

    → Both complete in parallel

    All 5 issues closed!
    ```
  </Step>
</Steps>

**Key coordination points:**

1. Dependencies enforced execution order automatically
2. Agents discovered work via `ready()` without explicit coordination
3. Blocker creation and linking prevented wasted work
4. Parallel work maximized throughput
5. No conflicts - proper dependency structure and focused issues

## Related Documentation

<CardGroup cols={2}>
  <Card title="Issue Creation" icon="list-check" href="/mcp/issue-creation">
    Creating and organizing issues
  </Card>

  <Card title="Issue Execution" icon="play" href="/mcp/issue-execution">
    How agents claim and complete work
  </Card>

  <Card title="Agent Best Practices" icon="robot" href="/mcp/agent-best-practices">
    Guidelines for effective agent work
  </Card>

  <Card title="Relationships" icon="diagram-project" href="/concepts/relationships">
    Understanding dependencies and links
  </Card>
</CardGroup>