work-on git:20261023.5f1d1f9A

Immutable. This exact content never changes and is served at /api/v1/blob/3c38c263eaeadd97.

---
name: work-on
description: skill to "execute a task", "work on task N", or "implement TASK-NNN" - orchestrates worktree isolation, TDD implementation, validation, and merge.
requires: plan-task, implement-task, validate
argument-hint: "[task-number]"
---

# Execute Task Skill

Thin orchestrator that delegates to `plan-task`, `implement-task`, and `validate` skills for the three phases of task execution.

## Token Discipline

This skill orchestrates long multi-agent workflows. Every turn re-reads the full context window, so unnecessary turns are expensive.

1. **No narration turns.** Do not output text-only turns like "Let me load the task" or "Now I'll launch the plan agent." Combine text with a tool call in the same turn, or skip the text entirely.
2. **Batch tool calls.** When multiple tool calls are independent, issue them all in one turn.
3. **No waiting updates.** Do not output "Waiting for results..." turns. Wait silently until results arrive.
4. **Keep context lean.** Do not read file contents you won't use directly. Pass file paths to subagents and let them read in their own context windows.

## Delegation Ownership

Keep implementation and validation delegated to fresh, isolated contexts. The executor owns implementation and test monitoring; the validation coordinator owns its reviewer/fixer loop. The root owns dispatch, required decisions, and phase transitions.

Wait for completion, a concrete blocker, or a required decision. Do not request periodic progress, repeat the executor's checks, or independently monitor its test processes. Use existing runner status and heartbeats for routine visibility; intervene only on concrete failure or loss of liveness. Executors send exception reports and their terminal result, not periodic progress messages. Delegation for context isolation remains required.

## Pre-flight: Model Recommendation

**Your current effort level is `{{effort_level}}`.**

Skip this step silently if effort is `high`, `xhigh`, or `max` (the scale is `low` < `medium` < `high` < `xhigh` < `max`, so `xhigh` and `max` are already above `high`) AND you are Sonnet or Opus.
If effort is `low` or `medium` (i.e. below `high`), you MUST show the recommendation prompt — regardless of model.
If you are not Sonnet or Opus, you MUST show the recommendation prompt — regardless of effort level.

Otherwise → use `AskUserQuestion`:

```json
{
  "questions": [{
    "question": "Task execution benefits from consistent multi-domain reasoning.\n\nRecommended: Sonnet or Opus at high effort.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke.",
    "header": "Effort check",
    "options": [
      { "label": "Continue anyway" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}
```

If the user selects "Cancel — I'll switch first": output the switching commands and stop. Do not proceed with the skill.

## Plan Mode Handling

1. Execute Steps 0-2 below as normal (they are read-only — planning produces a plan file).
2. After Step 2 produces the plan file, write the plan mode output:

   ```markdown
   ## Task: [TASK-NNN] [Title]

   ### Execution Context
   **Working Directory:** [run `node ${CLAUDE_PLUGIN_ROOT}/lib/worktree-identity.js <TASK-NNN>` and use its `path` value — project-qualified in monorepos]
   **Branch:** [use the same helper output's `branch` value]
   **Base Branch:** [current branch]

   ## Implementation Plan
   **IMPORTANT: DO NOT just execute the plan below.** Re-invoke `groundwork:work-on` which will use the saved plan. Set:
   - `GROUNDWORK_EXECUTE_SKIP_TO_STEP_SEVEN=true`
   - `GROUNDWORK_EXECUTE_PLAN_FILE=<absolute path to plan file>`
   Then invoke `groundwork:work-on` with the same task ID.
   ```

3. Call `ExitPlanMode()`

## Step 0: Resolve Context

1. **Check skip flag:** If session context contains `GROUNDWORK_EXECUTE_SKIP_TO_STEP_SEVEN=true`, set `plan_file_path = $GROUNDWORK_EXECUTE_PLAN_FILE` and skip directly to Step 3 (Implementation). Do NOT read the plan file's contents into this orchestrator's context — the implement-task skill will pass the path to the executor agent.

2. **Monorepo check:** Does `.groundwork.yml` exist at the repo root?
   - If yes → Is `{{project_name}}` non-empty?
     - If empty → Invoke `Skill(skill="groundwork:select-project")` to select a project, then restart this skill.
     - If set → Project is `{{project_name}}`, specs at `{{specs_dir}}/`.
   - If no → Continue (single-project repo).
3. **CWD mismatch check (monorepo only):**
   - Skip if not in monorepo mode or if the project was just selected above.
   - If CWD is the repo root → fine, proceed.
   - Check which project's path CWD falls inside (compare against all projects in `.groundwork.yml`).
   - If CWD is inside the selected project's path → fine, proceed.
   - If CWD is inside a different project's path → warn via `AskUserQuestion`:
     > "You're working from `<cwd>` (inside **[cwd-project]**), but the selected Groundwork project is **[selected-project]** (`[selected-project-path]/`). What would you like to do?"
     > - "Switch to [cwd-project]"
     > - "Stay with [selected-project]"
     If the user switches, invoke `Skill(skill="groundwork:select-project")`.
   - If CWD doesn't match any project → proceed without warning (shared directory).

