claude-code-workflow 6.3.9 → 6.3.10

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

@@ -1,7 +1,7 @@
 ---
 name: execute
-description: Execute queue with codex using endpoint-driven task fetching (single task per codex instance)
-argument-hint: "[--parallel <n>] [--executor codex|gemini]"
+description: Execute queue with codex using DAG-based parallel orchestration (solution-level)
+argument-hint: "[--parallel <n>] [--executor codex|gemini|agent]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---
 
@@ -9,26 +9,14 @@ allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 
 ## Overview
 
-Execution orchestrator that coordinates codex instances. Each task is executed by an independent codex instance that fetches its task via CLI endpoint. **Codex does NOT read task files** - it calls `ccw issue next` to get task data dynamically.
+Minimal orchestrator that dispatches **solution IDs** to executors. Each executor receives a complete solution with all its tasks.
 
-**Core design:**
-- Single task per codex instance (not loop mode)
-- Endpoint-driven: `ccw issue next` → execute → `ccw issue complete`
-- No file reading in codex
-- Orchestrator manages parallelism
-
-## Storage Structure (Queue History)
-
-```
-.workflow/issues/
-├── issues.jsonl              # All issues (one per line)
-├── queues/                   # Queue history directory
-│   ├── index.json            # Queue index (active + history)
-│   └── {queue-id}.json       # Individual queue files
-└── solutions/
-    ├── {issue-id}.jsonl      # Solutions for issue
-    └── ...
-```
+**Design Principles:**
+- `queue dag` → returns parallel batches with solution IDs (S-1, S-2, ...)
+- `detail <id>` → READ-ONLY solution fetch (returns full solution with all tasks)
+- `done <id>` → update solution completion status
+- No race conditions: status changes only via `done`
+- **Executor handles all tasks within a solution sequentially**
 
 ## Usage
 
@@ -36,427 +24,271 @@ Execution orchestrator that coordinates codex instances. Each task is executed b
 /issue:execute [FLAGS]
 
 # Examples
-/issue:execute                    # Execute all ready tasks
-/issue:execute --parallel 3       # Execute up to 3 tasks in parallel
-/issue:execute --executor codex   # Force codex executor
+/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 codex instances (default: 1)
---executor <type>     Force executor: codex|gemini|agent
---dry-run             Show what would execute without running
+--parallel <n>        Max parallel executors (default: 3)
+--executor <type>     Force executor: codex|gemini|agent (default: codex)
+--dry-run             Show DAG and batches without executing
 ```
 
-## Execution Process
+## Execution Flow
 
 ```
-Phase 1: Queue Loading
-   ├─ Load queue.json
-   ├─ Count pending/ready tasks
-   └─ Initialize TodoWrite tracking
-
-Phase 2: Ready Task Detection
-   ├─ Find tasks with satisfied dependencies
-   ├─ Group by execution_group (parallel batches)
-   └─ Determine execution order
-
-Phase 3: Codex Coordination
-   ├─ For each ready task:
-   │   ├─ Launch independent codex instance
-   │   ├─ Codex calls: ccw issue next
-   │   ├─ Codex receives task data (NOT file)
-   │   ├─ Codex executes task
-   │   ├─ Codex calls: ccw issue complete <queue-id>
-   │   └─ Update TodoWrite
-   └─ Parallel execution based on --parallel flag
-
-Phase 4: Completion
-   ├─ Generate execution summary
-   ├─ Update issue statuses in issues.jsonl
-   └─ Display results
+Phase 1: Get DAG
+   └─ ccw issue queue dag → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
+
+Phase 2: Dispatch Parallel Batch
+   ├─ For each solution ID in batch (parallel):
+   │   ├─ 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>
+   └─ Wait for batch completion
+
+Phase 3: Next Batch
+   └─ ccw issue queue dag → check for newly-ready solutions
 ```
 
 ## Implementation
 
-### Phase 1: Queue Loading
+### Phase 1: Get DAG
 
 ```javascript
-// Load active queue via CLI endpoint
-const queueJson = Bash(`ccw issue status --json 2>/dev/null || echo '{}'`);
-const queue = JSON.parse(queueJson);
+// Get dependency graph and parallel batches
+const dagJson = Bash(`ccw issue queue dag`).trim();
+const dag = JSON.parse(dagJson);
 
