sudocode issue create

Syntax

sudocode issue create <title> [options]

Description

The issue create command creates a new issue in your sudocode project. Issues are the second tier in sudocode’s abstraction structure, capturing how to implement what specs define. When you create an issue, sudocode:

Generates a unique issue ID (e.g., ISSUE-001, ISSUE-002)
Stores the issue in the SQLite database with status open
Exports to JSONL for version control
Applies any tags and assignee you specify

Issues represent concrete, actionable tasks scoped to what an agent (or human) can complete in a single focused session.

Arguments

string

required

The title of your issueExample: "Implement OAuth 2.0 token endpoint"The title should be clear and action-oriented. Use verb phrases like “Implement X”, “Fix Y”, or “Add Z”.

Options

number

default:"2"

Priority level (0-4, where 0 is highest)Example: --priority 1Priority levels:

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

Priority affects execution order when combined with dependency resolution.

string

Initial description/content for the issueExample: --description "Create REST endpoint for OAuth token exchange"This becomes the content of the issue. You can provide detailed information, acceptance criteria, or implementation notes.

string

Assignee for the issueExample: --assignee "agent-backend-dev"Can be an agent ID, username, or any identifier for who should work on this issue.

string

Parent issue ID for hierarchical organizationExample: --parent ISSUE-001Use this to create subtasks under a parent issue (epic), enabling hierarchical organization of work.

string

Comma-separated tags for organizationExample: --tags "backend,api,auth"Tags help with filtering and organizing issues. Use commas to separate multiple tags (no spaces).

Examples

Basic Issue Creation

Create a simple issue with default priority:

sudocode issue create "Implement login endpoint"

Expected output

✓ Created issue ISSUE-001
  Title: Implement login endpoint

This creates:

Issue ID: ISSUE-001
Status: open
Priority: 2 (default)
No assignee

Issue with Description and Priority

Create a high-priority issue with detailed description:

sudocode issue create "Fix token expiration bug" \
  --priority 0 \
  --description "Users report tokens expiring after 5 minutes instead of 1 hour. Need to investigate and fix."

Expected output

✓ Created issue ISSUE-002
  Title: Fix token expiration bug

Issue with Assignee

Create an issue and assign it immediately:

sudocode issue create "Add unit tests for auth service" \
  --priority 2 \
  --assignee "agent-testing"

Expected output

✓ Created issue ISSUE-003
  Title: Add unit tests for auth service
  Assignee: agent-testing

Subtask (Child Issue)

Create a subtask under a parent issue:

sudocode issue create "Build authentication system" \
  --priority 0

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

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

Expected output

✓ Created issue ISSUE-001
  Title: Build authentication system

✓ Created issue ISSUE-002
  Title: Implement login endpoint

✓ Created issue ISSUE-003
  Title: Implement registration endpoint

This creates a hierarchy:

ISSUE-001: Build authentication system (parent/epic)
├── ISSUE-002: Implement login endpoint (subtask)
└── ISSUE-003: Implement registration endpoint (subtask)

Issue with Tags

Create an issue with multiple tags:

sudocode issue create "Implement rate limiting" \
  --priority 1 \
  --tags "api,security,performance"

Expected output

✓ Created issue ISSUE-004
  Title: Implement rate limiting

Complete Issue with All Options

Create a fully-specified issue:

sudocode issue create "Add password reset flow" \
  --priority 1 \
  --description "Implement email-based password reset with secure tokens" \
  --assignee "agent-backend-dev" \
  --tags "auth,email,security"

Expected output

✓ Created issue ISSUE-005
  Title: Add password reset flow
  Assignee: agent-backend-dev

After Creating an Issue

After creating your issue, you can:

Link to Spec

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

View Issue Details

sudocode issue show ISSUE-001

Update Status

sudocode issue update ISSUE-001 --status in_progress

Create Dependencies

sudocode link ISSUE-002 ISSUE-001 --type blocks

Issue Lifecycle

Issues progress through these statuses:

open (default)

Ready to be worked on

in_progress

Currently being worked on

blocked

Waiting on dependencies

needs_review

Implementation complete, awaiting review

closed

Work completed

Use sudocode issue update to change status as work progresses.

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

# Login must be done before registration
sudocode link ISSUE-001 ISSUE-002 --type blocks

Creating an Epic with Subtasks

Create the epic

sudocode issue create "Build Authentication System" \
  --priority 0 \
  --tags "epic,auth"

Create subtasks

sudocode issue create "Database schema" --parent ISSUE-001 --priority 1
sudocode issue create "API endpoints" --parent ISSUE-001 --priority 1
sudocode issue create "UI components" --parent ISSUE-001 --priority 2

