From groundwork
Executes all remaining tasks in sequence until completion, stopping on first failure. Includes pre-flight recommendation for Sonnet/Opus at high effort and monorepo project context resolution.
How this skill is triggered — by the user, by Claude, or both
Slash command
/groundwork:just-do-itThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Executes all remaining tasks in sequence until completion, stopping on first failure.
Executes all remaining tasks in sequence until completion, stopping on first failure.
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:
{
"questions": [{
"question": "Do you want to switch? Batch orchestration with dependency ordering and failure handling benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
"header": "Recommended: Sonnet or Opus at high effort",
"options": [
{ "label": "Continue" },
{ "label": "Cancel — I'll switch first" }
],
"multiSelect": false
}]
}
If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.
Before loading tasks, ensure project context is resolved:
.groundwork.yml exist at the repo root?
{{project_name}} non-empty?
Skill(skill="groundwork:select-project") to select a project, then restart this skill.{{project_name}}, specs at {{specs_dir}}/..groundwork.yml).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").
{{specs_dir}}/ paths will resolve to the correct location.Read the tasks file to find all tasks:
{{specs_dir}}/tasks.md{{specs_dir}}/tasks/ (aggregated in sorted order)Parse all tasks and extract:
TASK-001)Not Started, In Progress, Complete, Blocked)Blocked by: field)Build dependency graph and calculate execution order:
Detection: Check for file first (takes precedence), then directory.
Present a summary to the user:
Total tasks: X Already complete: Y Remaining: Z
Each task will execute in an isolated git worktree:
task/TASK-NNN created from current HEAD.worktrees/TASK-NNNThis ensures each task starts from a clean baseline and changes are integrated incrementally.
Ask for confirmation before proceeding.
If user declines, stop and suggest alternatives:
/groundwork:work-on N to work on a specific task/groundwork:work-on-next-task to work on just the next available taskEach task is executed through 5 phases orchestrated directly from this conversation. This avoids nested sub-tasks (sub-tasks cannot spawn other sub-tasks). The main loop holds only: task list + per-task plan summary, IMPLEMENTED result, validation verdicts, and merge result.
For each remaining task in dependency order:
Read the task section from {{specs_dir}}/tasks.md (or aggregated from {{specs_dir}}/tasks/) to extract the full task definition (goal, action items, acceptance criteria, dependencies).
Announce start: "Starting TASK-NNN: [Title]"
Update task status to **Status:** In Progress in the tasks file.
Agent(
subagent_type="Plan",
description="Plan TASK-NNN",
prompt="Create implementation plan for TASK-NNN: [task title]
Task definition:
[goal, action items, acceptance criteria from task file]
Relevant product specs:
[extracted from {{specs_dir}}/product_specs.md or {{specs_dir}}/product_specs/]
Relevant architecture:
[extracted from {{specs_dir}}/architecture.md or {{specs_dir}}/architecture/]
REQUIREMENTS FOR THE PLAN:
1. All work happens in worktree .worktrees/TASK-NNN (not main workspace)
2. Must follow TDD: write test → implement → verify cycle
3. Plan covers implementation only — validation and merge are handled separately by the caller
"
)
If the plan does not mention worktree or TDD, reject it and re-invoke the Plan agent.
After validation, persist the plan to disk in the same turn as receiving the Plan agent's output:
mkdir -p .groundwork-plans && grep -qxF '.groundwork-plans/' .gitignore 2>/dev/null || printf '.groundwork-plans/\n' >> .gitignore, then set plan_file_path=.groundwork-plans/TASK-NNN-plan.md (substitute the actual task ID). Re-running on the same task overwrites — intentional.Write tool to save the Plan agent's full output to plan_file_path, formatted as:
# Implementation Plan: TASK-NNN [Title]
<verbatim Plan agent output>
plan_file_path. Do NOT re-quote the plan in subsequent turns.Agent(
subagent_type="groundwork:task-executor:task-executor",
description="Implement TASK-NNN",
prompt="You are implementing a task as part of an automated batch run.
PROJECT ROOT: [absolute path to project root]
TASK:
- task_id: [TASK-NNN]
- tasks_path: [absolute path to {{specs_dir}}/tasks.md or {{specs_dir}}/tasks/]
Read the '### TASK-NNN:' section from tasks_path for goal, action items,
and acceptance criteria. Do not ask the caller for task details.
PLAN FILE: [plan_file_path]
Read this file first with the Read tool — it contains the validated implementation plan.
INSTRUCTIONS:
1. Follow your preloaded skills to create a worktree, implement with TDD, and commit.
2. Read the task section from tasks_path and the plan from PLAN FILE — they provide all session context.
3. Do NOT use AskUserQuestion — proceed automatically.
4. When complete, output your final line in EXACTLY this format:
RESULT: IMPLEMENTED | <worktree_path> | <branch> | <base_branch>
OR:
RESULT: FAILURE | [one-line reason]
Your LAST line of output MUST be the RESULT line.
"
)
Parse the result:
RESULT: IMPLEMENTED | <path> | <branch> | <base_branch> → Save these values, proceed to Phase CRESULT: FAILURE | ... → STOP immediately, report failureFindings storage prologue (run FIRST): Create a per-task findings directory and initialize an iteration counter. Validation agents will write their full review JSON to per-iteration files inside this directory; the orchestrator will only see compact one-line responses.
cd <worktree_path>
mktemp -d -t groundwork-validation-XXXXXX # save the printed path as findings_dir
git diff --name-only HEAD~1 # changed file paths
git diff --stat HEAD~1 # diff stat summary
Initialize iteration_number = 1. Maintain orchestrator working notes (in-context, NOT in any project file) of the form:
findings_dir: /tmp/groundwork-validation-XXXXXX
iteration_number: 1
iterations:
1:
agent_files:
code-quality-reviewer: /tmp/groundwork-validation-XXXXXX/findings-code-quality-reviewer-iter1.json
security-reviewer: /tmp/groundwork-validation-XXXXXX/findings-security-reviewer-iter1.json
...
findings_fixed: []
findings_skipped: []
Then launch all 10 validation agents in parallel using the Agent tool:
Agent(subagent_type="groundwork:code-quality-reviewer:code-quality-reviewer", description="Review TASK-NNN quality", prompt="...")
Agent(subagent_type="groundwork:security-reviewer:security-reviewer", description="Review TASK-NNN security", prompt="...")
Agent(subagent_type="groundwork:spec-alignment-checker:spec-alignment-checker", description="Check TASK-NNN spec alignment", prompt="...")
Agent(subagent_type="groundwork:architecture-alignment-checker:architecture-alignment-checker", description="Check TASK-NNN arch alignment", prompt="...")
Agent(subagent_type="groundwork:code-simplifier:code-simplifier", description="Simplify TASK-NNN code", prompt="...")
Agent(subagent_type="groundwork:housekeeper:housekeeper", description="Check TASK-NNN housekeeping", prompt="...")
Agent(subagent_type="groundwork:performance-reviewer:performance-reviewer", description="Review TASK-NNN performance", prompt="...")
Agent(subagent_type="groundwork:test-quality-reviewer:test-quality-reviewer", description="Review TASK-NNN test quality", prompt="...")
Agent(subagent_type="groundwork:design-consistency-checker:design-consistency-checker", description="Check TASK-NNN design", prompt="...")
Agent(subagent_type="groundwork:cloud-infrastructure-reviewer:cloud-infrastructure-reviewer", description="Check TASK-NNN cloud infra", prompt="...")
Agent(subagent_type="groundwork:conventions-reviewer:conventions-reviewer", description="Check TASK-NNN cloud infra", prompt="...")
Each agent receives: changed file paths, diff stat, task definition, and relevant spec/architecture/design paths. Each prompt MUST also include:
findings_file: {findings_dir}/findings-{agent_name}-iter{iteration_number}.json
agent_name: {agent_name}
iteration: {iteration_number}
Substitute {agent_name} with the agent's short name (code-quality-reviewer, etc.). Also include in each prompt: "Use the Read tool to examine these files. Do NOT expect file contents in this prompt — read them yourself. Write your full review JSON to the findings_file path above using the Write tool, then return ONLY the compact one-line JSON response. Do NOT print findings inline."
Each agent's compact response is a single JSON line:
{"verdict":"approve","score":85,"summary":"...","findings_file":"/tmp/groundwork-validation-XXXXXX/findings-<agent>-iter1.json","counts":{"critical":0,"major":1,"minor":2}}
The full review file format (written by the agent to findings_file) is:
{
"agent": "code-quality-reviewer",
"iteration": 1,
"summary": "...",
"score": 85,
"verdict": "approve",
"findings": [
{"id": 1, "severity": "major", "category": "...", "file": "...", "line": 42, "finding": "...", "recommendation": "..."}
]
}
The stable global ID of a finding is {agent_name}-iter{N}-{id} (e.g. code-quality-reviewer-iter1-2).
Parse only the compact line. Record each agent's findings_file path in the iteration tracking notes. Do NOT read finding bodies into context.
If any agent returns request-changes:
Build the list of findings_file paths from agents whose verdict in this iteration is request-changes (look them up in your iteration tracking notes for the current iteration_number). Do NOT inline the contents of those files into the prompt.
Spawn the validation-fixer agent:
Agent(
subagent_type="groundwork:validation-fixer:validation-fixer",
description="Fix TASK-NNN validation findings",
prompt="Working directory: <worktree_path>
Iteration: N
FINDINGS FILES:
- [path to findings-<agent>-iter<N>.json]
- [path to findings-<other-agent>-iter<N>.json]
...
Read each file with the Read tool. Each is a JSON object with shape:
{ agent, iteration, summary, score, verdict, findings: [{id, severity, category, file, line, finding, recommendation}, ...] }
Address all critical and major findings across these files. Skip minor findings.
Reference each finding by its global ID: {agent}-iter{iteration}-{id} (e.g. code-quality-reviewer-iter1-2)."
)
Parse the fix agent result. Its RESULT: line uses global IDs ({agent}-iter{N}-{id}):
RESULT: FIXED | files_touched: [...] | findings_fixed: [global-id, ...] → all findings addressed, proceed to re-validationRESULT: PARTIAL | files_touched: [...] | findings_fixed: [global-id, ...] | findings_skipped: [global-id: reason, ...] → log skipped findings, proceed to re-validation with fixed subset; skipped findings feed stuck detectionRESULT: FAILURE | [reason] → log failure, report and continueRecord findings_fixed and findings_skipped (as global ID lists) in the iteration tracking notes under the current iteration_number. These are what Phase D.5 uses to compute the unexecuted set.
Re-run validation agents (same as Phase C). Bump iteration_number by 1 first, append a new iteration block to your tracking notes, and pass each re-run agent a new findings_file path (...-iter{N+1}.json) so the previous iteration's file is preserved on disk for Phase D.5.
Repeat until all agents approve
Stuck detection: Track findings by their global ID prefix [Agent]-[Category]-[File]-[Line]. If the same finding persists after 3 iterations (including findings repeatedly skipped by the fix agent), report it and continue (do not block indefinitely). If you need to surface body details for the report, Read the relevant findings_file once.
After all agents approve, persist any unfixed findings via the helper script. The orchestrator does not Read any findings file itself, and does not Read the file the script produces. The helper does all of the file I/O outside the orchestrator's context window.
fixed_ids_csv by joining (with commas, no spaces) every global ID in findings_fixed across every iteration of the tracking notes. (Free — these IDs are already in context.) If no findings were fixed, pass an empty string.TASK-042: Title) as task_id.node ${CLAUDE_PLUGIN_ROOT}/lib/persist-unworked-findings.js \
--findings-dir "<findings_dir>" \
--specs-dir "{{specs_dir}}" \
--task-id "<task_id>" \
--fixed-ids "<fixed_ids_csv>"
cat, or Read the contents of the file the script produces — that would re-pollute the orchestrator's context with the very findings the script exists to keep out. The single-line JSON the script writes to stdout is the only thing to look at.status: "written" → record Unexecuted findings: <total> persisted to <written> in the per-task log line, where <total> is counts.critical + counts.major + counts.minor and <written> is the path the script returned.status: "empty" or status: "no-findings-files" → record Unexecuted findings: 0.Cleanup (run at the very end of Phase D.5, before proceeding to Phase E): delete the per-task findings directory created at the start of Phase C. Only delete the findings_dir path that was returned by mktemp -d -t groundwork-validation-XXXXXX:
rm -rf "<findings_dir>"
If findings_dir was never created (e.g., Phase C bailed out before creating it), skip cleanup.
From the project root (NOT the worktree):
git checkout <base_branch>
git merge --no-ff <branch> -m "Merge <branch>: [Task Title]"
git worktree remove .worktrees/TASK-NNN
git branch -d <branch>
If merge conflicts occur, report them and preserve the worktree for investigation. STOP.
Update task status to **Status:** Complete in the tasks file.
Log result: "Completed TASK-NNN: [Title] — [one-line summary]"
On Failure at any phase: Report the failed task, phase, reason, tasks completed this session, and tasks remaining. Note that the failed task's worktree is preserved at .worktrees/TASK-NNN for investigation.
When all tasks complete successfully, report:
## Batch Execution Complete
**Session Summary:**
- Tasks completed: X
- Total tasks complete: Y/Z
- All worktrees merged and cleaned up
### Completed Tasks
| Task | Title | Branch | Status |
|------|-------|--------|--------|
| TASK-001 | [Title] | task/TASK-001 | Merged |
| TASK-002 | [Title] | task/TASK-002 | Merged |
...
### Worktree Summary
- Worktrees created: X
- Successfully merged: X
- Cleaned up: X
### Next Steps
- Run `/source-product-specs-from-code` to update specs with any implementation changes
- Plan next phase if milestone complete
- Review merged changes with `git log --oneline -10`
| Situation | Response |
|---|---|
| No tasks file | "Tasks file not found. Run /groundwork:create-tasks to generate tasks." |
| No remaining tasks | "All tasks are already complete! Nothing to execute." |
| All remaining blocked | "All remaining tasks are blocked. Cannot proceed automatically." |
| Single task remaining | Execute normally (still confirm before starting) |
npx claudepluginhub etr/groundworkExecutes remaining tasks in parallel using agent teams for context isolation. Each task runs in its own teammate session. For large batches (>5 tasks) where context accumulation is a concern.
Executes Plans.md tasks end-to-end in solo, parallel, or full team modes with auto-mode selection based on task count.