> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Executing Issues
> How agents discover, claim, and complete issues using the sudocode MCP server
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.
```
> 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: 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.
```
⏺ 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"]
}
```
```
⏺ 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.
````
⏺ 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.
```
⏺ Agent: While implementing rate limiting, I discovered we need Redis
configured first.
```
```
⏺ 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" }
```
```
⏺ 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:
```mermaid theme={null}
graph LR
A[open] --> B[in_progress]
B --> C[closed]
A --> D[blocked]
B --> D
D --> A
style A fill:#6B9AFF
style B fill:#A855F7
style D fill:#EF4444
style C fill:#10B981
```
**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.
```
## Related Documentation
How to create and organize implementation issues
Writing specifications for requirements
Practical workflow examples
Guidelines for effective agent work