Agent Workflow Examples

Overview

These examples demonstrate real-world patterns for AI agents working with sudocode:

Finding and claiming work
Creating implementation plans
Providing feedback on specifications
Multi-agent collaboration
Handling blocked work

All examples show actual MCP tool invocations with parameters. These patterns work with any MCP-compatible AI assistant.

Workflow 1: Claiming and Executing Work

Scenario: Agent finds available work, understands requirements, claims it, completes it.

User asks about available work

User: "What work is ready to start?"

Agent checks for ready work

Agent calls ready() tool:

{
  "tool": "ready",
  "parameters": {}
}

Returns:

{
  "issues": [
    {
      "id": "ISSUE-042",
      "title": "Add rate limiting to API endpoints",
      "priority": 1,
      "status": "open"
    },
    {
      "id": "ISSUE-043",
      "title": "Implement token refresh logic",
      "priority": 2,
      "status": "open"
    },
    {
      "id": "ISSUE-044",
      "title": "Add OAuth 2.0 error handling",
      "priority": 2,
      "status": "open"
    }
  ]
}

Agent responds: “Found 3 unblocked issues ready to work on:

ISSUE-042: Add rate limiting to API endpoints (P1)
ISSUE-043: Implement token refresh logic (P2)
ISSUE-044: Add OAuth 2.0 error handling (P2)”

User selects work

User: "Work on ISSUE-042"

Agent reviews issue details

Agent calls show_issue():

{
  "tool": "show_issue",
  "parameters": {
    "issue_id": "ISSUE-042"
  }
}

Returns: Full issue details including description, relationships, and feedback

Agent claims the issue

Agent calls upsert_issue() to mark as in progress:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-042",
    "status": "in_progress"
  }
}

Agent responds: “Claimed ISSUE-042. Now working on implementing rate limiting…”

Agent implements the feature

Agent writes code, makes changes…

Agent completes the work

Agent calls upsert_issue() to close:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-042",
    "status": "closed",
    "description": "Added rate limiting middleware to all API endpoints.\n\nImplemented:\n- Redis-based rate limiter\n- Per-user rate limits (100 req/min)\n- Global rate limits (10000 req/min)\n- Rate limit headers in responses\n\nTested with integration tests."
  }
}

Agent responds: “Completed ISSUE-042. Rate limiting has been implemented and tested.”

Key Takeaways:

Always check ready() before claiming work
Use show_issue() to understand full context
Update status to in_progress when claiming
Update description when closing to document what was done

Workflow 2: Creating Implementation Plan

Scenario: Agent breaks down a specification into actionable issues with dependencies.

User requests implementation plan

User: "Create a plan to implement SPEC-005 (OAuth 2.0 Authentication System)"

Agent reviews the specification

Agent calls show_spec():

{
  "tool": "show_spec",
  "parameters": {
    "spec_id": "SPEC-005"
  }
}

Returns: Complete spec with requirements, architecture, and existing feedback

Agent analyzes and breaks down work

Agent thinks: “This spec requires:

OAuth provider integration
Token management
User authentication flow
Session management
Security hardening”

Agent creates implementation issues

Agent calls upsert_issue() multiple times:Issue 1: Foundation

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Set up OAuth 2.0 provider configuration",
    "description": "Configure OAuth providers (Google, GitHub) with client IDs and secrets.\n\nImplements [[SPEC-005]] section 2.1",
    "priority": 0,
    "tags": ["auth", "oauth", "setup"]
  }
}

Returns: { "id": "ISSUE-050" }Issue 2: Token handling

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Implement OAuth token exchange and storage",
    "description": "Exchange authorization codes for access tokens and store securely.\n\nImplements [[SPEC-005]] section 2.2",
    "priority": 1,
    "tags": ["auth", "oauth", "tokens"]
  }
}

Returns: { "id": "ISSUE-051" }Issue 3: Authentication flow

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Build OAuth callback handler and user flow",
    "description": "Handle OAuth callbacks, create user sessions, implement login/logout.\n\nImplements [[SPEC-005]] section 2.3",
    "priority": 1,
    "tags": ["auth", "oauth", "flow"]
  }
}

