claude-code-workflow 6.3.12 → 6.3.13

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

@@ -49,12 +49,14 @@ color: green
 ```
 Phase 1: Issue Understanding (5%)
     ↓ Fetch details, extract requirements, determine complexity
-Phase 2: ACE Exploration (30%)
+Phase 2: ACE Exploration (25%)
     ↓ 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%)
+Phase 4: Validation & Output (10%)
     ↓ DAG validation, conflict detection, solution registration
+Phase 5: Conflict Analysis (15%)
+    ↓ Gemini CLI multi-solution conflict detection
 ```
 
 #### Phase 1: Issue Understanding
@@ -199,6 +201,67 @@ for (const issue of issues) {
 }
 ```
 
+#### Phase 5: Conflict Analysis (Gemini CLI)
+
+**Trigger**: When batch contains 2+ solutions
+
+**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
+
+**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:
+{
+  "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));
+}
+```
+
+**Integration**: After Phase 4 validation, call `analyzeConflictsGemini()` and merge results into return summary.
+
 ---
 
 ## 2. Output Requirements
@@ -224,8 +287,17 @@ 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 }] }],
+  "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": "..." }]
+  }]
 }
 ```
 

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

@@ -37,7 +37,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 +52,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
@@ -86,22 +88,106 @@ function buildDependencyGraph(solutions) {
 }
 ```
 
-### 2.2 Conflict Detection
+### 2.2 Conflict Detection (5 Types)
 
-Conflict when multiple solutions modify same file:
+Detect all conflict types between solutions:
 ```javascript
-function detectConflicts(fileModifications, graph) {
-  return [...fileModifications.entries()]
-    .filter(([_, solutions]) => solutions.length > 1)
-    .map(([file, solutions]) => ({
-      type: 'file_conflict',
-      file,
-      solutions,
-      resolved: false
-    }))
+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
+      });
+    }
+  }
+
+  // 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
+  })));
+
+  return conflicts;
+}
+```
+
+### 2.2.5 Clarification (BLOCKING)
+
+**Purpose**: Surface ambiguous dependencies for user/system clarification
+
+**Trigger Conditions**:
+- High severity conflicts with no clear resolution order
+- 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
+      });
+    }
+  }
+
+  return clarifications;
 }
 ```
 
+**Blocking Behavior**: Agent BLOCKS execution until clarifications are resolved
+- Return `clarifications` array in output
+- Main agent presents to user via AskUserQuestion
+- Agent waits for response before proceeding to Phase 3
+- No best-guess fallback - explicit user decision required
+
 ### 2.3 Resolution Rules
 
 | Priority | Rule | Example |
@@ -161,7 +247,7 @@ 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",
@@ -189,7 +275,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 +285,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

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

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

@@ -35,16 +35,11 @@ interface Issue {
   affected_components?: string[];// Files/modules affected
   reproduction_steps?: string[]; // Steps to reproduce
 
-  // Discovery context (when source='discovery')
-  discovery_context?: {
-    discovery_id: string;        // Source discovery session
-    perspective: string;         // bug, test, quality, etc.
-    category: string;            // Finding category
-    file: string;                // Primary affected file
-    line: number;                // Line number
-    snippet?: string;            // Code snippet
-    confidence: number;          // Agent confidence (0-1)
+  // Extended context (minimal, for planning hints)
+  extended_context?: {
+    location?: string;           // file:line when specific line matters
     suggested_fix?: string;      // Suggested remediation
+    notes?: string;              // Additional notes (user clarifications or discovery hints)
   };
 
   // Closed-loop requirements (guide plan generation)
@@ -290,6 +285,108 @@ const lifecycle = {
 issueData.lifecycle_requirements = lifecycle;
 ```
 
