Issues

What Are Issues?

Issues are the second tier in sudocode’s 4-tier abstraction structure. They capture agent intent - the HOW to implement what specs define. Think of issues as actionable work items scoped to what an AI agent (or human developer) can accomplish in a single focused session.

Key Principle: Issues capture how to implement. Specs (tier 1) capture what to build. Issues are derived from specs and linked back to the requirements they fulfill.

An issue is a structured work item that represents a concrete, actionable task. Issues can be:

Implementation tasks - “Implement login endpoint”
Bug fixes - “Fix token expiration bug”
Feature work - “Add password reset flow”
Epics - “Build authentication system” (contains sub-issues)
Chores - “Update dependency versions”

Issues vs. Specs

Specs

User intent (WHAT)

High-level requirements
Written primarily by humans
Long-lived, evolve over time
Multiple issues per spec

Agent tasks (HOW)

Actionable implementation
Created by humans or agents
Closed when complete
One spec per issue (typically)

Rule of thumb: If it can be completed in one agent session or represents a single unit of work, it’s an issue. If it requires multiple independent tasks or is strategic/architectural, it’s a spec.

Issue Lifecycle

Issues progress through a well-defined lifecycle from creation to completion:

open - Ready to be worked on

Issues start as open when created. An open issue means:

Ready to be claimed by an agent or developer
No blocking dependencies (or blockers resolved)
Has sufficient detail to begin work
May be in the “ready” queue for execution

in_progress - Currently being worked on

When an agent or developer claims an issue:

Status changes to in_progress
Assignee is set to the agent/user
Other agents know this work is claimed
Implementation is actively happening

blocked - Waiting on dependencies

Issues can become blocked when:

Another issue must be completed first
External dependency is unavailable
Waiting for spec clarification
Blockers tracked via blocks relationships

needs_review - Implementation complete, awaiting review

After implementation is done but before closing:

Code changes awaiting review
Testing in progress
Validation needed
Feedback being incorporated

closed - Work completed

Issues are closed when:

Implementation is complete
Tests pass
Code reviewed and merged
Requirements fulfilled
Can be reopened if needed

Issue Types

Issues are categorized by type to help with organization and filtering:

Type	Purpose	Example
task	Implementation work	”Create login endpoint”
bug	Fix defects	”Fix token expiration bug”
feature	New functionality	”Add password reset flow”
epic	Large work with sub-issues	”Build authentication system”
chore	Maintenance work	”Update dependencies”

Issue Structure

Issues are stored as markdown files with YAML frontmatter in .sudocode/issues/:

File Format

---
id: ISSUE-001
title: Implement OAuth 2.0 token endpoint
description: Create REST endpoint for OAuth token exchange
status: in_progress
priority: 1
issue_type: task
assignee: agent-backend-dev
estimated_minutes: 120
created_at: 2025-10-29T10:00:00Z
updated_at: 2025-10-29T15:30:00Z
closed_at: null
created_by: agent-planner
tags: [auth, backend, api]
---

# Implement OAuth 2.0 token endpoint

Create REST endpoint for OAuth token exchange following RFC 6749.

## Description

Build the OAuth 2.0 token endpoint that handles authorization
code exchange and refresh token flows. This implements the
requirements from [[SPEC-001]].

## Design Notes

### Endpoint Details
- **URL:** `POST /api/auth/token`
- **Grant types:** `authorization_code`, `refresh_token`
- **Response:** JWT access token + refresh token
- **Expiration:** 1hr access, 30-day refresh

### Security
- Validate client credentials
- Verify authorization code hasn't been used
- Rate limit: 10 requests/minute per client
- Store refresh tokens securely hashed

## Acceptance Criteria

- [ ] Endpoint accepts valid authorization codes
- [ ] Returns valid JWT access tokens
- [ ] Handles refresh token flow
- [ ] Returns proper error codes for invalid requests
- [ ] Unit tests with >90% coverage
- [ ] Integration tests for both grant types

## Implementation Notes

Depends on [[@ISSUE-002]] (database schema) being completed first.

## Related Specs

This implements requirement #1 from [[SPEC-001]].

id: string                    # ISSUE-001, ISSUE-042, etc.
title: string                 # Short description (max 500 chars)
description: string           # Detailed problem statement
status: enum                  # open | in_progress | blocked | needs_review | closed
priority: int                 # 0-4 (0=highest, 2=default)
issue_type: enum              # bug | feature | task | epic | chore
assignee: string?             # Agent ID or username (null if unassigned)
estimated_minutes: int?       # Estimated effort (optional)
created_at: timestamp         # ISO 8601 format
updated_at: timestamp         # ISO 8601 format
closed_at: timestamp?         # When closed (null if open)
created_by: string            # Who created (user or agent)
tags: [string]                # Free-form labels for organization

