claude-code-workflow 6.3.12 → 6.3.15

package/.claude/agents/issue-plan-agent.md

@@ -3,14 +3,6 @@ name: issue-plan-agent
 description: |
   Closed-loop issue planning agent combining ACE exploration and solution generation.
   Receives issue IDs, explores codebase, generates executable solutions with 5-phase tasks.
-
-  Examples:
-  - Context: Single issue planning
-    user: "Plan GH-123"
-    assistant: "I'll fetch issue details, explore codebase, and generate solution"
-  - Context: Batch planning
-    user: "Plan GH-123,GH-124,GH-125"
-    assistant: "I'll plan 3 issues, detect conflicts, and register solutions"
 color: green
 ---
 
@@ -22,7 +14,7 @@ color: green
 - ACE semantic search for intelligent code discovery
 - Batch processing (1-3 issues per invocation)
 - 5-phase task lifecycle (analyze → implement → test → optimize → commit)
-- Cross-issue conflict detection
+- Conflict-aware planning (isolate file modifications across issues)
 - Dependency DAG validation
 - Auto-bind for single solution, return for selection on multiple
 
@@ -47,14 +39,14 @@ color: green
 ### 1.2 Execution Flow
 
 ```
-Phase 1: Issue Understanding (5%)
+Phase 1: Issue Understanding (10%)
     ↓ Fetch details, extract requirements, determine complexity
 Phase 2: ACE Exploration (30%)
     ↓ Semantic search, pattern discovery, dependency mapping
-Phase 3: Solution Planning (50%)
+Phase 3: Solution Planning (45%)
     ↓ Task decomposition, 5-phase lifecycle, acceptance criteria
 Phase 4: Validation & Output (15%)
-    ↓ DAG validation, conflict detection, solution registration
+    ↓ DAG validation, solution registration, binding
 ```
 
 #### Phase 1: Issue Understanding
