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

# sudocode issue create

> Create a new issue to represent an actionable work item that can be assigned and tracked

## Syntax

```bash theme={null}
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

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

## Arguments

<ParamField path="title" type="string" required>
  The title of your issue

  **Example:** `"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".
</ParamField>

## Options

<ParamField path="-p, --priority" type="number" default="2">
  Priority level (0-4, where 0 is highest)

  **Example:** `--priority 1`

  Priority levels:

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

  Priority affects execution order when combined with dependency resolution.
</ParamField>

<ParamField path="-d, --description" type="string">
  Initial description/content for the issue

  **Example:** `--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.
</ParamField>

<ParamField path="-a, --assignee" type="string">
  Assignee for the issue

  **Example:** `--assignee "agent-backend-dev"`

  Can be an agent ID, username, or any identifier for who should work on this issue.
</ParamField>

<ParamField path="--parent" type="string">
  Parent issue ID for hierarchical organization

  **Example:** `--parent ISSUE-001`

  Use this to create subtasks under a parent issue (epic), enabling hierarchical organization of work.
</ParamField>

<ParamField path="--tags" type="string">
  Comma-separated tags for organization

  **Example:** `--tags "backend,api,auth"`

  Tags help with filtering and organizing issues. Use commas to separate multiple tags (no spaces).
</ParamField>

## Examples

### Basic Issue Creation

Create a simple issue with default priority:

```bash theme={null}
sudocode issue create "Implement login endpoint"
```

<Accordion title="Expected output">
  ```
  ✓ Created issue ISSUE-001
    Title: Implement login endpoint
  ```
</Accordion>

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:

```bash theme={null}
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."
```

<Accordion title="Expected output">
  ```
  ✓ Created issue ISSUE-002
    Title: Fix token expiration bug
  ```
</Accordion>

### Issue with Assignee

Create an issue and assign it immediately:

```bash theme={null}
sudocode issue create "Add unit tests for auth service" \
  --priority 2 \
  --assignee "agent-testing"
```

<Accordion title="Expected output">
  ```
  ✓ Created issue ISSUE-003
    Title: Add unit tests for auth service
    Assignee: agent-testing
  ```
</Accordion>

### Subtask (Child Issue)

Create a subtask under a parent issue:

```bash theme={null}
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
```

<Accordion title="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
  ```
</Accordion>

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:

```bash theme={null}
sudocode issue create "Implement rate limiting" \
  --priority 1 \
  --tags "api,security,performance"
```

<Accordion title="Expected output">
  ```
  ✓ Created issue ISSUE-004
    Title: Implement rate limiting
  ```
</Accordion>

### Complete Issue with All Options

Create a fully-specified issue:

```bash theme={null}
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"
```

<Accordion title="Expected output">
  ```
  ✓ Created issue ISSUE-005
    Title: Add password reset flow
    Assignee: agent-backend-dev
  ```
</Accordion>

## After Creating an Issue

After creating your issue, you can:

<CardGroup cols={2}>
  <Card title="Link to Spec" icon="link" href="/cli/link">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Card>

  <Card title="View Issue Details" icon="eye" href="/cli/issue-show">
    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Card>

  <Card title="Update Status" icon="pen-to-square" href="/cli/issue-update">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress
    ```
  </Card>

  <Card title="Create Dependencies" icon="diagram-project">
    ```bash theme={null}
    sudocode link ISSUE-002 ISSUE-001 --type blocks
    ```
  </Card>
</CardGroup>

## Issue Lifecycle

Issues progress through these statuses:

<Steps>
  <Step title="open (default)">
    Ready to be worked on
  </Step>

  <Step title="in_progress">
    Currently being worked on
  </Step>

  <Step title="blocked">
    Waiting on dependencies
  </Step>

  <Step title="needs_review">
    Implementation complete, awaiting review
  </Step>

  <Step title="closed">
    Work completed
  </Step>
</Steps>

Use `sudocode issue update` to change status as work progresses.

## Common Workflows

### Creating Issues from a Spec

<Steps>
  <Step title="Review the spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>

  <Step title="Create implementation issues">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Link issues to spec">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    sudocode link ISSUE-002 SPEC-001 --type implements
    sudocode link ISSUE-003 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Model dependencies">
    ```bash theme={null}
    # Login must be done before registration
    sudocode link ISSUE-001 ISSUE-002 --type blocks
    ```
  </Step>
</Steps>

### Creating an Epic with Subtasks

<Steps>
  <Step title="Create the epic">
    ```bash theme={null}
    sudocode issue create "Build Authentication System" \
      --priority 0 \
      --tags "epic,auth"
    ```
  </Step>

  <Step title="Create subtasks">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Assign subtasks">
    ```bash theme={null}
    sudocode issue update ISSUE-002 --assignee "agent-backend"
    sudocode issue update ISSUE-003 --assignee "agent-backend"
    sudocode issue update ISSUE-004 --assignee "agent-frontend"
    ```
  </Step>
</Steps>

### Bug Report to Issue

<Steps>
  <Step title="Create bug issue">
    ```bash theme={null}
    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"
    ```
  </Step>

  <Step title="Assign immediately">
    ```bash theme={null}
    sudocode issue update ISSUE-001 \
      --assignee "alice" \
      --status in_progress
    ```
  </Step>

  <Step title="Link to spec if applicable">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>
</Steps>

## JSON Output

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

```bash theme={null}
sudocode --json issue create "Test Issue" --priority 1 --assignee "alice"
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "id": "ISSUE-001",
    "title": "Test Issue",
    "status": "open"
  }
  ```
</Accordion>

## Common Questions

<AccordionGroup>
  <Accordion title="Can I change the issue ID after creation?">
    No, issue IDs are immutable and generated sequentially. They ensure stable references across the system.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I claim an issue for myself?">
    Use `issue update` to set yourself as assignee:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --assignee "your-name"
    ```
  </Accordion>

  <Accordion title="Can I have nested epics (parent of parent)?">
    Yes, you can create hierarchical issue structures with multiple levels:

    ```bash theme={null}
    sudocode issue create "Major Feature" --priority 0
    sudocode issue create "Phase 1" --parent ISSUE-001
    sudocode issue create "Task A" --parent ISSUE-002
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: sudocode not initialized">
    **Cause:** No `.sudocode/` directory found

    **Solution:**

    ```bash theme={null}
    sudocode init
    ```
  </Accordion>

  <Accordion title="Error: Invalid priority value">
    **Cause:** Priority must be 0-4

    **Solution:**

    ```bash theme={null}
    sudocode issue create "My Issue" --priority 2
    ```
  </Accordion>

  <Accordion title="Error: Parent issue not found">
    **Cause:** The parent issue ID doesn't exist

    **Solution:**
    Verify the parent issue exists:

    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```

    Create the parent issue first if needed.
  </Accordion>

  <Accordion title="Issue created but I can't find it">
    **Cause:** Issues are stored in the database, not as visible files by default

    **Solution:**
    List all issues:

    ```bash theme={null}
    sudocode issue list
    ```

    View specific issue:

    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="issue list" icon="list" href="/cli/issue-list">
    List all issues with filtering
  </Card>

  <Card title="issue show" icon="eye" href="/cli/issue-show">
    View issue details
  </Card>

  <Card title="issue update" icon="pen-to-square" href="/cli/issue-update">
    Update existing issue
  </Card>

  <Card title="issue close" icon="circle-check" href="/cli/issue-close">
    Close completed issues
  </Card>

  <Card title="link" icon="link" href="/cli/link">
    Link issues to specs
  </Card>

  <Card title="ready" icon="circle-check" href="/cli/ready">
    Find ready work
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Create your first issue">
    ```bash theme={null}
    sudocode issue create "My Task" --priority 1
    ```
  </Step>

  <Step title="Link to a spec">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Start working on it">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "you"
    ```
  </Step>

  <Step title="Complete and close">
    ```bash theme={null}
    sudocode issue close ISSUE-001
    ```
  </Step>
</Steps>

<Card title="Issues Concept Guide" icon="book" href="/concepts/issues">
  Learn more about issues and their role in sudocode's workflow
</Card>