Claude-Code-Workflow/.claude/commands/issue/queue.md

---
name: queue
description: Form execution queue from bound solutions using issue-queue-agent (solution-level)
argument-hint: "[--rebuild] [--issue <id>]"
allowed-tools: TodoWrite(*), Task(*), Bash(*), Read(*), Write(*)
---

# Issue Queue Command (/issue:queue)

## Overview

Queue formation command using **issue-queue-agent** that analyzes all bound solutions, resolves **inter-solution** conflicts, and creates an ordered execution queue at **solution level**.

**Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks.

## Core Capabilities

- **Agent-driven**: issue-queue-agent handles all ordering logic
- **Solution-level granularity**: Queue items are solutions, not tasks
- Inter-solution dependency DAG (based on file conflicts)
- File conflict detection between solutions
- Semantic priority calculation per solution (0.0-1.0)
- Parallel/Sequential group assignment for solutions



## Usage

```bash
/issue:queue [FLAGS]

# Examples
/issue:queue                      # Form NEW queue from all bound solutions
/issue:queue --issue GH-123       # Form queue for specific issue only
/issue:queue --append GH-124      # Append to active queue
/issue:queue --list               # List all queues (history)
/issue:queue --switch QUE-xxx     # Switch active queue
/issue:queue --archive            # Archive completed active queue

# Flags
--issue <id>          Form queue for specific issue only
--append <id>         Append issue to active queue (don't create new)

# CLI subcommands (ccw issue queue ...)
ccw issue queue list                  List all queues with status
ccw issue queue switch <queue-id>     Switch active queue
ccw issue queue archive               Archive current queue
ccw issue queue delete <queue-id>     Delete queue from history
```

## Execution Process

```
Phase 1: Solution Loading
   ├─ Load issues.jsonl
   ├─ Filter issues with bound_solution_id
   ├─ Read solutions/{issue-id}.jsonl for each issue
   ├─ Find bound solution by ID
   ├─ Collect files_touched from all tasks in solution
   └─ Build solution objects (NOT individual tasks)

Phase 2-4: Agent-Driven Queue Formation (issue-queue-agent)
   ├─ Launch issue-queue-agent with all solutions
   ├─ Agent performs:
   │   ├─ Detect file overlaps between solutions
   │   ├─ Build dependency DAG from file conflicts
   │   ├─ Detect circular dependencies
   │   ├─ Resolve conflicts using priority rules
   │   ├─ Calculate semantic priority per solution
   │   └─ Assign execution groups (parallel/sequential)
   └─ Output: queue JSON with ordered solutions (S-1, S-2, ...)

Phase 5: Queue Output
   ├─ Write queue.json with solutions array
   ├─ Update issue statuses in issues.jsonl
   └─ Display queue summary
```

## Implementation

### Phase 1: Solution Loading

**Data Loading:**
- Load `issues.jsonl` and filter issues with `status === 'planned'` and `bound_solution_id`
- If no planned issues found → display message, suggest `/issue:plan`

**Solution Collection** (for each planned issue):
- Read `solutions/{issue-id}.jsonl`
- Find bound solution by `bound_solution_id`
- If bound solution not found → warn and skip issue
- Extract `files_touched` from all task `modification_points`

**Build Solution Objects:**
```json
{
  "issue_id": "ISS-xxx",
  "solution_id": "SOL-ISS-xxx-1",
  "task_count": 3,
  "files_touched": ["src/auth.ts", "src/utils.ts"],
  "priority": "medium"
}
```

**Output:** Array of solution objects ready for agent processing

### Phase 2-4: Agent-Driven Queue Formation