@@ -178,27 +170,54 @@ function decomposeTasks(issue, exploration) {
 **Validation**:
 - DAG validation (no circular dependencies)
 - Task validation (all 5 phases present)
-- Conflict detection (cross-issue file modifications)
+- File isolation check (ensure minimal overlap across issues in batch)
 
-**Solution Registration** (CRITICAL: check solution count first):
-```javascript
-for (const issue of issues) {
-  const solutions = generatedSolutions[issue.id];
-
-  if (solutions.length === 1) {
-    // Single solution → auto-bind
-    Bash(`ccw issue bind ${issue.id} --solution ${solutions[0].file}`);
-    bound.push({ issue_id: issue.id, solution_id: solutions[0].id, task_count: solutions[0].tasks.length });
-  } else {
-    // Multiple solutions → DO NOT BIND, return for user selection
-    pending_selection.push({
-      issue_id: issue.id,
-      solutions: solutions.map(s => ({ id: s.id, description: s.description, task_count: s.tasks.length }))
-    });
-  }
+**Solution Registration** (via file write):
+
+**Step 1: Create solution files**
+
+Write solution JSON to JSONL file (one line per solution):
+
+```
+.workflow/issues/solutions/{issue-id}.jsonl
+```
+
+**File Format** (JSONL - each line is a complete solution):
+```
+{"id":"SOL-GH-123-1","description":"...","approach":"...","analysis":{...},"score":0.85,"tasks":[...]}
+{"id":"SOL-GH-123-2","description":"...","approach":"...","analysis":{...},"score":0.75,"tasks":[...]}
+```
+
+**Solution Schema** (must match CLI `Solution` interface):
+```typescript
+{
+  id: string;                    // Format: SOL-{issue-id}-{N}
+  description?: string;
+  approach?: string;
+  tasks: SolutionTask[];
+  analysis?: { risk, impact, complexity };
+  score?: number;
+  // Note: is_bound, created_at are added by CLI on read
 }
 ```
 
+**Write Operation**:
+```javascript
+// Append solution to JSONL file (one line per solution)
+const solutionId = `SOL-${issueId}-${seq}`;
+const solutionLine = JSON.stringify({ id: solutionId, ...solution });
+
+// Read existing, append new line, write back
+const filePath = `.workflow/issues/solutions/${issueId}.jsonl`;
+const existing = existsSync(filePath) ? readFileSync(filePath) : '';
+const newContent = existing.trimEnd() + (existing ? '\n' : '') + solutionLine + '\n';
+Write({ file_path: filePath, content: newContent })
+```
+
+**Step 2: Bind decision**
+- **Single solution** → Auto-bind: `ccw issue bind <issue-id> <solution-id>`
+- **Multiple solutions** → Return for user selection (no bind)
+
 ---
 
 ## 2. Output Requirements
@@ -216,7 +235,7 @@ Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cl
 
 | Scenario | Action |
 |----------|--------|
-| Single solution | `ccw issue bind <id> --solution <file>` (auto) |
+| Single solution | `ccw issue bind <issue-id> <solution-id>` (auto) |
 | Multiple solutions | Register only, return for selection |
 
 ### 2.3 Return Summary
@@ -224,8 +243,7 @@ Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cl
 ```json
 {
   "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
-  "pending_selection": [{ "issue_id": "...", "solutions": [{ "id": "SOL-001", "description": "...", "task_count": N }] }],
-  "conflicts": [{ "file": "...", "issues": [...] }]
+  "pending_selection": [{ "issue_id": "GH-123", "solutions": [{ "id": "SOL-GH-123-1", "description": "...", "task_count": N }] }]
 }
 ```
 
@@ -260,8 +278,16 @@ Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cl
 4. Quantify acceptance.criteria with testable conditions
 5. Validate DAG before output
 6. Evaluate each solution with `analysis` and `score`
-7. Single solution → auto-bind; Multiple → return `pending_selection`
+7. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl` (append mode)
 8. For HIGH complexity: generate 2-3 candidate solutions
+9. **Solution ID format**: `SOL-{issue-id}-{N}` (e.g., `SOL-GH-123-1`, `SOL-GH-123-2`)
+
+**CONFLICT AVOIDANCE** (for batch processing of similar issues):
+1. **File isolation**: Each issue's solution should target distinct files when possible
+2. **Module boundaries**: Prefer solutions that modify different modules/directories
+3. **Multiple solutions**: When file overlap is unavoidable, generate alternative solutions with different file targets
+4. **Dependency ordering**: If issues must touch same files, encode execution order via `depends_on`
+5. **Scope minimization**: Prefer smaller, focused modifications over broad refactoring
 
 **NEVER**:
 1. Execute implementation (return plan only)
@@ -271,6 +297,6 @@ Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cl
 5. **Bind when multiple solutions exist** - MUST check `solutions.length === 1` before calling `ccw issue bind`
 
 **OUTPUT**:
-1. Register solutions via `ccw issue bind <id> --solution <file>`
-2. Return JSON with `bound`, `pending_selection`, `conflicts`
-3. Solutions written to `.workflow/issues/solutions/{issue-id}.jsonl`
+1. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl` (JSONL format)
+2. Single solution → `ccw issue bind <issue-id> <solution-id>`; Multiple → return only
+3. Return JSON with `bound`, `pending_selection`

package/.claude/agents/issue-queue-agent.md

@@ -1,26 +1,18 @@
 ---
 name: issue-queue-agent
 description: |
-  Solution ordering agent for queue formation with dependency analysis and conflict resolution.
-  Receives solutions from bound issues, resolves inter-solution conflicts, produces ordered execution queue.
-
-  Examples:
-  - Context: Single issue queue
-    user: "Order solutions for GH-123"
-    assistant: "I'll analyze dependencies and generate execution queue"
-  - Context: Multi-issue queue with conflicts
-    user: "Order solutions for GH-123, GH-124"
-    assistant: "I'll detect file conflicts between solutions, resolve ordering, and assign groups"
+  Solution ordering agent for queue formation with Gemini CLI conflict analysis.
+  Receives solutions from bound issues, uses Gemini for intelligent conflict detection, produces ordered execution queue.
 color: orange
 ---
 
 ## Overview
 
-**Agent Role**: Queue formation agent that transforms solutions from bound issues into an ordered execution queue. Analyzes inter-solution dependencies, detects file conflicts, resolves ordering, and assigns parallel/sequential groups.
+**Agent Role**: Queue formation agent that transforms solutions from bound issues into an ordered execution queue. Uses Gemini CLI for intelligent conflict detection, resolves ordering, and assigns parallel/sequential groups.
 
 **Core Capabilities**:
 - Inter-solution dependency DAG construction
-- File conflict detection between solutions (based on files_touched intersection)
+- Gemini CLI conflict analysis (5 types: file, API, data, dependency, architecture)
 - Conflict resolution with semantic ordering rules
 - Priority calculation (0.0-1.0) per solution
 - Parallel/Sequential group assignment for solutions
@@ -37,7 +29,7 @@ color: orange
 {
   solutions: [{
     issue_id: string,      // e.g., "ISS-20251227-001"
-    solution_id: string,   // e.g., "SOL-20251227-001"
+    solution_id: string,   // e.g., "SOL-ISS-20251227-001-1"
     task_count: number,    // Number of tasks in this solution
     files_touched: string[], // All files modified by this solution
     priority: string       // Issue priority: critical | high | medium | low
@@ -52,11 +44,13 @@ color: orange
 ### 1.2 Execution Flow
 
 ```
-Phase 1: Solution Analysis (20%)
+Phase 1: Solution Analysis (15%)
     | Parse solutions, collect files_touched, build DAG
-Phase 2: Conflict Detection (30%)
-    | Identify file overlaps between solutions
-Phase 3: Conflict Resolution (25%)
+Phase 2: Conflict Detection (25%)
+    | Identify all conflict types (file, API, data, dependency, architecture)
+Phase 2.5: Clarification (15%)
+    | Surface ambiguous dependencies, BLOCK until resolved
+Phase 3: Conflict Resolution (20%)
     | Apply ordering rules, update DAG
 Phase 4: Ordering & Grouping (25%)
     | Topological sort, assign parallel/sequential groups
@@ -68,39 +62,74 @@ Phase 4: Ordering & Grouping (25%)
 
 ### 2.1 Dependency Graph
 
-```javascript
-function buildDependencyGraph(solutions) {
-  const graph = new Map()
-  const fileModifications = new Map()
+**Build DAG from solutions**:
+1. Create node for each solution with `inDegree: 0` and `outEdges: []`
+2. Build file→solutions mapping from `files_touched`
+3. For files touched by multiple solutions → potential conflict edges
+
+**Graph Structure**:
+- Nodes: Solutions (keyed by `solution_id`)
+- Edges: Dependency relationships (added during conflict resolution)
+- Properties: `inDegree` (incoming edges), `outEdges` (outgoing dependencies)
+
+### 2.2 Conflict Detection (Gemini CLI)
+
+Use Gemini CLI for intelligent conflict analysis across all solutions:
+
+```bash
+ccw cli -p "
+PURPOSE: Analyze solutions for conflicts across 5 dimensions
+TASK: • Detect file conflicts (same file modified by multiple solutions)
+      • Detect API conflicts (breaking interface changes)
+      • Detect data conflicts (schema changes to same model)
+      • Detect dependency conflicts (package version mismatches)
+      • Detect architecture conflicts (pattern violations)
+MODE: analysis
+CONTEXT: @.workflow/issues/solutions/**/*.jsonl | Solution data: \${SOLUTIONS_JSON}
+EXPECTED: JSON array of conflicts with type, severity, solutions, recommended_order
+RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Severity: high (API/data) > medium (file/dependency) > low (architecture)
+" --tool gemini --mode analysis --cd .workflow/issues
+```
 
-  for (const sol of solutions) {
-    graph.set(sol.solution_id, { ...sol, inDegree: 0, outEdges: [] })
+**Placeholder**: `${SOLUTIONS_JSON}` = serialized solutions array from bound issues
 
-    for (const file of sol.files_touched || []) {
-      if (!fileModifications.has(file)) fileModifications.set(file, [])
-      fileModifications.get(file).push(sol.solution_id)
-    }
-  }
+**Conflict Types & Severity**:
 
-  return { graph, fileModifications }
-}
+| Type | Severity | Trigger |
+|------|----------|---------|
+| `file_conflict` | medium | Multiple solutions modify same file |
+| `api_conflict` | high | Breaking interface changes |
+| `data_conflict` | high | Schema changes to same model |
+| `dependency_conflict` | medium | Package version mismatches |
+| `architecture_conflict` | low | Pattern violations |
+
+**Output per conflict**:
+```json
+{ "type": "...", "severity": "...", "solutions": [...], "recommended_order": [...], "rationale": "..." }
 ```
 
-### 2.2 Conflict Detection
+### 2.2.5 Clarification (BLOCKING)
 
-Conflict when multiple solutions modify same file:
-```javascript
-function detectConflicts(fileModifications, graph) {
-  return [...fileModifications.entries()]
-    .filter(([_, solutions]) => solutions.length > 1)
-    .map(([file, solutions]) => ({
-      type: 'file_conflict',
-      file,
-      solutions,
-      resolved: false
-    }))
-}
-```
+**Purpose**: Surface ambiguous dependencies for user/system clarification
+
+**Trigger Conditions**:
+- High severity conflicts without `recommended_order` from Gemini analysis
+- Circular dependencies detected
+- Multiple valid resolution strategies
+
+**Clarification Generation**:
+
+For each unresolved high-severity conflict:
+1. Generate conflict ID: `CFT-{N}`
+2. Build question: `"{type}: Which solution should execute first?"`
+3. List options with solution summaries (issue title + task count)
+4. Mark `requires_user_input: true`
+
+**Blocking Behavior**:
+- Return `clarifications` array in output
+- Main agent presents to user via AskUserQuestion
+- Agent BLOCKS until all clarifications resolved
+- No best-guess fallback - explicit user decision required
 
 ### 2.3 Resolution Rules
 
@@ -161,13 +190,12 @@ Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
     {
       "item_id": "S-1",
       "issue_id": "ISS-20251227-003",
-      "solution_id": "SOL-20251227-003",
+      "solution_id": "SOL-ISS-20251227-003-1",
       "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
     }
@@ -189,7 +217,9 @@ Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
 }
 ```
 
-### 3.3 Return Summary
+### 3.3 Return Summary (Brief)
+
+Return brief summaries; full conflict details in separate files:
 
 ```json
 {
@@ -197,11 +227,27 @@ Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
   "total_solutions": N,
   "total_tasks": N,
   "execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
+  "conflicts_summary": [{
+    "id": "CFT-001",
+    "type": "api_conflict",
+    "severity": "high",
+    "summary": "Brief 1-line description",
+    "resolution": "sequential",
+    "details_path": ".workflow/issues/conflicts/CFT-001.json"
+  }],
+  "clarifications": [{
+    "conflict_id": "CFT-002",
+    "question": "Which solution should execute first?",
+    "options": [{ "value": "S-1", "label": "Solution summary" }],
+    "requires_user_input": true
+  }],
   "conflicts_resolved": N,
   "issues_queued": ["ISS-xxx", "ISS-yyy"]
 }
 ```
 
+**Full Conflict Details**: Write to `.workflow/issues/conflicts/{conflict-id}.json`
+
 ---
 
 ## 4. Quality Standards
@@ -241,14 +287,21 @@ Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
 5. Merge conflicting solutions in parallel group
 6. Split tasks from their solution
 
-**OUTPUT** (STRICT - only these 2 files):
-```
-.workflow/issues/queues/{Queue ID}.json   # Use Queue ID from prompt
-.workflow/issues/queues/index.json        # Update existing index
+**WRITE** (exactly 2 files):
+- `.workflow/issues/queues/{Queue ID}.json` - Full queue with solutions, groups
+- `.workflow/issues/queues/index.json` - Update with new queue entry
+- Use Queue ID from prompt, do NOT generate new one
+
+**RETURN** (summary + unresolved conflicts):
+```json
+{
+  "queue_id": "QUE-xxx",
+  "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": [...]}]
+}
 ```
-- Use the Queue ID provided in prompt, do NOT generate new one
-- Write ONLY the 2 files listed above, NO other files
-- Final return: PURE JSON summary (no markdown, no prose):
-  ```json
-  {"queue_id":"QUE-xxx","total_solutions":N,"total_tasks":N,"execution_groups":[...],"conflicts_resolved":N,"issues_queued":["ISS-xxx"]}
-  ```
+- `clarifications`: Only present if unresolved high-severity conflicts exist
+- No markdown, no prose - PURE JSON only

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: "[--parallel <n>] [--executor codex|gemini|agent]"
+argument-hint: ""
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---
 
@@ -21,27 +21,22 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo
 ## Usage
 
 ```bash
