feat(M3): Shared-source generator for agent variants
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,234 @@
|
||||
---
|
||||
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)
|
||||
- [docs/PI-COMMON-REVIEWER.md](../../../docs/PI-COMMON-REVIEWER.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 for Superpowers, verify it matches [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md) before continuing.
|
||||
|
||||
If you install the reviewer helper in a nonstandard location, verify it matches [docs/PI-COMMON-REVIEWER.md](../../../docs/PI-COMMON-REVIEWER.md) before continuing.
|
||||
|
||||
If any dependency is missing, stop and return:
|
||||
|
||||
`Missing dependency: pi planning requires Superpowers brainstorming/writing-plans skills plus the 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: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:
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`
|
||||
|
||||
1. Which CLI should review the plan?
|
||||
- `codex`
|
||||
- `claude`
|
||||
- `cursor`
|
||||
- `opencode`
|
||||
- `pi`
|
||||
- `skip`
|
||||
2. Which model?
|
||||
3. Max review rounds? Default: `10`
|
||||
|
||||
Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for the review loop.
|
||||
|
||||
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/plan-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/plan-${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: 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.
|
||||
@@ -0,0 +1,145 @@
|
||||
# Continuation Runbook: [Plan Title]
|
||||
|
||||
## Reference Files (START HERE)
|
||||
|
||||
Upon resumption, these files in this folder are the ONLY source of truth:
|
||||
|
||||
| File | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST |
|
||||
| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story |
|
||||
| `milestone-plan.md` | Complete plan with specifications | Reference implementation details |
|
||||
| `original-plan.md` | Original approved plan | Reference original intent |
|
||||
| `final-transcript.md` | Final planning transcript | Reference reasoning/context |
|
||||
|
||||
Do NOT reference planner-private files during implementation.
|
||||
|
||||
## Skill Workflow Guardrails
|
||||
|
||||
- Load relevant skills before action. If pi did not auto-load them, use `/skill:<name>`.
|
||||
- Announce which skill is being used and why.
|
||||
- If a checklist-driven workflow applies, keep its state current in the plan artifacts.
|
||||
- Do not use deprecated wrapper CLIs.
|
||||
|
||||
---
|
||||
|
||||
## Quick Resume Instructions
|
||||
|
||||
1. Read this runbook completely.
|
||||
2. Check `story-tracker.md`.
|
||||
3. Find next `pending` story and mark as `in-dev` before starting.
|
||||
4. Implement the story.
|
||||
5. Update tracker immediately after each change.
|
||||
|
||||
---
|
||||
|
||||
## Mandatory Execution Workflow
|
||||
|
||||
Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
|
||||
|
||||
1. Read `continuation-runbook.md` first.
|
||||
2. Execute stories milestone by milestone.
|
||||
3. After completing a milestone:
|
||||
- Run lint/typecheck/tests, prioritizing changed files for speed.
|
||||
- Commit locally (**DO NOT PUSH**).
|
||||
- Stop and ask user for feedback.
|
||||
4. If feedback is provided:
|
||||
- Apply feedback changes.
|
||||
- Re-run checks for changed files.
|
||||
- Commit locally again.
|
||||
- Ask for milestone approval.
|
||||
5. Only move to next milestone after explicit approval.
|
||||
6. After all milestones are completed and approved:
|
||||
- Ask permission to push.
|
||||
- If approved, push.
|
||||
- Mark plan status as `completed`.
|
||||
|
||||
---
|
||||
|
||||
## Git Note
|
||||
|
||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
|
||||
|
||||
---
|
||||
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Design Decisions
|
||||
|
||||
| Decision | Chosen Approach | Alternatives Rejected | Rationale |
|
||||
|----------|-----------------|----------------------|-----------|
|
||||
| [Topic] | [What we chose] | [Other options] | [Why] |
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Quick Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `original-plan.md` | Original approved plan |
|
||||
| `final-transcript.md` | Final planning transcript |
|
||||
| `milestone-plan.md` | Full specification |
|
||||
| `story-tracker.md` | Current progress tracker |
|
||||
| `continuation-runbook.md` | This runbook |
|
||||
@@ -0,0 +1,118 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
- Apply feedback, re-check changed files, commit again.
|
||||
- Move to next milestone only after user approval.
|
||||
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
- Apply feedback, re-check changed files, commit again.
|
||||
- Move to next milestone only after user approval.
|
||||
|
||||
---
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
|
||||
## Files Inventory
|
||||
|
||||
| File | Purpose | Milestone |
|
||||
|------|---------|-----------|
|
||||
| `path/to/file.ts` | [What it does] | M1 |
|
||||
| `path/to/other.ts` | [What it does] | M2 |
|
||||
|
||||
---
|
||||
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
- `story-tracker.md` - Status tracking (must be kept up to date)
|
||||
- `continuation-runbook.md` - Resume/execution context (read first)
|
||||
@@ -0,0 +1,71 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
- **Last Updated:** YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
| Story | Description | Status | Notes |
|
||||
|-------|-------------|--------|-------|
|
||||
| S-101 | [Brief description] | pending | |
|
||||
| S-102 | [Brief description] | pending | |
|
||||
| S-103 | [Brief description] | pending | |
|
||||
|
||||
**Approval Status:** pending
|
||||
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
| Story | Description | Status | Notes |
|
||||
|-------|-------------|--------|-------|
|
||||
| S-201 | [Brief description] | pending | |
|
||||
| S-202 | [Brief description] | pending | |
|
||||
| S-203 | [Brief description] | pending | |
|
||||
|
||||
**Approval Status:** pending
|
||||
|
||||
---
|
||||
|
||||
## Status Legend
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `pending` | Not started |
|
||||
| `in-dev` | Currently being worked on |
|
||||
| `completed` | Done - include commit hash in Notes |
|
||||
| `deferred` | Postponed - include reason in Notes |
|
||||
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
4. Apply feedback, re-check changed files, commit again
|
||||
5. Mark milestone **Approval Status: approved** only after user confirms
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
Reference in New Issue
Block a user