claude-code-workflow 6.3.18 → 6.3.20

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

@@ -1,7 +1,7 @@
 ---
 name: execute
-description: Execute queue with codex using DAG-based parallel orchestration (solution-level)
-argument-hint: ""
+description: Execute queue with DAG-based parallel orchestration (one commit per solution)
+argument-hint: "[--worktree [<existing-path>]] [--queue <queue-id>]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---
 
@@ -17,31 +17,51 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo
 - `done <id>` → update solution completion status
 - No race conditions: status changes only via `done`
 - **Executor handles all tasks within a solution sequentially**
+- **Worktree isolation**: Each executor can work in its own git worktree
 
 ## Usage
 
 ```bash
-/issue:execute
+/issue:execute                           # Execute active queue(s)
+/issue:execute --queue QUE-xxx           # Execute specific queue
+/issue:execute --worktree                # Use git worktrees for parallel isolation
+/issue:execute --worktree --queue QUE-xxx
+/issue:execute --worktree /path/to/existing/worktree  # Resume in existing worktree
 ```
 
 **Parallelism**: Determined automatically by task dependency DAG (no manual control)
 **Executor & Dry-run**: Selected via interactive prompt (AskUserQuestion)
+**Worktree**: Creates isolated git worktrees for each parallel executor
+
+**⭐ Recommended Executor**: **Codex** - Best for long-running autonomous work (2hr timeout), supports background execution and full write access
+
+**Worktree Options**:
+- `--worktree` - Create a new worktree with timestamp-based name
+- `--worktree <existing-path>` - Resume in an existing worktree (for recovery/continuation)
+
+**Resume**: Use `git worktree list` to find existing worktrees from interrupted executions
 
 ## Execution Flow
 
 ```
+Phase 0 (if --worktree): Setup Worktree Base
+   └─ Ensure .worktrees directory exists
+
 Phase 1: Get DAG & User Selection
-   ├─ ccw issue queue dag → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
-   └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode
+   ├─ ccw issue queue dag [--queue QUE-xxx] → { parallel_batches: [["S-1","S-2"], ["S-3"]] }
+   └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode, worktree mode
 
 Phase 2: Dispatch Parallel Batch (DAG-driven)
    ├─ Parallelism determined by DAG (no manual limit)
    ├─ For each solution ID in batch (parallel - all at once):
+   │   ├─ (if worktree) Create isolated worktree: git worktree add
    │   ├─ 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>
+   │   ├─ Executor tests + verifies each task
+   │   ├─ Executor commits ONCE per solution (with formatted summary)
+   │   ├─ Executor calls: ccw issue done <id>
+   │   └─ (if worktree) Cleanup: merge branch, remove worktree
    └─ Wait for batch completion
 
 Phase 3: Next Batch
@@ -93,12 +113,22 @@ const answer = AskUserQuestion({
         { label: 'Execute (Recommended)', description: 'Run all ready solutions' },
         { label: 'Dry-run', description: 'Show DAG and batches without executing' }
       ]
+    },
+    {
+      question: 'Use git worktrees for parallel isolation?',
+      header: 'Worktree',
+      multiSelect: false,
+      options: [
+        { label: 'Yes (Recommended for parallel)', description: 'Each executor works in isolated worktree branch' },
+        { label: 'No', description: 'Work directly in current directory (serial only)' }
+      ]
     }
   ]
 });
 
 const executor = answer['Executor'].toLowerCase().split(' ')[0];  // codex|gemini|agent
 const isDryRun = answer['Mode'].includes('Dry-run');
+const useWorktree = answer['Worktree'].includes('Yes');
 
 // Dry run mode
 if (isDryRun) {
@@ -128,10 +158,24 @@ TodoWrite({
 
 console.log(`\n### Executing Solutions (DAG batch 1): ${batch.join(', ')}`);
 
