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 user picks "Worktree (isolated)" or "Move to worktree", use the EnterWorktree tool to create an isolated worktree before proceeding. All subsequent steps (branch creation, task execution, reviews, finalize, stats) happen inside the worktree. At completion, report the worktree path and branch so the user can review and merge.

If user picks "In-place" or "Stay here", proceed normally without worktree.

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: codex external", description="adversarial codex/claude review loop", activeForm="Running codex 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

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.