Flexible Content: The markdown body is completely flexible. Common sections include Description, Design Notes, Acceptance Criteria, and Implementation Notes, but you can structure it however makes sense.

Cross-References

Issues support bidirectional linking to specs and other issues:

Link to Specs

Reference the spec(s) this issue implements:

This implements requirement #1 from [[SPEC-001]].

See also [[SPEC-010]] for API design patterns.

Link to Other Issues

Reference related issues:

Depends on [[@ISSUE-002]] (database schema) being completed first.

Related to [[@ISSUE-005]] (session management).

Automatic Backlinks: sudocode tracks all references automatically, enabling graph-based planning and dependency resolution.

Relationships and Dependencies

Issues can have typed relationships to model dependencies and connections:

Relationship Types

Type	Description	Example
blocks	Hard blocker dependency	”ISSUE-001 blocks ISSUE-002”
implements	Implements a spec	”ISSUE-001 implements SPEC-001”
parent-child	Epic/subtask hierarchy	”ISSUE-010 is parent of ISSUE-011”
related	Contextual connection	”ISSUE-001 related to ISSUE-005”
discovered-from	Found during implementation	”ISSUE-020 discovered from ISSUE-015”

Creating Dependencies

# ISSUE-002 cannot start until ISSUE-001 is done
sudocode link ISSUE-002 ISSUE-001 --type blocks

# ISSUE-001 implements SPEC-001
sudocode link ISSUE-001 SPEC-001 --type implements

# ISSUE-012 is a subtask of epic ISSUE-010
sudocode link ISSUE-012 ISSUE-010 --type parent-child

Relationships Documentation

Learn more about relationship types and graph-based planning

Hierarchical Organization

Issues can be organized hierarchically for complex work:

# Create an epic
sudocode issue create "Build Authentication System" \
  --issue-type epic \
  --priority 0

# Create subtasks
sudocode issue create "Implement login endpoint" \
  --parent ISSUE-001 \
  --priority 1

sudocode issue create "Implement registration endpoint" \
  --parent ISSUE-001 \
  --priority 1

sudocode issue create "Add password reset" \
  --parent ISSUE-001 \
  --priority 2

This creates a hierarchy:

ISSUE-001: Build Authentication System (epic)
├── ISSUE-002: Implement login endpoint
├── ISSUE-003: Implement registration endpoint
└── ISSUE-004: Add password reset

Use hierarchies to:

Break epics into manageable tasks
Organize related work items
Track progress on large features
Enable agent handoffs between subtasks

Priority Levels

Issues use a 0-4 priority scale (same as specs):

Priority Levels

0 - Critical (highest priority)
1 - High
2 - Medium (default)
3 - Low
4 - Lowest

Priority affects:

Execution order - Combined with topological ordering of dependencies
Ready queue - Higher priority issues surface first
Agent selection - Agents claim highest priority ready work

Storage and Versioning

Issues are stored in three synchronized layers:

.sudocode/
├── issues/
│   ├── issues.jsonl          # Source of truth (git-tracked)
│   ├── ISSUE-001.md          # Human-editable markdown
│   ├── ISSUE-002.md
│   └── ISSUE-003.md
└── cache.db                   # SQLite cache (gitignored)

Markdown Files (.md)

Purpose: Human-editable interface

Located in .sudocode/issues/
YAML frontmatter + markdown body
Edit directly or via CLI
Synced to JSONL automatically

JSONL File (issues.jsonl)

Purpose: Source of truth, git-tracked

One JSON object per line
Contains all issue data
Committed to version control
Used for distribution via git

SQLite Cache (cache.db)

Purpose: Fast queries and relationships

Rebuilt from JSONL after git pull
Enables efficient graph queries
Not committed to git
Auto-synced from JSONL

Git-Native: Issues are version-controlled alongside code. Track work history, see who did what, and understand evolution over time.

Best Practices

When to Create an Issue

✅ Good candidates for issues

Concrete implementation tasks
Bug fixes with clear reproduction steps
Work that can be completed in one session
Tasks scoped for a single agent or developer
Subtasks of a larger spec or epic
Actionable items with clear acceptance criteria

❌ Not good candidates for issues

Strategic decisions (create a spec instead)
Vague ideas without clear implementation path
Work requiring multiple independent components
High-level requirements (should be specs)

Writing Effective Issues

Clear, actionable title

Use verb phrases: “Implement X”, “Fix Y”, “Add Z”

Detailed description

Include enough context for someone to start work immediately

Concrete acceptance criteria

