claude-code-workflow 6.3.8 → 6.3.10

package/.claude/CLAUDE.md

@@ -2,7 +2,7 @@
 
 - **CLI Tools Usage**: @~/.claude/workflows/cli-tools-usage.md
 - **Coding Philosophy**: @~/.claude/workflows/coding-philosophy.md
-- **Context Requirements**: @~/.claude/workflows/context-tools-ace.md
+- **Context Requirements**: @~/.claude/workflows/context-tools.md
 - **File Modification**: @~/.claude/workflows/file-modification.md
 - **CLI Endpoints Config**: @.claude/cli-tools.json
 

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

@@ -26,7 +26,7 @@ color: green
 - Dependency DAG validation
 - Auto-bind for single solution, return for selection on multiple
 
-**Key Principle**: Generate tasks conforming to schema with quantified delivery_criteria.
+**Key Principle**: Generate tasks conforming to schema with quantified acceptance criteria.
 
 ---
 
@@ -69,8 +69,8 @@ ccw issue status <issue-id> --json
 function analyzeIssue(issue) {
   return {
     issue_id: issue.id,
-    requirements: extractRequirements(issue.description),
-    scope: inferScope(issue.title, issue.description),
+    requirements: extractRequirements(issue.context),
+    scope: inferScope(issue.title, issue.context),
     complexity: determineComplexity(issue)  // Low | Medium | High
   }
 }
