claude-code-workflow 6.3.12 → 6.3.15

package/.claude/commands/issue/queue.md

@@ -13,135 +13,38 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 
 **Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks.
 
-## Output Requirements
-
-**Generate Files:**
-1. `.workflow/issues/queues/{queue-id}.json` - Full queue with solutions, conflicts, groups
-2. `.workflow/issues/queues/index.json` - Update with new queue entry
-
-**Return Summary:**
-```json
-{
-  "queue_id": "QUE-20251227-143000",
-  "total_solutions": N,
-  "total_tasks": N,
-  "execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
-  "conflicts_resolved": N,
-  "issues_queued": ["ISS-xxx", "ISS-yyy"]
-}
-```
-
-**Completion Criteria:**
-- [ ] Queue JSON generated with valid DAG (no cycles between solutions)
-- [ ] All inter-solution file conflicts resolved with rationale
-- [ ] Semantic priority calculated for each solution
-- [ ] Execution groups assigned (parallel P* / sequential S*)
-- [ ] Issue statuses updated to `queued` via `ccw issue update`
-
 ## 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
+- **Conflict clarification**: High-severity conflicts prompt user decision
 - Semantic priority calculation per solution (0.0-1.0)
 - Parallel/Sequential group assignment for solutions
 
-## Storage Structure (Queue History)
+## Core Guidelines
 
-```
-.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
-    └── ...
-```
+**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow:
 
-### Queue Index Schema
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
+| 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 |
 
-```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"
-    }
-  ]
-}
-```
+**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.
 
-### 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-20251227-003",
-      "status": "pending",
-      "execution_order": 1,
-      "execution_group": "P1",
-      "depends_on": [],
-      "semantic_priority": 0.8,
-      "assigned_executor": "codex",
-      "files_touched": ["src/auth.ts", "src/utils.ts"],
-      "task_count": 3
-    },
-    {
-      "item_id": "S-2",
-      "issue_id": "ISS-20251227-001",
-      "solution_id": "SOL-20251227-001",
-      "status": "pending",
-      "execution_order": 2,
-      "execution_group": "P1",
-      "depends_on": [],
-      "semantic_priority": 0.7,
-      "assigned_executor": "codex",
-      "files_touched": ["src/api.ts"],
-      "task_count": 2
-    },
-    {
-      "item_id": "S-3",
-      "issue_id": "ISS-20251227-002",
-      "solution_id": "SOL-20251227-002",
-      "status": "pending",
-      "execution_order": 3,
-      "execution_group": "S2",
-      "depends_on": ["S-1"],
-      "semantic_priority": 0.5,
-      "assigned_executor": "codex",
-      "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"] }
-  ]
-}
-```
 
 ## Usage
 
@@ -171,280 +74,254 @@ ccw issue queue delete <queue-id>     Delete queue from history
 
 ```
 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)
+   ├─ Load issues.jsonl, filter by status='planned' + bound_solution_id
+   ├─ Read solutions/{issue-id}.jsonl, find bound solution
+   ├─ Extract files_touched from task modification_points
+   └─ Build solution objects array
 
 Phase 2-4: Agent-Driven Queue Formation (issue-queue-agent)
-   ├─ Launch issue-queue-agent with all solutions
+   ├─ Launch issue-queue-agent with solutions array
    ├─ Agent performs:
-   │   ├─ Detect file overlaps between solutions
-   │   ├─ Build dependency DAG from file conflicts
-   │   ├─ Detect circular dependencies
-   │   ├─ Resolve conflicts using priority rules
+   │   ├─ Conflict analysis (5 types via Gemini CLI)
+   │   ├─ Build dependency DAG from conflicts
    │   ├─ Calculate semantic priority per solution
    │   └─ Assign execution groups (parallel/sequential)
-   └─ Output: queue JSON with ordered solutions (S-1, S-2, ...)
+   └─ Agent writes: queue JSON + index update
+
+Phase 5: Conflict Clarification (if needed)
+   ├─ Check agent return for `clarifications` array
+   ├─ If clarifications exist → AskUserQuestion
+   ├─ Pass user decisions back to agent (resume)
+   └─ Agent updates queue with resolved conflicts
 
-Phase 5: Queue Output
-   ├─ Write queue.json with solutions array
-   ├─ Update issue statuses in issues.jsonl
-   └─ Display queue summary
+Phase 6: Status Update & Summary
+   ├─ Update issue statuses to 'queued'
+   └─ Display queue summary, next step: /issue:execute
 ```
 
 ## Implementation
 
 ### Phase 1: Solution Loading
 
-**NOTE**: Execute code directly. DO NOT pre-read solution files - Bash cat handles all reading.
+**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`
 
-```javascript
-// Load issues.jsonl
-const issuesPath = '.workflow/issues/issues.jsonl';
-const allIssues = Bash(`cat "${issuesPath}" 2>/dev/null || echo ''`)
-  .split('\n')
-  .filter(line => line.trim())
-  .map(line => JSON.parse(line));
-
-// Filter issues with bound solutions
-const plannedIssues = allIssues.filter(i =>
-  i.status === 'planned' && i.bound_solution_id
-);
+**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`
 
