Skip to main content
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.
1

Define dependencies

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

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

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
2

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
3

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

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

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

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

Agent updates status

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

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

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:

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:
Complete issue criteria:
  • All tests passing
  • Code follows style guidelines
  • No type errors
  • Documentation updated
  • Related issues updated

​
Multi-Agent CI Workflow

​
Best Practices

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 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!
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
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
1

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

Agents claim initial work

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

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

Agent B completes foundation

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

→ Unblocks i-tokens and i-flow
4

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
5

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)
6

Agent B picks up blocker

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

→ Unblocks i-tokens
7

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

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