sudocode ready - sudocode

Syntax

sudocode ready [options]

Description

The ready command identifies issues that are ready for immediate work. These are issues that:

Have status open (not already in progress or closed)
Are not archived
Have no active blocking relationships (or all blockers are closed)

This command is essential for:

Finding next work to start
Agent task selection
Daily planning and prioritization
Identifying available work for team members

“Ready” means the issue has no dependencies blocking it. Use this to find work you can start immediately without waiting for other issues.

How “Ready” is Determined

An issue is considered ready when:

Status is open

The issue must have status = 'open'Issues that are in_progress, needs_review, or closed are excluded.

Not archived

The issue must not be archived (archived = 0)

No active blockers

Either:

The issue has no “blocks” relationships pointing to it, OR
All issues blocking it have status = 'closed'

If any blocker is still open, in_progress, or blocked, the issue is not ready.

Ready Issues View

The command queries the ready_issues database view:

SELECT i.*
FROM issues i
WHERE i.status = 'open'
  AND i.archived = 0
  AND NOT EXISTS (
    SELECT 1 FROM relationships r
    JOIN issues blocker ON r.to_id = blocker.id
    WHERE r.from_id = i.id
      AND r.from_type = 'issue'
      AND r.to_type = 'issue'
      AND r.relationship_type = 'blocks'
      AND blocker.status IN ('open', 'in_progress', 'blocked')
  )
ORDER BY priority DESC, created_at DESC;

This ensures only truly unblocked work is shown.

Examples

Find Ready Issues

List all issues ready to work on:

sudocode ready

Expected output

Ready Issues (3):

ISSUE-005 Implement OAuth 2.0 authentication @alice
  Priority: 0

ISSUE-008 Add rate limiting to API endpoints
  Priority: 1

ISSUE-012 Write integration tests for auth flow @bob
  Priority: 2

No Ready Issues

When all issues are blocked or completed:

sudocode ready

Expected output

No ready issues

JSON Output

Get machine-readable output for scripting:

sudocode --json ready

JSON output

{
  "issues": [
    {
      "id": "ISSUE-005",
      "uuid": "a1b2c3...",
      "title": "Implement OAuth 2.0 authentication",
      "content": "...",
      "status": "open",
      "priority": 0,
      "assignee": "alice",
      "archived": 0,
      "created_at": "2025-10-29T08:00:00Z",
      "updated_at": "2025-10-29T09:00:00Z",
      "closed_at": null,
      "parent_id": null
    },
    {
      "id": "ISSUE-008",
      "uuid": "d4e5f6...",
      "title": "Add rate limiting to API endpoints",
      "content": "...",
      "status": "open",
      "priority": 1,
      "assignee": null,
      "archived": 0,
      "created_at": "2025-10-28T14:00:00Z",
      "updated_at": "2025-10-28T14:00:00Z",
      "closed_at": null,
      "parent_id": null
    }
  ]
}

Output Format

Ready issues are displayed with:

Issue ID (cyan) - The unique identifier
Title - Issue description
Assignee (gray) - If assigned, shown as @username
Priority - Lower number = higher priority (0 is highest)

Issues are sorted by:

Priority (descending) - Highest priority first
Created date (descending) - Older issues first within same priority

Common Workflows

Daily Work Selection

Check ready work

sudocode ready

Choose highest priority

Pick the first issue (highest priority)

Claim the work

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

Start implementation

Begin working on the issue

Agent Workflow

Automated agent claiming work:

#!/bin/bash
# Agent script to claim and start work

# Get first ready issue
issue_id=$(sudocode --json ready | jq -r '.issues[0].id')

if [ -n "$issue_id" ] && [ "$issue_id" != "null" ]; then
  echo "Claiming $issue_id"

  # Update status and assignee
  sudocode issue update "$issue_id" \
    --status in_progress \
    --assignee "agent-01"

  # Read the issue details
  sudocode issue show "$issue_id"

  # Start implementation
  # ... agent implementation logic ...
else
  echo "No ready work available"
fi

Filter by Priority

Find only high-priority ready work:

# Get ready issues
sudocode --json ready | jq '.issues[] | select(.priority <= 1)'

This shows only issues with priority 0 or 1.

Check for Specific Assignee

See what’s ready for a specific person:

# Get unassigned ready work
sudocode --json ready | jq '.issues[] | select(.assignee == null)'

# Get work assigned to alice
sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'

Understanding Blockers

Why an Issue Might Not Be Ready

Blocked by another issue

Scenario: ISSUE-010 has blocks relationship to ISSUE-005Result: ISSUE-005 won’t appear in ready list until ISSUE-010 is closedCheck blockers:

sudocode issue show ISSUE-005

Look for “Incoming Relationships” with type “blocks”

Status is not open

Scenario: Issue is in_progress or closedResult: Only open issues appear in ready listCheck status:

sudocode issue show ISSUE-005

Issue is archived

Scenario: Issue was archivedResult: Archived issues are excluded from ready listCheck archive status:

sudocode issue show ISSUE-005

Look for archived: true

Blocker was completed recently

Scenario: Blocker was just closed but database not syncedResult: May not appear in ready list yetSolution:

sudocode sync
sudocode ready

Making Issues Ready

To make a blocked issue ready:

Find the blockers

sudocode issue show ISSUE-005

Check “Incoming Relationships” for blocks

Complete blocker issues

Work on and close the blocking issues:

sudocode issue close ISSUE-010

Verify now ready

sudocode ready

ISSUE-005 should now appear

ready

Find available work

Shows open issues only
No active blockers
Sorted by priority
Ready to start immediately

