Claude-Code-Workflow/.codex/prompts/issue-execute.md

description, argument-hint

description	argument-hint
Execute all solutions from issue queue with git commit after each task	[--worktree] [--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.

Worktree Mode (Recommended for Parallel Execution)

When --worktree is specified, create a separate git worktree to isolate work:

# Step 0: Setup worktree before starting
WORKTREE_NAME="issue-exec-$(date +%Y%m%d-%H%M%S)"
WORKTREE_PATH="../.worktrees/${WORKTREE_NAME}"

# Create worktree from current branch
git worktree add "${WORKTREE_PATH}" -b "${WORKTREE_NAME}"

# Change to worktree directory
cd "${WORKTREE_PATH}"

# Now execute in isolated worktree...

Benefits:

• Parallel executors don't conflict with each other
• Main working directory stays clean
• Easy cleanup after execution

Completion - User Choice:

When all solutions are complete, ask user what to do with the worktree branch:

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:

# Return to main repo first
MAIN_REPO=$(git worktree list | head -1 | awk '{print $1}')
cd "${MAIN_REPO}"

# Option 1: Merge to main
git merge "${WORKTREE_NAME}" --no-ff -m "Merge issue queue execution: ${WORKTREE_NAME}"
git worktree remove "${WORKTREE_PATH}"
git branch -d "${WORKTREE_NAME}"

# Option 2: Create PR
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."

Execution Flow

INIT: Fetch first solution via ccw issue next

WHILE solution exists:
  1. Receive solution JSON from ccw issue next
  2. Execute all tasks in solution.tasks sequentially:
     FOR each task:
       - 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

WHEN queue empty:
  Output final summary

Step 1: Fetch First Solution

Run this command to get your first solution:

ccw issue next

This returns JSON with the full solution definition:

• item_id: Solution identifier in queue (e.g., "S-1")
• issue_id: Parent issue ID (e.g., "ISS-20251227-001")
• solution_id: Solution ID (e.g., "SOL-ISS-20251227-001-1")
• solution: Full solution with all tasks
• execution_hints: Timing and executor hints

If response contains { "status": "empty" }, all solutions are complete - skip to final summary.

Step 2: Parse Solution Response

Expected solution structure:

{
  "item_id": "S-1",
  "issue_id": "ISS-20251227-001",
  "solution_id": "SOL-ISS-20251227-001-1",
  "status": "pending",
  "solution": {
    "id": "SOL-ISS-20251227-001-1",
    "description": "Description of solution approach",
    "tasks": [
      {
        "id": "T1",
        "title": "Task title",
        "scope": "src/module/",
        "action": "Create|Modify|Fix|Refactor|Add",
        "description": "What to do",
        "modification_points": [
          { "file": "path/to/file.ts", "target": "function name", "change": "description" }
        ],
        "implementation": [
          "Step 1: Do this",
          "Step 2: Do that"
        ],
        "test": {
          "commands": ["npm test -- --filter=xxx"],
          "unit": ["Unit test requirement 1", "Unit test requirement 2"]
        },
        "regression": ["Verify existing tests still pass"],
        "acceptance": {
          "criteria": ["Criterion 1: Must pass", "Criterion 2: Must verify"],
          "verification": ["Run test command", "Manual verification step"]
        },
        "commit": {
          "type": "feat|fix|test|refactor",
          "scope": "module",
          "message_template": "feat(scope): description"
        },
        "depends_on": [],
        "estimated_minutes": 30,
        "priority": 1
      }
    ],
    "exploration_context": {
      "relevant_files": ["path/to/reference.ts"],
      "patterns": "Follow existing pattern in xxx",
      "integration_points": "Used by other modules"
    },
    "analysis": {
      "risk": "low|medium|high",
      "impact": "low|medium|high",
      "complexity": "low|medium|high"
    },
    "score": 0.95,
    "is_bound": true
  },
  "execution_hints": {
    "executor": "codex",
    "estimated_minutes": 180
  }
}

Step 2.5: Initialize Todo Tracking

After parsing solution, create todo list to track each task:

// 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}`,
    status: "pending"
  }))
})

