Skip to main content
This page contains best practices specifically for AI agents using the sudocode MCP server. These guidelines help agents work effectively with the sudocode workflow. Feel free to read them to understand how agents typically use sudocode!

​
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: 
1. ready() → Get available issues
2. show_issue() → Understand requirements
3. upsert_issue(status: in_progress) → Claim issue
Creating implementation plan: 
1. show_spec() → Review specification
2. upsert_issue() × N → Create issues
3. link(implements) × N → Link to spec
4. link(blocks) × M → Model dependencies
Providing feedback: 
1. show_spec() → Read spec content
2. add_feedback() → Anchor feedback
3. Continue with work...
Investigating blockers: 
1. ready() → Check for work
2. list_issues(status: blocked) → Find blocked issues
3. show_issue() → See what's blocking
4. show_issue() → Check blocker status
5. upsert_issue(blocker, status: in_progress) → Work on blocker
Completing work: 
1. upsert_issue(status: closed, description: ...) → Close with summary
2. Link discovered issues if any → link(discovered-from)
3. 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

Agent Workflow Examples

Practical examples of AI agents using sudocode

MCP Overview

Setup and tool reference

CLI Reference

Command-line equivalents