feat(pi): implement milestone M3 - workflow skills
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,206 @@
|
||||
---
|
||||
name: create-plan
|
||||
description: Use when a user asks to create or maintain a structured implementation plan in pi, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.
|
||||
---
|
||||
|
||||
# Create Plan (Pi)
|
||||
|
||||
Create and maintain a local plan workspace under `ai_plan/` at project root.
|
||||
|
||||
## Shared Setup
|
||||
|
||||
Before using this skill, read [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md). The workflow depends on:
|
||||
|
||||
- Obra 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 `writing-plans`
|
||||
- pi reviewer runtime helper:
|
||||
- `.pi/skills/reviewer-runtime/pi/run-review.sh`, or
|
||||
- `~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh`
|
||||
|
||||
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/writing-plans/SKILL.md || test -f ~/.pi/agent/skills/superpowers/writing-plans/SKILL.md
|
||||
test -x .pi/skills/reviewer-runtime/pi/run-review.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
|
||||
```
|
||||
|
||||
If you use a settings-defined skill path instead of the common locations above, verify it matches [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md) before continuing.
|
||||
|
||||
If any dependency is missing, stop and return:
|
||||
|
||||
`Missing dependency: pi planning requires Superpowers brainstorming/writing-plans skills plus the pi reviewer runtime 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:brainstorming` or `/skill:writing-plans`.
|
||||
- Announce skill usage explicitly:
|
||||
- `I've read the [Skill Name] skill and I'm using it to [purpose].`
|
||||
- Track checklist-style progress inside the plan artifacts that this skill generates.
|
||||
- Do not use deprecated wrapper CLIs.
|
||||
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
- Review any current docs, scripts, or variant layouts that affect the plan.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until the scope is clear.
|
||||
- Confirm constraints, success criteria, dependencies, and what is out of scope.
|
||||
|
||||
### Phase 3: Configure Reviewer
|
||||
|
||||
If the user already specified a reviewer CLI and model, use those values. Otherwise ask:
|
||||
|
||||
1. Which CLI should review the plan?
|
||||
- `codex`
|
||||
- `claude`
|
||||
- `cursor`
|
||||
- `opencode`
|
||||
- `skip`
|
||||
2. Which model?
|
||||
3. Max review rounds? Default: `10`
|
||||
|
||||
Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for the review loop.
|
||||
|
||||
### Phase 4: Design
|
||||
|
||||
- Load `brainstorming`.
|
||||
- Present 2-3 approaches and recommend one.
|
||||
- Resolve open design questions before the milestone breakdown.
|
||||
|
||||
### Phase 5: Plan
|
||||
|
||||
- Load `writing-plans`.
|
||||
- Break the work into milestones and bite-sized stories.
|
||||
- Story IDs should use the `S-101`, `S-102` style.
|
||||
|
||||
### Phase 6: Iterative Plan Review
|
||||
|
||||
Skip this phase if `REVIEWER_CLI=skip`.
|
||||
|
||||
#### Step 1: Generate Session ID
|
||||
|
||||
```bash
|
||||
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use these temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.sh`
|
||||
|
||||
Resolve the pi reviewer runtime helper in this order:
|
||||
|
||||
```bash
|
||||
REVIEWER_RUNTIME=""
|
||||
for candidate in ".pi/skills/reviewer-runtime/pi/run-review.sh" "$HOME/.pi/agent/skills/reviewer-runtime/pi/run-review.sh"; do
|
||||
if [ -x "$candidate" ]; then
|
||||
REVIEWER_RUNTIME="$candidate"
|
||||
break
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### Step 2: Write The Plan Payload
|
||||
|
||||
Write the full plan to `/tmp/plan-${REVIEW_ID}.md`.
|
||||
|
||||
Reviewer responses must use this structure:
|
||||
|
||||
```text
|
||||
## Summary
|
||||
...
|
||||
|
||||
## Findings
|
||||
### P0
|
||||
- ...
|
||||
### P1
|
||||
- ...
|
||||
### P2
|
||||
- ...
|
||||
### P3
|
||||
- ...
|
||||
|
||||
## Verdict
|
||||
VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`
|
||||
- Use `- None.` when a severity has no findings
|
||||
- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain
|
||||
|
||||
#### Step 3: Submit To Reviewer
|
||||
|
||||
Build a bash command script in `/tmp/plan-review-${REVIEW_ID}.sh` and execute it through the shared helper when present:
|
||||
|
||||
```bash
|
||||
"$REVIEWER_RUNTIME" \
|
||||
--command-file /tmp/plan-review-${REVIEW_ID}.sh \
|
||||
--stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
|
||||
--stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
|
||||
--status-file /tmp/plan-review-${REVIEW_ID}.status
|
||||
```
|
||||
|
||||
Fallback to direct execution only if the helper is missing.
|
||||
|
||||
#### Step 4: Wait And Parse Verdict
|
||||
|
||||
- Keep waiting while fresh `state=in-progress note="In progress N"` heartbeats continue to appear.
|
||||
- Treat `P0`, `P1`, or `P2` as must-fix findings.
|
||||
- `P3` findings are non-blocking, but fix them when cheap and safe.
|
||||
|
||||
#### Step 5: Revise And Re-Submit
|
||||
|
||||
- Address findings in priority order.
|
||||
- Rebuild the plan payload.
|
||||
- Re-submit until approved or `MAX_ROUNDS` is reached.
|
||||
|
||||
### Phase 7: Generate Plan Files
|
||||
|
||||
Once the plan is approved:
|
||||
|
||||
1. Ensure `/ai_plan/` exists in `.gitignore`
|
||||
2. Create `ai_plan/YYYY-MM-DD-<slug>/`
|
||||
3. Write:
|
||||
- `original-plan.md`
|
||||
- `final-transcript.md`
|
||||
- `milestone-plan.md`
|
||||
- `story-tracker.md`
|
||||
- `continuation-runbook.md`
|
||||
4. Use the template files from this skill's `templates/` directory
|
||||
|
||||
### Phase 8: Telegram Completion Notification
|
||||
|
||||
Resolve the notification 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. If not, state that no Telegram completion notification was sent.
|
||||
Reference in New Issue
Block a user