Returns: { "id": "ISSUE-052" }Issue 4: Token refresh

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Implement token refresh logic",
    "description": "Automatically refresh expired tokens using refresh tokens.\n\nImplements [[SPEC-005]] section 2.4",
    "priority": 2,
    "tags": ["auth", "oauth", "tokens"]
  }
}

Returns: { "id": "ISSUE-053" }Issue 5: Security

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Add OAuth security hardening (CSRF, state validation)",
    "description": "Implement CSRF protection, state parameter validation, and secure token storage.\n\nImplements [[SPEC-005]] section 3.0",
    "priority": 1,
    "tags": ["auth", "oauth", "security"]
  }
}

Returns: { "id": "ISSUE-054" }

Agent links issues to spec

Agent calls link() to connect each issue:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-050",
    "to_id": "SPEC-005",
    "type": "implements"
  }
}

(Repeated for all issues)

Agent models dependencies

Agent calls link() to create blocking relationships:ISSUE-051 depends on ISSUE-050:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-050",
    "to_id": "ISSUE-051",
    "type": "blocks"
  }
}

ISSUE-052 depends on ISSUE-051:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-051",
    "to_id": "ISSUE-052",
    "type": "blocks"
  }
}

ISSUE-053 depends on ISSUE-051:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-051",
    "to_id": "ISSUE-053",
    "type": "blocks"
  }
}

ISSUE-054 depends on ISSUE-052:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-052",
    "to_id": "ISSUE-054",
    "type": "blocks"
  }
}

Agent summarizes plan

Agent responds: “Created implementation plan for SPEC-005:Phase 1 (P0) - Foundation:

ISSUE-050: Set up OAuth provider configuration

Phase 2 (P1) - Core functionality:

ISSUE-051: Implement token exchange (blocked by ISSUE-050)
ISSUE-052: Build authentication flow (blocked by ISSUE-051)
ISSUE-054: Add security hardening (blocked by ISSUE-052)

Phase 3 (P2) - Enhancement:

ISSUE-053: Implement token refresh (blocked by ISSUE-051)

You can start with ISSUE-050, which is ready to work on now.”

Key Takeaways:

Break down specs into logical, manageable issues
Use implements relationship to link issues to specs
Use blocks relationship to model dependencies
Include spec references in issue descriptions using [[SPEC-ID]] syntax
Prioritize foundation work higher to unblock dependent issues

Workflow 3: Providing Feedback on Specs

Scenario: Agent discovers ambiguity while implementing and provides anchored feedback.

Agent is working on an issue

Agent is implementing ISSUE-025: “Implement session expiration”

Agent reviews related spec

Agent calls show_spec() to understand requirements:

{
  "tool": "show_spec",
  "parameters": {
    "spec_id": "SPEC-003"
  }
}

Spec mentions “tokens should expire appropriately” but doesn’t specify the expiration time.

Agent provides feedback

Agent calls add_feedback():

{
  "tool": "add_feedback",
  "parameters": {
    "issue_id": "ISSUE-025",
    "spec_id": "SPEC-003",
    "content": "Token expiration policy not specified. Recommend:\n- Access tokens: 15 minutes\n- Refresh tokens: 7 days\n- Session tokens: 24 hours\n\nPlease clarify in spec.",
    "type": "request",
    "line": 42
  }
}

Feedback is now anchored to line 42 of SPEC-003.

Agent continues with reasonable assumption

Agent responds: “I’ve added feedback to SPEC-003 requesting clarification on token expiration times. For now, I’ll proceed with industry-standard values (15min access tokens, 7-day refresh tokens). You can review and update the spec if different values are needed.”Agent continues implementation…

User reviews feedback later

User runs: sudocode feedback list --spec SPEC-003User sees the feedback, updates SPEC-003 with explicit expiration times.

Key Takeaways:

Provide feedback early when discovering ambiguities
Use request type for clarifications
Use suggestion type for improvements
Use comment type for observations
Anchor feedback to specific lines with line parameter
Continue with reasonable assumptions while waiting for clarification

Workflow 4: Research and Documentation

Scenario: Agent conducts research and creates a specification document.

User requests research

User: "Research OAuth 2.0 best practices and create a security spec"

Agent performs research

Agent gathers information about OAuth 2.0 security best practices…

Agent creates specification

Agent calls upsert_spec():

{
  "tool": "upsert_spec",
  "parameters": {
    "title": "OAuth 2.0 Security Best Practices",
    "description": "# OAuth 2.0 Security Best Practices\n\n## Overview\n\nThis spec outlines security best practices for implementing OAuth 2.0 authentication.\n\n## Key Practices\n\n### 1. State Parameter\n\nAlways use the state parameter to prevent CSRF attacks:\n- Generate cryptographically random state value\n- Store state in session\n- Validate state on callback\n\nReference: RFC 6749 Section 10.12\n\n### 2. Token Storage\n\nStore tokens securely:\n- Never store tokens in localStorage (XSS risk)\n- Use httpOnly cookies for refresh tokens\n- Store access tokens in memory only\n- Encrypt tokens at rest in database\n\n### 3. Token Expiration\n\nImplement short-lived tokens:\n- Access tokens: 15 minutes maximum\n- Refresh tokens: 7 days maximum\n- Implement token rotation for refresh tokens\n\n### 4. PKCE (Proof Key for Code Exchange)\n\nRequired for all OAuth flows:\n- Generate code_verifier (43-128 chars)\n- Compute code_challenge = SHA256(code_verifier)\n- Send code_challenge with authorization request\n- Send code_verifier with token exchange\n\nReference: RFC 7636\n\n### 5. Scope Validation\n\nValidate and limit scopes:\n- Request minimum necessary scopes\n- Validate scopes on token use\n- Never trust client-provided scopes\n\n## Related Specs\n\n- [[SPEC-005]] - OAuth 2.0 Authentication System (implementation)\n- [[SPEC-012]] - API Security Architecture\n\n## References\n\n- RFC 6749: OAuth 2.0 Authorization Framework\n- RFC 7636: PKCE\n- OWASP OAuth 2.0 Security Cheat Sheet",
    "priority": 0,
    "tags": ["security", "oauth", "research", "best-practices"]
  }
}

Returns: { "id": "SPEC-015" }

Agent links to related specs

Agent calls add_reference() to link related specs:

{
  "tool": "add_reference",
  "parameters": {
    "entity_id": "SPEC-015",
    "reference_id": "SPEC-005",
    "relationship_type": "related"
  }
}

Agent creates implementation issues

Agent calls upsert_issue() for follow-up work:

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Implement PKCE for OAuth flows",
    "description": "Add Proof Key for Code Exchange to all OAuth 2.0 flows as specified in [[SPEC-015]] section 4.",
    "priority": 0,
    "tags": ["security", "oauth", "pkce"]
  }
}

Returns: { "id": "ISSUE-060" }Agent links issue to spec:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-060",
    "to_id": "SPEC-015",
    "type": "implements"
  }
}

Agent summarizes

Agent responds: “Created SPEC-015: OAuth 2.0 Security Best Practices with comprehensive security guidelines. Also created ISSUE-060 to implement PKCE, which is a critical security enhancement. The spec includes references to related specifications and external RFCs.”

Key Takeaways:

Create specs for research and documentation
Use markdown formatting for clear structure
Include references to external sources (RFCs, documentation)
Link related specs using add_reference()
Create follow-up issues for implementation work
Use tags to categorize specs

Workflow 5: Multi-Agent Collaboration

Scenario: Multiple agents working on the same project, coordinating through issue status.

Agent A checks for work

Agent A calls ready():

{
  "tool": "ready",
  "parameters": {}
}

Returns:

