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

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

<!-- ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/do-task/_source/pi/ and run `pnpm run sync:pi`. -->

# 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-SUPERPOWERS.md)
- [docs/PI-COMMON-REVIEWER.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:

```bash
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](../../../docs/PI-SUPERPOWERS.md) before continuing.

If you install the reviewer helper in a nonstandard location, confirm it matches [docs/PI-COMMON-REVIEWER.md](../../../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:

```bash
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:

```bash
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:

```text
## 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:

```bash
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.