## Step 1: Parse Task Identifier

Parse the task identifier from the argument:

- **Numeric** (e.g., `4`): Interpret as `TASK-004` (zero-padded to 3 digits)
- **Full format** (e.g., `TASK-004`): Use as-is
- **No argument**: Run `/groundwork:work-on-next-task` to determine the next workable task, then use that ID. If it returns nothing workable, report and stop.

**Error:** Invalid format → "Please specify a task number, e.g. `/groundwork:work-on 4` or `/groundwork:work-on TASK-004`"

### Batch Mode Detection

If session context contains `GROUNDWORK_BATCH_MODE=true`, batch mode is active. In batch mode:
- All `AskUserQuestion` calls are skipped
- On completion or failure, output a structured result line (Step 7)

## Step 2: Plan → `plan-task`

Call `Skill(skill="groundwork:plan-task")` with the task ID from Step 1 in the conversation context.

**Parse the output:**
- `RESULT: PLANNED | plan_file_path=<path> | identifier=<id> | branch_prefix=<prefix>` → Save `plan_file_path`, `identifier`, `branch_prefix`, then **continue to Step 2.5 in this same turn**.
- `RESULT: FAILURE | ...` → Report failure. In batch mode output `RESULT: FAILURE | [TASK-NNN] <reason>` and stop. In interactive mode, report the failure and stop.

> **Do NOT stop after planning.** Planning is only the first of three phases in `work-on`. The "DO NOT proceed past this step" note inside `plan-task` applies to `plan-task` itself, not to this orchestrator — when control returns here with `RESULT: PLANNED`, you are NOT done. Never end your turn on a bare plan summary; the very next action after a successful plan is the Step 2.5 question.

### Step 2.5: Confirm Start (Interactive Only)

**Batch mode (GROUNDWORK_BATCH_MODE=true):** Skip to Step 3.

**Interactive mode:** This question is **mandatory** — if you reached here with a plan, you must ask it rather than stopping. Use `AskUserQuestion`:

> "[TASK-NNN] [Title] — plan ready. Proceed to implementation?"
> - Option 1: "Yes, begin implementation"
> - Option 2: "Stop here — I'll review the plan first"

**If "Stop here":** Print the plan file path and resume instructions, then STOP:

    Plan saved to: <plan_file_path>
    
    To resume implementation later:
    /groundwork:implement-task <task-number>

## Step 3: Implement → `implement-task`

Call `Skill(skill="groundwork:implement-task")` with `task_id` and `plan_file_path` in the conversation context.

**Parse the output:**
- `RESULT: IMPLEMENTED | worktree_path=<path> | branch=<branch> | base_branch=<bb>` → Save values. Proceed.
- `RESULT: FAILURE | ...` → Report failure. In batch mode output `RESULT: FAILURE | [TASK-NNN] <reason>` and stop. In interactive mode, report and stop.

### Step 3.5: Optional Context Clear Pause (Interactive Only)

**Skip this step entirely if `GROUNDWORK_BATCH_MODE=true`** — proceed directly to Step 4.

In interactive mode, the orchestrator's context now holds the plan summary and the executor result. Validation runs 9 reviewer agents and may iterate through a fix loop, which compounds context further. Offer the user a chance to stop here so they can clear context before validation begins.

Use `AskUserQuestion` to ask:

> "Implementation complete for [TASK-NNN]. Validation runs 9 reviewer agents next and can compound context. Clear context before validation?"
> - Option 1: "Continue to validation now"
> - Option 2: "Stop here — I'll clear and resume manually"

**If "Continue to validation now":** Proceed to Step 4.

**If "Stop here":** Print the resume instructions below and STOP. Do NOT call validate. Do NOT proceed to Steps 4, 5, 6, or 7.

    ## Paused before validation

    Implementation is committed in:
    - **Worktree:** `<worktree_path>`
    - **Branch:** `<branch>`
    - **Base branch:** `<base_branch>`

    To resume validation in a clean context:

    1. Run `/clear` to clear Claude Code context
    2. `cd <worktree_path>`
    3. Run `/groundwork:validate`

    After validation passes, merge manually from the project root:

        cd <project_root>
        git checkout <base_branch>
        git merge --no-ff <branch>
        git worktree remove <worktree_path>
        git branch -d <branch>

    Then mark **TASK-NNN** as `Complete` in the tasks file.

This is a hard stop. The user explicitly chose to take over the rest of the workflow.

