claude-code-workflow 6.3.18 → 6.3.19

package/.claude/commands/issue/execute.md

@@ -1,7 +1,7 @@
 ---
 name: execute
-description: Execute queue with codex using DAG-based parallel orchestration (solution-level)
-argument-hint: ""
+description: Execute queue with DAG-based parallel orchestration (one commit per solution)
+argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---
 
@@ -17,31 +17,51 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo
 - `done <id>` → update solution completion status
 - No race conditions: status changes only via `done`
 - **Executor handles all tasks within a solution sequentially**
+- **Worktree isolation**: Each executor can work in its own git worktree
 
 ## Usage
 
 ```bash
-/issue:execute
+/issue:execute                           # Execute active queue(s)
+/issue:execute --queue QUE-xxx           # Execute specific queue
+/issue:execute --worktree                # Use git worktrees for parallel isolation
+/issue:execute --worktree --queue QUE-xxx
+/issue:execute --worktree /path/to/existing/worktree  # Resume in existing worktree
 ```
 
 **Parallelism**: Determined automatically by task dependency DAG (no manual control)
 **Executor & Dry-run**: Selected via interactive prompt (AskUserQuestion)
+**Worktree**: Creates isolated git worktrees for each parallel executor
+
+**⭐ Recommended Executor**: **Codex** - Best for long-running autonomous work (2hr timeout), supports background execution and full write access
+
+**Worktree Options**:
+- `--worktree` - Create a new worktree with timestamp-based name
+- `--worktree <existing-path>` - Resume in an existing worktree (for recovery/continuation)
+
+**Resume**: Use `git worktree list` to find existing worktrees from interrupted executions
 
 ## Execution Flow
 
 ```
+Phase 0 (if --worktree): Setup Worktree Base
+   └─ Ensure .worktrees directory exists
+
 Phase 1: Get DAG & User Selection
-   ├─ ccw issue queue dag → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
-   └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode
+   ├─ ccw issue queue dag [--queue QUE-xxx] → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
+   └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode, worktree mode
 
 Phase 2: Dispatch Parallel Batch (DAG-driven)
    ├─ Parallelism determined by DAG (no manual limit)
    ├─ For each solution ID in batch (parallel - all at once):
+   │   ├─ (if worktree) Create isolated worktree: git worktree add
    │   ├─ Executor calls: ccw issue detail <id>  (READ-ONLY)
    │   ├─ Executor gets FULL SOLUTION with all tasks
    │   ├─ Executor implements all tasks sequentially (T1 → T2 → T3)
-   │   ├─ Executor tests + commits per task
-   │   └─ Executor calls: ccw issue done <id>
+   │   ├─ Executor tests + verifies each task
+   │   ├─ Executor commits ONCE per solution (with formatted summary)
+   │   ├─ Executor calls: ccw issue done <id>
+   │   └─ (if worktree) Cleanup: merge branch, remove worktree
    └─ Wait for batch completion
 
 Phase 3: Next Batch
@@ -93,12 +113,22 @@ const answer = AskUserQuestion({
         { label: 'Execute (Recommended)', description: 'Run all ready solutions' },
         { label: 'Dry-run', description: 'Show DAG and batches without executing' }
       ]
+    },
+    {
+      question: 'Use git worktrees for parallel isolation?',
+      header: 'Worktree',
+      multiSelect: false,
+      options: [
+        { label: 'Yes (Recommended for parallel)', description: 'Each executor works in isolated worktree branch' },
+        { label: 'No', description: 'Work directly in current directory (serial only)' }
+      ]
     }
   ]
 });
 
 const executor = answer['Executor'].toLowerCase().split(' ')[0];  // codex|gemini|agent
 const isDryRun = answer['Mode'].includes('Dry-run');
+const useWorktree = answer['Worktree'].includes('Yes');
 
 // Dry run mode
 if (isDryRun) {
@@ -128,10 +158,24 @@ TodoWrite({
 
 console.log(`\n### Executing Solutions (DAG batch 1): ${batch.join(', ')}`);
 
+// Setup worktree base directory if needed (using absolute paths)
+if (useWorktree) {
+  // Use absolute paths to avoid issues when running from subdirectories
+  const repoRoot = Bash('git rev-parse --show-toplevel').trim();
+  const worktreeBase = `${repoRoot}/.ccw/worktrees`;
+  Bash(`mkdir -p "${worktreeBase}"`);
+  // Prune stale worktrees from previous interrupted executions
+  Bash('git worktree prune');
+}
+
+// Parse existing worktree path from args if provided
+// Example: --worktree /path/to/existing/worktree
+const existingWorktree = args.worktree && typeof args.worktree === 'string' ? args.worktree : null;
+
 // Launch ALL solutions in batch in parallel (DAG guarantees no conflicts)
 const executions = batch.map(solutionId => {
   updateTodo(solutionId, 'in_progress');
-  return dispatchExecutor(solutionId, executor);
+  return dispatchExecutor(solutionId, executor, useWorktree, existingWorktree);
 });
 
 await Promise.all(executions);
