claude-code-workflow 6.3.17 → 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-plan.md

@@ -11,6 +11,23 @@ Create executable solution(s) for issue(s) and bind the selected solution to eac
 
 This workflow is **planning + registration** (no implementation): it explores the codebase just enough to produce a high-quality task breakdown that can be executed later (e.g., by `issue-execute.md`).
 
+## Core Guidelines
+
+**⚠️ Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| Update status | `ccw issue update <id> --status ...` | Direct file edit |
+| Bind solution | `ccw issue bind <id> <sol-id>` | Direct file edit |
+
+**Output Options**:
+- `--brief`: JSON with minimal fields (id, title, status, priority, tags)
+- `--json`: Full JSON (for detailed processing)
+
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly.
+
 ## Inputs
 
 - **Explicit issues**: comma-separated IDs, e.g. `ISS-123,ISS-124`
@@ -91,10 +108,38 @@ ccw issue solution <issue-id> --data '{"description":"...", "approach":"...", "t
 ### Step 6: Detect cross-issue file conflicts (best-effort)
 
 Across the issues planned in this run:
-- Build a set of touched files from each solution’s `modification_points.file` (and/or task `scope` when explicit files are missing).
+- Build a set of touched files from each solution's `modification_points.file` (and/or task `scope` when explicit files are missing).
 - If the same file appears in multiple issues, add it to `conflicts` with all involved issue IDs.
 - Recommend a safe execution order (sequential) when conflicts exist.
 
+### Step 7: Update issue status
+
+After binding, update issue status to `planned`:
+```bash
+ccw issue update <issue-id> --status planned
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] All input issues have solutions in `solutions/{issue-id}.jsonl`
+- [ ] Single solution issues are auto-bound (`bound_solution_id` set)
+- [ ] Multi-solution issues returned in `pending_selection` for user choice
+- [ ] Each solution has executable tasks with `modification_points`
+- [ ] Task acceptance criteria are quantified (not vague)
+- [ ] Conflicts detected and reported (if multiple issues touch same files)
+- [ ] Issue status updated to `planned` after binding
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Issue not found | Auto-create via `ccw issue init` |
+| No solutions generated | Display error, suggest manual planning |
+| User cancels selection | Skip issue, continue with others |
+| File conflicts | Detect and suggest resolution order |
+
 ## Done Criteria
 
 - A bound solution exists for each issue unless explicitly deferred for user selection.