```javascript
// Generate queue-id ONCE here, pass to agent
const now = new Date();
const queueId = `QUE-${now.toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;

// Build minimal prompt - agent orders SOLUTIONS, not tasks
const agentPrompt = `
## Order Solutions

**Queue ID**: ${queueId}
**Solutions**: ${allSolutions.length} from ${plannedIssues.length} issues
**Project Root**: ${process.cwd()}

### Input (Solution-Level)
\`\`\`json
${JSON.stringify(allSolutions, null, 2)}
\`\`\`

### Steps
1. Parse solutions: Extract solution IDs, files_touched, task_count, priority
2. Detect conflicts: Find file overlaps between solutions (files_touched intersection)
3. Build DAG: Create dependency edges where solutions share files
4. Detect cycles: Verify no circular dependencies (abort if found)
5. Resolve conflicts: Apply ordering rules based on action types
6. Calculate priority: Compute semantic priority (0.0-1.0) per solution
7. Assign groups: Parallel (P*) for no-conflict, Sequential (S*) for conflicts
8. Generate queue: Write queue JSON with ordered solutions
9. Update index: Update queues/index.json with new queue entry

### Rules
- **Solution Granularity**: Queue items are solutions, NOT individual tasks
- **DAG Validity**: Output must be valid DAG with no circular dependencies
- **Conflict Detection**: Two solutions conflict if files_touched intersect
- **Ordering Priority**:
  1. Higher issue priority first (critical > high > medium > low)
  2. Fewer dependencies first (foundation solutions)
  3. More tasks = higher priority (larger impact)
- **Parallel Safety**: Solutions in same parallel group must have NO file overlaps
- **Queue Item ID Format**: \`S-N\` (S-1, S-2, S-3, ...)
- **Queue ID**: Use the provided Queue ID (passed above), do NOT generate new one

### Generate Files (STRICT - only these 2)
1. \`.workflow/issues/queues/{Queue ID}.json\` - Use Queue ID from above
2. \`.workflow/issues/queues/index.json\` - Update existing index

Write ONLY these 2 files, using the provided Queue ID.

### Return Summary
\`\`\`json
{
  "queue_id": "QUE-YYYYMMDD-HHMMSS",
  "total_solutions": N,
  "total_tasks": N,
  "execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
  "conflicts_resolved": N,
  "issues_queued": ["ISS-xxx"]
}
\`\`\`
`;

const result = Task(
  subagent_type="issue-queue-agent",
  run_in_background=false,
  description=`Order ${allSolutions.length} solutions`,
  prompt=agentPrompt
);

const summary = JSON.parse(result);
```

### Phase 5: Validation & Status Update

**Validation:**
- Verify queue file exists at `queues/{queue-id}.json`
- Check `solutions` array is non-empty → abort if empty

**Status Update:**
- Update each queued issue status to `queued` via `ccw issue update <id> --status queued`

**Summary Output:**
- Display queue ID, solution count, task count, issue IDs
- Show next step: `/issue:execute`


## Storage Structure (Queue History)

```
.workflow/issues/
├── issues.jsonl              # All issues (one per line)
├── queues/                   # Queue history directory
│   ├── index.json            # Queue index (active + history)
│   ├── {queue-id}.json       # Individual queue files
│   └── ...
└── solutions/
    ├── {issue-id}.jsonl      # Solutions for issue
    └── ...
```

### Queue Index Schema

```json
{
  "active_queue_id": "QUE-20251227-143000",
  "queues": [
    {
      "id": "QUE-20251227-143000",
      "status": "active",
      "issue_ids": ["ISS-xxx", "ISS-yyy"],
      "total_solutions": 3,
      "completed_solutions": 1,
      "created_at": "2025-12-27T14:30:00Z"
    }
  ]
}
```

### Queue File Schema (Solution-Level)

```json
{
  "id": "QUE-20251227-143000",
  "status": "active",
  "solutions": [
    {
      "item_id": "S-1",
      "issue_id": "ISS-20251227-003",
      "solution_id": "SOL-ISS-20251227-003-1",
      "status": "pending",
      "execution_order": 1,
      "execution_group": "P1",
      "depends_on": [],
      "semantic_priority": 0.8,
      "files_touched": ["src/auth.ts", "src/utils.ts"],
      "task_count": 3
    },
    {
      "item_id": "S-2",
      "issue_id": "ISS-20251227-001",
      "solution_id": "SOL-ISS-20251227-001-1",
      "status": "pending",
      "execution_order": 2,
      "execution_group": "P1",
      "depends_on": [],
      "semantic_priority": 0.7,
      "files_touched": ["src/api.ts"],
      "task_count": 2
    },
    {
      "item_id": "S-3",
      "issue_id": "ISS-20251227-002",
      "solution_id": "SOL-ISS-20251227-002-1",
      "status": "pending",
      "execution_order": 3,
      "execution_group": "S2",
      "depends_on": ["S-1"],
      "semantic_priority": 0.5,
      "files_touched": ["src/auth.ts"],
      "task_count": 4
    }
  ],
  "conflicts": [
    {
      "type": "file_conflict",
      "file": "src/auth.ts",
      "solutions": ["S-1", "S-3"],
      "resolution": "sequential",
      "resolution_order": ["S-1", "S-3"],
      "rationale": "S-1 creates auth module, S-3 extends it"
    }
  ],
  "execution_groups": [
    { "id": "P1", "type": "parallel", "solutions": ["S-1", "S-2"] },
    { "id": "S2", "type": "sequential", "solutions": ["S-3"] }
  ]
}
```
## Error Handling

| Error | Resolution |
|-------|------------|
| No bound solutions | Display message, suggest /issue:plan |
| Circular dependency | List cycles, abort queue formation |
| Unresolved conflicts | Agent resolves using ordering rules |
| Invalid task reference | Skip and warn |
| **index.json not updated** | Auto-fix: Set active_queue_id to new queue |
| **Wrong status value** | Auto-fix: Convert non-pending status to "pending" |
| **No entry points (all have deps)** | Auto-fix: Clear depends_on for first item |
| **Queue file missing solutions** | Abort with error, agent must regenerate |

## Quality Checklist

Before completing, verify:

- [ ] All planned issues with `bound_solution_id` are included
- [ ] Queue JSON written to `queues/{queue-id}.json`
- [ ] Index updated in `queues/index.json` with `active_queue_id`
- [ ] No circular dependencies in solution DAG
- [ ] File conflicts resolved with rationale
- [ ] Parallel groups have no file overlaps
- [ ] Issue statuses updated to `queued`

## Related Commands

- `/issue:plan` - Plan issues and bind solutions
- `/issue:execute` - Execute queue with codex
- `ccw issue queue list` - View current queue