feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability
This commit is contained in:
Stefano Fiorini
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Overview
|
||||
|
||||
This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Locate plan files under `ai_plan/`
|
||||
2. Set up an isolated git worktree
|
||||
3. Execute milestones one-by-one with lint/typecheck/test gates
|
||||
@@ -21,6 +22,7 @@ This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`curso
|
||||
## 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)
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
@@ -96,7 +98,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +135,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -168,6 +170,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -183,6 +186,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -263,6 +267,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.
|
||||
@@ -285,7 +290,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -408,6 +412,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/milestone-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
|
||||
@@ -432,6 +437,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/milestone-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
|
||||
@@ -457,14 +463,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone 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 4 Step 6 (commit & approve)
|
||||
- **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
|
||||
@@ -481,7 +487,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -492,7 +498,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-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):
|
||||
@@ -602,20 +607,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -645,6 +650,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.
|
||||
@@ -666,12 +672,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. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
Reference in New Issue
Block a user