## Step 4: Validate

**Call the validate skill directly.** Do NOT wrap this in a subagent — this skill runs in the main conversation, which CAN spawn the 9 validation subagents it needs.

1. `cd` into the worktree path from Step 3
2. Call: `Skill(skill="groundwork:validate")`
3. The validate skill will run 9 verification agents in parallel and fix issues autonomously.

**After validate completes:**
- All required gates pass and all agents approve → Proceed to Step 5
- Validation is incomplete because of an incidental or uncertain failure → Finish safe, independent work still within the task, preserve the implementation and valid evidence, then report implementation readiness, validation limits and any publication constraint together. Ask whether/how the user wants the separate issue investigated only once that work is ready. Do not restart validation or expand repair scope automatically. In batch mode, preserve the worktree and return `RESULT: FAILURE | [TASK-NNN] Validation incomplete: ...`.
- Other validation failure or a stuck in-scope repair → Report the specific blocker and preserve completed work; in batch mode output `RESULT: FAILURE | [TASK-NNN] Validation failed: ...` and stop.

Follow the validate skill's bounded failure assessment. A passing rerun does not prove a failure unrelated. Retain that assessment, checks already performed and the pending decision in the existing task/validation record across delegation and resume. Publication remains subject to the source workflow's rules and explicit user decisions; never report a failed or waived gate as passed.

## Step 5: Merge

**From the project root** (NOT the worktree), handle merge:

**Determine merge action:**

| Condition | Behavior |
|-----------|----------|
| `GROUNDWORK_BATCH_MODE=true` | Auto-merge immediately |
| `GROUNDWORK_AUTO_MERGE` env var is `true` | Auto-merge immediately |
| Otherwise | Prompt user for decision |

**If prompting user:**

Use `AskUserQuestion` to ask:

> "Implementation and validation complete for [TASK-NNN]. Would you like me to merge this into [base-branch] now?"
> - Option 1: "Yes, merge now"
> - Option 2: "No, I'll merge manually later"

**Wait for user response before proceeding.**

**If merging:**

1. Ensure you are in the project root (cd out of worktree if needed)
2. Checkout base branch: `git checkout <base-branch>`
3. Merge: `git merge --no-ff <branch> -m "Merge <branch>: [Task Title]"`
4. If success: Remove worktree and delete branch:
   ```bash
   git worktree remove <worktree-path from the execution context>
   git branch -d <branch>
   ```
5. If conflicts: Report conflicts and keep worktree for manual resolution

**If not merging or conflicts occurred:**

Report worktree location and manual merge instructions:

```markdown
## Implementation Complete in Worktree

**Location:** [worktree path from the execution context]
**Branch:** [branch from the execution context]

When ready to merge:
```bash
git checkout [base-branch]
git merge --no-ff <branch>
git worktree remove <worktree-path>
git branch -d <branch>
```

To continue working:
```bash
cd <worktree-path>
```
```

## Step 6: Complete Task

After successful merge or user acknowledgment:

1. **Update status** — Change task file to `**Status:** Complete` and update the status table in `{{specs_dir}}/tasks/_index.md` or `{{specs_dir}}/tasks.md` (change the task's row to `Complete`)

## Step 7: Report

**Batch mode (GROUNDWORK_BATCH_MODE=true):** Output the structured result as your final line:
```
RESULT: SUCCESS | [TASK-NNN] [Task Title] - [one-line summary of what was done]
```
If the task failed at any step, output:
```
RESULT: FAILURE | [TASK-NNN] [reason for failure]
```

**Interactive mode:** Output exactly one line:

```
Done: [TASK-NNN] merged → <base>. Validation passed in N iter(s).
```

If the merge did not happen, replace `merged → <base>` with `pending at <worktree_path>`.

---

## Reference

### Task Status Values
- `**Status:** Not Started`
- `**Status:** In Progress`
- `**Status:** Complete`
- `**Status:** Blocked`

### Dependency Handling
Task is blocked if `Blocked by:` lists any task not Complete.

### Final Checklist
Before marking complete, verify ALL:
- [ ] Working in the task worktree (path recorded from the worktree-identity helper)
- [ ] Plan agent was used (not your own plan)
- [ ] TDD was followed
- [ ] All acceptance criteria verified
- [ ] validate returned PASS (via direct Skill call)
- [ ] All validation fixes were applied by the validation-fixer subagent — zero `Edit`/`Write`/`NotebookEdit` calls and zero file-mutating `Bash` calls (`sed -i`, `awk -i`, `tee`, `>`, `>>`, etc.) by this orchestrator during the validation phase. If you fixed anything yourself instead of dispatching to validation-fixer, that is a violation of the validate hard rule and the task is NOT complete.
- [ ] Merge completed or user acknowledged worktree location

If any unchecked: task is NOT complete.