plan next Command

Summary

Dependency-aware work item selection. Finds the highest-priority ready item, skipping items whose dependencies aren't complete. This is the entry point of the AI agent workflow — refrakt plan next --format json tells the agent what to work on.

Acceptance Criteria

• Scans for work items with status="ready" and bugs with status="confirmed"
• Excludes items whose dependency IDs (from References/Dependencies section) are not yet done or fixed
• Sorts by priority (critical > high > medium > low), then complexity (simpler items first as tiebreaker)
• --milestone <name> scopes results to a specific milestone
• --tag <tag>, --assignee <name>, --type work|bug|all filters work correctly
• --count N returns top N items (default: 1)
• --format json outputs structured data including criteria list, referenced specs, dependencies, and file path
• Text output shows ID, title, priority, complexity, file path, and acceptance criteria
• Exit codes: 0 = items found, 1 = no matches, 2 = invalid arguments
• Tests for filtering, sorting, dependency exclusion, and edge cases

Approach

Use the scanner (Plan File Scanner Library) to get all entities. Build a status lookup map (ID → status). Filter work/bug items by ready status, then exclude those with unfinished dependencies. Sort and slice. For JSON output, include the full criteria list and spec references.

Dependencies

• CLI Plugin Discovery Architecture (plugin architecture)
• Plan File Scanner Library (plan file scanner)

References

• Plan CLI (Plan CLI)