Assign subtasks

sudocode issue update ISSUE-002 --assignee "agent-backend"
sudocode issue update ISSUE-003 --assignee "agent-backend"
sudocode issue update ISSUE-004 --assignee "agent-frontend"

Bug Report to Issue

Create bug issue

sudocode issue create "Fix token expiration bug" \
  --priority 0 \
  --description "Users report tokens expiring too early. Steps to reproduce: 1) Login, 2) Wait 5 min, 3) Token invalid" \
  --tags "bug,auth,critical"

Assign immediately

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

Link to spec if applicable

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

JSON Output

Use the global --json flag for machine-readable output:

sudocode --json issue create "Test Issue" --priority 1 --assignee "alice"

JSON output

{
  "id": "ISSUE-001",
  "title": "Test Issue",
  "status": "open"
}

Common Questions

Can I change the issue ID after creation?

No, issue IDs are immutable and generated sequentially. They ensure stable references across the system.

What's the difference between an issue and a spec?

Specs capture WHAT to build (user intent, requirements, design decisions).Issues capture HOW to implement (actionable tasks, implementation details).Rule of thumb: If it can be completed in one agent session, it’s an issue. If it requires multiple independent tasks, it’s a spec.

Can I create an issue without linking to a spec?

Yes! Issues can exist independently. While it’s common to link issues to specs with implements relationships, it’s not required. Bug fixes and chores often don’t need specs.

How do I claim an issue for myself?

Use issue update to set yourself as assignee:

sudocode issue update ISSUE-001 --assignee "your-name"

Can I have nested epics (parent of parent)?

Yes, you can create hierarchical issue structures with multiple levels:

sudocode issue create "Major Feature" --priority 0
sudocode issue create "Phase 1" --parent ISSUE-001
sudocode issue create "Task A" --parent ISSUE-002

Troubleshooting

Error: sudocode not initialized

Cause: No .sudocode/ directory foundSolution:

sudocode init

Error: Invalid priority value

Cause: Priority must be 0-4Solution:

sudocode issue create "My Issue" --priority 2

Error: Parent issue not found

Cause: The parent issue ID doesn’t existSolution: Verify the parent issue exists:

sudocode issue show ISSUE-001

Create the parent issue first if needed.

Issue created but I can't find it

Cause: Issues are stored in the database, not as visible files by defaultSolution: List all issues:

sudocode issue list

View specific issue:

sudocode issue show ISSUE-001

issue list

List all issues with filtering

issue show

View issue details

issue update

Update existing issue

issue close

Close completed issues

link

Link issues to specs

ready

Find ready work

Next Steps

Create your first issue

sudocode issue create "My Task" --priority 1

Link to a spec

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

Start working on it

sudocode issue update ISSUE-001 --status in_progress --assignee "you"

Complete and close

sudocode issue close ISSUE-001

Issues Concept Guide

Learn more about issues and their role in sudocode’s workflow

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

sudocode issue create

Syntax

Description

Arguments

Options

Examples

Basic Issue Creation

Issue with Description and Priority

Issue with Assignee

Subtask (Child Issue)

Issue with Tags

Complete Issue with All Options

After Creating an Issue

Link to Spec

View Issue Details

Update Status

Create Dependencies

Issue Lifecycle

Common Workflows

Creating Issues from a Spec

Creating an Epic with Subtasks

Bug Report to Issue

JSON Output

Common Questions

Troubleshooting

issue list

issue show

issue update

issue close

link

ready

Next Steps

Issues Concept Guide

​Syntax

​Description

​Arguments

​Options

​Examples

​Basic Issue Creation

​Issue with Description and Priority

​Issue with Assignee

​Subtask (Child Issue)

​Issue with Tags

​Complete Issue with All Options

​After Creating an Issue

Link to Spec

View Issue Details

Update Status

Create Dependencies

​Issue Lifecycle

​Common Workflows

​Creating Issues from a Spec

​Creating an Epic with Subtasks

​Bug Report to Issue

​JSON Output

​Common Questions

​Troubleshooting

​Related Commands

issue list

issue show

issue update

issue close

link

ready

​Next Steps

Issues Concept Guide

Syntax

Description

Arguments

Options

Examples

Basic Issue Creation

Issue with Description and Priority

Issue with Assignee

Subtask (Child Issue)

Issue with Tags

Complete Issue with All Options

After Creating an Issue

Issue Lifecycle

Common Workflows

Creating Issues from a Spec

Creating an Epic with Subtasks

Bug Report to Issue

JSON Output

Common Questions

Troubleshooting

Related Commands

Next Steps