feat: Add unified-execute-parallel, unified-execute-with-file, and worktree-merge workflows

- Implemented unified-execute-parallel for executing tasks in isolated Git worktrees with parallel execution capabilities. - Developed unified-execute-with-file for universal task execution from various planning outputs with progress tracking. - Created worktree-merge to handle merging of completed worktrees back to the main branch, including dependency management and conflict detection. - Enhanced documentation for each workflow, detailing core functionalities, implementation phases, and configuration options.
2026-02-12 02:37:45 +08:00 · 2026-02-05 18:44:00 +08:00
parent 1480873008
commit eac1bb81c8
17 changed files with 16 additions and 0 deletions
--- a/.codex/skills/issue-queue/SKILL.md
+++ b/.codex/skills/issue-queue/SKILL.md
@@ -0,0 +1,299 @@
+---
+name: issue-queue
+description: Form execution queue from bound solutions using subagent for conflict analysis and ordering
+argument-hint: "[--queues <n>] [--issue <id>] [--append <id>]"
+---
+
+# Issue Queue (Codex Version)
+
+## Goal
+
+Create an ordered execution queue from all bound solutions. Uses **subagent pattern** to analyze inter-solution file conflicts, calculate semantic priorities, and assign parallel/sequential execution groups.
+
+**Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks.
+
+## Core Guidelines
+
+**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status planned --brief` | Read issues.jsonl |
+| List queue (brief) | `ccw issue queue --brief` | Read queues/*.json |
+| Read issue details | `ccw issue status <id> --json` | Read issues.jsonl |
+| Get next item | `ccw issue next --json` | Read queues/*.json |
+| Sync from queue | `ccw issue update --from-queue` | Direct file edit |
+
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `queues/*.json` directly.
+
+## Inputs
+
+- **All planned**: Default behavior → queue all issues with `planned` status and bound solutions
+- **Multiple queues**: `--queues <n>` → create N parallel queues
+- **Specific issue**: `--issue <id>` → queue only that issue's solution
+- **Append mode**: `--append <id>` → append issue to active queue (don't create new)
+
+## Output Requirements
+
+**Generate Files (EXACTLY 2):**
+1. `.workflow/issues/queues/{queue-id}.json` - Full queue with solutions, conflicts, groups
+2. `.workflow/issues/queues/index.json` - Update with new queue entry
+
+**Return Summary:**
+```json
+{
+  "queue_id": "QUE-YYYYMMDD-HHMMSS",
+  "total_solutions": 3,
+  "total_tasks": 12,
+  "execution_groups": [{ "id": "P1", "type": "parallel", "count": 2 }],
+  "conflicts_resolved": 1,
+  "issues_queued": ["ISS-xxx", "ISS-yyy"]
+}
+```
+
+## Workflow
+
+### Step 1: Generate Queue ID and Load Solutions
+
+```bash
+# Generate queue ID
+QUEUE_ID="QUE-$(date -u +%Y%m%d-%H%M%S)"
+
+# Load planned issues with bound solutions
+ccw issue list --status planned --json
+```
+
+For each issue, extract:
+- `id`, `bound_solution_id`, `priority`
+- Read solution from `.workflow/issues/solutions/{issue-id}.jsonl`
+- Collect `files_touched` from all tasks' `modification_points.file`
+
+Build solution list:
+```json
+[
+  {
+    "issue_id": "ISS-xxx",
+    "solution_id": "SOL-xxx",
+    "task_count": 3,
+    "files_touched": ["src/auth.ts", "src/utils.ts"],
+    "priority": "medium"
+  }
+]
+```
+
+### Step 2: Spawn Queue Agent for Conflict Analysis
+
+Spawn subagent to analyze conflicts and order solutions:
+
+```javascript
+const agentId = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/issue-queue-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+---
+
+Goal: Order ${solutions.length} solutions into execution queue with conflict resolution
+
+Scope:
+- CAN DO: Analyze file conflicts, calculate priorities, assign groups
+- CANNOT DO: Execute solutions, modify code
+- Queue ID: ${QUEUE_ID}
+
+Context:
+- Solutions: ${JSON.stringify(solutions, null, 2)}
+- Project Root: ${process.cwd()}
+
+Deliverables:
+1. Write queue JSON to: .workflow/issues/queues/${QUEUE_ID}.json
+2. Update index: .workflow/issues/queues/index.json
+3. Return summary JSON
+
+Quality bar:
+- No circular dependencies in DAG
+- Parallel groups have NO file overlaps
+- Semantic priority calculated (0.0-1.0)
+- All conflicts resolved with rationale
+`
+})
+
+// Wait for agent completion
+const result = wait({ ids: [agentId], timeout_ms: 600000 })
+
+// Parse result
+const summary = JSON.parse(result.status[agentId].completed)
+
+// Check for clarifications
+if (summary.clarifications?.length > 0) {
+  // Handle high-severity conflicts requiring user input
+  for (const clarification of summary.clarifications) {
+    console.log(`Conflict: ${clarification.question}`)
+    console.log(`Options: ${clarification.options.join(', ')}`)
+    // Get user input and send back
+    send_input({
+      id: agentId,
+      message: `Conflict ${clarification.conflict_id} resolved: ${userChoice}`
+    })
+    wait({ ids: [agentId], timeout_ms: 300000 })
+  }
+}
+
+// Close agent
+close_agent({ id: agentId })
+```
+
+### Step 3: Multi-Queue Support (if --queues > 1)
+
+When creating multiple parallel queues:
+
+1. **Partition solutions** to minimize cross-queue file conflicts
+2. **Spawn N agents in parallel** (one per queue)
+3. **Wait for all agents** with batch wait
+
+```javascript
+// Partition solutions by file overlap
+const partitions = partitionSolutions(solutions, numQueues)
+
+// Spawn agents in parallel
+const agentIds = partitions.map((partition, i) => 
+  spawn_agent({
+    message: buildQueuePrompt(partition, `${QUEUE_ID}-${i+1}`, i+1, numQueues)
+  })
+)
+
+// Batch wait for all agents
+const results = wait({ ids: agentIds, timeout_ms: 600000 })
+
+// Collect clarifications from all agents
+const allClarifications = agentIds.flatMap((id, i) => 
+  (results.status[id].clarifications || []).map(c => ({ ...c, queue_id: `${QUEUE_ID}-${i+1}`, agent_id: id }))
+)
+
+// Handle clarifications, then close all agents
+agentIds.forEach(id => close_agent({ id }))
+```
+
+### Step 4: Update Issue Statuses
+
+**MUST use CLI command:**
+
+```bash
+# Batch update from queue (recommended)
+ccw issue update --from-queue ${QUEUE_ID}
+
+# Or individual update
+ccw issue update <issue-id> --status queued
+```
+
+### Step 5: Active Queue Check
+
+```bash
+ccw issue queue list --brief
+```
+
+**Decision:**
+- If no active queue: `ccw issue queue switch ${QUEUE_ID}`
+- If active queue exists: Present options to user
+
+```
+Active queue exists. Choose action:
+1. Merge into existing queue
+2. Use new queue (keep existing in history)
+3. Cancel (delete new queue)
+
+Select (1-3):
+```
+
+### Step 6: Output Summary
+
+```markdown
+## Queue Formed: ${QUEUE_ID}
+
+**Solutions**: 5
+**Tasks**: 18
+**Execution Groups**: 3
+
+### Execution Order
+| # | Item | Issue | Tasks | Group | Files |
+|---|------|-------|-------|-------|-------|
+| 1 | S-1 | ISS-001 | 3 | P1 | src/auth.ts |
+| 2 | S-2 | ISS-002 | 2 | P1 | src/api.ts |
+| 3 | S-3 | ISS-003 | 4 | S2 | src/auth.ts |
+
+### Conflicts Resolved
+- src/auth.ts: S-1 → S-3 (sequential, S-1 creates module)
+
+**Next Step**: `/issue:execute --queue ${QUEUE_ID}`
+```
+
+## Subagent Role Reference
+
+Queue agent uses role file at: `~/.codex/agents/issue-queue-agent.md`
+
+Role capabilities:
+- File conflict detection (5 types)
+- Dependency DAG construction
+- Semantic priority calculation
+- Execution group assignment
+
+## Queue File Schema
+
+```json
+{
+  "id": "QUE-20251228-120000",
+  "status": "active",
+  "issue_ids": ["ISS-001", "ISS-002"],
+  "solutions": [
+    {
+      "item_id": "S-1",
+      "issue_id": "ISS-001",
+      "solution_id": "SOL-ISS-001-1",
+      "status": "pending",
+      "execution_order": 1,
+      "execution_group": "P1",
+      "depends_on": [],
+      "semantic_priority": 0.8,
+      "files_touched": ["src/auth.ts"],
+      "task_count": 3
+    }
+  ],
+  "conflicts": [...],
+  "execution_groups": [...]
+}
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] Exactly 2 files generated: queue JSON + index update
+- [ ] Queue has valid DAG (no circular dependencies)
+- [ ] All file conflicts resolved with rationale
+- [ ] Semantic priority calculated for each solution (0.0-1.0)
+- [ ] Execution groups assigned (P* for parallel, S* for sequential)
+- [ ] Issue statuses updated to `queued`
+- [ ] All subagents closed after completion
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No planned issues | Return empty queue summary |
+| Circular dependency detected | Abort, report cycle details |
+| Missing solution file | Skip issue, log warning |
+| Agent timeout | Retry with increased timeout |
+| Clarification rejected | Abort queue formation |
+
+## Start Execution
+
+Begin by listing planned issues:
+
+```bash
+ccw issue list --status planned --json
+```
+
+Then extract solution data and spawn queue agent.