feat(M3): Shared-source generator for agent variants
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,210 @@
|
||||
---
|
||||
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:
|
||||
|
||||
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.
|
||||
@@ -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 \| pi |
|
||||
| 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.
|
||||
Reference in New Issue
Block a user