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.
- 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...",
...
}
- 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 ✓
- 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```"
)
comment - Implementation results, what was built (most common)suggestion - Spec needs updates based on learningsrequest - 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.
