claude-code-workflow 6.3.13 → 6.3.16

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,16 +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 (25%)
+Phase 2: ACE Exploration (30%)
     ↓ Semantic search, pattern discovery, dependency mapping
 Phase 3: Solution Planning (45%)
     ↓ Task decomposition, 5-phase lifecycle, acceptance criteria
-Phase 4: Validation & Output (10%)
-    ↓ DAG validation, conflict detection, solution registration
-Phase 5: Conflict Analysis (15%)
-    ↓ Gemini CLI multi-solution conflict detection
+Phase 4: Validation & Output (15%)
+    ↓ DAG validation, solution registration, binding
 ```
 
 #### Phase 1: Issue Understanding
@@ -180,87 +170,53 @@ 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):
 
-#### Phase 5: Conflict Analysis (Gemini CLI)
+**Step 1: Create solution files**
 
-**Trigger**: When batch contains 2+ solutions
+Write solution JSON to JSONL file (one line per solution):
 
-**Conflict Types Analyzed**:
-1. **File Conflicts**: Modified file overlaps
-2. **API Conflicts**: Interface/breaking changes
-3. **Data Model Conflicts**: Schema changes
-4. **Dependency Conflicts**: Package version conflicts
-5. **Architecture Conflicts**: Pattern violations
+```
+.workflow/issues/solutions/{issue-id}.jsonl
+```
 
-**Gemini CLI Call**:
-```javascript
-function analyzeConflictsGemini(solutions, projectRoot) {
-  if (solutions.length < 2) return { conflicts: [], safe_parallel: [solutions.map(s => s.id)] };
-
-  const solutionSummaries = solutions.map(sol => ({
-    issue_id: sol.issue_id,
-    solution_id: sol.id,
-    files_modified: extractFilesFromTasks(sol.tasks),
-    api_changes: extractApiChanges(sol.tasks),
-    data_changes: extractDataChanges(sol.tasks)
-  }));
-
-  const prompt = `
-PURPOSE: Detect conflicts between solution implementations; identify all conflict types; provide resolution recommendations
-TASK: • Analyze file overlaps • Check API breaking changes • Detect schema conflicts • Find dependency conflicts • Identify architecture violations
-MODE: analysis
-CONTEXT: Solution summaries
-EXPECTED: JSON conflict report with type, severity, solutions_affected, resolution_strategy
-RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Mark severity (high/medium/low) | Provide recommended_order
-
-SOLUTIONS:
-${JSON.stringify(solutionSummaries, null, 2)}
-
-OUTPUT FORMAT:
+**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
 {
-  "conflicts": [{
-    "type": "file_conflict|api_conflict|data_conflict|dependency_conflict|architecture_conflict",
-    "severity": "high|medium|low",
-    "solutions_affected": ["SOL-GH-123-1", "SOL-GH-123-2"],
-    "summary": "brief description",
-    "resolution_strategy": "sequential|parallel_with_coordination|refactor_merge",
-    "recommended_order": ["SOL-GH-123-1", "SOL-GH-123-2"],
-    "rationale": "why this order"
-  }],
-  "safe_parallel": [["SOL-GH-124-1", "SOL-GH-125-1"]]
-}
-`;
-
-  const taskId = Bash({
-    command: `ccw cli -p "${prompt}" --tool gemini --mode analysis --cd "${projectRoot}"`,
-    run_in_background: true, timeout: 900000
-  });
-  const output = TaskOutput({ task_id: taskId, block: true });
-  return JSON.parse(extractJsonFromMarkdown(output));
+  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
 }
 ```
 
-**Integration**: After Phase 4 validation, call `analyzeConflictsGemini()` and merge results into return summary.
+**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)
 
 ---
 
@@ -279,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
@@ -287,17 +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": "GH-123", "solutions": [{ "id": "SOL-GH-123-1", "description": "...", "task_count": N }] }],
-  "conflicts": [{
-    "type": "file_conflict|api_conflict|data_conflict|dependency_conflict|architecture_conflict",
-    "severity": "high|medium|low",
-    "solutions_affected": ["SOL-GH-123-1", "SOL-GH-123-2"],
-    "summary": "brief description",
-    "resolution_strategy": "sequential|parallel_with_coordination",
-    "recommended_order": ["SOL-GH-123-1", "SOL-GH-123-2"],
-    "recommended_resolution": "Use sequential execution: SOL-GH-123-1 first",
-    "resolution_options": [{ "strategy": "...", "rationale": "..." }]
-  }]
+  "pending_selection": [{ "issue_id": "GH-123", "solutions": [{ "id": "SOL-GH-123-1", "description": "...", "task_count": N }] }]
 }
 ```
 
@@ -332,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)
@@ -343,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
@@ -70,84 +62,50 @@ Phase 4: Ordering & Grouping (25%)
 
 ### 2.1 Dependency Graph
 