@@ -141,13 +185,126 @@ batch.forEach(id => updateTodo(id, 'completed'));
 ### Executor Dispatch
 
 ```javascript
-function dispatchExecutor(solutionId, executorType) {
-  // Executor fetches FULL SOLUTION via READ-ONLY detail command
-  // Executor handles all tasks within solution sequentially
-  // Then reports completion via done command
+function dispatchExecutor(solutionId, executorType, useWorktree = false, existingWorktree = null) {
+  // Worktree setup commands (if enabled) - using absolute paths
+  // Supports both creating new worktrees and resuming in existing ones
+  const worktreeSetup = useWorktree ? `
+### Step 0: Setup Isolated Worktree
+\`\`\`bash
+# Use absolute paths to avoid issues when running from subdirectories
+REPO_ROOT=$(git rev-parse --show-toplevel)
+WORKTREE_BASE="\${REPO_ROOT}/.ccw/worktrees"
+
+# Check if existing worktree path was provided
+EXISTING_WORKTREE="${existingWorktree || ''}"
+
+if [[ -n "\${EXISTING_WORKTREE}" && -d "\${EXISTING_WORKTREE}" ]]; then
+  # Resume mode: Use existing worktree
+  WORKTREE_PATH="\${EXISTING_WORKTREE}"
+  WORKTREE_NAME=$(basename "\${WORKTREE_PATH}")
+
+  # Verify it's a valid git worktree
+  if ! git -C "\${WORKTREE_PATH}" rev-parse --is-inside-work-tree &>/dev/null; then
+    echo "Error: \${EXISTING_WORKTREE} is not a valid git worktree"
+    exit 1
+  fi
+
+  echo "Resuming in existing worktree: \${WORKTREE_PATH}"
+else
+  # Create mode: New worktree with timestamp
+  WORKTREE_NAME="exec-${solutionId}-$(date +%H%M%S)"
+  WORKTREE_PATH="\${WORKTREE_BASE}/\${WORKTREE_NAME}"
+
+  # Ensure worktree base exists
+  mkdir -p "\${WORKTREE_BASE}"
+
+  # Prune stale worktrees
+  git worktree prune
+
+  # Create worktree
+  git worktree add "\${WORKTREE_PATH}" -b "\${WORKTREE_NAME}"
+
+  echo "Created new worktree: \${WORKTREE_PATH}"
+fi
+
+# Setup cleanup trap for graceful failure handling
+cleanup_worktree() {
+  echo "Cleaning up worktree due to interruption..."
+  cd "\${REPO_ROOT}" 2>/dev/null || true
+  git worktree remove "\${WORKTREE_PATH}" --force 2>/dev/null || true
+  echo "Worktree removed. Branch '\${WORKTREE_NAME}' kept for inspection."
+}
+trap cleanup_worktree EXIT INT TERM
+
+cd "\${WORKTREE_PATH}"
+\`\`\`
+` : '';
+
+  const worktreeCleanup = useWorktree ? `
+### Step 5: Worktree Completion (User Choice)
+
+After all tasks complete, prompt for merge strategy:
+
+\`\`\`javascript
+AskUserQuestion({
+  questions: [{
+    question: "Solution ${solutionId} completed. What to do with worktree branch?",
+    header: "Merge",
+    multiSelect: false,
+    options: [
+      { label: "Create PR (Recommended)", description: "Push branch and create pull request - safest for parallel execution" },
+      { label: "Merge to main", description: "Merge branch and cleanup worktree (requires clean main)" },
+      { label: "Keep branch", description: "Cleanup worktree, keep branch for manual handling" }
+    ]
+  }]
+})
+\`\`\`
+
+**Based on selection:**
+\`\`\`bash
+# Disable cleanup trap before intentional cleanup
+trap - EXIT INT TERM
+
+# Return to repo root (use REPO_ROOT from setup)
+cd "\${REPO_ROOT}"
+
+# Validate main repo state before merge
+validate_main_clean() {
+  if [[ -n \$(git status --porcelain) ]]; then
+    echo "⚠️ Warning: Main repo has uncommitted changes."
+    echo "Cannot auto-merge. Falling back to 'Create PR' option."
+    return 1
+  fi
+  return 0
+}
+
+# Create PR (Recommended for parallel execution):
+git push -u origin "\${WORKTREE_NAME}"
+gh pr create --title "Solution ${solutionId}" --body "Issue queue execution"
+git worktree remove "\${WORKTREE_PATH}"
+
+# Merge to main (only if main is clean):
+if validate_main_clean; then
+  git merge --no-ff "\${WORKTREE_NAME}" -m "Merge solution ${solutionId}"
+  git worktree remove "\${WORKTREE_PATH}" && git branch -d "\${WORKTREE_NAME}"
+else
+  # Fallback to PR if main is dirty
+  git push -u origin "\${WORKTREE_NAME}"
+  gh pr create --title "Solution ${solutionId}" --body "Issue queue execution (main had uncommitted changes)"
+  git worktree remove "\${WORKTREE_PATH}"
+fi
+
+# Keep branch:
+git worktree remove "\${WORKTREE_PATH}"
+echo "Branch \${WORKTREE_NAME} kept for manual handling"
+\`\`\`
+
+**Parallel Execution Safety**: "Create PR" is the default and safest option for parallel executors, avoiding merge race conditions.
+` : '';
+
   const prompt = `
 ## Execute Solution ${solutionId}
-
+${worktreeSetup}
 ### Step 1: Get Solution (read-only)
 \`\`\`bash
 ccw issue detail ${solutionId}
@@ -161,19 +318,41 @@ For each task:
 1. Follow task.implementation steps
 2. Run task.test commands
 3. Verify task.acceptance criteria
-4. Commit using task.commit specification
+(Do NOT commit after each task)
+
+### Step 3: Commit Solution (Once)
+After ALL tasks pass, commit once with formatted summary:
+\`\`\`bash
+git add <all-modified-files>
+git commit -m "[type](scope): [solution.description]
+
+## Solution Summary
+- Solution-ID: ${solutionId}
+- Tasks: T1, T2, ...
+
+## Tasks Completed
+- [T1] task1.title: action
+- [T2] task2.title: action
+
+## Files Modified
+- file1.ts
+- file2.ts
+
+## Verification
+- All tests passed
+- All acceptance criteria verified"
+\`\`\`
 
-### Step 3: Report Completion
-When ALL tasks in solution are done:
+### Step 4: Report Completion
 \`\`\`bash
-ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "tasks_completed": N}'
+ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "commit": {"hash": "...", "type": "feat"}, "tasks_completed": N}'
 \`\`\`
 
 If any task failed:
 \`\`\`bash
-ccw issue done ${solutionId} --fail --reason "Task TX failed: ..."
+ccw issue done ${solutionId} --fail --reason '{"task_id": "TX", "error_type": "test_failure", "message": "..."}'
 \`\`\`
-`;
+${worktreeCleanup}`;
 
   if (executorType === 'codex') {
     return Bash(
@@ -229,6 +408,7 @@ if (refreshedDag.ready_count > 0) {
 │    │ detail S-1           │ │ detail S-2           │       │
 │    │ → gets full solution │ │ → gets full solution │       │
 │    │ [T1→T2→T3 sequential]│ │ [T1→T2 sequential]   │       │
+│    │ commit (1x solution) │ │ commit (1x solution) │       │
 │    │ done S-1             │ │ done S-2             │       │
 │    └──────────────────────┘ └──────────────────────┘       │
 │                                                             │
@@ -240,6 +420,7 @@ if (refreshedDag.ready_count > 0) {
 **Why this works for parallel:**
 - `detail <id>` is READ-ONLY → no race conditions
 - Each executor handles **all tasks within a solution** sequentially
+- **One commit per solution** with formatted summary (not per-task)
 - `done <id>` updates only its own solution status
 - `queue dag` recalculates ready solutions after each batch
 - Solutions in same batch have NO file conflicts

package/.claude/commands/issue/new.md

@@ -320,4 +320,4 @@ function parseMarkdownBody(body) {
 ## Related Commands
 
 - `/issue:plan` - Plan solution for issue
-- `/issue:manage` - Interactive issue management
+

package/.claude/commands/issue/plan.md

@@ -304,6 +304,12 @@ Next: \`/issue:queue\` → \`/issue:execute\`
 | User cancels selection | Skip issue, continue with others |
 | File conflicts | Agent detects and suggests resolution order |
 
+## Bash Compatibility
+
+**Avoid**: `$(cmd)`, `$var`, `for` loops — will be escaped incorrectly
+
+**Use**: Simple commands + `&&` chains, quote comma params `"pending,registered"`
+
 ## Quality Checklist
 
 Before completing, verify:
@@ -319,6 +325,5 @@ Before completing, verify:
 ## Related Commands
 
 - `/issue:queue` - Form execution queue from bound solutions
-- `/issue:execute` - Execute queue with codex
 - `ccw issue list` - List all issues
 - `ccw issue status` - View issue and solution details

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

@@ -1,7 +1,7 @@
 ---
 name: queue
 description: Form execution queue from bound solutions using issue-queue-agent (solution-level)
-argument-hint: "[--rebuild] [--issue <id>]"
+argument-hint: "[--queues <n>] [--issue <id>]"
 allowed-tools: TodoWrite(*), Task(*), Bash(*), Read(*), Write(*)
 ---
 
@@ -33,6 +33,7 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 | 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 (brief)** | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
 
 **Output Options**:
 - `--brief`: JSON with minimal fields (id, status, counts)
@@ -53,6 +54,7 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 
 # 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)
@@ -60,6 +62,7 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 /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)
 
@@ -73,45 +76,48 @@ ccw issue queue delete <queue-id>     Delete queue from history
 ## Execution Process
 
 ```
