claude-code-workflow 7.2.29 → 7.2.30

package/.claude/skills/ccw-chain/phases/issue-queue.md

@@ -0,0 +1,464 @@
+---
+name: queue
+description: Form execution queue from bound solutions using issue-queue-agent (solution-level)
+argument-hint: "[-y|--yes] [--queues <n>] [--issue <id>]"
+allowed-tools: TodoWrite(*), Agent(*), Bash(*), Read(*), Write(*)
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm queue formation, use recommended conflict resolutions.
+
+# 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
+- **Conflict clarification**: High-severity conflicts prompt user decision
+- Semantic priority calculation per solution (0.0-1.0)
+- Parallel/Sequential group assignment for solutions
+
+## Core Guidelines
+
+**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
+| **Batch solutions (NEW)** | `ccw issue solutions --status planned --brief` | Loop `ccw issue solution <id>` |
+| List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| Get next item | `ccw issue next --json` | `Read('queues/*.json')` |
+| Update status | `ccw issue update <id> --status ...` | Direct file edit |
+| Sync from queue | `ccw issue update --from-queue` | Direct file edit |
+| Read solution (single) | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
+
+**Output Options**:
+- `--brief`: JSON with minimal fields (id, status, counts)
+- `--json`: Full JSON (agent use only)
+
+**Orchestration vs Execution**:
+- **Command (orchestrator)**: Use `--brief` for minimal context
+- **Agent (executor)**: Fetch full details → `ccw issue status <id> --json`
+
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `queues/*.json` directly.
+
+
+
+## Usage
+
+```bash
+/issue:queue [FLAGS]
+
+# Examples
+/issue:queue                      # Form NEW queue from all bound solutions
+/issue:queue --queues 3           # Form 3 parallel queues (solutions distributed)
+/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
+--queues <n>          Number of parallel queues (default: 1)
+--issue <id>          Form queue for specific issue only
+--append <id>         Append issue to active queue (don't create new)
+--force               Skip active queue check, always create new queue
+
+# CLI subcommands (ccw issue queue ...)
+ccw issue queue list                  List all queues with status
+ccw issue queue add <issue-id>        Add issue to queue (interactive if active queue exists)
+ccw issue queue add <issue-id> -f     Add to new queue without prompt (force)
+ccw issue queue merge <src> --queue <target>  Merge source queue into target queue
+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 & Distribution
+   ├─ Load issues.jsonl, filter by status='planned' + bound_solution_id
+   ├─ Read solutions/{issue-id}.jsonl, find bound solution
+   ├─ Extract files_touched from task files[] or modification_points (legacy)
+   ├─ Build solution objects array
+   └─ If --queues > 1: Partition solutions into N groups (minimize cross-group file conflicts)
+
+Phase 2-4: Agent-Driven Queue Formation (issue-queue-agent)
+   ├─ Generate N queue IDs (QUE-xxx-1, QUE-xxx-2, ...)
+   ├─ If --queues == 1: Launch single issue-queue-agent
+   ├─ If --queues > 1: Launch N issue-queue-agents IN PARALLEL
+   ├─ Each agent performs:
+   │   ├─ Conflict analysis (5 types via Gemini CLI)
+   │   ├─ Build dependency DAG from conflicts
+   │   ├─ Calculate semantic priority per solution
+   │   └─ Assign execution groups (parallel/sequential)
+   └─ Each agent writes: queue JSON + index update (NOT active yet)
+
+Phase 5: Conflict Clarification (if needed)
+   ├─ Collect `clarifications` arrays from all agents
+   ├─ If clarifications exist → AskUserQuestion (batched)
+   ├─ Pass user decisions back to respective agents (resume)
+   └─ Agents update queues with resolved conflicts
+
+Phase 6: Status Update & Summary
+   ├─ Update issue statuses to 'queued'
+   └─ Display new queue summary (N queues)
+
+Phase 7: Active Queue Check & Decision (REQUIRED)
+   ├─ Read queue index: ccw issue queue list --brief
+   ├─ Get generated queue ID from agent output
+   ├─ If NO active queue exists:
+   │   ├─ Set generated queue as active_queue_id
+   │   ├─ Update index.json
+   │   └─ Display: "Queue created and activated"
+   │
+   └─ If active queue exists with items:
+       ├─ Display both queues to user
+       ├─ Use AskUserQuestion to prompt:
+       │   ├─ "Use new queue (keep existing)" → Set new as active, keep old inactive
+       │   ├─ "Merge: add new items to existing" → Merge new → existing, delete new
+       │   ├─ "Merge: add existing items to new" → Merge existing → new, archive old
+       │   └─ "Cancel" → Delete new queue, keep existing active
+       └─ Execute chosen action
+```
+
+## Implementation
+
+### Phase 1: Solution Loading & Distribution
+
+**Data Loading:**
+- Use `ccw issue solutions --status planned --brief` to get all planned issues with solutions in **one call**
+- Returns: Array of `{ issue_id, solution_id, is_bound, task_count, files_touched[], priority }`
+- If no bound solutions found → display message, suggest `/issue:plan`
+
+**Build Solution Objects:**
+```javascript
+// Single CLI call replaces N individual queries
+const result = Bash(`ccw issue solutions --status planned --brief`).trim();
+const solutions = result ? JSON.parse(result) : [];
+
+if (solutions.length === 0) {
+  console.log('No bound solutions found. Run /issue:plan first.');
+  return;
+}
+
+// solutions already in correct format:
+// { issue_id, solution_id, is_bound, task_count, files_touched[], priority }
+```
+
+**Multi-Queue Distribution** (if `--queues > 1`):
+- Use `files_touched` from brief output for partitioning
+- Group solutions with overlapping files into same queue
+
+**Output:** Array of solution objects (or N arrays if multi-queue)
+
+### Phase 2-4: Agent-Driven Queue Formation
+
+**Generate Queue IDs** (command layer, pass to agent):
+```javascript
+const timestamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+const numQueues = args.queues || 1;
+const queueIds = numQueues === 1
+  ? [`QUE-${timestamp}`]
+  : Array.from({length: numQueues}, (_, i) => `QUE-${timestamp}-${i + 1}`);
+```
+
+**Agent Prompt** (same for each queue, with assigned solutions):
+```
+## Order Solutions into Execution Queue
+
+**Queue ID**: ${queueId}
+**Solutions**: ${solutions.length} from ${issues.length} issues
+**Project Root**: ${cwd}
+**Queue Index**: ${queueIndex} of ${numQueues}
+
+### Input
+${JSON.stringify(solutions)}
+// Each object: { issue_id, solution_id, task_count, files_touched[], priority }
+
+### Workflow
+
+Step 1: Build dependency graph from solutions (nodes=solutions, edges=file conflicts via files_touched)
+Step 2: Use Gemini CLI for conflict analysis (5 types: file, API, data, dependency, architecture)
+Step 3: For high-severity conflicts without clear resolution → add to `clarifications`
+Step 4: Calculate semantic priority (base from issue priority + task_count boost)
+Step 5: Assign execution groups: P* (parallel, no overlaps) / S* (sequential, shared files)
+Step 6: Write queue JSON + update index
+
+### Output Requirements
+
+**Write files** (exactly 2):
+- `.workflow/issues/queues/${queueId}.json` - Full queue with solutions, conflicts, groups
+- `.workflow/issues/queues/index.json` - Update with new queue entry
+
+**Return JSON**:
+\`\`\`json
+{
+  "queue_id": "${queueId}",
+  "total_solutions": N,
+  "total_tasks": N,
+  "execution_groups": [{"id": "P1", "type": "parallel", "count": N}],
+  "issues_queued": ["ISS-xxx"],
+  "clarifications": [{"conflict_id": "CFT-1", "question": "...", "options": [...]}]
+}
+\`\`\`
+
+### Rules
+- Solution granularity (NOT individual tasks)
+- Queue Item ID format: S-1, S-2, S-3, ...
+- Use provided Queue ID (do NOT generate new)
+- `clarifications` only present if high-severity unresolved conflicts exist
+- Use `files_touched` from input (already extracted by orchestrator)
+
+### Done Criteria
+- [ ] Queue JSON written with all solutions ordered
+- [ ] Index updated with active_queue_id
+- [ ] No circular dependencies
+- [ ] Parallel groups have no file overlaps
+- [ ] Return JSON matches required shape
+```
+
+**Launch Agents** (parallel if multi-queue):
+```javascript
+const numQueues = args.queues || 1;
+
+if (numQueues === 1) {
+  // Single queue: single agent call
+  const result = Task(
+    subagent_type="issue-queue-agent",
+    prompt=buildPrompt(queueIds[0], solutions),
+    description=`Order ${solutions.length} solutions`
+  );
+} else {
+  // Multi-queue: parallel agent calls (single message with N Task calls)
+  const agentPromises = solutionGroups.map((group, i) =>
+    Task(
+      subagent_type="issue-queue-agent",
+      prompt=buildPrompt(queueIds[i], group, i + 1, numQueues),
+      description=`Queue ${i + 1}/${numQueues}: ${group.length} solutions`
+    )
+  );
+  // All agents launched in parallel via single message with multiple Agent tool calls
+}
+```
+
+**Multi-Queue Index Update:**
+- First queue sets `active_queue_id`
+- All queues added to `queues` array with `queue_group` field linking them
+
+### Phase 5: Conflict Clarification
+
+**Collect Agent Results** (multi-queue):
+```javascript
+// Collect clarifications from all agents
+const allClarifications = results.flatMap((r, i) =>
+  (r.clarifications || []).map(c => ({ ...c, queue_id: queueIds[i], agent_id: agentIds[i] }))
+);
+```
+
+**Check Agent Return:**
+- Parse agent result JSON (or all results if multi-queue)
+- If any `clarifications` array exists and non-empty → user decision required
+
+**Clarification Flow:**
+```javascript
+if (allClarifications.length > 0) {
+  for (const clarification of allClarifications) {
+    // Auto mode: use recommended resolution (first option)
+    if (autoYes) {
+      const autoAnswer = clarification.options[0]?.label || 'skip';
+      Task(
+        subagent_type="issue-queue-agent",
+        resume=clarification.agent_id,
+        prompt=`Conflict ${clarification.conflict_id} resolved: ${autoAnswer}`
+      );
+      continue;
+    }
+
+    // Present to user via AskUserQuestion
+    const answer = AskUserQuestion({
+      questions: [{
+        question: `[${clarification.queue_id}] ${clarification.question}`,
+        header: clarification.conflict_id,
+        options: clarification.options,
+        multiSelect: false
+      }]
+    });
+
+    // Resume respective agent with user decision
+    Task(
+      subagent_type="issue-queue-agent",
+      resume=clarification.agent_id,
+      prompt=`Conflict ${clarification.conflict_id} resolved: ${answer.selected}`
+    );
+  }
+}
+```
+
+### Phase 6: Status Update & Summary
+
+**Status Update** (MUST use CLI command, NOT direct file operations):
+
+```bash
+# Option 1: Batch update from queue (recommended)
+ccw issue update --from-queue [queue-id] --json
+ccw issue update --from-queue --json              # Use active queue
+ccw issue update --from-queue QUE-xxx --json      # Use specific queue
+
+# Option 2: Individual issue update
+ccw issue update <issue-id> --status queued
+```
+
+**⚠️ IMPORTANT**: Do NOT directly modify `issues.jsonl`. Always use CLI command to ensure proper validation and history tracking.
+
+**Output** (JSON):
+```json
+{
+  "success": true,
+  "queue_id": "QUE-xxx",
+  "queued": ["ISS-001", "ISS-002"],
+  "queued_count": 2,
+  "unplanned": ["ISS-003"],
+  "unplanned_count": 1
+}
+```
+
+**Behavior:**
+- Updates issues in queue to `status: 'queued'` (skips already queued/executing/completed)
+- Identifies planned issues with `bound_solution_id` NOT in queue → `unplanned` array
+- Optional `queue-id`: defaults to active queue if omitted
+
+**Summary Output:**
+- Display queue ID, solution count, task count
+- Show unplanned issues (planned but NOT in queue)
+- Show next step: `/issue:execute`
+
+### Phase 7: Active Queue Check & Decision
+
+**After agent completes Phase 1-6, check for active queue:**
+
+```bash
+ccw issue queue list --brief
+```
+
+**Decision:**
+- If `active_queue_id` is null → `ccw issue queue switch <new-queue-id>` (activate new queue)
+- If active queue exists → Use **AskUserQuestion** to prompt user
+
+**AskUserQuestion:**
+```javascript
+// Auto mode: merge into existing queue
+if (autoYes) {
+  Bash(`ccw issue queue merge ${newQueueId} --queue ${activeQueueId}`);
+  Bash(`ccw issue queue delete ${newQueueId}`);
+  console.log(`Auto-merged new queue into ${activeQueueId}`);
+  return;
+}
+
+AskUserQuestion({
+  questions: [{
+    question: "Active queue exists. How would you like to proceed?",
+    header: "Queue Action",
+    options: [
+      { label: "Merge into existing queue", description: "Add new items to active queue, delete new queue" },
+      { label: "Use new queue", description: "Switch to new queue, keep existing in history" },
+      { label: "Cancel", description: "Delete new queue, keep existing active" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Action Commands:**
+
+| User Choice | Commands |
+|-------------|----------|
+| **Merge into existing** | `ccw issue queue merge <new-queue-id> --queue <active-queue-id>` then `ccw issue queue delete <new-queue-id>` |
+| **Use new queue** | `ccw issue queue switch <new-queue-id>` |
+| **Cancel** | `ccw issue queue delete <new-queue-id>` |
+
+## 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",
+  "active_queue_group": "QGR-20251227-143000",
+  "queues": [
+    {
+      "id": "QUE-20251227-143000-1",
+      "queue_group": "QGR-20251227-143000",
+      "queue_index": 1,
+      "total_queues": 3,
+      "status": "active",
+      "issue_ids": ["ISS-xxx", "ISS-yyy"],
+      "total_solutions": 3,
+      "completed_solutions": 1,
+      "created_at": "2025-12-27T14:30:00Z"
+    }
+  ]
+}
+```
+
+**Multi-Queue Fields:**
+- `queue_group`: Links queues created in same batch (format: `QGR-{timestamp}`)
+- `queue_index`: Position in group (1-based)
+- `total_queues`: Total queues in group
+- `active_queue_group`: Current active group (for multi-queue execution)
+
+**Note**: Queue file schema is produced by `issue-queue-agent`. See agent documentation for details.
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No bound solutions | Display message, suggest /issue:plan |
+| Circular dependency | List cycles, abort queue formation |
+| High-severity conflict | Return `clarifications`, prompt user decision |
+| User cancels clarification | Abort queue formation |
+| **index.json not updated** | Auto-fix: Set active_queue_id to new queue |
+| **Queue file missing solutions** | Abort with error, agent must regenerate |
+| **User cancels queue add** | Display message, return without changes |
+| **Merge with empty source** | Skip merge, display warning |
+| **All items duplicate** | Skip merge, display "All items already exist" |
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] All planned issues with `bound_solution_id` are included
+- [ ] Queue JSON written to `queues/{queue-id}.json` (N files if multi-queue)
+- [ ] Index updated in `queues/index.json` with `active_queue_id`
+- [ ] Multi-queue: All queues share same `queue_group`
+- [ ] No circular dependencies in solution DAG
+- [ ] All conflicts resolved (auto or via user clarification)
+- [ ] Parallel groups have no file overlaps
+- [ ] Cross-queue: No file overlaps between queues
+- [ ] Issue statuses updated to `queued`
+
+## Related Commands
+
+- `/issue:execute` - Execute queue with codex
+- `ccw issue queue list` - View current queue
+- `ccw issue update --from-queue [queue-id]` - Sync issue statuses from queue