> ## 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.

# Issue Management

> Manage and coordinate issues through the sudocode web interface

## Overview

The sudocode web server provides a visual Kanban-style interface for managing issues. Unlike spec creation (which currently lives in the MCP server), issue management is fully supported in the web interface.

<Frame>
  <img src="https://mintcdn.com/sudocode/Ik176kmcsPL91kj4/images/web/issues.png?fit=max&auto=format&n=Ik176kmcsPL91kj4&q=85&s=d45773f8b12b48f2bf7bb9965ef41c22" alt="sudocode issues board" width="5086" height="2380" data-path="images/web/issues.png" />
</Frame>

## Issue Board

The issue board shows all your issues organized by status:

* **Open** - Ready to work on (no blockers)
* **In Progress** - Currently being worked on
* **Blocked** - Waiting on dependencies
* **Closed** - Completed

### Drag and Drop

Simply drag issues between columns to update their status:

```
Open → In Progress    (Start working)
In Progress → Closed  (Complete work)
In Progress → Blocked (Hit a blocker)
Blocked → Open        (Blocker resolved)
```

The web server automatically syncs these changes to the underlying `.sudocode/issues/` files.

## Filtering and Search

Use the filter controls to focus on specific work:

* **Priority**: Filter by priority level (0-4)
* **Tags**: Show only issues with specific tags
* **Search**: Search issue titles and descriptions
* **Assignee**: Filter by who's working on what

## Issue Creation

The current recommended way to create issues is through AI agents using the MCP server:

<Card title="Issue Creation via MCP" icon="robot" href="/mcp/issue-creation">
  Learn how agents create and manage issues
</Card>

The MCP server provides tools for:

* Creating new issues with `upsert_issue`
* Setting priority, status, tags, and descriptions
* Linking issues to specs they implement
* Creating parent-child issue relationships

<Info>
  **Web-based issue creation is in development.** For now, use the MCP server or CLI for creating issues, and the web interface for managing and dispatching them.
</Info>

## Issue Linking

Connecting issues to specs and other issues is done through the MCP server:

<Card title="Creating Relationships" icon="link" href="/mcp/issue-creation">
  Learn how to link issues using the MCP server
</Card>

The MCP server's `link` tool creates relationships between entities:

**Common relationship types:**

* `implements` - Issue implements a spec or another issue
* `blocks` - Issue must complete before another can start
* `depends-on` - Issue depends on another completing first
* `related` - General relationship between entities

**Example:**

```
link(from_id="i-abc123", to_id="s-xyz789", type="implements")
```

This creates the dependency graph that determines which issues are ready to work on.

<Info>
  **Web-based issue linking is in development.** For now, use the MCP server or CLI for linking issues, and the web interface for managing and dispatching them.
</Info>

## Dispatching Issues to Agents

Dispatch agents directly through the web-server, with the click of a button.

<Frame>
  <img src="https://mintcdn.com/sudocode/Ik176kmcsPL91kj4/images/web/dispatch.png?fit=max&auto=format&n=Ik176kmcsPL91kj4&q=85&s=4543157fa4684bc85d5a96d58e85b0ce" alt="sudocode issues board dispatching" width="5106" height="2382" data-path="images/web/dispatch.png" />
</Frame>

### How It Works

The dispatch workflow is simple and visual:

1. **Click an Issue**: Select any issue from the Kanban board to view its details in the right panel
2. **Configure Agent**: Choose your agent (Claude, custom agent, etc.) from the dropdown
3. **Configure Branch**: Have the agent run from a worktree (default) or from your local project directory.
4. **Add Context** (Optional): Provide additional instructions or context for the agent
5. **Press Enter or Click Start**: Launch the agent - it starts working immediately in the specified environment.

### Running Multiple Issues Simultaneously

The real power comes from parallel execution:

<Steps>
  <Step title="Select First Issue">
    Click an issue and hit "Run in worktree" - the agent starts working
  </Step>

  <Step title="Select Next Issue">
    Immediately select another ready issue (no blockers)
  </Step>

  <Step title="Launch Another Agent">
    Click Run again - a second agent starts in parallel
  </Step>

  <Step title="Monitor All Agents">
    Watch the "Activity" section on each issue to see real-time progress across all running agents
  </Step>
</Steps>

**Key benefits:**

* Each agent can work in its own isolated worktree (no conflicts)
* Run as many agents as you want in parallel
* Web server coordinates and monitors all agents
* Real-time updates show progress across all work
* Agents automatically provide feedback when complete

### Agent Worktrees

When you click "Run in worktree", the web server:

1. Creates an isolated git worktree for the agent
2. Launches the agent with MCP access to the sudocode database
3. Provides the issue context and any additional instructions
4. Monitors the agent's progress in real-time
5. Collects feedback when the agent completes

This isolation means multiple agents can work on different issues simultaneously without interfering with each other or your main branch.

## Issue Details

Click any issue to see full details:

* **Description**: Full markdown content
* **Implements**: Which spec(s) and issue(s) this issue implements
* **Blocked By**: Dependencies that must complete first
* **Blocks**: Issues waiting on this one
* **Feedback**: Agent feedback from implementation
* **Related**: Connected issues and specs

## Best Practices

<AccordionGroup>
  <Accordion title="Link Issues to Specs">
    Issues can implement specs. Use the `implements` relationship to connect them.

    ```markdown theme={null}
    [[s-abc123]]{implements}
    ```
  </Accordion>

  <Accordion title="Define Dependencies Clearly">
    Use `blocks` and `depends-on` relationships to establish work order. This helps the `ready` command show only unblocked work. Use the MCP server to manage these links.
  </Accordion>

  <Accordion title="Keep Issues Focused">
    Each issue should be a single, completable unit of work. Break large features into multiple issues.
  </Accordion>

  <Accordion title="Review Agent Feedback">
    When agents complete issues, they provide feedback on the spec. Review this to improve future specs.
  </Accordion>
</AccordionGroup>

## Workflow Example

Here's a typical workflow using the web interface:

<Steps>
  <Step title="View Ready Work">
    Open the web interface and see all ready (unblocked) issues
  </Step>

  <Step title="Select an Issue">
    Choose an issue to work on based on priority and dependencies
  </Step>

  <Step title="Dispatch to Agent">
    Click the Run button and configure which agent should work on it
  </Step>

  <Step title="Monitor Progress">
    Watch real-time updates as the agent works
  </Step>

  <Step title="Review Results">
    When complete, review the agent's implementation and feedback
  </Step>

  <Step title="Merge or Iterate">
    Either merge the issue results or continue the conversation with the agent to guide it further
  </Step>
</Steps>

## Real-Time Sync

The web server provides real-time updates via WebSockets:

* See changes as agents work
* File watcher detects external edits (CLI, direct file edits)
* Automatic sync across all connected browser clients
* No manual refresh needed

## Next Steps

<CardGroup cols={2}>
  <Card title="Issue Creation via MCP" icon="robot" href="/mcp/issue-creation">
    Learn how agents create issues
  </Card>

  <Card title="Feedback Workflows" icon="comments" href="/web/feedback-workflows">
    Manage and review agent feedback
  </Card>

  <Card title="CLI Issue Commands" icon="terminal" href="/cli/issue-create">
    Use the command-line interface
  </Card>

  <Card title="Core Concepts: Issues" icon="book" href="/concepts/issues">
    Understand issue fundamentals
  </Card>
</CardGroup>