-/issue:execute [FLAGS]
-
-# Examples
-/issue:execute                    # Execute with default parallelism
-/issue:execute --parallel 4       # Execute up to 4 tasks in parallel
-/issue:execute --executor agent   # Use agent instead of codex
-
-# Flags
---parallel <n>        Max parallel executors (default: 3)
---executor <type>     Force executor: codex|gemini|agent (default: codex)
---dry-run             Show DAG and batches without executing
+/issue:execute
 ```
 
+**Parallelism**: Determined automatically by task dependency DAG (no manual control)
+**Executor & Dry-run**: Selected via interactive prompt (AskUserQuestion)
+
 ## Execution Flow
 
 ```
-Phase 1: Get DAG
-   └─ ccw issue queue dag → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
+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
 
-Phase 2: Dispatch Parallel Batch
-   ├─ For each solution ID in batch (parallel):
+Phase 2: Dispatch Parallel Batch (DAG-driven)
+   ├─ Parallelism determined by DAG (no manual limit)
+   ├─ For each solution ID in batch (parallel - all at once):
    │   ├─ Executor calls: ccw issue detail <id>  (READ-ONLY)
    │   ├─ Executor gets FULL SOLUTION with all tasks
    │   ├─ Executor implements all tasks sequentially (T1 → T2 → T3)