+// Setup worktree base directory if needed (using absolute paths)
+if (useWorktree) {
+  // Use absolute paths to avoid issues when running from subdirectories
+  const repoRoot = Bash('git rev-parse --show-toplevel').trim();
+  const worktreeBase = `${repoRoot}/.ccw/worktrees`;
+  Bash(`mkdir -p "${worktreeBase}"`);
+  // Prune stale worktrees from previous interrupted executions
+  Bash('git worktree prune');
+}
+
+// Parse existing worktree path from args if provided
+// Example: --worktree /path/to/existing/worktree
+const existingWorktree = args.worktree && typeof args.worktree === 'string' ? args.worktree : null;
+
 // Launch ALL solutions in batch in parallel (DAG guarantees no conflicts)
 const executions = batch.map(solutionId => {
   updateTodo(solutionId, 'in_progress');
-  return dispatchExecutor(solutionId, executor);
+  return dispatchExecutor(solutionId, executor, useWorktree, existingWorktree);
 });
 
 await Promise.all(executions);
@@ -141,13 +185,126 @@ batch.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
+function dispatchExecutor(solutionId, executorType, useWorktree = false, existingWorktree = null) {
+  // Worktree setup commands (if enabled) - using absolute paths
+  // Supports both creating new worktrees and resuming in existing ones
+  const worktreeSetup = useWorktree ? `
+### Step 0: Setup Isolated Worktree
+\`\`\`bash
+# 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="${existingWorktree || ''}"
+
+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="exec-${solutionId}-$(date +%H%M%S)"
+  WORKTREE_PATH="\${WORKTREE_BASE}/\${WORKTREE_NAME}"
+
+  # Ensure worktree base exists
+  mkdir -p "\${WORKTREE_BASE}"
+
+  # Prune stale worktrees
+  git worktree prune
+
+  # Create worktree
+  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
+  echo "Worktree removed. Branch '\${WORKTREE_NAME}' kept for inspection."
+}
+trap cleanup_worktree EXIT INT TERM
+
+cd "\${WORKTREE_PATH}"
+\`\`\`
+` : '';
+
+  const worktreeCleanup = useWorktree ? `
+### Step 5: Worktree Completion (User Choice)
+
+After all tasks complete, prompt for merge strategy:
+
+\`\`\`javascript
+AskUserQuestion({
+  questions: [{
+    question: "Solution ${solutionId} completed. What to do with worktree branch?",
+    header: "Merge",
+    multiSelect: false,
+    options: [
+      { label: "Create PR (Recommended)", description: "Push branch and create pull request - safest for parallel execution" },
+      { label: "Merge to main", description: "Merge branch and cleanup worktree (requires clean main)" },
+      { label: "Keep branch", description: "Cleanup worktree, keep branch for manual handling" }
+    ]
+  }]
+})
+\`\`\`
+
+**Based on selection:**
+\`\`\`bash
+# Disable cleanup trap before intentional cleanup
+trap - EXIT INT TERM
+
+# Return to repo root (use REPO_ROOT from setup)
+cd "\${REPO_ROOT}"
+
+# Validate main repo state before merge
+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
+}
+
+# Create PR (Recommended for parallel execution):
+git push -u origin "\${WORKTREE_NAME}"
+gh pr create --title "Solution ${solutionId}" --body "Issue queue execution"
+git worktree remove "\${WORKTREE_PATH}"
+
+# Merge to main (only if main is clean):
+if validate_main_clean; then
+  git merge --no-ff "\${WORKTREE_NAME}" -m "Merge solution ${solutionId}"
+  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 "Solution ${solutionId}" --body "Issue queue execution (main had uncommitted changes)"
+  git worktree remove "\${WORKTREE_PATH}"
+fi
+
+# Keep branch:
+git worktree remove "\${WORKTREE_PATH}"
+echo "Branch \${WORKTREE_NAME} kept for manual handling"
+\`\`\`
+
+**Parallel Execution Safety**: "Create PR" is the default and safest option for parallel executors, avoiding merge race conditions.
+` : '';
+
   const prompt = `
 ## Execute Solution ${solutionId}
-
+${worktreeSetup}
 ### Step 1: Get Solution (read-only)
 \`\`\`bash
 ccw issue detail ${solutionId}
@@ -161,19 +318,41 @@ For each task:
 1. Follow task.implementation steps
 2. Run task.test commands
 3. Verify task.acceptance criteria
-4. Commit using task.commit specification
+(Do NOT commit after each task)
+
+### Step 3: Commit Solution (Once)
+After ALL tasks pass, commit once with formatted summary:
+\`\`\`bash
+git add <all-modified-files>
+git commit -m "[type](scope): [solution.description]
+
+## Solution Summary
+- Solution-ID: ${solutionId}
+- Tasks: T1, T2, ...
+
+## Tasks Completed
+- [T1] task1.title: action
+- [T2] task2.title: action
+
+## Files Modified
+- file1.ts
+- file2.ts
+
+## Verification
+- All tests passed
+- All acceptance criteria verified"
+\`\`\`
 
-### Step 3: Report Completion
-When ALL tasks in solution are done:
+### Step 4: Report Completion
 \`\`\`bash
-ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "tasks_completed": N}'
+ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "commit": {"hash": "...", "type": "feat"}, "tasks_completed": N}'
 \`\`\`
 
 If any task failed:
 \`\`\`bash
-ccw issue done ${solutionId} --fail --reason "Task TX failed: ..."
+ccw issue done ${solutionId} --fail --reason '{"task_id": "TX", "error_type": "test_failure", "message": "..."}'
 \`\`\`
-`;
+${worktreeCleanup}`;
 
   if (executorType === 'codex') {
     return Bash(
@@ -229,6 +408,7 @@ if (refreshedDag.ready_count > 0) {
 │    │ detail S-1           │ │ detail S-2           │       │
 │    │ → gets full solution │ │ → gets full solution │       │
 │    │ [T1→T2→T3 sequential]│ │ [T1→T2 sequential]   │       │
+│    │ commit (1x solution) │ │ commit (1x solution) │       │
 │    │ done S-1             │ │ done S-2             │       │
 │    └──────────────────────┘ └──────────────────────┘       │
 │                                                             │
@@ -240,6 +420,7 @@ if (refreshedDag.ready_count > 0) {
 **Why this works for parallel:**
 - `detail <id>` is READ-ONLY → no race conditions
 - Each executor handles **all tasks within a solution** sequentially
+- **One commit per solution** with formatted summary (not per-task)
 - `done <id>` updates only its own solution status
 - `queue dag` recalculates ready solutions after each batch
 - Solutions in same batch have NO file conflicts

package/.claude/commands/issue/new.md

@@ -29,6 +29,10 @@ interface Issue {
   source_url?: string;
   labels?: string[];
 
+  // GitHub binding (for non-GitHub sources that publish to GitHub)
+  github_url?: string;           // https://github.com/owner/repo/issues/123
+  github_number?: number;        // 123
+
   // Optional structured fields
   expected_behavior?: string;
   actual_behavior?: string;
@@ -165,7 +169,30 @@ if (clarityScore < 2 && (!issueData.context || issueData.context.length < 20)) {
 }
 ```
 
-### Phase 5: Create Issue
+### Phase 5: GitHub Publishing Decision (Non-GitHub Sources)
+
+```javascript
+// For non-GitHub sources, ask if user wants to publish to GitHub
+let publishToGitHub = false;
+
+if (issueData.source !== 'github') {
+  const publishAnswer = AskUserQuestion({
+    questions: [{
+      question: 'Would you like to publish this issue to GitHub?',
+      header: 'Publish',
+      multiSelect: false,
+      options: [
+        { label: 'Yes, publish to GitHub', description: 'Create issue on GitHub and link it' },
+        { label: 'No, keep local only', description: 'Store as local issue without GitHub sync' }
+      ]
+    }]
+  });
+
+  publishToGitHub = publishAnswer.answers?.['Publish']?.includes('Yes');
+}
+```
+
+### Phase 6: Create Issue
 
 **Summary Display:**
 - Show ID, title, source, affected files (if any)
@@ -220,8 +247,64 @@ EOF
 }
 ```
 
+**GitHub Publishing** (if user opted in):
+```javascript
+// Step 1: Create local issue FIRST
+const localIssue = createLocalIssue(issueData);  // ccw issue create
+
+// Step 2: Publish to GitHub if requested
+if (publishToGitHub) {
+  const ghResult = Bash(`gh issue create --title "${issueData.title}" --body "${issueData.context}"`);
+  // Parse GitHub URL from output
+  const ghUrl = ghResult.match(/https:\/\/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/)?.[0];
+  const ghNumber = parseInt(ghUrl?.match(/\/issues\/(\d+)/)?.[1]);
+
+  if (ghNumber) {
+    // Step 3: Update local issue with GitHub binding
+    Bash(`ccw issue update ${localIssue.id} --github-url "${ghUrl}" --github-number ${ghNumber}`);
+    // Or via pipe:
+    // echo '{"github_url":"${ghUrl}","github_number":${ghNumber}}' | ccw issue update ${localIssue.id}
+  }
+}
+```
+
+**Workflow:**
+```
+1. Create local issue (ISS-YYYYMMDD-NNN) → stored in .workflow/issues.jsonl
+2. If publishToGitHub:
+   a. gh issue create → returns GitHub URL
+   b. Update local issue with github_url + github_number binding
+3. Both local and GitHub issues exist, linked together
+```
+
+**Example with GitHub Publishing:**
+```bash
+# User creates text issue
+/issue:new "Login fails with special chars. Expected: success. Actual: 500"
+
+# System asks: "Would you like to publish this issue to GitHub?"
+# User selects: "Yes, publish to GitHub"
+
+# Output:
+# ✓ Local issue created: ISS-20251229-001
+# ✓ Published to GitHub: https://github.com/org/repo/issues/123
+# ✓ GitHub binding saved to local issue
+# → Next step: /issue:plan ISS-20251229-001
+
+# Resulting issue JSON:
+{
+  "id": "ISS-20251229-001",
+  "title": "Login fails with special chars",
+  "source": "text",
+  "github_url": "https://github.com/org/repo/issues/123",
+  "github_number": 123,
+  ...
+}
+```
+
 **Completion:**
 - Display created issue ID
+- Show GitHub URL (if published)
 - Show next step: `/issue:plan <id>`
 
 ## Execution Flow
@@ -240,9 +323,16 @@ Phase 2: Data Extraction (branched by clarity)
    │            │  (3 files max)  │  → feedback  │
    └────────────┴─────────────────┴──────────────┘
 
-Phase 3: Create Issue
+Phase 3: GitHub Publishing Decision (non-GitHub only)
+   ├─ Source = github: Skip (already from GitHub)
+   └─ Source ≠ github: AskUserQuestion
+      ├─ Yes → publishToGitHub = true
+      └─ No  → publishToGitHub = false
+
+Phase 4: Create Issue
    ├─ Score ≥ 2: Direct creation
    └─ Score < 2: Confirm first → Create
+   └─ If publishToGitHub: gh issue create → link URL
 
 Note: Deep exploration & lifecycle deferred to /issue:plan
 ```