Use checkboxes for clear definition of “done”

Link to specs

Use [[SPEC-XXX]] to reference requirements

Specify dependencies

Use blocks relationships for hard dependencies

Estimate effort (optional)

Help with capacity planning and prioritization

Scoping Issues for Agents

Issues should be scoped to what an agent can complete in one focused session:

✅ Well-scoped

“Implement POST /api/auth/login endpoint”
“Fix token expiration validation bug”
“Add unit tests for user service”
“Update API documentation for auth endpoints”

❌ Too broad

“Build authentication system” (epic, not issue)
“Improve performance” (too vague)
“Refactor codebase” (too large)
“Add features” (not specific)

CLI Commands

Quick reference for working with issues:

# Create an issue
sudocode issue create "Feature Title" --type task --priority 1

# List all issues
sudocode issue list

# Filter by status or assignee
sudocode issue list --status in_progress --assignee agent-1

# View issue details
sudocode issue show ISSUE-001

# Update issue
sudocode issue update ISSUE-001 --status in_progress --assignee alice

# Close issue
sudocode issue close ISSUE-001

# Delete issue
sudocode issue delete ISSUE-001

Complete CLI Reference

See full documentation for all issue commands and options

Agent Workflows

Claiming and Executing Work

Agents use issues to coordinate work:

Query ready work

sudocode ready

Returns unblocked issues in priority order

Claim an issue

sudocode issue update ISSUE-001 \
  --status in_progress \
  --assignee agent-backend-dev

Implement and commit

Agent implements the feature and commits code

Provide feedback (if needed)

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Need token rotation policy specified" \
  --type request

Close the issue

sudocode issue close ISSUE-001

Handling Blocked Work

When an issue is blocked:

# Mark as blocked
sudocode issue update ISSUE-003 --status blocked

# See what's blocking it
sudocode issue show ISSUE-003

# View all blocked issues
sudocode issue list --status blocked

# Or use the blocked command
sudocode blocked

Common Workflows

Creating Issues from a Spec

Review the spec

sudocode spec show SPEC-001

Create implementation issues

sudocode issue create "Implement login endpoint" --priority 1
sudocode issue create "Implement registration endpoint" --priority 1
sudocode issue create "Add password reset flow" --priority 2

Link issues to spec

sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-002 SPEC-001 --type implements
sudocode link ISSUE-003 SPEC-001 --type implements

Model dependencies

# Registration depends on login being done first
sudocode link ISSUE-002 ISSUE-001 --type blocks

Converting a Bug Report to an Issue

Create bug issue

sudocode issue create "Fix token expiration bug" \
  --type bug \
  --priority 0 \
  --description "Users report tokens expiring too early"

Add reproduction steps

Edit .sudocode/issues/ISSUE-001.md to add:

Steps to reproduce
Expected behavior
Actual behavior
System information

Link to related spec (if applicable)

sudocode link ISSUE-001 SPEC-001 --type implements

Assign and track

sudocode issue update ISSUE-001 --assignee alice --status in_progress

Next Steps

Specs

Learn about specs - the high-level requirements issues implement

Relationships

Understand how to model dependencies and connections

Feedback System

See how to provide feedback on specs from issues

Issue Commands

Complete CLI reference for managing issues

​What Are Issues?

​Issues vs. Specs

Specs

Issues

​Issue Lifecycle

​Issue Types

​Issue Structure

​File Format

​Cross-References

​Link to Specs

​Link to Other Issues

​Relationships and Dependencies

​Relationship Types

​Creating Dependencies

Relationships Documentation

​Hierarchical Organization

​Priority Levels

​Storage and Versioning

​Best Practices

​When to Create an Issue

​Writing Effective Issues

​Scoping Issues for Agents

✅ Well-scoped

❌ Too broad

​CLI Commands

Complete CLI Reference

​Agent Workflows

​Claiming and Executing Work

​Handling Blocked Work

​Common Workflows

​Creating Issues from a Spec

​Converting a Bug Report to an Issue

​Next Steps

Specs

Relationships

Feedback System

Issue Commands

What Are Issues?

Issues vs. Specs

Issue Lifecycle

Issue Types

Issue Structure

File Format

Cross-References

Link to Specs

Link to Other Issues

Relationships and Dependencies

Relationship Types

Creating Dependencies

Hierarchical Organization

Priority Levels

Storage and Versioning

Best Practices

When to Create an Issue

Writing Effective Issues

Scoping Issues for Agents

CLI Commands

Agent Workflows

Claiming and Executing Work

Handling Blocked Work

Common Workflows

Creating Issues from a Spec

Converting a Bug Report to an Issue

Next Steps