Multi-Agent Coordination

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.

Define dependencies

i-migration (database schema)
  blocks →
i-api (API endpoints using new schema)
  blocks →
i-frontend (UI using new API)

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

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.

// 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"
  }
}

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

Workflow:

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

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

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!

Discovery Coordination

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

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."

Agent creates blocker issue

{
  "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" }

Agent links relationships

// 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"
  }
}

Agent updates status

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "i-oauth",
    "status": "blocked"
  }
}

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, ...]

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:

{
  "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:

{
  "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:

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

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

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:

Run tests: npm test
Run linter: npm run lint
Run type check: npm run type-check
If all pass → close issue
If any fail → fix issues or mark as blocked

Atomic Issue Completion

Each issue should represent a complete, mergeable unit:

Complete issue criteria:

All tests passing
Code follows style guidelines
No type errors
Documentation updated
Related issues updated

Multi-Agent CI Workflow

Best Practices

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!

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!

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

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

Real-World Scenario

Project: Building OAuth 2.0 authentication system with 3 agents

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"

Agents claim initial work

Agent B: ready() → [i-config]
Agent B: Claims i-config

Agent C: ready() → []  // Nothing else ready yet
Agent C: Waits...

Agent B completes foundation

Agent B: Implements OAuth config
Agent B: upsert_issue(i-config, status: closed)

→ Unblocks i-tokens and i-flow

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

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)

Agent B picks up blocker

Agent B: ready() → [i-redis]
Agent B: Claims i-redis, implements, closes

→ Unblocks i-tokens

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!

Key coordination points:

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

Issue Creation

Creating and organizing issues

Issue Execution

How agents claim and complete work

Agent Best Practices

Guidelines for effective agent work

Relationships

Understanding dependencies and links

MCP Server

MCP Workflow Examples

Multi-Agent Coordination

Core Coordination Mechanisms

Status-Based Work Discovery

Dependency-Based Ordering

Parallel Independent Work

Sequential Dependencies

Example: Feature with Dependencies

Discovery Coordination

Communication via Feedback

Feedback to Issues

Feedback to Specs

Preventing Conflicts

File-Level Organization

Scope-Based Breakdown

CI/CD Integration

Pre-Commit Checks

Atomic Issue Completion

Multi-Agent CI Workflow

Best Practices

Real-World Scenario

Issue Creation

Issue Execution

Agent Best Practices

Relationships

MCP Server

MCP Workflow Examples

Documentation Index

​Core Coordination Mechanisms

​Status-Based Work Discovery

​Dependency-Based Ordering

​Parallel Independent Work

​Sequential Dependencies

​Example: Feature with Dependencies

​Discovery Coordination

​Communication via Feedback

​Feedback to Issues

​Feedback to Specs

​Preventing Conflicts

​File-Level Organization

​Scope-Based Breakdown

​CI/CD Integration

​Pre-Commit Checks

​Atomic Issue Completion

​Multi-Agent CI Workflow

​Best Practices

​Real-World Scenario

​Related Documentation

Issue Creation

Issue Execution

Agent Best Practices

Relationships

Core Coordination Mechanisms

Status-Based Work Discovery

Dependency-Based Ordering

Parallel Independent Work

Sequential Dependencies

Example: Feature with Dependencies

Discovery Coordination

Communication via Feedback

Feedback to Issues

Feedback to Specs

Preventing Conflicts

File-Level Organization

Scope-Based Breakdown

CI/CD Integration

Pre-Commit Checks

Atomic Issue Completion

Multi-Agent CI Workflow

Best Practices

Real-World Scenario

Related Documentation