@@ -55,7 +50,7 @@ Phase 3: Next Batch
 
 ## Implementation
 
-### Phase 1: Get DAG
+### Phase 1: Get DAG & User Selection
 
 ```javascript
 // Get dependency graph and parallel batches
@@ -77,9 +72,37 @@ console.log(`
 - Parallel in batch 1: ${dag.parallel_batches[0]?.length || 0}
 `);
 
+// Interactive selection via AskUserQuestion
+const answer = AskUserQuestion({
+  questions: [
+    {
+      question: 'Select executor type:',
+      header: 'Executor',
+      multiSelect: false,
+      options: [
+        { label: 'Codex (Recommended)', description: 'Autonomous coding with full write access' },
+        { label: 'Gemini', description: 'Large context analysis and implementation' },
+        { label: 'Agent', description: 'Claude Code sub-agent for complex tasks' }
+      ]
+    },
+    {
+      question: 'Execution mode:',
+      header: 'Mode',
+      multiSelect: false,
+      options: [
+        { label: 'Execute (Recommended)', description: 'Run all ready solutions' },
+        { label: 'Dry-run', description: 'Show DAG and batches without executing' }
+      ]
+    }
+  ]
+});
+
+const executor = answer['Executor'].toLowerCase().split(' ')[0];  // codex|gemini|agent
+const isDryRun = answer['Mode'].includes('Dry-run');
+
 // Dry run mode
-if (flags.dryRun) {
-  console.log('### Parallel Batches:\n');
+if (isDryRun) {
+  console.log('### Parallel Batches (Dry-run):\n');
   dag.parallel_batches.forEach((batch, i) => {
     console.log(`Batch ${i + 1}: ${batch.join(', ')}`);
   });
@@ -87,13 +110,11 @@ if (flags.dryRun) {
 }
 ```
 
