Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

Browse Source
This commit is contained in:
Stefano Fiorini
2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/implement-plan/claude-code/SKILL.md
+16 -10
View File
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
## Prerequisite Check (MANDATORY)
Required:
- Plan folder exists under `ai_plan/` at project root
- `continuation-runbook.md` exists in plan folder
- `milestone-plan.md` exists in plan folder
@@ -63,7 +64,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
@@ -101,6 +101,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`
@@ -135,6 +136,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.
@@ -150,6 +152,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`
@@ -226,6 +229,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.
@@ -248,7 +252,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):
@@ -389,6 +392,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
@@ -414,14 +418,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
@@ -438,7 +442,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]
```
@@ -449,7 +453,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):
@@ -559,20 +562,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>
@@ -598,6 +601,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.
@@ -608,12 +612,14 @@ Rules:
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
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
skills/implement-plan/codex/SKILL.md
+17 -10
View File
@@ -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 Codex:
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 Codex:
## Prerequisite Check (MANDATORY)
Required:
- Plan folder exists under `ai_plan/` at project root
- `continuation-runbook.md` exists in plan folder
- `milestone-plan.md` exists in plan folder
@@ -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`
@@ -259,6 +263,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.
@@ -281,7 +286,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):
@@ -422,6 +426,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
@@ -447,14 +452,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
@@ -471,7 +476,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]
```
@@ -482,7 +487,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):
@@ -592,20 +596,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>
@@ -631,6 +635,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.
@@ -654,12 +659,14 @@ Rules:
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
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
skills/implement-plan/cursor/SKILL.md
+18 -10
View File
@@ -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
skills/implement-plan/opencode/SKILL.md
+148 -10
View File
@@ -12,6 +12,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
This OpenCode variant depends on Superpowers execution skills being installed via OpenCode's native skill system.
Required:
- Plan folder exists under `ai_plan/` at project root
- `continuation-runbook.md` exists in plan folder
- `milestone-plan.md` exists in plan folder
@@ -46,6 +47,7 @@ If no plan folder exists:
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
Use OpenCode's native skill tool:
- list skills
- verify `superpowers/executing-plans`, `superpowers/using-git-worktrees`, `superpowers/verification-before-completion`, and `superpowers/finishing-a-development-branch` are discoverable
@@ -81,7 +83,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
@@ -95,9 +96,11 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
### Phase 4: Set Up Worktree (REQUIRED SUB-SKILL)
Use OpenCode's native skill tool to load:
- `superpowers/using-git-worktrees`
Then:
1. Branch naming: `implement/<plan-folder-name>` (e.g., `implement/2026-03-04-auth-system`).
2. Follow worktree skill's directory priority: `.worktrees/` > `worktrees/` > CLAUDE.md > ask user.
3. Verify `.gitignore` covers worktree directory.
@@ -121,6 +124,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`
@@ -130,6 +134,7 @@ Commit hashes are not available yet — they are backfilled in Step 6 after the
#### Step 4: Verify Milestone (REQUIRED SUB-SKILL)
Use OpenCode's native skill tool to load:
- `superpowers/verification-before-completion`
```bash
@@ -156,6 +161,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.
@@ -171,6 +177,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`
@@ -196,6 +203,9 @@ case "$REVIEWER_CLI" in
cursor)
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.json)
;;
opencode)
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.md)
;;
esac
```
@@ -247,6 +257,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.
@@ -269,7 +280,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):
@@ -391,6 +401,77 @@ 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. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
**If `REVIEWER_CLI` is `opencode`:**
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
Round 1:
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"Read the file /tmp/milestone-${REVIEW_ID}.md and review this milestone implementation.
Evaluate:
1. Correctness — Does the implementation match the milestone spec?
2. Acceptance criteria — Are all criteria met?
3. Code quality — Clean, maintainable, no obvious issues?
4. Test coverage — Are changes adequately tested?
5. Security — Any security concerns introduced?
Return exactly these sections in order:
## Summary
## Findings
### P0
### P1
### P2
### P3
## Verdict
Rules:
- Order findings from highest severity to lowest.
- Use \`- None.\` when a severity has no findings.
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
> /tmp/milestone-review-${REVIEW_ID}.json
```
Round 2 and later (fresh-call, recommended default):
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"You previously reviewed this milestone and requested revisions.
Previous feedback summary: [key points from last review]
I've revised. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
> /tmp/milestone-review-${REVIEW_ID}.json
```
Extract the review body:
```bash
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/milestone-review-${REVIEW_ID}.json \
> /tmp/milestone-review-${REVIEW_ID}.md \
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
```
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
helper-failure escalation in Step 4.
Run the command script through the shared helper when available:
```bash
@@ -410,6 +491,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
@@ -418,6 +500,7 @@ jq -r '.result' /tmp/milestone-review-${REVIEW_ID}.json > /tmp/milestone-review-
```
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/milestone-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/milestone-review-${REVIEW_ID}.md` before verdict parsing.
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/milestone-review-${REVIEW_ID}.runner.out /tmp/milestone-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/milestone-review-${REVIEW_ID}.json 2>/dev/null || true)`
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
```bash
@@ -435,14 +518,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 5 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
@@ -459,7 +542,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]
```
@@ -470,7 +553,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):
@@ -546,6 +628,59 @@ Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no finding
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
**If `REVIEWER_CLI` is `opencode`:**
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"You previously reviewed this milestone and requested revisions.
Previous feedback summary: [key points from last review]
I've addressed your feedback. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
> /tmp/milestone-review-${REVIEW_ID}.json
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/milestone-review-${REVIEW_ID}.json \
> /tmp/milestone-review-${REVIEW_ID}.md \
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
```
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
```bash
opencode run \
-s ${OPENCODE_SESSION_ID} \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"I've addressed your feedback on this milestone. Updated diff and verification output are in /tmp/milestone-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
> /tmp/milestone-review-${REVIEW_ID}.json
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/milestone-review-${REVIEW_ID}.json \
> /tmp/milestone-review-${REVIEW_ID}.md \
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
```
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
Do not run `jq` extraction until after the helper or fallback execution completes, then extract `/tmp/milestone-review-${REVIEW_ID}.md` from the JSON response.
After updating `/tmp/milestone-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
@@ -580,20 +715,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 8: Final Report
Present summary:
```
```markdown
## Implementation Complete
**Plan:** <plan-folder-name>
@@ -619,6 +754,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.
@@ -627,12 +763,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