Executing Issues

Agents execute issues to implement specifications and deliver working code. This page covers the complete lifecycle from discovery to completion.

Discovering Ready Issues

Agents use the ready command to find issues that are unblocked and available to work on.

Check for ready work

> User: Can you work on what's ready?

⏺ Agent: I'll check what issues are ready to work on.

⏺ plugin:sudocode:sudocode - ready (MCP)()
  ⎿  {
       "ready": {
         "issues": [
           {
             "id": "i-yy9c",
             "title": "Implement EditorService for detection and launching",
             "priority": 1
           },
           {
             "id": "i-78fl",
             "title": "Add .sudocode/config.local.json to .gitignore",
             "priority": 2
           }
         ]
       }
     }

Agent prioritizes work

⏺ Agent: I found 2 ready issues. Since i-yy9c has higher priority (P1),
I'll work on implementing the EditorService.

What makes an issue “ready”:

Status is open (not in_progress or closed)
No blocking dependencies (all blockers are closed)
Appears in the ready queue in priority order

The ready command automatically filters out blocked work, so agents can trust that everything returned is safe to claim.

Understanding Issue Context

Before claiming an issue, agents will review context as needed to understand requirements and relationships.

Get issue details

⏺ plugin:sudocode:sudocode - show_issue (MCP)(issue_id: "i-yy9c")
  ⎿  {
       "id": "i-yy9c",
       "title": "Implement EditorService for detection and launching",
       "content": "Create backend service that detects and launches editors...",
       "status": "open",
       "priority": 1,
       "relationships": {
         "outgoing": [
           {
             "to_id": "s-7mug",
             "relationship_type": "implements"
           }
         ],
         "incoming": []
       },
       "tags": ["backend", "editor-service"]
     }

Review the spec

⏺ Agent: Let me check the spec this implements to get more context.

⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-7mug")
  ⎿  {
       "id": "s-7mug",
       "title": "Open in IDE - Global User Preference",
       "content": "## Goals\n\nSingle-click launch of worktree in user's preferred editor...",
       ...
     }

Why review context:

Understand what the issue implements (linked specs, issues, feedback)
Check for dependencies and blockers
See feedback from previous work
Identify related issues

Claiming an Issue

Agents claim issues by updating the status to in_progress. This signals to other agents that the work is taken.

⏺ Agent: Perfect! I'll start working on the EditorService implementation.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-yy9c",
                                                  status: "in_progress")
  ⎿  {
       "id": "i-yy9c",
       "status": "in_progress",
       "updated_at": "2025-12-06 15:30:00"
     }

Implementing the Issue

Once claimed, agents implement the requirements by writing code, creating files, and making changes.

⏺ Agent: Now let me implement the EditorService...

[Agent creates files, writes code, runs tests]

⏺ Agent: I've created:
- server/src/services/editor-service.ts
- server/tests/unit/services/editor-service.test.ts

All 24 tests passing ✓

During implementation:

Reference the spec for requirements
Create necessary files and code
Run tests to verify functionality
Handle errors and edge cases

Providing Feedback on Specs

When an issue implements a spec, agents will provide feedback before closing the issue. This creates a record of what was accomplished and helps improve specs.

Document implementation results

⏺ plugin:sudocode:sudocode - add_feedback (MCP)(
    issue_id: "i-yy9c",
    to_id: "s-7mug",
    type: "comment",
    content: "## Implementation Complete\n\nSuccessfully implemented the EditorService backend service...\n\n### What Was Accomplished\n\n1. **EditorService Class**\n   - ✅ Complete service implementation\n   - ✅ Configuration management\n   - ✅ Editor detection for 6 editor types\n\n2. **Security & Validation**\n   - ✅ Path validation\n   - ✅ Command injection prevention\n\n3. **Unit Tests**\n   - ✅ 24 comprehensive tests\n   - ✅ All tests passing\n\n### Design Decisions\n\n- Used detached processes to avoid blocking\n- Auto-detection uses first available editor\n\n### Evidence of Completion\n\n```bash\nnpm test -- editor-service.test.ts\n✓ 24 tests passed\n```"
  )

Feedback types:

