--- title: issue:queue sidebar_label: issue:queue sidebar_position: 4 description: Form execution queue from bound solutions with conflict resolution --- # issue:queue Queue formation command using issue-queue-agent that analyzes bound solutions, resolves inter-solution conflicts, and creates an ordered execution queue. ## Description The `issue:queue` command creates execution queues from planned issues with bound solutions. It performs solution-level conflict analysis, builds dependency DAGs, calculates semantic priority, and assigns execution groups (parallel/sequential). ### Key Features - **Solution-level granularity**: Queue items are complete solutions, not individual tasks - **Conflict resolution**: Automatic detection and user clarification for high-severity conflicts - **Multi-queue support**: Create parallel queues for distributed execution - **Semantic priority**: Intelligent ordering based on issue priority and task complexity - **DAG-based grouping**: Parallel (P*) and Sequential (S*) execution groups - **Queue history**: Track all queues with active queue management ## Usage ```bash # Form new queue from all bound solutions /issue:queue # Form 3 parallel queues (solutions distributed) /issue:queue --queues 3 # Form queue for specific issue only /issue:queue --issue GH-123 # Append to active queue /issue:queue --append GH-124 # List all queues /issue:queue --list # Switch active queue /issue:queue --switch QUE-xxx # Archive completed queue /issue:queue --archive ``` ### Arguments | Argument | Required | Description | |----------|----------|-------------| | `--queues ` | No | Number of parallel queues (default: 1) | | `--issue ` | No | Form queue for specific issue only | | `--append ` | No | Append issue to active queue | | `--force` | No | Skip active queue check, always create new | | `-y, --yes` | No | Auto-confirm, use recommended resolutions | ### CLI Subcommands ```bash ccw issue queue list # List all queues with status ccw issue queue add # Add issue to queue ccw issue queue add -f # Force add to new queue ccw issue queue merge --queue # Merge queues ccw issue queue switch # Switch active queue ccw issue queue archive # Archive current queue ccw issue queue delete # Delete queue from history ``` ## Examples ### Create Single Queue ```bash /issue:queue # Output: # Loading 5 bound solutions... # Generating queue: QUE-20251227-143000 # Analyzing conflicts... # ✓ Queue created: 5 solutions, 3 execution groups # - P1: S-1, S-2 (parallel) # - S1: S-3 (sequential) # - P2: S-4, S-5 (parallel) # Next: /issue:execute --queue QUE-20251227-143000 ``` ### Create Multiple Parallel Queues ```bash /issue:queue --queues 3 # Distributes solutions to minimize cross-queue conflicts # Creates: QUE-20251227-143000-1, QUE-20251227-143000-2, QUE-20251227-143000-3 # All linked via queue_group: QGR-20251227-143000 ``` ### Append to Existing Queue ```bash /issue:queue --append GH-124 # Checks active queue exists # Adds new solution to end of active queue # Recalculates execution groups ``` ## Issue Lifecycle Flow ```mermaid graph TB A[Planned Issues + Bound Solutions] --> B[Load Solutions] B --> C{Multi-Queue?} C -->|Yes| D[Partition Solutions] C -->|No| E[Single Queue] D --> F[Launch N Agents Parallel] E --> G[Launch Agent] F --> H[Conflict Analysis] G --> H H --> I{High-Severity Conflicts?} I -->|Yes| J[User Clarification] I -->|No| K[Build DAG] J --> K K --> L[Calculate Priority] L --> M[Assign Groups] M --> N[Write Queue + Index] N --> O{Active Queue Exists?} O -->|No| P[Activate New Queue] O -->|Yes| Q[User Decision] Q --> R1[Merge] Q --> R2[Switch] Q --> R3[Cancel] R1 --> S[Queue Ready] R2 --> S P --> S ``` ## Execution Groups ### Parallel Groups (P*) Solutions with NO file conflicts can execute simultaneously: ``` P1: S-1, S-2, S-3 → 3 executors work in parallel ``` ### Sequential Groups (S*) Solutions with shared dependencies must execute in order: ``` S1: S-4 → S-5 → S-6 → Execute one after another ``` ### Mixed Execution ``` P1: S-1, S-2 (parallel) ↓ S1: S-3 (sequential, waits for P1) ↓ P2: S-4, S-5 (parallel, waits for S1) ``` ## Conflict Types ### 1. File Conflicts Solutions modify the same file: ```json { "conflict_id": "CFT-1", "type": "file", "severity": "high", "solutions": ["S-1", "S-2"], "files": ["src/auth/login.ts"], "resolution": "sequential" } ``` **Resolution**: S-1 before S-2 in sequential group ### 2. API Conflicts Solutions change shared interfaces: ```json { "conflict_id": "CFT-2", "type": "api", "severity": "high", "solutions": ["S-3", "S-4"], "interfaces": ["AuthService.login()"], "resolution": "sequential" } ``` **Resolution**: User clarifies which approach to use ### 3. Data Conflicts Solutions modify same database schema: ```json { "conflict_id": "CFT-3", "type": "data", "severity": "medium", "solutions": ["S-5", "S-6"], "tables": ["users"], "resolution": "sequential" } ``` **Resolution**: S-5 before S-6 ### 4. Dependency Conflicts Solutions require incompatible versions: ```json { "conflict_id": "CFT-4", "type": "dependency", "severity": "high", "solutions": ["S-7", "S-8"], "packages": ["redis@4.x vs 5.x"], "resolution": "clarification" } ``` **Resolution**: User selects version or defers one solution ### 5. Architecture Conflicts Solutions have opposing architectural approaches: ```json { "conflict_id": "CFT-5", "type": "architecture", "severity": "medium", "solutions": ["S-9", "S-10"], "approaches": ["monolithic", "microservice"], "resolution": "clarification" } ``` **Resolution**: User selects approach or separates concerns ## Queue Structure ### Directory Layout ``` .workflow/issues/queues/ ├── index.json # Queue index (active + history) ├── QUE-20251227-143000.json # Individual queue file ├── QUE-20251227-143000-1.json # Multi-queue partition 1 ├── QUE-20251227-143000-2.json # Multi-queue partition 2 └── QUE-20251227-143000-3.json # Multi-queue partition 3 ``` ### Index Schema ```typescript interface QueueIndex { active_queue_id: string | null; active_queue_group: string | null; queues: QueueEntry[]; } interface QueueEntry { id: string; queue_group?: string; // Links multi-queue partitions queue_index?: number; // Position in group (1-based) total_queues?: number; // Total queues in group status: 'active' | 'archived' | 'deleted'; issue_ids: string[]; total_solutions: number; completed_solutions: number; created_at: string; } ``` ### Queue File Schema ```typescript interface Queue { queue_id: string; queue_group?: string; solutions: QueueSolution[]; execution_groups: ExecutionGroup[]; conflicts: Conflict[]; priority_order: string[]; created_at: string; } interface QueueSolution { item_id: string; // S-1, S-2, S-3... issue_id: string; solution_id: string; status: 'pending' | 'in_progress' | 'completed' | 'failed'; task_count: number; files_touched: string[]; priority_score: number; } interface ExecutionGroup { id: string; // P1, S1, P2... type: 'parallel' | 'sequential'; items: string[]; // S-1, S-2... } ``` ## Clarification Flow When high-severity conflicts exist without clear resolution: ```bash # Interactive prompt [CFT-5] File conflict: src/auth/login.ts modified by both S-1 and S-2 Options: [1] Sequential: Execute S-1 first, then S-2 [2] Sequential: Execute S-2 first, then S-1 [3] Merge: Combine changes into single solution [4] Defer: Remove one solution from queue User selects: [1] # Agent resumes with resolution # Updates queue with sequential ordering: S1: [S-1, S-2] ``` ## Related Commands - **[issue:plan](./issue-plan.md)** - Plan solutions before queuing - **[issue:execute](./issue-execute.md)** - Execute queued solutions - **[issue:new](./issue-new.md)** - Create issues to plan and queue - **ccw issue queue dag** - View dependency graph - **ccw issue next** - Get next item from queue ## Best Practices 1. **Plan before queue**: Ensure all issues have bound solutions 2. **Review conflicts**: Check conflict report before execution 3. **Use parallel queues**: For large projects, distribute work 4. **Archive completed**: Keep queue history for reference 5. **Check unplanned**: Review planned but unqueued issues 6. **Validate DAG**: Ensure no circular dependencies ## CLI Endpoints ```bash # List planned issues with bound solutions ccw issue solutions --status planned --brief # Create/update queue ccw issue queue form # Sync issue statuses from queue ccw issue update --from-queue [queue-id] # View queue DAG ccw issue queue dag --queue # Get next item ccw issue next --queue ```