-if (plannedIssues.length === 0) {
-  console.log('No issues with bound solutions found.');
-  console.log('Run /issue:plan first to create and bind solutions.');
-  return;
+**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"
 }
+```
 
-// Load bound solutions (not individual tasks)
-const allSolutions = [];
-for (const issue of plannedIssues) {
-  const solPath = `.workflow/issues/solutions/${issue.id}.jsonl`;
-  const solutions = Bash(`cat "${solPath}" 2>/dev/null || echo ''`)
-    .split('\n')
-    .filter(line => line.trim())
-    .map(line => JSON.parse(line));
-
-  // Find bound solution
-  const boundSol = solutions.find(s => s.id === issue.bound_solution_id);
-
-  if (!boundSol) {
-    console.log(`⚠ Bound solution ${issue.bound_solution_id} not found for ${issue.id}`);
-    continue;
-  }
+**Output:** Array of solution objects ready for agent processing
 
-  // Collect all files touched by this solution
-  const filesTouched = new Set();
-  for (const task of boundSol.tasks || []) {
-    for (const mp of task.modification_points || []) {
-      filesTouched.add(mp.file);
-    }
-  }
+### Phase 2-4: Agent-Driven Queue Formation
 
-  allSolutions.push({
-    issue_id: issue.id,
-    solution_id: issue.bound_solution_id,
-    task_count: boundSol.tasks?.length || 0,
-    files_touched: Array.from(filesTouched),
-    priority: issue.priority || 'medium'
-  });
-}
+**Generate Queue ID** (command layer, pass to agent):
+```javascript
+const queueId = `QUE-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+```
 
-console.log(`Loaded ${allSolutions.length} solutions from ${plannedIssues.length} issues`);
+**Agent Prompt**:
 ```
+## Order Solutions into Execution Queue
 
-### Phase 2-4: Agent-Driven Queue Formation
+**Queue ID**: ${queueId}
+**Solutions**: ${solutions.length} from ${issues.length} issues
+**Project Root**: ${cwd}
 
-```javascript
-// Generate queue-id ONCE here, pass to agent
-const now = new Date();
-const queueId = `QUE-${now.toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+### Input
+${JSON.stringify(solutions)}
 
-// Build minimal prompt - agent orders SOLUTIONS, not tasks
-const agentPrompt = `
-## Order Solutions
+### Workflow
 
-**Queue ID**: ${queueId}
-**Solutions**: ${allSolutions.length} from ${plannedIssues.length} issues
-**Project Root**: ${process.cwd()}
+Step 1: Build dependency graph from solutions (nodes=solutions, edges=file conflicts)
+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
 
-### Input (Solution-Level)
-\`\`\`json
-${JSON.stringify(allSolutions, null, 2)}
-\`\`\`
+### Output Requirements
 
-### 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
+**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
 
-### 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
+**Return JSON**:
 \`\`\`json
 {
-  "queue_id": "QUE-YYYYMMDD-HHMMSS",
+  "queue_id": "${queueId}",
   "total_solutions": N,
   "total_tasks": N,
-  "execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
-  "conflicts_resolved": N,
-  "issues_queued": ["ISS-xxx"]
+  "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
+
+### 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 Agent**:
+```javascript
 const result = Task(
   subagent_type="issue-queue-agent",
-  run_in_background=false,
-  description=`Order ${allSolutions.length} solutions`,
-  prompt=agentPrompt
+  prompt=agentPrompt,
+  description=`Order ${solutions.length} solutions`
 );
-
-const summary = JSON.parse(result);
 ```
 
-### Phase 5: Validation & Status Update
+### Phase 5: Conflict Clarification
+
+**Check Agent Return:**
+- Parse agent result JSON
+- If `clarifications` array exists and non-empty → user decision required
 
+**Clarification Flow:**
 ```javascript
