plan-task
Plans a task or feature - loads context, optionally clarifies requirements, spawns Plan agent, persists plan to .groundwork-plans/
etr · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add etr/groundwork --skill plan-taskAbout this skill
name: plan-task description: Plans a task or feature - loads context, optionally clarifies requirements, spawns Plan agent, persists plan to .groundwork-plans/ requires: understanding-feature-requests argument-hint: "[task-number-or-description] [--project name]"
Task Planning Skill
Plans a task or feature by loading context, optionally clarifying requirements, spawning a Plan agent, and persisting the validated plan to .groundwork-plans/.
Explicit Project Input
If arguments include --project <name>, resolve that project directly from the repository's .groundwork.yml for this invocation. Treat it as authoritative; do not depend on or change persisted project selection. In runner mode, GROUNDWORK_PROJECT and GROUNDWORK_PROJECT_ROOT provide the same invocation-local selection.
Runner Mode
If session context contains GROUNDWORK_RUNNER_MODE=true:
- Skip the model recommendation pre-flight.
- Treat
GROUNDWORK_BATCH_MODE=trueas authoritative: do not callAskUserQuestion. - When information or a decision is missing, return
RESULT: FAILUREinstead of asking. - Do not modify
.gitignore; the runner keeps.groundwork-plans/out of Git state. - Keep the existing terminal
RESULT: PLANNEDcontract unchanged.
Token Discipline
This skill orchestrates planning workflows. Every turn re-reads the full context window, so unnecessary turns are expensive.
- No narration turns. Do not output text-only turns like "Let me load the task" or "Now I'll spawn the plan agent." Combine text with a tool call in the same turn, or skip the text entirely.
- Batch tool calls. When multiple tool calls are independent, issue them all in one turn.
- No waiting updates. Do not output "Waiting for results..." turns. Wait silently until results arrive.
- 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 < 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": "Planning benefits from consistent multi-domain reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke.",
"header": "Effort check",
"options": [
{ "label": "Continue" },
{ "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.
Step 0: Resolve Project Context
Before loading specs, ensure project context is resolved:
- Monorepo check: Does
.groundwork.ymlexist 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 empty → Invoke
- If no → Continue (single-project repo).
- If yes → Is
- CWD mismatch check (monorepo only):
- Skip if not in monorepo mode or if the project was just selected in item 1 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).
- Proceed with the resolved project context. All
{{specs_dir}}/paths will resolve to the correct location.
Step 1: Detect Input Mode
Parse the input from the caller's conversation context. Three modes:
- Task ID (numeric like
4, or full format likeTASK-004): Setmode=task,task_id=TASK-NNN(zero-padded to 3 digits). - Blurb (free text, no task ID): Set
mode=feature,blurb=<text>. - Task ID + blurb (both present): Set
mode=task+blurb,task_id=TASK-NNN,blurb=<text>. - Neither (no argument, no context): Output
RESULT: FAILURE | No task ID or feature description provided.and stop.
Step 2: Load Context (mode-dependent)
Task ID mode (mode=task or mode=task+blurb)
-
Locate task file:
- Single file:
{{specs_dir}}/tasks.md - Directory:
{{specs_dir}}/tasks/Search for### TASK-NNN:pattern. Error: Task not found → OutputRESULT: FAILURE | TASK-NNN not found in {{specs_dir}}/tasks/and stop.
- Single file:
-
Read task definition — only the
### TASK-NNN:section (goal, action items, acceptance criteria, dependencies, status). Do NOT read full specs/architecture/design files. -
Validate task is workable:
- Status
Complete→ OutputRESULT: FAILURE | TASK-NNN is already Complete.and stop. - Blocked by incomplete tasks → Output
RESULT: FAILURE | TASK-NNN is blocked by: [list].and stop.
- Status
-
Verify spec paths exist (use Glob, not Read):
{{specs_dir}}/product_specs.mdor{{specs_dir}}/product_specs/{{specs_dir}}/architecture.mdor{{specs_dir}}/architecture/{{specs_dir}}/design_system.md- Tasks file (already found above)
If specs missing: Report which are m