-```javascript
-function buildDependencyGraph(solutions) {
-  const graph = new Map()
-  const fileModifications = new Map()
-
-  for (const sol of solutions) {
-    graph.set(sol.solution_id, { ...sol, inDegree: 0, outEdges: [] })
-
-    for (const file of sol.files_touched || []) {
-      if (!fileModifications.has(file)) fileModifications.set(file, [])
-      fileModifications.get(file).push(sol.solution_id)
-    }
-  }
-
-  return { graph, fileModifications }
-}
+**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
 ```
 
-### 2.2 Conflict Detection (5 Types)
+**Placeholder**: `${SOLUTIONS_JSON}` = serialized solutions array from bound issues
 
-Detect all conflict types between solutions:
-```javascript
-function detectConflicts(solutions, graph) {
-  const conflicts = [];
-  const fileModifications = buildFileModificationMap(solutions);
-
-  // 1. File conflicts (multiple solutions modify same file)
-  for (const [file, solIds] of fileModifications.entries()) {
-    if (solIds.length > 1) {
-      conflicts.push({
-        type: 'file_conflict', severity: 'medium',
-        file, solutions: solIds, resolved: false
-      });
-    }
-  }
-
-  // 2. API conflicts (breaking interface changes)
-  const apiChanges = extractApiChangesFromAllSolutions(solutions);
-  for (const [api, changes] of apiChanges.entries()) {
-    if (changes.some(c => c.breaking)) {
-      conflicts.push({
-        type: 'api_conflict', severity: 'high',
-        api, solutions: changes.map(c => c.solution_id), resolved: false
-      });
-    }
-  }
-
-  // 3. Data model conflicts (schema changes to same model)
-  const dataChanges = extractDataChangesFromAllSolutions(solutions);
-  for (const [model, changes] of dataChanges.entries()) {
-    if (changes.length > 1) {
-      conflicts.push({
-        type: 'data_conflict', severity: 'high',
-        model, solutions: changes.map(c => c.solution_id), resolved: false
-      });
-    }
-  }
-
-  // 4. Dependency conflicts (package version conflicts)
-  const depChanges = extractDependencyChanges(solutions);
-  for (const [pkg, versions] of depChanges.entries()) {
-    if (versions.length > 1 && !versionsCompatible(versions)) {
-      conflicts.push({
-        type: 'dependency_conflict', severity: 'medium',
-        package: pkg, solutions: versions.map(v => v.solution_id), resolved: false
-      });
-    }
-  }
+**Conflict Types & Severity**:
 
-  // 5. Architecture conflicts (pattern violations)
-  const archIssues = detectArchitectureViolations(solutions);
-  conflicts.push(...archIssues.map(issue => ({
-    type: 'architecture_conflict', severity: 'low',
-    pattern: issue.pattern, solutions: issue.solutions, resolved: false
-  })));
+| 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 |
 
-  return conflicts;
-}
+**Output per conflict**:
+```json
+{ "type": "...", "severity": "...", "solutions": [...], "recommended_order": [...], "rationale": "..." }
 ```
 
 ### 2.2.5 Clarification (BLOCKING)
@@ -155,37 +113,22 @@ function detectConflicts(solutions, graph) {
 **Purpose**: Surface ambiguous dependencies for user/system clarification
 
 **Trigger Conditions**:
-- High severity conflicts with no clear resolution order
+- High severity conflicts without `recommended_order` from Gemini analysis
 - Circular dependencies detected
 - Multiple valid resolution strategies
 
-**Clarification Logic**:
-```javascript
-function generateClarifications(conflicts, solutions) {
-  const clarifications = [];
-
-  for (const conflict of conflicts) {
-    if (conflict.severity === 'high' && !conflict.recommended_order) {
-      clarifications.push({
-        conflict_id: `CFT-${clarifications.length + 1}`,
-        question: `${conflict.type}: Which solution should execute first?`,
-        options: conflict.solutions.map(solId => ({
-          value: solId,
-          label: getSolutionSummary(solId, solutions)
-        })),
-        requires_user_input: true
-      });
-    }
-  }
+**Clarification Generation**:
 
-  return clarifications;
-}
-```
+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**: Agent BLOCKS execution until clarifications are resolved
+**Blocking Behavior**:
 - Return `clarifications` array in output
 - Main agent presents to user via AskUserQuestion
-- Agent waits for response before proceeding to Phase 3
+- Agent BLOCKS until all clarifications resolved
 - No best-guess fallback - explicit user decision required
 
 ### 2.3 Resolution Rules
@@ -253,7 +196,6 @@ Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
       "execution_group": "P1",
       "depends_on": [],
       "semantic_priority": 0.8,
-      "assigned_executor": "codex",
       "files_touched": ["src/auth.ts", "src/utils.ts"],
       "task_count": 3
     }
@@ -345,14 +287,21 @@ Return brief summaries; full conflict details in separate files:
 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