Work On

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.

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 Then invoke groundwork:work-on with the same task ID. ``

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

1. 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).

1. 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 ` (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= | identifier= | branch_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] 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 (GROUNDWORKBATCHMODE=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:

To resume implementation later: /groundwork:implement-task

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= | branch= | base_branch= → Save values. Proceed.
• RESULT: FAILURE | ... → Report failure. In batch mode output RESULT: FAILURE | [TASK-NNN] 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: ``
• Branch: ``
• Base branch: ``

To resume validation in a clean context:

1. Run /clear to clear Claude Code context
2. cd
3. Run /groundwork:validate

After validation passes, merge manually from the project root:

cd git checkout git merge --no-ff git worktree remove git branch -d

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 agents approved → Proceed to Step 5
• Validation failed → Report failure; in batch mode output RESULT: FAILURE | [TASK-NNN] Validation failed: ... and stop
• Stuck on recurring issue → Report the stuck finding and stop

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
3. Merge: git merge --no-ff -m "Merge : [Task Title]"
4. If success: Remove worktree and delete branch:

``bash git worktree remove .worktrees/TASK-NNN git branch -d ``

1. If conflicts: Report conflicts and keep worktree for manual resolution

If not merging or conflicts occurred:

Report worktree location and manual merge instructions:

## Implementation Complete in Worktree

**Location:** .worktrees/TASK-NNN
**Branch:** task/TASK-NNN

When ready to merge:
```bash
git checkout [base-branch]
git merge --no-ff 
git worktree remove .worktrees/TASK-NNN
git branch -d 

To continue working:

cd .worktrees/TASK-NNN

## 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 → . Validation passed in N iter(s).

If the merge did not happen, replace `merged → ` with `pending at `.

---

## 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 worktree (`.worktrees/TASK-NNN`)
- [ ] 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/groundwork](https://github.com/etr/groundwork)
- **License:** MIT

Install and usage instructions live in the source repository linked above.