{
  "issues": [
    { "id": "ISSUE-042", "title": "Add rate limiting", "priority": 1 },
    { "id": "ISSUE-043", "title": "Implement token refresh", "priority": 2 },
    { "id": "ISSUE-044", "title": "Add error handling", "priority": 2 }
  ]
}

Agent A claims work

Agent A calls upsert_issue():

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-042",
    "status": "in_progress"
  }
}

Agent A is now working on ISSUE-042.

Agent B checks for work

Agent B calls ready():

{
  "tool": "ready",
  "parameters": {}
}

Returns:

{
  "issues": [
    { "id": "ISSUE-043", "title": "Implement token refresh", "priority": 2 },
    { "id": "ISSUE-044", "title": "Add error handling", "priority": 2 }
  ]
}

Note: ISSUE-042 is NOT returned because it’s now in_progress.

Agent B claims different work

Agent B calls upsert_issue():

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-043",
    "status": "in_progress"
  }
}

Agent A and Agent B are now working independently on different issues.

Agent A discovers blocker

While working on ISSUE-042, Agent A discovers that ISSUE-050 must be completed first.Agent A calls upsert_issue() to create the blocker:

{
  "tool": "upsert_issue",
  "parameters": {
    "title": "Configure Redis for rate limiting",
    "description": "Set up Redis instance and connection pooling for rate limiter.\n\nDiscovered while working on [[ISSUE-042]]",
    "priority": 0,
    "tags": ["redis", "setup", "blocker"]
  }
}

Returns: { "id": "ISSUE-065" }

Agent A links the blocker

Agent A calls link():

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-065",
    "to_id": "ISSUE-042",
    "type": "blocks"
  }
}

Also uses discovered-from relationship:

{
  "tool": "link",
  "parameters": {
    "from_id": "ISSUE-065",
    "to_id": "ISSUE-042",
    "type": "discovered-from"
  }
}

Agent A updates status

Agent A calls upsert_issue() to mark ISSUE-042 as blocked:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-042",
    "status": "blocked",
    "description": "Add rate limiting middleware to all API endpoints.\n\n**Blocked by:** ISSUE-065 - Need Redis setup first"
  }
}

Agent A can now work on ISSUE-065 or find other work.

Agent A works on blocker

Agent A claims the blocker:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-065",
    "status": "in_progress"
  }
}

Agent A implements Redis configuration…

Agent A completes blocker

Agent A closes the blocker:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-065",
    "status": "closed",
    "description": "Set up Redis instance and connection pooling for rate limiter.\n\nCompleted:\n- Redis server configured on port 6379\n- Connection pool with 10 connections\n- Health check endpoint added"
  }
}

Now ISSUE-042 is automatically unblocked.

Agent A returns to original work

Agent A resumes ISSUE-042:

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-042",
    "status": "in_progress"
  }
}

Agent A completes the rate limiting implementation…

Key Takeaways:

Always check ready() before claiming - it filters out in-progress work
Update status to in_progress immediately when claiming
Create new issues for discovered blockers
Use blocks relationship to model blocking dependencies
Use discovered-from to track where work originated
Blocked issues automatically become ready when blockers close

Workflow 6: Handling Blocked Work

Scenario: Agent finds no ready work and investigates blockers.

Agent checks for ready work

Agent calls ready():

{
  "tool": "ready",
  "parameters": {}
}

Returns:

{
  "issues": []
}

No unblocked issues available.

Agent investigates blocked work

Agent calls list_issues() with status filter:

{
  "tool": "list_issues",
  "parameters": {
    "status": "blocked"
  }
}

Returns:

{
  "issues": [
    {
      "id": "ISSUE-047",
      "title": "Deploy authentication service",
      "status": "blocked",
      "priority": 0
    },
    {
      "id": "ISSUE-048",
      "title": "Add integration tests for OAuth",
      "status": "blocked",
      "priority": 1
    }
  ]
}

Agent examines specific blocked issue

Agent calls show_issue():