-if (!queue.id || queue.tasks?.length === 0) {
-  console.log('No active queue found. Run /issue:queue first.');
+if (dag.error || dag.ready_count === 0) {
+  console.log(dag.error || 'No solutions ready for execution');
+  console.log('Use /issue:queue to form a queue first');
   return;
 }
 
-// Count by status
-const pending = queue.tasks.filter(q => q.status === 'pending');
-const executing = queue.tasks.filter(q => q.status === 'executing');
-const completed = queue.tasks.filter(q => q.status === 'completed');
-
 console.log(`
-## Execution Queue Status
+## Queue DAG (Solution-Level)
 
-- Pending: ${pending.length}
-- Executing: ${executing.length}
-- Completed: ${completed.length}
-- Total: ${queue.tasks.length}
+- Total Solutions: ${dag.total}
+- Ready: ${dag.ready_count}
+- Completed: ${dag.completed_count}
+- Parallel in batch 1: ${dag.parallel_batches[0]?.length || 0}
 `);
 
-if (pending.length === 0 && executing.length === 0) {
-  console.log('All tasks completed!');
+// Dry run mode
+if (flags.dryRun) {
+  console.log('### Parallel Batches:\n');
+  dag.parallel_batches.forEach((batch, i) => {
+    console.log(`Batch ${i + 1}: ${batch.join(', ')}`);
+  });
   return;
 }
 ```
 
-### Phase 2: Ready Task Detection
+### Phase 2: Dispatch Parallel Batch
 
 ```javascript
-// Find ready tasks (dependencies satisfied)
-function getReadyTasks() {
-  const completedIds = new Set(
-    queue.tasks.filter(q => q.status === 'completed').map(q => q.item_id)
-  );
-
-  return queue.tasks.filter(item => {
-    if (item.status !== 'pending') return false;
-    return item.depends_on.every(depId => completedIds.has(depId));
-  });
-}
-
-const readyTasks = getReadyTasks();
-
-if (readyTasks.length === 0) {
-  if (executing.length > 0) {
-    console.log('Tasks are currently executing. Wait for completion.');
-  } else {
-    console.log('No ready tasks. Check for blocked dependencies.');
-  }
-  return;
-}
-
-console.log(`Found ${readyTasks.length} ready tasks`);
+const parallelLimit = flags.parallel || 3;
+const executor = flags.executor || 'codex';
 
-// Sort by execution order
-readyTasks.sort((a, b) => a.execution_order - b.execution_order);
+// Process first batch (all solutions can run in parallel)
+const batch = dag.parallel_batches[0] || [];
 
 // Initialize TodoWrite
 TodoWrite({
-  todos: readyTasks.slice(0, parallelLimit).map(t => ({
-    content: `[${t.item_id}] ${t.issue_id}:${t.task_id}`,
+  todos: batch.map(id => ({
+    content: `Execute solution ${id}`,
     status: 'pending',
-    activeForm: `Executing ${t.item_id}`
+    activeForm: `Executing solution ${id}`
   }))
 });
-```
 
-### Phase 3: Codex Coordination (Single Task Mode - Full Lifecycle)
+// 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));
+}
 
-```javascript
-// Execute tasks - single codex instance per task with full lifecycle
-async function executeTask(queueItem) {
-  const codexPrompt = `
-## Single Task Execution - CLOSED-LOOP LIFECYCLE
+for (const chunk of chunks) {
+  console.log(`\n### Executing Solutions: ${chunk.join(', ')}`);
 
-You are executing ONE task from the issue queue. Each task has 5 phases that MUST ALL complete successfully.
+  // Launch all in parallel
+  const executions = chunk.map(solutionId => {
+    updateTodo(solutionId, 'in_progress');
+    return dispatchExecutor(solutionId, executor);
+  });
 
-### Step 1: Fetch Task
-Run this command to get your task:
+  await Promise.all(executions);
+  chunk.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
+  const prompt = `
+## Execute Solution ${solutionId}
+
+### Step 1: Get Solution (read-only)
 \`\`\`bash
-ccw issue next
+ccw issue detail ${solutionId}
 \`\`\`
 
-This returns JSON with full lifecycle definition:
-- task.implementation: Implementation steps
-- task.test: Test requirements and commands
-- task.regression: Regression check commands
-- task.acceptance: Acceptance criteria and verification
-- task.commit: Commit specification
-
-### Step 2: Execute Full Lifecycle
-
-**Phase 1: IMPLEMENT**
-1. Follow task.implementation steps in order
-2. Modify files specified in modification_points
-3. Use context.relevant_files for reference
-4. Use context.patterns for code style
-
-**Phase 2: TEST**
-1. Run test commands from task.test.commands
-2. Ensure all unit tests pass (task.test.unit)
-3. Run integration tests if specified (task.test.integration)
-4. Verify coverage meets task.test.coverage_target if specified
-5. If tests fail → fix code and re-run, do NOT proceed until tests pass
-
-**Phase 3: REGRESSION**
-1. Run all commands in task.regression
-2. Ensure no existing tests are broken
-3. If regression fails → fix and re-run
-
-**Phase 4: ACCEPTANCE**
-1. Verify each criterion in task.acceptance.criteria
-2. Execute verification steps in task.acceptance.verification
-3. Complete any manual_checks if specified
-4. All criteria MUST pass before proceeding
-
-**Phase 5: COMMIT**
-1. Stage all modified files
-2. Use task.commit.message_template as commit message
-3. Commit with: git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"
-4. If commit_strategy is 'per-task', commit now
-5. If commit_strategy is 'atomic' or 'squash', stage but don't commit
+### Step 2: Execute All Tasks Sequentially
+The detail command returns a FULL SOLUTION with all tasks.
+Execute each task in order (T1 → T2 → T3 → ...):
+
+For each task:
+1. Follow task.implementation steps
+2. Run task.test commands
+3. Verify task.acceptance criteria
+4. Commit using task.commit specification
 
 ### Step 3: Report Completion
-When ALL phases complete successfully:
+When ALL tasks in solution are done:
 \`\`\`bash
-ccw issue complete <item_id> --result '{
-  "files_modified": ["path1", "path2"],
-  "tests_passed": true,
-  "regression_passed": true,
-  "acceptance_passed": true,
-  "committed": true,
-  "commit_hash": "<hash>",
-  "summary": "What was done"
-}'
+ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "tasks_completed": N}'
 \`\`\`
 
-If any phase fails and cannot be fixed:
+If any task failed:
 \`\`\`bash
-ccw issue fail <item_id> --reason "Phase X failed: <details>"
+ccw issue done ${solutionId} --fail --reason "Task TX failed: ..."
 \`\`\`
-
-### Rules
-- NEVER skip any lifecycle phase
-- Tests MUST pass before proceeding to acceptance
-- Regression MUST pass before commit
-- ALL acceptance criteria MUST be verified
-- Report accurate lifecycle status in result
-
-### Start Now
-Begin by running: ccw issue next
 `;
 
-  // Execute codex
-  const executor = queueItem.assigned_executor || flags.executor || 'codex';
-
-  if (executor === 'codex') {
-    Bash(
-      `ccw cli -p "${escapePrompt(codexPrompt)}" --tool codex --mode write --id exec-${queueItem.item_id}`,
-      timeout=3600000  // 1 hour timeout
+  if (executorType === 'codex') {
+    return Bash(
+      `ccw cli -p "${escapePrompt(prompt)}" --tool codex --mode write --id exec-${solutionId}`,
+      { timeout: 7200000, run_in_background: true }  // 2hr for full solution
     );
-  } else if (executor === 'gemini') {
-    Bash(
-      `ccw cli -p "${escapePrompt(codexPrompt)}" --tool gemini --mode write --id exec-${queueItem.item_id}`,
-      timeout=1800000  // 30 min timeout
+  } else if (executorType === 'gemini') {
+    return Bash(
+      `ccw cli -p "${escapePrompt(prompt)}" --tool gemini --mode write --id exec-${solutionId}`,
+      { timeout: 3600000, run_in_background: true }
     );
   } else {
-    // Agent execution
-    Task(
-      subagent_type="code-developer",
-      run_in_background=false,
-      description=`Execute ${queueItem.item_id}`,
-      prompt=codexPrompt
-    );
-  }
-}
-
-// Execute with parallelism
-const parallelLimit = flags.parallel || 1;
-
-for (let i = 0; i < readyTasks.length; i += parallelLimit) {
-  const batch = readyTasks.slice(i, i + parallelLimit);
-
-  console.log(`\n### Executing Batch ${Math.floor(i / parallelLimit) + 1}`);
-  console.log(batch.map(t => `- ${t.item_id}: ${t.issue_id}:${t.task_id}`).join('\n'));
-
-  if (parallelLimit === 1) {
-    // Sequential execution
-    for (const task of batch) {
-      updateTodo(task.item_id, 'in_progress');
-      await executeTask(task);
-      updateTodo(task.item_id, 'completed');
-    }
-  } else {
-    // Parallel execution - launch all at once
-    const executions = batch.map(task => {
-      updateTodo(task.item_id, 'in_progress');
-      return executeTask(task);
+    return Task({
+      subagent_type: 'code-developer',
+      run_in_background: false,
+      description: `Execute solution ${solutionId}`,
+      prompt: prompt
     });
-    await Promise.all(executions);
-    batch.forEach(task => updateTodo(task.item_id, 'completed'));
-  }
-
-  // Refresh ready tasks after batch
-  const newReady = getReadyTasks();
-  if (newReady.length > 0) {
-    console.log(`${newReady.length} more tasks now ready`);
   }
 }
 ```
 
-### Codex Task Fetch Response
-
-When codex calls `ccw issue next`, it receives:
-
-```json
-{
-  "item_id": "T-1",
-  "issue_id": "GH-123",
-  "solution_id": "SOL-001",
-  "task": {
-    "id": "T1",
-    "title": "Create auth middleware",
-    "scope": "src/middleware/",
-    "action": "Create",
-    "description": "Create JWT validation middleware",
-    "modification_points": [
-      { "file": "src/middleware/auth.ts", "target": "new file", "change": "Create middleware" }
-    ],
-    "implementation": [
-      "Create auth.ts file in src/middleware/",
-      "Implement JWT token validation using jsonwebtoken",
-      "Add error handling for invalid/expired tokens",
-      "Export middleware function"
-    ],
-    "acceptance": [
-      "Middleware validates JWT tokens successfully",
-      "Returns 401 for invalid or missing tokens",
-      "Passes token payload to request context"
-    ]
-  },
-  "context": {
-    "relevant_files": ["src/config/auth.ts", "src/types/auth.d.ts"],
-    "patterns": "Follow existing middleware pattern in src/middleware/logger.ts"
-  },
-  "execution_hints": {
-    "executor": "codex",
-    "estimated_minutes": 30
-  }
-}
-```
-
-### Phase 4: Completion Summary
+### Phase 3: Check Next Batch
 
 ```javascript
-// Reload queue for final status via CLI
-const finalQueueJson = Bash(`ccw issue status --json 2>/dev/null || echo '{}'`);
-const finalQueue = JSON.parse(finalQueueJson);
-
-// Use queue._metadata for summary (already calculated by CLI)
-const summary = finalQueue._metadata || {
-  completed_count: 0,
-  failed_count: 0,
-  pending_count: 0,
-  total_tasks: 0
-};
+// Refresh DAG after batch completes
+const refreshedDag = JSON.parse(Bash(`ccw issue queue dag`).trim());
 
 console.log(`
-## Execution Complete
-
-**Completed**: ${summary.completed_count}/${summary.total_tasks}
-**Failed**: ${summary.failed_count}
-**Pending**: ${summary.pending_count}
-
-### Task Results
-${(finalQueue.tasks || []).map(q => {
-  const icon = q.status === 'completed' ? '✓' :
-               q.status === 'failed' ? '✗' :
-               q.status === 'executing' ? '⟳' : '○';
-  return `${icon} ${q.item_id} [${q.issue_id}:${q.task_id}] - ${q.status}`;
-}).join('\n')}
-`);
+## Batch Complete
 
-// Issue status updates are handled by ccw issue complete/fail endpoints
-// No need to manually update issues.jsonl here
-
-if (summary.pending_count > 0) {
-  console.log(`
-### Continue Execution
-Run \`/issue:execute\` again to execute remaining tasks.
+- Solutions Completed: ${refreshedDag.completed_count}/${refreshedDag.total}
+- Next ready: ${refreshedDag.ready_count}
 `);
-}
-```
-
-## Dry Run Mode
 
-```javascript
-if (flags.dryRun) {
-  console.log(`
-## Dry Run - Would Execute
-
-${readyTasks.map((t, i) => `
-${i + 1}. ${t.item_id}
-   Issue: ${t.issue_id}
-   Task: ${t.task_id}
-   Executor: ${t.assigned_executor}
-   Group: ${t.execution_group}
-`).join('')}
-
-No changes made. Remove --dry-run to execute.
-`);
-  return;
+if (refreshedDag.ready_count > 0) {
+  console.log('Run `/issue:execute` again for next batch.');
 }
 ```
 
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Queue not found | Display message, suggest /issue:queue |
-| No ready tasks | Check dependencies, show blocked tasks |
-| Codex timeout | Mark as failed, allow retry |
-| ccw issue next empty | All tasks done or blocked |
-| Task execution failure | Marked via ccw issue fail, use `ccw issue retry` to reset |
-
-## Troubleshooting
-
-### Interrupted Tasks
-
-If execution was interrupted (crashed/stopped), `ccw issue next` will automatically resume:
+## Parallel Execution Model
 
-```bash
-# Automatically returns the executing task for resumption
-ccw issue next
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Orchestrator                                                │
+├─────────────────────────────────────────────────────────────┤
+│ 1. ccw issue queue dag                                      │
+│    → { parallel_batches: [["S-1","S-2"], ["S-3"]] }        │
+│                                                             │
+│ 2. Dispatch batch 1 (parallel):                            │
+│    ┌──────────────────────┐ ┌──────────────────────┐       │
+│    │ Executor 1           │ │ Executor 2           │       │
+│    │ detail S-1           │ │ detail S-2           │       │
+│    │ → gets full solution │ │ → gets full solution │       │
+│    │ [T1→T2→T3 sequential]│ │ [T1→T2 sequential]   │       │
+│    │ done S-1             │ │ done S-2             │       │
+│    └──────────────────────┘ └──────────────────────┘       │
+│                                                             │
+│ 3. ccw issue queue dag (refresh)                           │
+│    → S-3 now ready (S-1 completed, file conflict resolved) │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-Tasks in `executing` status are prioritized and returned first, no manual reset needed.
-
-### Failed Tasks
-
-If a task failed and you want to retry:
+**Why this works for parallel:**
+- `detail <id>` is READ-ONLY → no race conditions
+- Each executor handles **all tasks within a solution** sequentially
+- `done <id>` updates only its own solution status
+- `queue dag` recalculates ready solutions after each batch
+- Solutions in same batch have NO file conflicts
 
-```bash
-# Reset all failed tasks to pending
-ccw issue retry
+## CLI Endpoint Contract
 
-# Reset failed tasks for specific issue
-ccw issue retry <issue-id>
+### `ccw issue queue dag`
+Returns dependency graph with parallel batches (solution-level):
+```json
+{
+  "queue_id": "QUE-...",
+  "total": 3,
+  "ready_count": 2,
+  "completed_count": 0,
+  "nodes": [
+    { "id": "S-1", "issue_id": "ISS-xxx", "status": "pending", "ready": true, "task_count": 3 },
+    { "id": "S-2", "issue_id": "ISS-yyy", "status": "pending", "ready": true, "task_count": 2 },
+    { "id": "S-3", "issue_id": "ISS-zzz", "status": "pending", "ready": false, "depends_on": ["S-1"] }
+  ],
+  "parallel_batches": [["S-1", "S-2"], ["S-3"]]
+}
 ```
 
-## Endpoint Contract
-
-### `ccw issue next`
-- Returns next ready task as JSON
-- Marks task as 'executing'
-- Returns `{ status: 'empty' }` when no tasks
+### `ccw issue detail <item_id>`
+Returns FULL SOLUTION with all tasks (READ-ONLY):
+```json
+{
+  "item_id": "S-1",
+  "issue_id": "ISS-xxx",
+  "solution_id": "SOL-xxx",
+  "status": "pending",
+  "solution": {
+    "id": "SOL-xxx",
+    "approach": "...",
+    "tasks": [
+      { "id": "T1", "title": "...", "implementation": [...], "test": {...} },
+      { "id": "T2", "title": "...", "implementation": [...], "test": {...} },
+      { "id": "T3", "title": "...", "implementation": [...], "test": {...} }
+    ],
+    "exploration_context": { "relevant_files": [...] }
+  },
+  "execution_hints": { "executor": "codex", "estimated_minutes": 180 }
+}
+```
 
-### `ccw issue complete <item-id>`
-- Marks task as 'completed'
-- Updates queue.json
-- Checks if issue is fully complete
+### `ccw issue done <item_id>`
+Marks solution completed/failed, updates queue state, checks for queue completion.
 
-### `ccw issue fail <item-id>`
-- Marks task as 'failed'
-- Records failure reason
-- Allows retry via /issue:execute
+## Error Handling
 
-### `ccw issue retry [issue-id]`
-- Resets failed tasks to 'pending'
-- Allows re-execution via `ccw issue next`
+| Error | Resolution |
+|-------|------------|
+| No queue | Run /issue:queue first |
+| No ready solutions | Dependencies blocked, check DAG |
+| Executor timeout | Solution not marked done, can retry |
+| Solution failure | Use `ccw issue retry` to reset |
+| Partial task failure | Executor reports which task failed via `done --fail` |
 
 ## Related Commands
 
 - `/issue:plan` - Plan issues with solutions
 - `/issue:queue` - Form execution queue
-- `ccw issue queue list` - View queue status
-- `ccw issue retry` - Retry failed tasks
+- `ccw issue queue dag` - View dependency graph
+- `ccw issue detail <id>` - View task details
+- `ccw issue retry` - Reset failed tasks