Exec

exec

Execute plan file tasks sequentially, each in an isolated subagent.

Arguments

• $ARGUMENTS — path to plan file (optional; if omitted, ask user to pick from plans_dir userConfig directory, default: docs/plans/)

File Resolution

ALWAYS use the resolve script to read prompt and agent files. NEVER construct the override chain manually:

bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/resolve-file.sh prompts/task.md ${CLAUDE_PLUGIN_DATA}
bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/resolve-file.sh agents/quality.txt ${CLAUDE_PLUGIN_DATA}

The script checks project overrides, user overrides, and bundled defaults automatically.

Placeholder Substitution

After reading a prompt file, replace ALL placeholders with actual values before passing to a subagent. Subagents run in fresh contexts without plugin env vars.

Always substitute: PLAN_FILE_PATH, PROGRESS_FILE_PATH, DEFAULT_BRANCH, ${CLAUDE_PLUGIN_ROOT} (resolve to actual absolute path), RESOLVE_SCRIPT (absolute path to ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/resolve-file.sh), PLUGIN_DATA_DIR (resolved ${CLAUDE_PLUGIN_DATA} path — passed as second argument to resolve-file.sh so it can find user overrides), USER_RULES (resolved custom rules content from the rules loading step, or empty string if no rules found), and phase-specific values (FINDINGS_LIST, REVIEW_PHASE, DIFF_COMMAND).

Custom Rules Loading

Before starting execution, run this command via Bash tool to check for user-provided custom rules:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-rules.sh planning-rules.md ${CLAUDE_PLUGIN_DATA}

If the output is non-empty, store it as the resolved custom rules content. When substituting USER_RULES in task prompts, wrap the content with a label so the subagent understands it: use "ADDITIONAL CUSTOM RULES:\n<content>" as the substitution. If the output is empty, substitute an empty string for USER_RULES. See ${CLAUDE_PLUGIN_ROOT}/references/custom-rules.md for full documentation on the rules mechanism.

Process

Step 1. Resolve plan file

If $ARGUMENTS contains a file path, use it. Otherwise, list .md files in the plans_dir userConfig directory (default: docs/plans/), excluding completed/. If exactly one plan found, use it automatically. If multiple found, ask the user to pick one using AskUserQuestion.

Read the plan file. Count total Task sections (### Task N: or ### Iteration N:) to know the scope.

Determine the default branch: bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/detect-branch.sh

Note: in hg repos, detect-branch.sh returns remote/<name> (checking master, main, trunk in that order) in modern-Mercurial repos that expose upstream default via remote/<name> refs, and falls back to default in repos that use the traditional named-branch convention instead. The external-review prompt (prompts/codex-review.md) and the finalize prompt (prompts/finalizer.md) use git-specific commands and are not VCS-translated upstream. Both phases will be skipped (see step 9 and step 11, which re-detect VCS locally). Users who want hg-native review/finalize can override via .claude/exec-plan/prompts/codex-review.md and .claude/exec-plan/prompts/finalizer.md — any git rebase origin/DEFAULT_BRANCH in the bundled template must be replaced with the hg equivalent in the override, e.g. hg rebase -d remote/master when the repo exposes remote-tracking refs, or hg rebase -d default when it uses the traditional named-branch convention.

Step 2. Ask about worktree isolation

hg skip: Detect VCS with vcs=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/detect-vcs.sh). If vcs is hg, skip the worktree question and proceed in current directory. The EnterWorktree tool is git-only (wraps git worktree add) and has no hg equivalent upstream; users who want isolation in hg repos can use hg share manually before invoking /exec.

First detect current branch state — run git branch --show-current and compare with the default branch detected earlier (from detect-branch.sh). Two cases:

Case A — currently on the default branch (master/main/trunk). Step 4 will create a new feature branch. Ask the user where it should live. Invoke the AskUserQuestion tool with this payload:

{
  "questions": [{
    "question": "Where should the feature branch be created?",
    "header": "Branch location",
    "options": [
      {"label": "Worktree (isolated)", "description": "Create the feature branch in a new isolated git worktree (under .claude/worktrees/). Main working directory stays on the default branch."},
      {"label": "In-place", "description": "Create the feature branch in this working directory. Main directory switches to the feature branch for the duration of the run."}
    ],
    "multiSelect": false
  }]
}

Case B — currently on a feature branch. Step 4 will keep using this branch. Ask whether to move it to an isolated worktree or stay here. Invoke the AskUserQuestion tool with this payload:

{
  "questions": [{
    "question": "You're already on a feature branch. Run the plan here, or in an isolated worktree?",
    "header": "Isolation",
    "options": [
      {"label": "Stay here", "description": "Run the plan in this working directory, on the existing feature branch."},
      {"label": "Move to worktree", "description": "Copy this branch into a new isolated git worktree (under .claude/worktrees/). Main directory stays untouched."}
    ],
    "multiSelect": false
  }]
}