-Phase 1: Solution Loading
+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 modification_points
-   └─ Build solution objects array
+   ├─ 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)
-   ├─ Launch issue-queue-agent with solutions array
-   ├─ Agent performs:
+   ├─ 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)
-   └─ Agent writes: queue JSON + index update
+   └─ Each 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
+   ├─ 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 queue summary, next step: /issue:execute
+   └─ Display queue summary (N queues), next step: /issue:execute
 ```
 
 ## Implementation
 
-### Phase 1: Solution Loading
+### Phase 1: Solution Loading & Distribution
 
 **Data Loading:**
-- Load `issues.jsonl` and filter issues with `status === 'planned'` and `bound_solution_id`
+- Use `ccw issue list --status planned --brief` to get planned issues with `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`
+**Solution Brief Loading** (for each planned issue):
+```bash
+ccw issue solution <issue-id> --brief
+# Returns: [{ solution_id, is_bound, task_count, files_touched[] }]
+```
 
 **Build Solution Objects:**
 ```json
@@ -124,29 +130,39 @@ Phase 6: Status Update & Summary
 }
 ```
 
-**Output:** Array of solution objects ready for agent processing
+**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 ID** (command layer, pass to agent):
+**Generate Queue IDs** (command layer, pass to agent):
 ```javascript