comment - Implementation results, what was built (most common)
suggestion - Spec needs updates based on learnings
request - Need clarification or spec is incomplete

What to include in feedback:

Requirements met from the spec
Design decisions made during implementation
Challenges encountered and how they were resolved
Evidence of completion (test results, screenshots)

Detailed feedback helps users understand what was built and helps future agents learn from implementation experience.

Closing the Issue

After implementation is complete and feedback is provided, agents close the issue.

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-yy9c",
                                                  status: "closed")
  ⎿  {
       "id": "i-yy9c",
       "status": "closed",
       "closed_at": "2025-12-06 17:45:00"
     }

⏺ Agent: Completed i-yy9c. EditorService is implemented and ready for API integration.

After closing, users should verify:

Implementation is complete (including any testing)
Feedback provided (if implements spec)
Documentation updated (if needed)

Handling Blocked Issues

Sometimes agents discover blockers during implementation. When this happens, update the issue status and create blocker issues.

Discover blocker during work

⏺ Agent: While implementing rate limiting, I discovered we need Redis
configured first.

Create blocker issue

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(
    title: "Configure Redis for rate limiting",
    description: "Set up Redis instance and connection pooling.\n\nDiscovered while working on [[i-abc123]]",
    priority: 0,
    tags: ["redis", "setup", "blocker"]
  )
  ⎿  { "id": "i-xyz789" }

Link blocker

⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-xyz789",
                                         to_id: "i-abc123",
                                         type: "blocks")

⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "i-xyz789",
                                         to_id: "i-abc123",
                                         type: "discovered-from")

Status Transitions

Issues follow a defined status lifecycle: Valid transitions:

open → in_progress (claiming work)
in_progress → closed (completing work)
open → blocked (discovered blocker before starting)
in_progress → blocked (discovered blocker during work)
blocked → open (blocker resolved, issue becomes ready again)

When a blocker is resolved, the issue returns to open status and appears in the ready() queue. An agent must then claim it again by setting status: in_progress.

Complete Execution Example

Here’s a full execution flow from discovery to completion:

> User: Can you work on what's ready?

⏺ Agent: I'll check what issues are ready to work on.
⏺ plugin:sudocode:sudocode - ready (MCP)()
  → Found 2 issues: i-yy9c (P1), i-78fl (P2)

⏺ Agent: I'll work on i-yy9c (higher priority).
⏺ plugin:sudocode:sudocode - show_issue (MCP)(issue_id: "i-yy9c")
⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-7mug")
  → Reviewed requirements

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-yy9c",
                                                  status: "in_progress")
  → Claimed issue

⏺ Agent: Implementing EditorService...
[Creates files, writes code, runs tests]

⏺ plugin:sudocode:sudocode - add_feedback (MCP)(issue_id: "i-yy9c",
                                                  to_id: "s-7mug",
                                                  type: "comment",
                                                  content: "## Implementation Complete...")
  → Provided detailed feedback

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)(issue_id: "i-yy9c",
                                                  status: "closed")
  → Closed issue

⏺ Agent: Completed i-yy9c! EditorService is implemented with 24 passing tests.

Creating Issues

How to create and organize implementation issues

Creating Specs

Writing specifications for requirements

Agent Workflows

Practical workflow examples

Agent Best Practices

Guidelines for effective agent work

MCP Server

MCP Workflow Examples

Discovering Ready Issues

Understanding Issue Context

Claiming an Issue

Implementing the Issue

Providing Feedback on Specs

Closing the Issue

Handling Blocked Issues

Status Transitions

Complete Execution Example

Creating Issues

Creating Specs

Agent Workflows

Agent Best Practices

​Discovering Ready Issues

​Understanding Issue Context

​Claiming an Issue

​Implementing the Issue

​Providing Feedback on Specs

​Closing the Issue

​Handling Blocked Issues

​Status Transitions

​Complete Execution Example

​Related Documentation

Creating Issues

Creating Specs

Agent Workflows

Agent Best Practices

Discovering Ready Issues

Understanding Issue Context

Claiming an Issue

Implementing the Issue

Providing Feedback on Specs

Closing the Issue

Handling Blocked Issues

Status Transitions

Complete Execution Example

Related Documentation