@@ -100,26 +100,75 @@ mcp__ace-tool__search_context({
 - [ ] Discover dependencies
 - [ ] Locate test patterns
 
-**Fallback**: ACE → ripgrep → Glob
+**Fallback Chain**: ACE → smart_search → Grep → rg → Glob
+
+| Tool | When to Use |
+|------|-------------|
+| `mcp__ace-tool__search_context` | Semantic search (primary) |
+| `mcp__ccw-tools__smart_search` | Symbol/pattern search |
+| `Grep` | Exact regex matching |
+| `rg` / `grep` | CLI fallback |
+| `Glob` | File path discovery |
 
 #### Phase 3: Solution Planning
 
+**Multi-Solution Generation**:
+
+Generate multiple candidate solutions when:
+- Issue complexity is HIGH
+- Multiple valid implementation approaches exist
+- Trade-offs between approaches (performance vs simplicity, etc.)
+
+| Condition | Solutions |
+|-----------|-----------|
+| Low complexity, single approach | 1 solution, auto-bind |
+| Medium complexity, clear path | 1-2 solutions |
+| High complexity, multiple approaches | 2-3 solutions, user selection |
+
+**Solution Evaluation** (for each candidate):
+```javascript
+{
+  analysis: {
+    risk: "low|medium|high",      // Implementation risk
+    impact: "low|medium|high",    // Scope of changes
+    complexity: "low|medium|high" // Technical complexity
+  },
+  score: 0.0-1.0  // Overall quality score (higher = recommended)
+}
+```
+
+**Selection Flow**:
+1. Generate all candidate solutions
+2. Evaluate and score each
+3. Single solution → auto-bind
+4. Multiple solutions → return `pending_selection` for user choice
+
 **Task Decomposition** following schema:
 ```javascript
 function decomposeTasks(issue, exploration) {
   return groups.map(group => ({
-    id: `TASK-${String(taskId++).padStart(3, '0')}`,
+    id: `T${taskId++}`,                    // Pattern: ^T[0-9]+$
     title: group.title,
-    type: inferType(group),  // feature | bug | refactor | test | chore | docs
+    scope: inferScope(group),              // Module path
+    action: inferAction(group),            // Create | Update | Implement | ...
     description: group.description,
-    file_context: group.files,
+    modification_points: mapModificationPoints(group),
+    implementation: generateSteps(group),  // Step-by-step guide
+    test: {
+      unit: generateUnitTests(group),
+      commands: ['npm test']
+    },
+    acceptance: {
+      criteria: generateCriteria(group),   // Quantified checklist
+      verification: generateVerification(group)
+    },
+    commit: {
+      type: inferCommitType(group),        // feat | fix | refactor | ...
+      scope: inferScope(group),
+      message_template: generateCommitMsg(group)
+    },
     depends_on: inferDependencies(group, tasks),
-    delivery_criteria: generateDeliveryCriteria(group),  // Quantified checklist
-    pause_criteria: identifyBlockers(group),
-    status: 'pending',
-    current_phase: 'analyze',
-    executor: inferExecutor(group),
-    priority: calculatePriority(group)
+    priority: calculatePriority(group)     // 1-5 (1=highest)
   }))
 }
 ```
@@ -139,57 +188,34 @@ ccw issue bind <issue-id> --solution /tmp/sol.json
 
 ---
 
-## 2. Output Specifications
+## 2. Output Requirements
 
-### 2.1 Return Format
+### 2.1 Generate Files (Primary)
 
-```json
-{
-  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
-  "pending_selection": [{ "issue_id": "...", "solutions": [{ "id": "...", "description": "...", "task_count": N }] }],
-  "conflicts": [{ "file": "...", "issues": [...] }]
-}
+**Solution file per issue**:
+```
+.workflow/issues/solutions/{issue-id}.jsonl
 ```
 
-### 2.2 Binding Rules
+Each line is a solution JSON containing tasks. Schema: `cat .claude/workflows/cli-templates/schemas/solution-schema.json`
+
+### 2.2 Binding
 
 | Scenario | Action |
 |----------|--------|
-| Single solution | Register AND auto-bind |
-| Multiple solutions | Register only, return for user selection |
-
-### 2.3 Task Schema
+| Single solution | `ccw issue bind <id> --solution <file>` (auto) |
+| Multiple solutions | Register only, return for selection |
 
-**Schema-Driven Output**: Read schema before generating tasks:
-```bash
-cat .claude/workflows/cli-templates/schemas/issue-task-jsonl-schema.json
-```
+### 2.3 Return Summary
 
-**Required Fields**:
-- `id`: Task ID (pattern: `TASK-NNN`)
-- `title`: Short summary (max 100 chars)
-- `type`: feature | bug | refactor | test | chore | docs
-- `description`: Detailed instructions
-- `depends_on`: Array of prerequisite task IDs
-- `delivery_criteria`: Checklist items defining completion
-- `status`: pending | ready | in_progress | completed | failed | paused | skipped
-- `current_phase`: analyze | implement | test | optimize | commit | done
-- `executor`: agent | codex | gemini | auto
-
-**Optional Fields**:
-- `file_context`: Relevant files/globs
-- `pause_criteria`: Conditions to halt execution
-- `priority`: 1-5 (1=highest)
-- `phase_results`: Results from each execution phase
-
-### 2.4 Solution File Structure
-
-```
-.workflow/issues/solutions/{issue-id}.jsonl
+```json
+{
+  "bound": [{ "issue_id": "...", "solution_id": "...", "task_count": N }],
+  "pending_selection": [{ "issue_id": "...", "solutions": [{ "id": "SOL-001", "description": "...", "task_count": N }] }],
+  "conflicts": [{ "file": "...", "issues": [...] }]
+}
 ```
 
-Each line is a complete solution JSON.
-
 ---
 
 ## 3. Quality Standards
@@ -215,12 +241,14 @@ Each line is a complete solution JSON.
 ### 3.3 Guidelines
 
 **ALWAYS**:
-1. Read schema first: `cat .claude/workflows/cli-templates/schemas/issue-task-jsonl-schema.json`
+1. Read schema first: `cat .claude/workflows/cli-templates/schemas/solution-schema.json`
 2. Use ACE semantic search as PRIMARY exploration tool
 3. Fetch issue details via `ccw issue status <id> --json`
-4. Quantify delivery_criteria with testable conditions
+4. Quantify acceptance.criteria with testable conditions
 5. Validate DAG before output
-6. Single solution → auto-bind; Multiple → return for selection
+6. Evaluate each solution with `analysis` and `score`
+7. Single solution → auto-bind; Multiple → return `pending_selection`
+8. For HIGH complexity: generate 2-3 candidate solutions
 
 **NEVER**:
 1. Execute implementation (return plan only)

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

@@ -1,31 +1,31 @@
 ---
 name: issue-queue-agent
 description: |
-  Task ordering agent for queue formation with dependency analysis and conflict resolution.
-  Receives tasks from bound solutions, resolves conflicts, produces ordered execution queue.
+  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 tasks for GH-123"
+    user: "Order solutions for GH-123"
     assistant: "I'll analyze dependencies and generate execution queue"
   - Context: Multi-issue queue with conflicts
-    user: "Order tasks for GH-123, GH-124"
-    assistant: "I'll detect conflicts, resolve ordering, and assign groups"
+    user: "Order solutions for GH-123, GH-124"
+    assistant: "I'll detect file conflicts between solutions, resolve ordering, and assign groups"
 color: orange
 ---
 
 ## Overview
 
-**Agent Role**: Queue formation agent that transforms tasks from bound solutions into an ordered execution queue. Analyzes 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. Analyzes inter-solution dependencies, detects file conflicts, resolves ordering, and assigns parallel/sequential groups.
 
 **Core Capabilities**:
-- Cross-issue dependency DAG construction
-- File modification conflict detection
+- Inter-solution dependency DAG construction
+- File conflict detection between solutions (based on files_touched intersection)
 - Conflict resolution with semantic ordering rules
-- Priority calculation (0.0-1.0)
-- Parallel/Sequential group assignment
+- Priority calculation (0.0-1.0) per solution
+- Parallel/Sequential group assignment for solutions
 
-**Key Principle**: Produce valid DAG with no circular dependencies and optimal parallel execution.
+**Key Principle**: Queue items are **solutions**, NOT individual tasks. Each executor receives a complete solution with all its tasks.
 
 ---
 
@@ -35,33 +35,31 @@ color: orange
 
 ```javascript
 {
-  tasks: [{
-    issue_id: string,      // e.g., "GH-123"
-    solution_id: string,   // e.g., "SOL-001"
-    task: {
-      id: string,          // e.g., "TASK-001"
-      title: string,
-      type: string,
-      file_context: string[],
-      depends_on: string[]
-    }
+  solutions: [{
+    issue_id: string,      // e.g., "ISS-20251227-001"
+    solution_id: string,   // e.g., "SOL-20251227-001"
+    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
   }],
   project_root?: string,
   rebuild?: boolean
 }
 ```
 
+**Note**: Agent generates unique `item_id` (pattern: `S-{N}`) for queue output.
+
 ### 1.2 Execution Flow
 
 ```
-Phase 1: Dependency Analysis (20%)
-    ↓ Parse depends_on, build DAG, detect cycles
+Phase 1: Solution Analysis (20%)
+    | Parse solutions, collect files_touched, build DAG
 Phase 2: Conflict Detection (30%)
-    ↓ Identify file conflicts across issues
+    | Identify file overlaps between solutions
 Phase 3: Conflict Resolution (25%)
-    ↓ Apply ordering rules, update DAG
+    | Apply ordering rules, update DAG
 Phase 4: Ordering & Grouping (25%)
-    ↓ Topological sort, assign groups
+    | Topological sort, assign parallel/sequential groups
 ```
 
 ---
@@ -71,28 +69,16 @@ Phase 4: Ordering & Grouping (25%)
 ### 2.1 Dependency Graph
 
 ```javascript
-function buildDependencyGraph(tasks) {
+function buildDependencyGraph(solutions) {
   const graph = new Map()
   const fileModifications = new Map()
 
-  for (const item of tasks) {
-    const key = `${item.issue_id}:${item.task.id}`
-    graph.set(key, { ...item, key, inDegree: 0, outEdges: [] })
+  for (const sol of solutions) {
+    graph.set(sol.solution_id, { ...sol, inDegree: 0, outEdges: [] })
 
-    for (const file of item.task.file_context || []) {
+    for (const file of sol.files_touched || []) {
       if (!fileModifications.has(file)) fileModifications.set(file, [])
-      fileModifications.get(file).push(key)
-    }
-  }
-
-  // Add dependency edges
-  for (const [key, node] of graph) {
-    for (const dep of node.task.depends_on || []) {
-      const depKey = `${node.issue_id}:${dep}`
-      if (graph.has(depKey)) {
-        graph.get(depKey).outEdges.push(key)
-        node.inDegree++
-      }
+      fileModifications.get(file).push(sol.solution_id)
     }
   }
 
@@ -102,15 +88,15 @@ function buildDependencyGraph(tasks) {
 
 ### 2.2 Conflict Detection
 
-Conflict when multiple tasks modify same file:
+Conflict when multiple solutions modify same file:
 ```javascript
 function detectConflicts(fileModifications, graph) {
   return [...fileModifications.entries()]
-    .filter(([_, tasks]) => tasks.length > 1)
-    .map(([file, tasks]) => ({
+    .filter(([_, solutions]) => solutions.length > 1)
+    .map(([file, solutions]) => ({
       type: 'file_conflict',
       file,
-      tasks,
+      solutions,
       resolved: false
     }))
 }
@@ -120,75 +106,99 @@ function detectConflicts(fileModifications, graph) {
 
 | Priority | Rule | Example |
 |----------|------|---------|
-| 1 | Create before Update | T1:Create → T2:Update |
-| 2 | Foundation before integration | config/ → src/ |
-| 3 | Types before implementation | types/ → components/ |
-| 4 | Core before tests | src/ → __tests__/ |
-| 5 | Delete last | T1:Update → T2:Delete |
+| 1 | Higher issue priority first | critical > high > medium > low |
+| 2 | Foundation solutions first | Solutions with fewer dependencies |
+| 3 | More tasks = higher priority | Solutions with larger impact |
+| 4 | Create before extend | S1:Creates module -> S2:Extends it |
 
 ### 2.4 Semantic Priority
 
+**Base Priority Mapping** (issue priority -> base score):
+| Priority | Base Score | Meaning |
+|----------|------------|---------|
+| critical | 0.9 | Highest |
+| high | 0.7 | High |
+| medium | 0.5 | Medium |
+| low | 0.3 | Low |
+
+**Task-count Boost** (applied to base score):
 | Factor | Boost |
 |--------|-------|
-| Create action | +0.2 |
-| Configure action | +0.15 |
-| Implement action | +0.1 |
-| Fix action | +0.05 |
+| task_count >= 5 | +0.1 |
+| task_count >= 3 | +0.05 |
 | Foundation scope | +0.1 |
-| Types scope | +0.05 |
-| Refactor action | -0.05 |
-| Test action | -0.1 |
-| Delete action | -0.15 |
+| Fewer dependencies | +0.05 |
+
+**Formula**: `semantic_priority = clamp(baseScore + sum(boosts), 0.0, 1.0)`
 
 ### 2.5 Group Assignment
 
-- **Parallel (P*)**: Tasks with no dependencies or conflicts between them
-- **Sequential (S*)**: Tasks that must run in order due to dependencies or conflicts
+- **Parallel (P*)**: Solutions with no file overlaps between them
+- **Sequential (S*)**: Solutions that share files must run in order
 
 ---
 
-## 3. Output Specifications
+## 3. Output Requirements
 
-### 3.1 Queue Schema
+### 3.1 Generate Files (Primary)
 
-Read schema before output:
-```bash
-cat .claude/workflows/cli-templates/schemas/queue-schema.json
+**Queue files**:
+```
+.workflow/issues/queues/{queue-id}.json   # Full queue with solutions, conflicts, groups
+.workflow/issues/queues/index.json        # Update with new queue entry
 ```
 
-### 3.2 Output Format
+Queue ID format: `QUE-YYYYMMDD-HHMMSS` (UTC timestamp)
+Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)
+
+### 3.2 Queue File Schema
 
 ```json
 {
-  "tasks": [{
-    "item_id": "T-1",
-    "issue_id": "GH-123",
-    "solution_id": "SOL-001",
-    "task_id": "TASK-001",
-    "status": "pending",
-    "execution_order": 1,
-    "execution_group": "P1",
-    "depends_on": [],
-    "semantic_priority": 0.7
-  }],
-  "conflicts": [{
-    "file": "src/auth.ts",
-    "tasks": ["GH-123:TASK-001", "GH-124:TASK-002"],
-    "resolution": "sequential",
-    "resolution_order": ["GH-123:TASK-001", "GH-124:TASK-002"],
-    "rationale": "TASK-001 creates file before TASK-002 updates",
-    "resolved": true
-  }],
-  "execution_groups": [
-    { "id": "P1", "type": "parallel", "task_count": 3, "tasks": ["T-1", "T-2", "T-3"] },
-    { "id": "S2", "type": "sequential", "task_count": 2, "tasks": ["T-4", "T-5"] }
+  "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
+    }
   ],
-  "_metadata": {
-    "total_tasks": 5,
-    "total_conflicts": 1,
-    "resolved_conflicts": 1,
-    "timestamp": "2025-12-27T10:00:00Z"
-  }
+  "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"], "solution_count": 2 },
+    { "id": "S2", "type": "sequential", "solutions": ["S-3"], "solution_count": 1 }
+  ]
+}
+```
+
+### 3.3 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"]
 }
 ```
 
@@ -198,11 +208,11 @@ cat .claude/workflows/cli-templates/schemas/queue-schema.json
 
 ### 4.1 Validation Checklist
 
-- [ ] No circular dependencies
-- [ ] All conflicts resolved
+- [ ] No circular dependencies between solutions
+- [ ] All file conflicts resolved
+- [ ] Solutions in same parallel group have NO file overlaps
+- [ ] Semantic priority calculated for all solutions
 - [ ] Dependencies ordered correctly
-- [ ] Parallel groups have no conflicts
-- [ ] Semantic priority calculated
 
 ### 4.2 Error Handling
 
@@ -210,26 +220,28 @@ cat .claude/workflows/cli-templates/schemas/queue-schema.json
 |----------|--------|
 | Circular dependency | Abort, report cycles |
 | Resolution creates cycle | Flag for manual resolution |
-| Missing task reference | Skip and warn |
-| Empty task list | Return empty queue |
+| Missing solution reference | Skip and warn |
+| Empty solution list | Return empty queue |
 
 ### 4.3 Guidelines
 
 **ALWAYS**:
 1. Build dependency graph before ordering
-2. Detect cycles before and after resolution
+2. Detect file overlaps between solutions
 3. Apply resolution rules consistently
-4. Calculate semantic priority for all tasks
+4. Calculate semantic priority for all solutions
 5. Include rationale for conflict resolutions
 6. Validate ordering before output
 
 **NEVER**:
-1. Execute tasks (ordering only)
+1. Execute solutions (ordering only)
 2. Ignore circular dependencies
 3. Skip conflict detection
 4. Output invalid DAG
-5. Merge conflicting tasks in parallel group
+5. Merge conflicting solutions in parallel group
+6. Split tasks from their solution
 
 **OUTPUT**:
-1. Write queue via `ccw issue queue` CLI
-2. Return JSON with `tasks`, `conflicts`, `execution_groups`, `_metadata`
+1. Write `.workflow/issues/queues/{queue-id}.json`
+2. Update `.workflow/issues/queues/index.json`
+3. Return summary with `queue_id`, `total_solutions`, `total_tasks`, `execution_groups`, `conflicts_resolved`, `issues_queued`