sudocode ready

blocked

Find blocked work

Shows blocked issues
Lists what blocks them
Identifies bottlenecks
Cannot start yet

sudocode blocked

issue list --status open

All open issues

Shows ALL open issues
Includes blocked ones
More filtering options
General issue browsing

sudocode issue list --status open

status

Project overview

Shows ready count
Shows blocked count
Project-wide statistics
Quick health check

sudocode status

Scripting Examples

Auto-assign Ready Work

Automatically assign ready issues to agents:

#!/bin/bash
agents=("agent-01" "agent-02" "agent-03")
agent_index=0

sudocode --json ready | jq -r '.issues[] | select(.assignee == null) | .id' | \
while read issue_id; do
  agent="${agents[$agent_index]}"
  echo "Assigning $issue_id to $agent"

  sudocode issue update "$issue_id" --assignee "$agent"

  agent_index=$(( (agent_index + 1) % ${#agents[@]} ))
done

Ready Work Digest

Generate a daily ready work report:

#!/bin/bash
echo "Ready Work Report - $(date)"
echo "============================"
echo ""

count=$(sudocode --json ready | jq '.issues | length')
echo "Total ready issues: $count"
echo ""

if [ "$count" -gt 0 ]; then
  echo "By Priority:"
  for p in 0 1 2 3 4; do
    p_count=$(sudocode --json ready | jq ".issues[] | select(.priority == $p)" | jq -s 'length')
    if [ "$p_count" -gt 0 ]; then
      echo "  Priority $p: $p_count issues"
    fi
  done

  echo ""
  echo "Unassigned: $(sudocode --json ready | jq '.issues[] | select(.assignee == null)' | jq -s 'length')"
fi

Monitor Ready Work

Check if ready work becomes available:

#!/bin/bash
# Run periodically to alert when work becomes ready

prev_count=0
while true; do
  count=$(sudocode --json ready | jq '.issues | length')

  if [ "$count" -gt "$prev_count" ]; then
    echo "$(date): New ready work available! ($count issues)"
    sudocode ready
  fi

  prev_count=$count
  sleep 300  # Check every 5 minutes
done

Common Questions

Why doesn't my issue appear in ready list?

Check these conditions:

Status must be open
Must not be archived
No open/in_progress blockers

Run:

sudocode issue show ISSUE-005
sudocode blocked

Can I filter ready issues by assignee?

Not directly, but use JSON output with jq:

sudocode --json ready | jq '.issues[] | select(.assignee == "alice")'

What if ready shows issues I can't work on?

Some ready issues may require specific skills or context. Consider:

Adding assignee field to track who should work on it
Using priority to indicate difficulty
Adding tags for skill requirements

How do I prioritize within ready list?

The list is already sorted by priority (highest first), then by creation date (oldest first). To change priority:

sudocode issue update ISSUE-005 --priority 0

Can agents automatically claim ready work?

Yes, use the JSON output to build automation:

issue_id=$(sudocode --json ready | jq -r '.issues[0].id')
sudocode issue update "$issue_id" --status in_progress --assignee "agent-01"

What's the difference between ready and issue list --status open?

ready: Only shows open issues with NO blockers
issue list —status open: Shows ALL open issues, including blocked ones

Use ready when you want to find work you can start immediately.

Troubleshooting

Ready list is empty but I know there are open issues

Cause: All open issues are blockedSolution: Check blocked issues:

sudocode blocked

Complete blocker issues to make them ready.

Issue appears ready but shows as blocked in issue show

Cause: Database may be out of syncSolution: Run sync:

sudocode sync
sudocode ready

Just closed a blocker but dependent issue not showing as ready

Cause: Database view not refreshedSolution: Views should update automatically. If not:

sudocode sync

Too many ready issues, hard to choose

Cause: Need better prioritizationSolution: Use priority field:

# Set high priority
sudocode issue update ISSUE-005 --priority 0

# Ready list automatically sorts by priority
sudocode ready

blocked

Find blocked issues

status

Project status overview

issue list

List all issues with filters

issue show

View issue details

issue update

Update issue status

Next Steps

Find ready work

sudocode ready

Choose an issue

Select based on priority and your skills

Claim the work

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

View details

sudocode issue show ISSUE-005

Start implementation

Begin working on the issue

Issues Concept Guide

Learn more about issue lifecycle and workflows

​Syntax

​Description

​How “Ready” is Determined

​Ready Issues View

​Examples

​Find Ready Issues

​No Ready Issues

​JSON Output

​Output Format

​Common Workflows

​Daily Work Selection

​Agent Workflow

​Filter by Priority

​Check for Specific Assignee

​Understanding Blockers

​Why an Issue Might Not Be Ready

​Making Issues Ready

​Related Commands Comparison

ready

blocked

issue list --status open

status

​Scripting Examples

​Auto-assign Ready Work

​Ready Work Digest

​Monitor Ready Work

​Common Questions

​Troubleshooting

​Related Commands

blocked

status

issue list

issue show

issue update

​Next Steps

Issues Concept Guide

Syntax

Description

How “Ready” is Determined

Ready Issues View

Examples

Find Ready Issues

No Ready Issues

JSON Output

Output Format

Common Workflows

Daily Work Selection

Agent Workflow

Filter by Priority

Check for Specific Assignee

Understanding Blockers

Why an Issue Might Not Be Ready

Making Issues Ready

Related Commands Comparison

Scripting Examples

Auto-assign Ready Work

Ready Work Digest

Monitor Ready Work

Common Questions

Troubleshooting

Related Commands

Next Steps