claude-code-workflow 6.3.18 → 6.3.19

package/.codex/prompts/issue-execute.md

@@ -1,13 +1,178 @@
 ---
-description: Execute all solutions from issue queue with git commit after each task
-argument-hint: ""
+description: Execute all solutions from issue queue with git commit after each solution
+argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"
 ---
 
 # Issue Execute (Codex Version)
 
 ## Core Principle
 
-**Serial Execution**: Execute solutions ONE BY ONE from the issue queue via `ccw issue next`. For each solution, complete all tasks sequentially (implement → test → commit per task). Continue autonomously until queue is empty.
+**Serial Execution**: Execute solutions ONE BY ONE from the issue queue via `ccw issue next`. For each solution, complete all tasks sequentially (implement → test → verify), then commit once per solution with formatted summary. Continue autonomously until queue is empty.
+
+## Worktree Mode (Recommended for Parallel Execution)
+
+When `--worktree` is specified, create or use a git worktree to isolate work.
+
+**Usage**:
+- `--worktree` - Create a new worktree with timestamp-based name
+- `--worktree <existing-path>` - Resume in an existing worktree (for recovery/continuation)
+
+**Note**: `ccw issue` commands auto-detect worktree and redirect to main repo automatically.
+
+```bash
+# Step 0: Setup worktree before starting (run from MAIN REPO)
+
+# Use absolute paths to avoid issues when running from subdirectories
+REPO_ROOT=$(git rev-parse --show-toplevel)
+WORKTREE_BASE="${REPO_ROOT}/.ccw/worktrees"
+
+# Check if existing worktree path was provided
+EXISTING_WORKTREE="${1:-}"  # Pass as argument or empty
+
+if [[ -n "${EXISTING_WORKTREE}" && -d "${EXISTING_WORKTREE}" ]]; then
+  # Resume mode: Use existing worktree
+  WORKTREE_PATH="${EXISTING_WORKTREE}"
+  WORKTREE_NAME=$(basename "${WORKTREE_PATH}")
+
+  # Verify it's a valid git worktree
+  if ! git -C "${WORKTREE_PATH}" rev-parse --is-inside-work-tree &>/dev/null; then
+    echo "Error: ${EXISTING_WORKTREE} is not a valid git worktree"
+    exit 1
+  fi
+
+  echo "Resuming in existing worktree: ${WORKTREE_PATH}"
+else
+  # Create mode: New worktree with timestamp
+  WORKTREE_NAME="issue-exec-$(date +%Y%m%d-%H%M%S)"
+  WORKTREE_PATH="${WORKTREE_BASE}/${WORKTREE_NAME}"
+
+  # Ensure worktree base directory exists (gitignored)
+  mkdir -p "${WORKTREE_BASE}"
+
+  # Prune stale worktrees from previous interrupted executions
+  git worktree prune
+
+  # Create worktree from current branch
+  git worktree add "${WORKTREE_PATH}" -b "${WORKTREE_NAME}"
+
+  echo "Created new worktree: ${WORKTREE_PATH}"
+fi
+
+# Setup cleanup trap for graceful failure handling
+cleanup_worktree() {
+  echo "Cleaning up worktree due to interruption..."
+  cd "${REPO_ROOT}" 2>/dev/null || true
+  git worktree remove "${WORKTREE_PATH}" --force 2>/dev/null || true
+  # Keep branch for debugging failed executions
+  echo "Worktree removed. Branch '${WORKTREE_NAME}' kept for inspection."
+}
+trap cleanup_worktree EXIT INT TERM
+
+# Change to worktree directory
+cd "${WORKTREE_PATH}"
+
+# ccw issue commands auto-detect worktree and use main repo's .workflow/
+# So you can run ccw issue next/done directly from worktree
+```
+
+**Worktree Execution Pattern**:
+```
+1. [WORKTREE] ccw issue next → auto-redirects to main repo's .workflow/
+2. [WORKTREE] Implement all tasks, run tests, git commit
+3. [WORKTREE] ccw issue done <item_id> → auto-redirects to main repo
+4. Repeat from step 1
+```
+
+**Note**: Add `.ccw/worktrees/` to `.gitignore` to prevent tracking worktree contents.
+
+**Benefits:**
+- Parallel executors don't conflict with each other
+- Main working directory stays clean
+- Easy cleanup after execution
+- **Resume support**: Pass existing worktree path to continue interrupted executions
+
+**Resume Examples:**
+```bash
+# List existing worktrees to find interrupted execution
+git worktree list
+
+# Resume in existing worktree (pass path as argument)
+# The worktree path will be used instead of creating a new one
+codex -p "@.codex/prompts/issue-execute.md --worktree /path/to/existing/worktree"
+```
+
+**Completion - User Choice:**
+
+When all solutions are complete, ask user what to do with the worktree branch:
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "All solutions completed in worktree. What would you like to do with the changes?",
+    header: "Merge",
+    multiSelect: false,
+    options: [
+      {
+        label: "Merge to main",
+        description: "Merge worktree branch into main branch and cleanup"
+      },
+      {
+        label: "Create PR",
+        description: "Push branch and create a pull request for review"
+      },
+      {
+        label: "Keep branch",
+        description: "Keep the branch for manual handling, cleanup worktree only"
+      }
+    ]
+  }]
+})
+```
+
+**Based on user selection:**
+
+```bash
+# Disable cleanup trap before intentional cleanup
+trap - EXIT INT TERM
+
+# Return to main repo first (use REPO_ROOT from setup)
+cd "${REPO_ROOT}"
+
+# Validate main repo state before merge (prevents conflicts)
+validate_main_clean() {
+  if [[ -n $(git status --porcelain) ]]; then
+    echo "⚠️ Warning: Main repo has uncommitted changes."
+    echo "Cannot auto-merge. Falling back to 'Create PR' option."
+    return 1
+  fi
+  return 0
+}
+
+# Option 1: Merge to main (only if main is clean)
+if validate_main_clean; then
+  git merge "${WORKTREE_NAME}" --no-ff -m "Merge issue queue execution: ${WORKTREE_NAME}"
+  git worktree remove "${WORKTREE_PATH}"
+  git branch -d "${WORKTREE_NAME}"
+else
+  # Fallback to PR if main is dirty
+  git push -u origin "${WORKTREE_NAME}"
+  gh pr create --title "Issue Queue: ${WORKTREE_NAME}" --body "Automated issue queue execution (main had uncommitted changes)"
+  git worktree remove "${WORKTREE_PATH}"
+fi
+
+# Option 2: Create PR (Recommended for parallel execution)
+git push -u origin "${WORKTREE_NAME}"
+gh pr create --title "Issue Queue: ${WORKTREE_NAME}" --body "Automated issue queue execution"
+git worktree remove "${WORKTREE_PATH}"
+# Branch kept on remote
+
+# Option 3: Keep branch
+git worktree remove "${WORKTREE_PATH}"
+# Branch kept locally for manual handling
+echo "Branch '${WORKTREE_NAME}' kept. Merge manually when ready."
+```
+
+**Parallel Execution Safety**: For parallel executors, "Create PR" is the safest option as it avoids race conditions during merge. Multiple PRs can be reviewed and merged sequentially.
 
 ## Execution Flow
 
@@ -21,9 +186,9 @@ WHILE solution exists:
        - IMPLEMENT: Follow task.implementation steps
        - TEST: Run task.test commands
        - VERIFY: Check task.acceptance criteria
-       - COMMIT: Stage files, commit with task.commit.message_template
-  3. Report completion via ccw issue done <item_id>
-  4. Fetch next solution via ccw issue next
+  3. COMMIT: Stage all files, commit once with formatted summary
+  4. Report completion via ccw issue done <item_id>
+  5. Fetch next solution via ccw issue next
 
 WHEN queue empty:
   Output final summary
@@ -33,8 +198,9 @@ WHEN queue empty:
 
 Run this command to get your first solution:
 
-```bash
-ccw issue next
+```javascript
+// ccw auto-detects worktree and uses main repo's .workflow/
+const result = shell_command({ command: "ccw issue next" })
 ```
 
 This returns JSON with the full solution definition:
@@ -112,44 +278,64 @@ Expected solution structure:
 }
 ```
 
-## Step 2.5: Initialize Todo Tracking
+## Step 2.5: Initialize Task Tracking
 
-After parsing solution, create todo list to track each task:
+After parsing solution, use `update_plan` to track each task:
 
 ```javascript
-// Create todos for all tasks in current solution
-TodoWrite({
-  todos: solution.tasks.map(task => ({
-    content: `${task.id}: ${task.title}`,
-    activeForm: `Executing ${task.id}: ${task.title}`,
+// Initialize plan with all tasks from solution
+update_plan({
+  explanation: `Starting solution ${item_id}`,
+  plan: solution.tasks.map(task => ({
+    step: `${task.id}: ${task.title}`,
     status: "pending"
   }))
 })
 ```
 
+**Note**: Codex uses `update_plan` tool for task tracking (not TodoWrite).
+
 ## Step 3: Execute Tasks Sequentially
 
 Iterate through `solution.tasks` array and execute each task.
 
 **Before starting each task**, mark it as in_progress:
 ```javascript
-// Update current task status to in_progress
-TodoWrite({ todos: [...existingTodos.map(t =>
-  t.content.startsWith(currentTask.id) ? {...t, status: "in_progress"} : t
-)] })
+// Update current task status
+update_plan({
+  explanation: `Working on ${task.id}: ${task.title}`,
+  plan: tasks.map(t => ({
+    step: `${t.id}: ${t.title}`,
+    status: t.id === task.id ? "in_progress" : (t.completed ? "completed" : "pending")
+  }))
+})
 ```
 
-**After completing each task** (commit done), mark it as completed:
+**After completing each task** (verification passed), mark it as completed:
 ```javascript
-// Update completed task status
-TodoWrite({ todos: [...existingTodos.map(t =>
-  t.content.startsWith(completedTask.id) ? {...t, status: "completed"} : t
-)] })
+// Mark task as completed (commit happens at solution level)
+update_plan({
+  explanation: `Completed ${task.id}: ${task.title}`,
+  plan: tasks.map(t => ({
+    step: `${t.id}: ${t.title}`,
+    status: t.id === task.id ? "completed" : t.status
+  }))
+})
 ```
 
 ### Phase A: IMPLEMENT
 
-1. Read all `solution.exploration_context.relevant_files` to understand existing patterns
+1. **Read context files in parallel** using `multi_tool_use.parallel`:
+```javascript
+// Read all relevant files in parallel for context
+multi_tool_use.parallel({
+  tool_uses: solution.exploration_context.relevant_files.map(file => ({
+    recipient_name: "functions.read_file",
+    parameters: { path: file }
+  }))
+})
+```
+
 2. Follow `task.implementation` steps in order
 3. Apply changes to `task.modification_points` files
 4. Follow `solution.exploration_context.patterns` for code style consistency
@@ -210,80 +396,111 @@ All criteria met: YES
 
 **If any criterion fails**: Go back to IMPLEMENT phase and fix.
 
-### Phase D: COMMIT
+### Repeat for Next Task
+
+Continue to next task in `solution.tasks` array until all tasks are complete.
+
+**Note**: Do NOT commit after each task. Commits happen at solution level after all tasks pass.
 
-After all phases pass, commit the changes for this task:
+## Step 3.5: Commit Solution
+
+After ALL tasks in the solution pass implementation, testing, and verification, commit once for the entire solution:
 
 ```bash
-# Stage all modified files
+# Stage all modified files from all tasks
 git add path/to/file1.ts path/to/file2.ts ...
 
-# Commit with task message template
+# Commit with formatted solution summary
 git commit -m "$(cat <<'EOF'
-[task.commit.message_template]
+[commit_type](scope): [solution.description - brief]
+
+## Solution Summary
+- **Solution-ID**: [solution_id]
+- **Issue-ID**: [issue_id]
+- **Risk/Impact/Complexity**: [solution.analysis.risk]/[solution.analysis.impact]/[solution.analysis.complexity]
 
-Solution-ID: [solution_id]
-Issue-ID: [issue_id]
-Task-ID: [task.id]
+## Tasks Completed
+- [T1] [task1.title]: [task1.action] [task1.scope]
+- [T2] [task2.title]: [task2.action] [task2.scope]
+- ...
+
+## Files Modified
+- path/to/file1.ts
+- path/to/file2.ts
+- ...
+
+## Verification
+- All unit tests passed
+- All acceptance criteria verified
 EOF
 )"
 ```
 
+**Commit Type Selection**:
+- `feat`: New feature or capability
+- `fix`: Bug fix
+- `refactor`: Code restructuring without behavior change
+- `test`: Adding or updating tests
+- `docs`: Documentation changes
+- `chore`: Maintenance tasks
+
 **Output format:**
 ```
-## Committed: [task.title]
+## Solution Committed: [solution_id]
 
 **Commit**: [commit hash]
-**Message**: [commit message]
-**Files**: N files changed
-```
+**Type**: [commit_type]
+**Scope**: [scope]
 
-### Repeat for Next Task
+**Summary**:
+[solution.description]
 
-Continue to next task in `solution.tasks` array until all tasks are complete.
+**Tasks**: [N] tasks completed
+- [x] T1: [task1.title]
+- [x] T2: [task2.title]
+...
+
+**Files**: [M] files changed
+```
 
 ## Step 4: Report Completion
 
-After ALL tasks in the solution are complete, report to queue system:
+After ALL tasks in the solution are complete and committed, report to queue system:
 
-```bash
-ccw issue done <item_id> --result '{
-  "files_modified": ["path1", "path2"],
-  "tests_passed": true,
-  "acceptance_passed": true,
-  "committed": true,
-  "commits": [
-    { "task_id": "T1", "hash": "abc123" },
-    { "task_id": "T2", "hash": "def456" }
-  ],
-  "summary": "[What was accomplished]"
-}'
+```javascript
+// ccw auto-detects worktree and uses main repo's .workflow/
+shell_command({
+  command: `ccw issue done ${item_id} --result '${JSON.stringify({
+    files_modified: ["path1", "path2"],
+    tests_passed: true,
+    commit: { hash: "abc123", type: "feat", tasks: ["T1", "T2"] },
+    summary: "[What was accomplished]"
+  })}'`
+})
 ```
 
-**If solution failed and cannot be fixed:**
+**If solution failed:**
 
-```bash
-ccw issue done <item_id> --fail --reason "Task [task.id] failed: [details]"
+```javascript
+shell_command({
+  command: `ccw issue done ${item_id} --fail --reason '{"task_id": "TX", "error_type": "test_failure", "message": "..."}'`
+})
 ```
 
 ## Step 5: Continue to Next Solution
 
-Clear current todo list and fetch next solution:
+Fetch next solution:
 
 ```javascript
-// Reset todos for next solution
-TodoWrite({ todos: [] })
-```
-
-Then fetch next solution:
-
-```bash
-ccw issue next
+// ccw auto-detects worktree
+const result = shell_command({ command: "ccw issue next" })
 ```
 
 **Output progress:**
 ```
-✓ [N/M] Completed: [item_id] - [solution.approach]
+✓ [N/M] Completed: [item_id] - [solution.description]
+  Commit: [commit_hash] ([commit_type])
+  Tasks: [task_count] completed
 → Fetching next solution...
 ```
 
@@ -293,18 +510,21 @@ ccw issue next
 
 When `ccw issue next` returns `{ "status": "empty" }`:
 
+**If running in worktree mode**: Prompt user for merge/PR/keep choice (see "Completion - User Choice" above) before outputting summary.
+
 ```markdown
 ## Issue Queue Execution Complete
 
 **Total Solutions Executed**: N
 **Total Tasks Executed**: M
+**Total Commits**: N (one per solution)
 
-**All Commits**:
-| # | Solution | Task | Commit |
-|---|----------|------|--------|
-| 1 | S-1 | T1 | abc123 |
-| 2 | S-1 | T2 | def456 |
-| 3 | S-2 | T1 | ghi789 |
+**Solution Commits**:
+| # | Solution | Tasks | Commit | Type |
+|---|----------|-------|--------|------|
+| 1 | SOL-xxx-1 | T1, T2 | abc123 | feat |
+| 2 | SOL-xxx-2 | T1 | def456 | fix |
+| 3 | SOL-yyy-1 | T1, T2, T3 | ghi789 | refactor |
 
 **Files Modified**:
 - path/to/file1.ts
@@ -317,14 +537,15 @@ When `ccw issue next` returns `{ "status": "empty" }`:
 ## Execution Rules
 
 1. **Never stop mid-queue** - Continue until queue is empty
-2. **One solution at a time** - Fully complete (all tasks + report) before moving on
-3. **Sequential within solution** - Complete each task (including commit) before next
-4. **Tests MUST pass** - Do not proceed to commit if tests fail
-5. **Commit after each task** - Each task gets its own commit
-6. **Self-verify** - All acceptance criteria must pass before commit
+2. **One solution at a time** - Fully complete (all tasks + commit + report) before moving on
+3. **Sequential within solution** - Complete each task's implement/test/verify before next task
+4. **Tests MUST pass** - Do not proceed if any task's tests fail
+5. **One commit per solution** - All tasks share a single commit with formatted summary
+6. **Self-verify** - All acceptance criteria must pass before solution commit
 7. **Report accurately** - Use `ccw issue done` after each solution
 8. **Handle failures gracefully** - If a solution fails, report via `ccw issue done --fail` and continue to next
-9. **Track with todos** - Use TodoWrite to track task progress within each solution
+9. **Track with update_plan** - Use update_plan tool for task progress tracking
+10. **Worktree auto-detect** - `ccw issue` commands auto-redirect to main repo from worktree
 
 ## Error Handling
 
@@ -333,17 +554,19 @@ When `ccw issue next` returns `{ "status": "empty" }`:
 | `ccw issue next` returns empty | All done - output final summary |
 | Tests fail | Fix code, re-run tests |
 | Verification fails | Go back to implement phase |
-| Git commit fails | Check staging, retry commit |
+| Solution commit fails | Check staging, retry commit |
 | `ccw issue done` fails | Log error, continue to next solution |
-| Unrecoverable error | Call `ccw issue done --fail`, continue to next |
+| Any task unrecoverable | Call `ccw issue done --fail`, continue to next solution |
 
 ## CLI Command Reference
 
 | Command | Purpose |
 |---------|---------|
-| `ccw issue next` | Fetch next solution from queue |
-| `ccw issue done <id>` | Mark solution complete with result |
-| `ccw issue done <id> --fail` | Mark solution failed with reason |
+| `ccw issue next` | Fetch next solution from queue (auto-selects from active queues) |
+| `ccw issue next --queue QUE-xxx` | Fetch from specific queue |
+| `ccw issue done <id>` | Mark solution complete with result (auto-detects queue) |
+| `ccw issue done <id> --fail --reason "..."` | Mark solution failed with structured reason |
+| `ccw issue retry --queue QUE-xxx` | Reset failed items in specific queue |
 
 ## Start Execution
 

package/.codex/prompts/issue-queue.md

@@ -183,10 +183,12 @@ Group assignment:
 ```json
 {
   "active_queue_id": "QUE-20251228-120000",
+  "active_queue_ids": ["QUE-20251228-120000"],
   "queues": [
     {
       "id": "QUE-20251228-120000",
       "status": "active",
+      "priority": 1,
       "issue_ids": ["ISS-001", "ISS-002"],
       "total_solutions": 3,
       "completed_solutions": 0,
@@ -196,6 +198,26 @@ Group assignment:
 }
 ```
 
+## Multi-Queue Management
+
+Multiple queues can be active simultaneously. The system executes queues in priority order (lower = higher priority).
+
+**Activate multiple queues:**
+```bash
+ccw issue queue activate QUE-001,QUE-002,QUE-003
+```
+
+**Set queue priority:**
+```bash
+ccw issue queue priority QUE-001 --priority 1
+ccw issue queue priority QUE-002 --priority 2
+```
+
+**Execution behavior with multi-queue:**
+- `ccw issue next` automatically selects from active queues in priority order
+- Complete all items in Q1 before moving to Q2 (serialized execution)
+- Use `--queue QUE-xxx` to target a specific queue
+
 ### Step 7: Update Issue Statuses
 
 **MUST use CLI command** (NOT direct file operations):

package/.codex/prompts/lite-execute.md

@@ -63,22 +63,29 @@ For current task, perform:
 ```markdown
 ## Executing: [task.title]
 
-**Target**: `[task.file]`
+**Scope**: `[task.scope]` (module/feature level)
 **Action**: [task.action]
 
+### Modification Points
+For each point in task.modification_points:
+- **File**: [point.file]
+- **Target**: [point.target] (function/class/line range)
+- **Change**: [point.change]
+
 ### Implementation
 [Follow task.implementation steps]
 
 ### Reference Pattern
 - Pattern: [task.reference.pattern]
-- Examples: [task.reference.files]
+- Files: [task.reference.files]
+- Examples: [task.reference.examples]
 
 ### Acceptance Criteria
 - [ ] [criterion 1]
 - [ ] [criterion 2]
 ```
 
-**Execute all implementation steps. Verify all acceptance criteria.**
+**Execute all modification points. Verify all acceptance criteria.**
 
 ### Step 4: Mark Completed
 
@@ -104,22 +111,40 @@ Output progress:
 
 ```json
 {
-  "id": "task-1",
-  "title": "Task Title",
-  "file": "path/to/file.ts",
-  "action": "create|modify|refactor",
-  "description": "What to do",
-  "implementation": ["step 1", "step 2"],
+  "id": "T1",
+  "title": "Implement auth validation",
+  "scope": "src/auth/",
+  "action": "Create|Update|Implement|Refactor|Add|Delete|Configure|Test|Fix",
+  "description": "What to implement (1-2 sentences)",
+  "modification_points": [
+    {
+      "file": "src/auth/validator.ts",
+      "target": "validateToken:45-60",
+      "change": "Add expiry check"
+    },
+    {
+      "file": "src/auth/middleware.ts",
+      "target": "authMiddleware",
+      "change": "Call new validator"
+    }
+  ],
+  "implementation": ["step 1", "step 2", "...max 7 steps"],
   "reference": {
     "pattern": "pattern name",
-    "files": ["example1.ts", "example2.ts"]
+    "files": ["example1.ts"],
+    "examples": "specific guidance"
   },
   "acceptance": ["criterion 1", "criterion 2"],
-  "depends_on": ["task-0"],
+  "depends_on": ["T0"],
   "status": "pending|completed"
 }
 ```
 
+**Key Fields**:
+- `scope`: Module/feature level path (prefer over single file)
+- `modification_points[]`: All files to modify with precise targets
+- `target`: Function/class/line range (e.g., `validateToken:45-60`)
+
 ## Execution Rules
 
 1. **Never stop mid-workflow** - Continue until all tasks complete