ai-coding-skills/skills/do-task/pi/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. 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 settings-defined paths instead of the common locations above, confirm they match docs/PI-SUPERPOWERS.md before continuing.

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

Missing dependency: pi do-task requires the workflow skills and pi reviewer-runtime setup documented in docs/PI-SUPERPOWERS.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:

1. Reviewer CLI: codex, claude, cursor, opencode, or skip
2. Reviewer model
3. Max rounds, default 10

Store REVIEWER_CLI, REVIEWER_MODEL, and MAX_ROUNDS.

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.