Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(pi): package warning-free skill mirror and docs

Browse Source
This commit is contained in:
Stefano Fiorini
2026-04-23 17:32:26 -05:00
parent 0456c51291
commit 3429dac894
51 changed files with 6703 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pi-package/skills/do-task/SKILL.md
+190
View File
@@ -0,0 +1,190 @@
---
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.
---
# 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:
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:
```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.
pi-package/skills/do-task/templates/task-plan.md
+128
View File
@@ -0,0 +1,128 @@
# Task Plan: [Short Title]
> **Variant guardrail (pi):** Required workflow skills (`brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch`, `using-git-worktrees`) must be available to pi as documented in `docs/PI-SUPERPOWERS.md`. Load the relevant workflow skill before entering its matching phase.
## Metadata
| Field | Value |
|-------|-------|
| Created | YYYY-MM-DD |
| Slug | YYYY-MM-DD-<slug> |
| Runtime | pi |
| Reviewer CLI | codex \| claude \| cursor \| opencode |
| Reviewer Model | <model> |
| MAX_ROUNDS | 10 |
| Branch Strategy | current-branch \| worktree |
| Branch Name | <current branch name, or new branch name when worktree is used> |
| Worktree Path | <absolute path to worktree dir; blank when Branch Strategy = current-branch> |
| Status | draft |
### Status Enum (authoritative)
| Value | Meaning |
|-------|---------|
| `draft` | Newly created; plan review not yet started |
| `plan-approved` | Plan review loop returned APPROVED |
| `implementation-in-progress` | Phase 6 executing |
| `implementation-approved` | Phase 8 review loop returned APPROVED; awaiting commit |
| `pushed` | Committed + pushed to remote |
| `local-only` | Committed locally; user declined push |
| `aborted-plan-review` | MAX_ROUNDS reached in Phase 5; user aborted |
| `aborted-impl-review` | MAX_ROUNDS reached in Phase 8; user aborted |
| `aborted-verification` | Phase 7 retries exhausted; user aborted |
| `failed` | Hard tooling failure |
---
## Prompt
<!-- Exact user prompt, verbatim. -->
## Interpretation
<!-- Short restatement of goal + out-of-scope items. -->
## Assumptions
<!-- Anything we're assuming and needs confirmation. Empty list OK after clarifying questions. -->
## Files
<!-- Files expected to be created / modified / deleted. Paths are absolute or repo-relative. -->
| Action | Path | Why |
|--------|------|-----|
| | | |
## Approach
<!-- 3-10 bullets describing implementation order. -->
## TDD Approach
<!-- One of:
(a) **TDD applies** — list the failing test(s) to write first, then implementation, then confirm green.
(b) **TDD auto-skipped** — reason must be exactly one of:
- `pure-documentation`
- `pure-comment-whitespace-rename`
(c) **TDD user-approved skip** — user explicitly approved skipping TDD for this task.
Record the approval timestamp (ISO-8601) and the specific reason.
-->
## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>
## Verification
<!-- Commands to run:
lint: <cmd>
typecheck: <cmd>
tests: <cmd>
-->
## Rollback
<!-- How to undo: `git revert <hash>`, or manual steps if the change is not easily reversible. -->
---
## Runtime State
```yaml
plan_review_round: 0
implementation_review_round: 0
CODEX_PLAN_SESSION_ID:
CODEX_IMPL_SESSION_ID:
CURSOR_PLAN_SESSION_ID:
CURSOR_IMPL_SESSION_ID:
OPENCODE_PLAN_SESSION_ID:
OPENCODE_IMPL_SESSION_ID:
last_phase_entered:
last_round_ts:
last_scan_outcome_plan:
last_scan_outcome_impl:
verification_attempts: 0
tests_added_count: 0
tdd_used: false
```
## Review History
| Timestamp (ISO-8601) | Loop | Round | Verdict | Summary |
|----------------------|------|-------|---------|---------|
| | | | | |
## Final Status
<!-- Populate the terminal status, commit hash if any, rounds used, TDD usage, tests added, verification attempts, and any revisit notes. -->
---
## Guardrails (do NOT remove)
- This file is the single persistent artifact for `do-task`. Do not split it or delete it on success.
- `Status` must always match one of the enum values.
- `Runtime State` is updated by the skill, not by the user.
- Review History is append-only.