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

skills/implement-plan/codex/SKILL.md

@@ -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