ai-coding-skills/pi-package/skills/do-task/SKILL.md

name, description

name	description
do-task	Execute a single user-supplied prompt end-to-end in pi with plan review, implementation review, verification, and one persistent task-plan artifact.

Do Task (Pi)

Execute an ad-hoc user prompt end-to-end: parse, clarify, plan, implement, verify, review, commit, and optionally push.

This variant uses one persistent task-plan.md under ai_plan/ and defaults to the current branch unless the prompt explicitly opts into a worktree workflow.

Shared Setup

Before using this skill, read:

• docs/PI-SUPERPOWERS.md
• docs/PI-COMMON-REVIEWER.md

This workflow depends on:

• Superpowers skills being visible to pi
• the pi reviewer-runtime helper being installed in a supported location

Prerequisite Check (MANDATORY)

Required:

• pi --version
• Superpowers brainstorming
• Superpowers test-driven-development
• Superpowers verification-before-completion
• Superpowers finishing-a-development-branch
• Superpowers using-git-worktrees when the prompt opts into a worktree
• pi reviewer runtime helper
• pi Telegram notifier helper

Quick checks for common installs:

pi --version
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md || test -f ~/.pi/agent/skills/superpowers/test-driven-development/SKILL.md
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md || test -f ~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md
test -x .pi/skills/reviewer-runtime/pi/run-review.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh

If you use a settings-defined skill path for Superpowers, confirm it matches docs/PI-SUPERPOWERS.md before continuing.

If you install the reviewer helper in a nonstandard location, confirm it matches docs/PI-COMMON-REVIEWER.md before continuing.

If any required dependency is missing, stop immediately and return:

Missing dependency: pi do-task requires the workflow skills and reviewer setup documented in docs/PI-SUPERPOWERS.md and docs/PI-COMMON-REVIEWER.md.

Required Workflow Rules

• Load the relevant workflow skill before entering its phase. If pi did not auto-load it, use /skill:<name>.
• Announce skill usage explicitly:
  • I've read the [Skill Name] skill and I'm using it to [purpose].
• Keep the task-plan.md artifact current as work progresses.
• Do not use deprecated wrapper CLIs.

Trigger Detection

Always use this skill for:

• /do-task
• do this task
• do task ...
• execute this task
• make it so
• just do ... when another skill is not a better fit

Use current-branch execution by default. Only switch to a worktree when the prompt explicitly asks for one.

Process

Phase 1: Preflight

1. Verify the repo: git rev-parse --is-inside-work-tree
2. Ensure /ai_plan/ exists in .gitignore
3. Confirm the required workflow skills are available to pi
4. Announce each workflow skill before using it

Phase 2: Parse Prompt And Clarify

1. Capture the user's prompt verbatim
2. Detect whether the prompt is concrete enough to proceed without questions
3. If needed, ask 1-3 short questions one at a time
4. Load brainstorming for behavior-changing work unless the task is pure documentation or pure comment/whitespace/rename work

Phase 3: Configure Reviewer

If the user already specified reviewer settings, use them. Otherwise ask:

Reviewer CLI: codex, claude, cursor, opencode, pi, or skip

1. Which CLI should review the plan and implementation?
2. Reviewer model
3. Max rounds, default 10

Store REVIEWER_CLI, REVIEWER_MODEL, and MAX_ROUNDS.

If REVIEWER_CLI=pi, verify the Pi reviewer binary before entering the review loop:

pi --version

For shorthand pi/<pi-model-name>, split only on the first slash when the prefix is exactly pi; store the complete remainder in REVIEWER_MODEL. Examples: pi/claude-opus-4-7 -> claude-opus-4-7, pi/anthropic/claude-opus-4-7 -> anthropic/claude-opus-4-7, and pi/openrouter/anthropic/claude-opus-4-7 -> openrouter/anthropic/claude-opus-4-7.

When REVIEWER_CLI=pi, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use pi --list-models [search] to inspect configured models.

The pi reviewer command rendered into /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.sh must be isolated and read-only:

pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md and review."

The pi reviewer invocation must not load workflow skills and must not include write, edit, or bash tools.

Phase 4: Initialize task-plan.md

1. Compute ai_plan/YYYY-MM-DD-<slug>/
2. Resume if an existing plan folder is active, otherwise create a new one
3. Write task-plan.md from this skill's templates/task-plan.md
4. Fill Metadata, Prompt, Interpretation, Assumptions, Files, Approach, TDD Approach, Acceptance Criteria, Verification, and Rollback
5. Set Status: draft

If the prompt explicitly opts into a worktree, load using-git-worktrees before implementation. Otherwise remain on the current branch.

Phase 5: Plan Review Loop

Skip this phase if REVIEWER_CLI=skip.

1. Write a reviewer payload from task-plan.md
2. Strip the runtime-only sections before sending it out
3. Run the reviewer through the pi reviewer-runtime helper when available
4. Fix P0, P1, and P2 findings before proceeding
5. Keep P3 findings for optional cleanup
6. Set Status: plan-approved when the reviewer approves

The reviewer response format must be:

## Summary
...

## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...

## Verdict
VERDICT: APPROVED

Phase 6: Execute

1. Set Status: implementation-in-progress
2. Load test-driven-development for every behavior-changing edit unless task-plan.md explicitly records an allowed skip
3. Update task-plan.md as acceptance criteria are completed
4. Do not commit yet

Phase 7: Verification Gate

1. Load verification-before-completion
2. Run the commands listed in task-plan.md
3. Fix failures and re-run verification until green
4. If verification stalls repeatedly, stop and surface the blocker

Phase 8: Implementation Review Loop

Skip this phase if REVIEWER_CLI=skip.

1. Build a review payload from the approved plan, current diff, and verification output
2. Run the reviewer through the pi reviewer-runtime helper
3. Address P0, P1, and P2 findings before approval
4. Fix cheap P3 findings when safe
5. Set Status: implementation-approved when approved

Phase 9: Commit And Push Decision

1. Load finishing-a-development-branch
2. Stage only the intended files
3. Create one commit for the task
4. Ask whether to push or keep the work local

Phase 10: Telegram Completion Notification

Resolve the helper in this order:

TELEGRAM_NOTIFY_RUNTIME=""
for candidate in ".pi/skills/reviewer-runtime/pi/notify-telegram.sh" "$HOME/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh"; do
  if [ -x "$candidate" ]; then
    TELEGRAM_NOTIFY_RUNTIME="$candidate"
    break
  fi
done

If the helper exists and both TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are configured, send a short completion summary. Otherwise state that no Telegram completion notification was sent.