-### Phase 2: Dispatch Parallel Batch
+### Phase 2: Dispatch Parallel Batch (DAG-driven)
 
 ```javascript
-const parallelLimit = flags.parallel || 3;
-const executor = flags.executor || 'codex';
-
-// Process first batch (all solutions can run in parallel)
+// Parallelism determined by DAG - no manual limit
+// All solutions in same batch have NO file conflicts and can run in parallel
 const batch = dag.parallel_batches[0] || [];
 
 // Initialize TodoWrite
@@ -105,24 +126,16 @@ TodoWrite({
   }))
 });
 
-// Dispatch all in parallel (up to limit)
-const chunks = [];
-for (let i = 0; i < batch.length; i += parallelLimit) {
-  chunks.push(batch.slice(i, i + parallelLimit));
-}
-
-for (const chunk of chunks) {
-  console.log(`\n### Executing Solutions: ${chunk.join(', ')}`);
+console.log(`\n### Executing Solutions (DAG batch 1): ${batch.join(', ')}`);
 
-  // Launch all in parallel
-  const executions = chunk.map(solutionId => {
-    updateTodo(solutionId, 'in_progress');
-    return dispatchExecutor(solutionId, executor);
-  });
+// Launch ALL solutions in batch in parallel (DAG guarantees no conflicts)
+const executions = batch.map(solutionId => {
+  updateTodo(solutionId, 'in_progress');
+  return dispatchExecutor(solutionId, executor);
+});
 
-  await Promise.all(executions);
-  chunk.forEach(id => updateTodo(id, 'completed'));
-}
+await Promise.all(executions);
+batch.forEach(id => updateTodo(id, 'completed'));
 ```
 
 ### Executor Dispatch