feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability
This commit is contained in:
Stefano Fiorini
@@ -10,6 +10,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
## Overview
|
||||
|
||||
This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Design first with `superpowers:brainstorming`
|
||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
||||
3. Review the plan iteratively with a second model/provider
|
||||
@@ -20,6 +21,7 @@ This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
@@ -51,9 +53,11 @@ If any dependency is missing, stop and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until user says ready.
|
||||
- Confirm scope, constraints, success criteria, dependencies.
|
||||
|
||||
@@ -71,7 +75,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -113,6 +116,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -172,6 +176,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -194,7 +199,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -309,6 +313,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
||||
|
||||
Notes on Cursor flags:
|
||||
|
||||
- `--mode=ask` — read-only mode, no file modifications
|
||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
||||
@@ -333,6 +338,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -356,14 +362,14 @@ cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -378,7 +384,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -389,7 +395,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -473,7 +478,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -500,16 +505,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (from template).
|
||||
@@ -546,6 +554,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -569,12 +578,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -634,4 +645,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
Reference in New Issue
Block a user