@@ -320,4 +410,4 @@ function parseMarkdownBody(body) {
 ## Related Commands
 
 - `/issue:plan` - Plan solution for issue
-- `/issue:manage` - Interactive issue management
+

package/.claude/commands/issue/plan.md

@@ -198,8 +198,9 @@ ${issueList}
 2. Load project context files
 3. Explore codebase (ACE semantic search)
 4. Plan solution with tasks (schema: solution-schema.json)
-5. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
-6. Single solution → auto-bind; Multiple → return for selection
+5. **If github_url exists**: Add final task to comment on GitHub issue
+6. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
+7. Single solution → auto-bind; Multiple → return for selection
 
 ### Rules
 - Solution ID format: SOL-{issue-id}-{seq}
@@ -304,6 +305,12 @@ Next: \`/issue:queue\` → \`/issue:execute\`
 | User cancels selection | Skip issue, continue with others |
 | File conflicts | Agent detects and suggests resolution order |
 
+## Bash Compatibility
+
+**Avoid**: `$(cmd)`, `$var`, `for` loops — will be escaped incorrectly
+
+**Use**: Simple commands + `&&` chains, quote comma params `"pending,registered"`
+
 ## Quality Checklist
 
 Before completing, verify:
@@ -319,6 +326,5 @@ Before completing, verify:
 ## Related Commands
 
 - `/issue:queue` - Form execution queue from bound solutions
-- `/issue:execute` - Execute queue with codex
 - `ccw issue list` - List all issues
 - `ccw issue status` - View issue and solution details