In BOTH cases: invoke the AskUserQuestion tool now, do not generate text first, do not skip, do not assume. Auto mode does NOT exempt this question — the choice affects the user's working directory and the orchestrator cannot decide on their behalf.

If the user picks "Worktree (isolated)" or "Move to worktree" — the main working directory MUST NOT be touched at all: no branch is created or checked out there, and no file changes land there. That isolation is the entire point of this mode. Set worktree_mode = true and do this:

1. Record the main tree's path and current branch so you can verify it stayed untouched: main_tree=$(git rev-parse --show-toplevel) and main_branch=$(git branch --show-current).
2. Derive the feature branch name with NO git side effects: name=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/create-branch.sh --print-name <plan-file-path>).
3. Create the isolated worktree with the EnterWorktree tool, passing <name> as the worktree name. It creates .claude/worktrees/<name>/ on a new branch worktree-<name> forked from the current HEAD and switches the session into it. Capture the worktree's absolute path as worktree_path.
4. Drop the worktree- prefix so the branch is just <name>, operating on the worktree only: git -C <worktree_path> branch -m <name>.
5. This means Step 4 (create-branch.sh) is SKIPPED — the branch already exists inside the worktree. Running create-branch.sh here would git checkout -b in the main tree and break isolation.
6. Isolation guard: verify the main tree is untouched — git -C "$main_tree" branch --show-current MUST still equal main_branch. If it changed, STOP and report the isolation breach instead of continuing.
7. Every later step (task execution, reviews, finalize, stats, the plan move) runs inside the worktree; use <name> wherever a branch name is needed. At completion, report worktree_path and <name> so the user can review and merge.

If the user picks "In-place" or "Stay here" — set worktree_mode = false and proceed normally; Step 4 creates the branch in this working directory.

Step 3. Create task list

ALWAYS create tasks using TaskCreate before starting any work. Create one task per plan Task section plus review phases:

For each ### Task N: section in the plan:

• TaskCreate(subject="Task N: <title>", description="<checkbox items>", activeForm="Executing task N...")

Then add review tasks:

• TaskCreate(subject="Review phase 1: comprehensive", description="5 parallel review agents + fixer", activeForm="Running review phase 1...")
• TaskCreate(subject="Review phase 2: code smells", description="smells agent + fixer", activeForm="Running smells review...")
• TaskCreate(subject="Review phase 3: external", description="adversarial external review loop", activeForm="Running external review...")
• TaskCreate(subject="Review phase 4: critical only", description="2 review agents + fixer", activeForm="Running review phase 4...")
• TaskCreate(subject="Finalize", description="rebase, clean up commits, verify", activeForm="Finalizing...")
• TaskCreate(subject="Stats summary", description="aggregate token/duration/git stats from session log", activeForm="Summarizing stats...")

Update tasks as you go: TaskUpdate(taskId, status="in_progress") when starting, TaskUpdate(taskId, status="completed") when done.

Step 4. Create branch

Skip this step entirely when worktree_mode is true — Step 2 already created the branch (<name>) inside the isolated worktree, and running this here would git checkout -b in the main working tree and break isolation. Carry <name> forward as the branch name and go to Step 5.

Otherwise (in-place mode), MANDATORY: run the script below. Do NOT create the branch manually — the script strips the date prefix from the plan filename (e.g., 20260329-feature-name.md → branch feature-name).

bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/create-branch.sh <plan-file-path>

The script creates a feature branch if currently on main/master, or stays on the current branch if already on a feature branch. Capture and use the branch name it outputs.

Step 5. Initialize progress file

Initialize the progress file: bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/init-progress.sh /tmp/progress-<plan-name>.txt <plan-file-path> <branch-name> (derive <plan-name> from the plan file stem, e.g., fix-issues.md → progress-fix-issues). The script creates the file with a header. Report the full progress file path to the user.

IMPORTANT: Always use ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/append-progress.sh to write to the progress file after initialization. Never write directly.

Step 6. Task loop

Repeat until no [ ] checkboxes remain in any Task section:

1. Re-read the plan file (subagent modifies it each iteration)
2. Find the first Task section (### Task N: or ### Iteration N:) that still has [ ] checkboxes
3. If none found — all tasks complete, go to step 7
4. Announce the task to the user — before spawning the subagent, output a visible summary:
   • Task number and title (from the ### Task N: header)
   • List all [ ] checkbox items in that task section
   • Example output:

     --- Task 1: Fix error handling ---
     - [ ] Handle the error from os.ReadFile
     - [ ] Either log and exit or handle gracefully

5. Spawn a subagent using Agent tool with:
   • mode: "bypassPermissions"
   • subagent_type: "general-purpose"
   • The task prompt from prompts/task.md, with all placeholders substituted as described in the Placeholder Substitution section above (including USER_RULES)
6. After subagent returns, re-read the plan file and check if that task's checkboxes are now [x]
   • If yes — task succeeded, continue loop
   • If no — retry with a fresh subagent for the same task up to task_retries times (userConfig, default: 1). If all retries fail, stop and report failure to user
7. Report to user: "Task N completed" (one line). The task subagent logs details to the progress file.

CRITICAL: Spawn exactly ONE task subagent per iteration and WAIT for it to return before starting the next. NEVER batch-spawn multiple task subagents in a single message. Plan tasks are ordered and interdependent — later tasks build on the files earlier tasks create, and every task subagent edits the same plan-file checkboxes and overlapping source files, so running them in parallel corrupts the plan and the working tree. The "launch in a single message for parallel execution" instruction applies ONLY to the review phases (steps 7 and 10), never to this task loop.

CRITICAL: Do NOT stop the loop based on subagent return text. The ONLY condition to stop is: no [ ] checkboxes remain in any Task section (### Task N: or ### Iteration N:). Always re-read the plan file to check.

CRITICAL: You are the ORCHESTRATOR. Never read code, debug errors, investigate diagnostics, or fix issues yourself. If a subagent leaves problems (compiler errors, test failures, lint issues), retry with a fresh subagent — pass the error details in the prompt so it can fix them. All code work happens inside subagents, not in the orchestrator.

Maximum iterations safety limit: 50. If reached, stop and report to user.

Step 7. Review phase 1 — comprehensive then critical re-check

After all tasks complete, run a comprehensive code review on iteration 1, then narrow to critical-only re-checks on subsequent iterations to verify the fixer's work without re-running the full heavy sweep.

Report to user: "--- Review phase 1: comprehensive ---"

Loop up to review_iterations times (userConfig, default: 5). Track the current iteration number:

1. Read review.md as a playbook (NOT as a subagent prompt) — resolve prompts/review.md through the override chain and read it from this main session. It tells YOU (the orchestrator) which specialist agents to fan out for the current REVIEW_PHASE. Substitute DEFAULT_BRANCH, PLAN_FILE_PATH, PROGRESS_FILE_PATH, ${CLAUDE_PLUGIN_ROOT}, and REVIEW_PHASE in the resolved content. Then follow the playbook FROM THIS SESSION: launch the specified Agent tool calls in a single message for parallel execution. Subagents do not have Agent tool access, so the fanout MUST be initiated from the main orchestrator.

   • Iteration 1: set REVIEW_PHASE to comprehensive. Per the playbook, launch 5 parallel review agents (quality, implementation, testing, simplification, documentation).
   • Iteration 2 and later: set REVIEW_PHASE to critical. Per the playbook, launch 2 parallel review agents (quality, implementation) focused on critical/major issues only. Before this iteration, report to user: "--- Review phase 1: critical re-check (iteration N) ---"

2. Collect findings — collect findings from ALL launched review agents. Pass the COMPLETE output (not a summary) to the fixer. Do NOT summarize, filter, or dismiss any findings. ALL findings are actionable. Report to user with a short list of findings. Log to progress file: bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/append-progress.sh <progress-file> "review phase 1: findings" Then pipe: echo "<findings>" | bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/append-progress.sh <progress-file>

3. If ALL agents reported zero issues → report "Review phase 1: clean" and proceed to the next phase.

4. Spawn a fixer agent — resolve prompts/fixer.md through the override chain. Launch with mode: "bypassPermissions", subagent_type: "general-purpose". Pass the FULL unedited review output as FINDINGS_LIST — the fixer decides what's real, not you.

5. After fixer returns → show the "FIXES:" section to the user. Report "Review phase 1: iteration N fixes applied". Check for uncommitted changes: detect VCS with vcs=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/detect-vcs.sh), then run git status --porcelain for git or hg status for hg. If output is non-empty, show every reported path and warn that these uncommitted changes are absent from the committed branch diff used by the next review. This is report-only: do not retry, abort, or commit leftovers because of this check. Loop back to step 1.

If review_iterations reached with issues still found, report "Review phase 1: max iterations reached, moving on" and continue.

Step 8. Review phase 2 — code smells

Report to user: "--- Review phase 2: code smells analysis ---"

Run once (no loop):

1. Spawn a smells agent — resolve agents/smells.txt through the override chain. Launch one Agent tool call with mode: "bypassPermissions", subagent_type: "general-purpose", and the resolved agent prompt.

2. Collect findings — after the agent returns, report to user with a compact list of findings (one line per finding). Log findings to progress file: bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/append-progress.sh <progress-file> "review phase 2: findings" Then pipe the findings: echo "<findings>" | bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/append-progress.sh <progress-file>

3. If no issues found → report "Smells analysis: clean" and proceed to the next phase.

4. Spawn a fixer agent — resolve prompts/fixer.md through the override chain. Launch with mode: "bypassPermissions", subagent_type: "general-purpose". Pass the FULL smells output as FINDINGS_LIST.

5. After fixer returns → report fixes to user. Check for uncommitted changes: detect VCS with vcs=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/exec/scripts/detect-vcs.sh), then run git status --porcelain for git or hg status for hg. If output is non-empty, show every reported path and warn that these uncommitted changes are absent from the committed branch diff used by the next review. This is report-only: do not retry, abort, or commit leftovers because of this check. Proceed to the next phase.