-const queueId = `QUE-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+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**:
+**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)
+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)
@@ -176,6 +192,7 @@ Step 6: Write queue JSON + update index
 - 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
@@ -185,39 +202,66 @@ Step 6: Write queue JSON + update index
 - [ ] Return JSON matches required shape
 ```
 
-**Launch Agent**:
+**Launch Agents** (parallel if multi-queue):
 ```javascript
-const result = Task(
-  subagent_type="issue-queue-agent",
-  prompt=agentPrompt,
-  description=`Order ${solutions.length} solutions`
-);
+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 Task 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
-- If `clarifications` array exists and non-empty → user decision required
+- 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 (result.clarifications?.length > 0) {
-  for (const clarification of result.clarifications) {
+if (allClarifications.length > 0) {
+  for (const clarification of allClarifications) {
     // Present to user via AskUserQuestion
     const answer = AskUserQuestion({
       questions: [{
-        question: clarification.question,
+        question: `[${clarification.queue_id}] ${clarification.question}`,
         header: clarification.conflict_id,
         options: clarification.options,
         multiSelect: false
       }]
     });
 
-    // Resume agent with user decision
+    // Resume respective agent with user decision
     Task(
       subagent_type="issue-queue-agent",
-      resume=agentId,
+      resume=clarification.agent_id,
       prompt=`Conflict ${clarification.conflict_id} resolved: ${answer.selected}`
     );
   }
@@ -282,9 +326,13 @@ ccw issue update <issue-id> --status queued
 ```json
 {
   "active_queue_id": "QUE-20251227-143000",
+  "active_queue_group": "QGR-20251227-143000",
   "queues": [
     {
-      "id": "QUE-20251227-143000",
+      "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,
@@ -295,6 +343,12 @@ ccw issue update <issue-id> --status queued
 }
 ```
 
+**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
 
@@ -312,16 +366,17 @@ ccw issue update <issue-id> --status queued
 Before completing, verify:
 
 - [ ] All planned issues with `bound_solution_id` are included
-- [ ] Queue JSON written to `queues/{queue-id}.json`
+- [ ] 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: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