-// ============ VALIDATION: Prevent "next returns empty" issues ============
-
-const queuesDir = '.workflow/issues/queues';
-const indexPath = `${queuesDir}/index.json`;
-const queuePath = `${queuesDir}/${queueId}.json`;
-
-// 1. Validate index.json has active_queue_id
-const indexContent = Bash(`cat "${indexPath}" 2>/dev/null || echo '{}'`);
-const index = JSON.parse(indexContent);
-
-if (index.active_queue_id !== queueId) {
-  console.log(`⚠ Fixing: index.json active_queue_id not set to ${queueId}`);
-  index.active_queue_id = queueId;
-  // Ensure queue entry exists in index
-  if (!index.queues) index.queues = [];
-  const existing = index.queues.find(q => q.id === queueId);
-  if (!existing) {
-    index.queues.unshift({
-      id: queueId,
-      status: 'active',
-      issue_ids: summary.issues_queued,
-      total_solutions: summary.total_solutions,
-      completed_solutions: 0,
-      created_at: new Date().toISOString()
+if (result.clarifications?.length > 0) {
+  for (const clarification of result.clarifications) {
+    // Present to user via AskUserQuestion
+    const answer = AskUserQuestion({
+      questions: [{
+        question: clarification.question,
+        header: clarification.conflict_id,
+        options: clarification.options,
+        multiSelect: false
+      }]
     });
+
+    // Resume agent with user decision
+    Task(
+      subagent_type="issue-queue-agent",
+      resume=agentId,
+      prompt=`Conflict ${clarification.conflict_id} resolved: ${answer.selected}`
+    );
   }
-  Bash(`echo '${JSON.stringify(index, null, 2)}' > "${indexPath}"`);
-  console.log(`✓ Fixed: index.json updated with active_queue_id: ${queueId}`);
 }
+```
 
-// 2. Validate queue file exists and has correct structure
-const queueContent = Bash(`cat "${queuePath}" 2>/dev/null || echo '{}'`);
-const queue = JSON.parse(queueContent);
+### Phase 6: Status Update & Summary
 
-if (!queue.solutions || queue.solutions.length === 0) {
-  console.error(`✗ ERROR: Queue file ${queuePath} has no solutions array`);
-  console.error('  Agent did not generate queue correctly. Aborting.');
-  return;
-}
+**Status Update** (MUST use CLI command, NOT direct file operations):
 
-// 3. Validate all solutions have status: "pending" (not "queued" or other)
-let statusFixed = 0;
-for (const sol of queue.solutions) {
-  if (sol.status !== 'pending' && sol.status !== 'executing' && sol.status !== 'completed') {
-    console.log(`⚠ Fixing: ${sol.item_id} status "${sol.status}" → "pending"`);
-    sol.status = 'pending';
-    statusFixed++;
-  }
-}
+```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
 
-// 4. Validate at least one item has no dependencies (DAG entry point)
-const entryPoints = queue.solutions.filter(s =>
-  s.status === 'pending' && (!s.depends_on || s.depends_on.length === 0)
-);
+# Option 2: Individual issue update
+ccw issue update <issue-id> --status queued
+```
 
-if (entryPoints.length === 0) {
-  console.error(`✗ ERROR: No entry points found (all items have dependencies)`);
-  console.error('  This will cause "ccw issue next" to return empty.');
-  console.error('  Check depends_on fields for circular dependencies.');
-  // Try to fix by clearing first item's dependencies
-  if (queue.solutions.length > 0) {
-    console.log(`⚠ Fixing: Clearing depends_on for first item ${queue.solutions[0].item_id}`);
-    queue.solutions[0].depends_on = [];
-  }
-}
+**⚠️ IMPORTANT**: Do NOT directly modify `issues.jsonl`. Always use CLI command to ensure proper validation and history tracking.
 
-// Write back fixed queue if any changes made
-if (statusFixed > 0 || entryPoints.length === 0) {
-  Bash(`echo '${JSON.stringify(queue, null, 2)}' > "${queuePath}"`);
-  console.log(`✓ Queue file updated with ${statusFixed} status fixes`);
+**Output** (JSON):
+```json
+{
+  "success": true,
+  "queue_id": "QUE-xxx",
+  "queued": ["ISS-001", "ISS-002"],
+  "queued_count": 2,
+  "unplanned": ["ISS-003"],
+  "unplanned_count": 1
 }
+```
 
-// ============ OUTPUT SUMMARY ============
+**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
 
-console.log(`
-## Queue Formed: ${summary.queue_id}
+**Summary Output:**
+- Display queue ID, solution count, task count
+- Show unplanned issues (planned but NOT in queue)
+- Show next step: `/issue:execute`
 
-**Solutions**: ${summary.total_solutions}
-**Tasks**: ${summary.total_tasks}
-**Issues**: ${summary.issues_queued.join(', ')}
-**Groups**: ${summary.execution_groups.map(g => `${g.id}(${g.count})`).join(', ')}
-**Conflicts Resolved**: ${summary.conflicts_resolved}
-**Entry Points**: ${entryPoints.length} (items ready for immediate execution)
 
-Next: \`/issue:execute\` or \`ccw issue next\`
-`);
+## Storage Structure (Queue History)
 
-// Update issue statuses via CLI
-for (const issueId of summary.issues_queued) {
-  Bash(`ccw issue update ${issueId} --status queued`);
-}
+```
+.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
+    └── ...
+```
 
-// Final verification
-const verifyResult = Bash(`ccw issue queue dag 2>/dev/null | head -20`);
-console.log('\n### Verification (DAG Preview):');
-console.log(verifyResult);
+### 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"
+    }
+  ]
+}
 ```
 
+**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 |
-| Unresolved conflicts | Agent resolves using ordering rules |
-| Invalid task reference | Skip and warn |
+| 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 |
-| **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
+- [ ] All conflicts resolved (auto or via user clarification)
+- [ ] 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
+- `ccw issue update --from-queue [queue-id]` - Sync issue statuses from queue