Step 3: Execute Tasks Sequentially

Iterate through solution.tasks array and execute each task.

Before starting each task, mark it as in_progress:

// Update current task status to in_progress
TodoWrite({ todos: [...existingTodos.map(t =>
  t.content.startsWith(currentTask.id) ? {...t, status: "in_progress"} : t
)] })

After completing each task (commit done), mark it as completed:

// Update completed task status
TodoWrite({ todos: [...existingTodos.map(t =>
  t.content.startsWith(completedTask.id) ? {...t, status: "completed"} : t
)] })

Phase A: IMPLEMENT

1. Read all solution.exploration_context.relevant_files to understand existing patterns
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
5. Run task.regression checks if specified to ensure no breakage

Output format:

## Implementing: [task.title] (Task [N]/[Total])

**Scope**: [task.scope]
**Action**: [task.action]

**Steps**:
1. ✓ [implementation step 1]
2. ✓ [implementation step 2]
...

**Files Modified**:
- path/to/file1.ts
- path/to/file2.ts

Phase B: TEST

1. Run all commands in task.test.commands
2. Verify unit tests pass (task.test.unit)
3. Run integration tests if specified (task.test.integration)

If tests fail: Fix the code and re-run. Do NOT proceed until tests pass.

Output format:

## Testing: [task.title]

**Test Results**:
- [x] Unit tests: PASSED
- [x] Integration tests: PASSED (or N/A)

Phase C: VERIFY

Check all task.acceptance.criteria are met using task.acceptance.verification steps:

## Verifying: [task.title]

**Acceptance Criteria**:
- [x] Criterion 1: Verified
- [x] Criterion 2: Verified
...

**Verification Steps**:
- [x] Run test command
- [x] Manual verification step

All criteria met: YES

If any criterion fails: Go back to IMPLEMENT phase and fix.

Phase D: COMMIT

After all phases pass, commit the changes for this task:

# Stage all modified files
git add path/to/file1.ts path/to/file2.ts ...

# Commit with task message template
git commit -m "$(cat <<'EOF'
[task.commit.message_template]

Solution-ID: [solution_id]
Issue-ID: [issue_id]
Task-ID: [task.id]
EOF
)"

Output format:

## Committed: [task.title]

**Commit**: [commit hash]
**Message**: [commit message]
**Files**: N files changed

Repeat for Next Task

Continue to next task in solution.tasks array until all tasks are complete.

Step 4: Report Completion

After ALL tasks in the solution are complete, report to queue system:

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]"
}'

If solution failed and cannot be fixed:

ccw issue done <item_id> --fail --reason "Task [task.id] failed: [details]"

Step 5: Continue to Next Solution

Clear current todo list and fetch next solution:

// Reset todos for next solution
TodoWrite({ todos: [] })

Then fetch next solution:

ccw issue next

Output progress:

✓ [N/M] Completed: [item_id] - [solution.approach]
→ Fetching next solution...

DO NOT STOP. Return to Step 2 and continue until queue is empty.

Final Summary

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.

## Issue Queue Execution Complete

**Total Solutions Executed**: N
**Total Tasks Executed**: M

**All Commits**:
| # | Solution | Task | Commit |
|---|----------|------|--------|
| 1 | S-1 | T1 | abc123 |
| 2 | S-1 | T2 | def456 |
| 3 | S-2 | T1 | ghi789 |

**Files Modified**:
- path/to/file1.ts
- path/to/file2.ts

**Summary**:
[Overall what was accomplished]

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
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

Error Handling

Situation	Action
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
ccw issue done fails	Log error, continue to next solution
Unrecoverable error	Call ccw issue done --fail, continue to next

CLI Command Reference

Command	Purpose
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

Begin by running:

ccw issue next

Then follow the solution lifecycle for each solution until queue is empty.