+### Phase 4.5: Follow-up Questions (Intelligent Suggestions)
+
+```javascript
+// Analyze parsed data and suggest follow-up questions for missing/unclear fields
+const suggestions = [];
+
+// Check for missing critical fields
+if (!issueData.expected_behavior) {
+  suggestions.push({
+    field: 'expected_behavior',
+    question: 'What is the expected behavior?',
+    hint: 'Describe what should happen when working correctly'
+  });
+}
+
+if (!issueData.actual_behavior && issueData.source !== 'discovery') {
+  suggestions.push({
+    field: 'actual_behavior',
+    question: 'What is the actual behavior?',
+    hint: 'Describe what currently happens (error message, wrong output, etc.)'
+  });
+}
+
+if (!issueData.affected_components?.length) {
+  suggestions.push({
+    field: 'affected_components',
+    question: 'Which files or modules are affected?',
+    hint: 'e.g., src/auth/login.ts, src/api/users.ts'
+  });
+}
+
+if (!issueData.reproduction_steps?.length && issueData.source === 'text') {
+  suggestions.push({
+    field: 'reproduction_steps',
+    question: 'How can this issue be reproduced?',
+    hint: 'Step-by-step instructions to trigger the issue'
+  });
+}
+
+// Ask follow-up questions if any suggestions exist
+let userNotes = '';
+if (suggestions.length > 0) {
+  console.log(`
+## Suggested Clarifications
+
+The following information would help with issue resolution:
+${suggestions.map((s, i) => `${i+1}. **${s.question}** - ${s.hint}`).join('\n')}
+`);
+
+  const followUpAnswer = AskUserQuestion({
+    questions: [{
+      question: 'Would you like to provide additional details?',
+      header: 'Clarify',
+      multiSelect: false,
+      options: [
+        { label: 'Add details', description: 'Provide clarifications for suggested questions' },
+        { label: 'Skip', description: 'Continue without additional details (Recommended)' }
+      ]
+    }]
+  });
+
+  if (followUpAnswer.includes('Add details')) {
+    // Collect additional notes via "Other" input
+    const notesAnswer = AskUserQuestion({
+      questions: [{
+        question: 'Enter additional details (address any of the suggested questions):',
+        header: 'Details',
+        multiSelect: false,
+        options: [
+          { label: 'Use template', description: 'Expected: ... | Actual: ... | Files: ...' }
+        ]
+      }]
+    });
+
+    if (notesAnswer.customText) {
+      userNotes = notesAnswer.customText;
+
+      // Parse structured input if provided
+      const expectedMatch = userNotes.match(/expected:\s*([^|]+)/i);
+      const actualMatch = userNotes.match(/actual:\s*([^|]+)/i);
+      const filesMatch = userNotes.match(/files?:\s*([^|]+)/i);
+
+      if (expectedMatch && !issueData.expected_behavior) {
+        issueData.expected_behavior = expectedMatch[1].trim();
+      }
+      if (actualMatch && !issueData.actual_behavior) {
+        issueData.actual_behavior = actualMatch[1].trim();
+      }
+      if (filesMatch && !issueData.affected_components?.length) {
+        issueData.affected_components = filesMatch[1].split(/[,\s]+/).filter(f => f.includes('/') || f.includes('.'));
+      }
+    }
+  }
+}
+
+// Store user notes in extended context
+issueData.extended_context = {
+  ...(issueData.extended_context || {}),
+  notes: userNotes || null
+};
+```
+
 ### Phase 5: User Confirmation
 
 ```javascript
@@ -377,6 +474,9 @@ const newIssue = {
   affected_components: issueData.affected_components || [],
   reproduction_steps: issueData.reproduction_steps || [],
 
+  // Extended context (universal)
+  extended_context: issueData.extended_context || null,
+
   // Closed-loop lifecycle requirements
   lifecycle_requirements: issueData.lifecycle_requirements || {
     test_strategy: 'auto',
@@ -395,9 +495,11 @@ const newIssue = {
 // Ensure directory exists
 Bash('mkdir -p .workflow/issues');
 
-// Append to issues.jsonl
+// Append to issues.jsonl with proper newline handling
 const issuesPath = '.workflow/issues/issues.jsonl';
-Bash(`echo '${JSON.stringify(newIssue)}' >> "${issuesPath}"`);
+const jsonLine = JSON.stringify(newIssue);
+// Ensure file ends with newline before appending, then append with trailing newline
+Bash(`[ -s "${issuesPath}" ] && [ -n "$(tail -c 1 "${issuesPath}")" ] && printf '\\n' >> "${issuesPath}"; printf '%s\\n' '${jsonLine}' >> "${issuesPath}"`);
 
 console.log(`
 ## Issue Created