{
  "tool": "show_issue",
  "parameters": {
    "issue_id": "ISSUE-047"
  }
}

Returns:

{
  "id": "ISSUE-047",
  "title": "Deploy authentication service",
  "status": "blocked",
  "relationships": {
    "incoming": [
      {
        "from_id": "ISSUE-046",
        "from_type": "issue",
        "relationship_type": "blocks",
        "from_title": "Complete OAuth security audit"
      }
    ]
  }
}

ISSUE-047 is blocked by ISSUE-046.

Agent checks blocker status

Agent calls show_issue() on the blocker:

{
  "tool": "show_issue",
  "parameters": {
    "issue_id": "ISSUE-046"
  }
}

Returns:

{
  "id": "ISSUE-046",
  "title": "Complete OAuth security audit",
  "status": "open",
  "priority": 0,
  "description": "Security audit of OAuth implementation before deployment"
}

The blocker is open and ready to work on!

Agent offers to work on blocker

Agent responds: “No issues are immediately ready, but I found that ISSUE-047 (Deploy authentication service) is blocked by ISSUE-046 (Complete OAuth security audit). The blocker is ready to work on. Should I work on the security audit to unblock the deployment?”

User approves

User: "Yes, work on the security audit"

Agent claims blocker

Agent calls upsert_issue():

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-046",
    "status": "in_progress"
  }
}

Agent performs security audit…

Agent completes blocker

Agent calls upsert_issue():

{
  "tool": "upsert_issue",
  "parameters": {
    "issue_id": "ISSUE-046",
    "status": "closed",
    "description": "Security audit of OAuth implementation before deployment.\n\nAudit Results:\n- ✓ PKCE implementation verified\n- ✓ Token storage uses secure cookies\n- ✓ State parameter validated\n- ✓ CSRF protection in place\n- ✓ Rate limiting configured\n\nNo critical issues found. Safe to deploy."
  }
}

Now ISSUE-047 is automatically unblocked!

Agent notifies about unblocked work

Agent responds: “Security audit complete. ISSUE-047 is now unblocked and ready to work on.”

Key Takeaways:

When ready() returns empty, investigate blocked work
Use show_issue() to understand what’s blocking work
Blockers may themselves be ready to work on
Offer to work on blockers to unblock critical work
Closing blockers automatically unblocks dependent issues

Best Practices for AI Agents

Work Selection

Always check ready() first - Don’t claim work that’s blocked or in progress
Review show_issue() before claiming - Understand full context and requirements
Prioritize by priority field - Work on P0 issues before lower priority
Prefer foundation work - Unblock other work by completing blockers first

Status Management

Claim immediately - Set status: in_progress when starting work
Close with documentation - Update description with summary of work completed
Mark blocked promptly - Don’t leave blocked work in in_progress state
Create blockers early - Discover and document blockers as soon as possible

Feedback and Communication

Provide feedback early - Don’t wait until completion to report ambiguities
Use appropriate feedback types:
- request - When you need clarification or decisions
- suggestion - When you have improvement ideas
- comment - For observations or context
Anchor feedback to lines - Use line parameter for precise feedback
Continue with reasonable assumptions - Don’t block on feedback, proceed intelligently

Relationship Management

Link issues to specs - Use implements relationship
Model dependencies - Use blocks for hard blockers
Document discovery - Use discovered-from when finding new work
Cross-reference liberally - Use [[ID]] syntax in descriptions

Multi-Agent Coordination

Check ready() frequently - Status changes as others work
Update status promptly - Keep status current so others know what’s available
Create specific issues - Break down work into claimable units
Communicate through issues - Use issue descriptions to coordinate

Error Handling

When tool calls fail: Issue not found:

Error: Issue ISSUE-999 not found

→ Verify ID spelling, check if issue was deleted Status transition invalid:

Error: Cannot transition from closed to in_progress

→ Use correct status workflow: open → in_progress → closed Missing required fields:

Error: title is required for creating issues

→ Always provide required fields (title, content) when creating Relationship already exists:

Error: Relationship already exists

→ No action needed, relationship is already recorded Circular dependency:

Error: Would create circular dependency

→ Restructure dependencies to avoid cycles

Tool Usage Patterns

Common Combinations

Finding and claiming work:

ready() → Get available issues
show_issue() → Understand requirements
upsert_issue(status: in_progress) → Claim issue

Creating implementation plan:

show_spec() → Review specification
upsert_issue() × N → Create issues
link(implements) × N → Link to spec
link(blocks) × M → Model dependencies

Providing feedback:

show_spec() → Read spec content
add_feedback() → Anchor feedback
Continue with work...

Investigating blockers:

ready() → Check for work
list_issues(status: blocked) → Find blocked issues
show_issue() → See what's blocking
show_issue() → Check blocker status
upsert_issue(blocker, status: in_progress) → Work on blocker

Completing work:

upsert_issue(status: closed, description: ...) → Close with summary
Link discovered issues if any → link(discovered-from)
Add feedback to specs if needed → add_feedback()

When to Use Each Tool

ready

Starting a work session
After completing an issue (to find next work)
When checking what’s available to claim
Before multi-agent coordination

list_issues

Filtering by status, priority, tags
Finding blocked work
Searching for specific issues
Getting overview of project state

show_issue

Before claiming work (understand context)
Investigating relationships
Checking feedback on issue
Understanding why issue is blocked

upsert_issue

Creating new issues from specs
Claiming work (status → in_progress)
Completing work (status → closed)
Updating issue details
Marking as blocked

list_specs

Finding relevant specifications
Searching for spec topics
Getting project overview

show_spec

Before implementing spec
Before creating implementation plan
Before providing feedback
Understanding requirements

upsert_spec

Creating research documentation
Documenting architecture
Recording decisions
Creating feature specifications

link

Connecting issues to specs (implements)
Modeling blockers (blocks)
Recording dependencies (depends-on)
Tracking discovery (discovered-from)
Cross-referencing (references, related)

add_reference

Adding cross-references to existing content
Linking related work
Creating navigation between entities

add_feedback

Requesting clarifications (type: request)
Suggesting improvements (type: suggestion)
Adding observations (type: comment)
Anchoring to specific lines

MCP Overview

Setup and tool reference

CLI Reference

Command-line equivalents

Next Steps

Set up MCP integration

Follow the MCP setup guide to install and configure

Try basic workflow

Start with Workflow 1: Find work with ready(), claim with upsert_issue()

Create implementation plans

Practice Workflow 2: Break down specs into issues with relationships

Provide feedback

Use Workflow 3: Add anchored feedback to specs

Coordinate with other agents

Try Workflow 5: Multi-agent collaboration patterns

MCP Tools Reference

Complete reference for all 10 MCP tools with parameters and examples

MCP Server

​Overview

​Workflow 1: Claiming and Executing Work

​Workflow 2: Creating Implementation Plan

​Workflow 3: Providing Feedback on Specs

​Workflow 4: Research and Documentation

​Workflow 5: Multi-Agent Collaboration

​Workflow 6: Handling Blocked Work

​Best Practices for AI Agents

​Work Selection

​Status Management

​Feedback and Communication

​Relationship Management

​Multi-Agent Coordination

​Error Handling

​Tool Usage Patterns

​Common Combinations

​When to Use Each Tool

​Related Documentation

MCP Overview

CLI Reference

​Next Steps

MCP Tools Reference

Overview

Workflow 1: Claiming and Executing Work

Workflow 2: Creating Implementation Plan

Workflow 3: Providing Feedback on Specs

Workflow 4: Research and Documentation

Workflow 5: Multi-Agent Collaboration

Workflow 6: Handling Blocked Work

Best Practices for AI Agents

Work Selection

Status Management

Feedback and Communication

Relationship Management

Multi-Agent Coordination

Error Handling

Tool Usage Patterns

Common Combinations

When to Use Each Tool

Related Documentation

Next Steps