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

2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
@@ -12,6 +12,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
 This OpenCode variant depends on Superpowers skills being available through OpenCode's native skill system.

 Required:
+
 - Superpowers repo: `https://github.com/obra/superpowers`
 - OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
 - `superpowers/brainstorming`
@@ -33,13 +34,16 @@ If dependencies are missing, stop immediately and return:
 ### Phase 1: Bootstrap Superpowers Context (REQUIRED)

 Use OpenCode's native skill tool:
+
 - list skills
 - verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable

 ### Phase 2: Analyze
+
 - Explore the codebase and existing patterns.

 ### Phase 3: Gather Requirements
+
 - Ask questions ONE AT A TIME until user says ready.
 - Cover scope, constraints, success criteria, dependencies.
 - Summarize before proceeding.
@@ -77,10 +81,10 @@ 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.

-
 ### Phase 5: Design (REQUIRED SUB-SKILL)

 Use OpenCode's native skill tool to load:
+
 - `superpowers/brainstorming`

 Then present 2-3 approaches and recommend one.
@@ -88,6 +92,7 @@ Then present 2-3 approaches and recommend one.
 ### Phase 6: Plan (REQUIRED SUB-SKILL)

 Use OpenCode's native skill tool to load:
+
 - `superpowers/writing-plans`

 Then break into milestones and bite-sized stories (2-5 min each).
@@ -106,6 +111,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)
@@ -131,6 +137,9 @@ case "$REVIEWER_CLI" in
  cursor)
    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
    ;;
+  opencode)
+    HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
+    ;;
 esac
 ```

@@ -161,6 +170,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.
@@ -183,7 +193,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):
@@ -297,6 +306,75 @@ 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. 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/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
+1. Correctness — Will this plan achieve the stated goals?
+2. Risks — What could go wrong? Edge cases? Data loss?
+3. Missing steps — Is anything forgotten?
+4. Alternatives — Is there a simpler or better approach?
+5. Security — Any security concerns?
+
+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/plan-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 plan and requested revisions.
+
+Previous feedback summary: [key points from last review]
+
+I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
+
+Changes made:
+[List specific changes]
+
+Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
+  > /tmp/plan-review-${REVIEW_ID}.json
+```
+
+Extract the review body:
+
+```bash
+jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  > /tmp/plan-review-${REVIEW_ID}.md \
+  || cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-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
@@ -316,6 +394,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
@@ -324,6 +403,7 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I
 ```

 - If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-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/plan-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/plan-review-${REVIEW_ID}.runner.out /tmp/plan-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/plan-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
@@ -339,14 +419,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 8 (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
@@ -361,7 +441,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]
 ```
@@ -372,7 +452,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):
@@ -450,13 +529,66 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I

 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 plan and requested revisions.
+
+Previous feedback summary: [key points from last review]
+
+I've revised. Updated payload is in /tmp/plan-${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/plan-review-${REVIEW_ID}.json
+
+jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  > /tmp/plan-review-${REVIEW_ID}.md \
+  || cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-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 revised the plan based on your feedback. Updated plan is in /tmp/plan-${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/plan-review-${REVIEW_ID}.json
+
+jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
+  /tmp/plan-review-${REVIEW_ID}.json \
+  > /tmp/plan-review-${REVIEW_ID}.md \
+  || cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
+```
+
+If session resume fails (session expired or not supported), fall back to the fresh-call path above.
+
 After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.

 Return to Step 4.

 #### Step 7: Present Final Result

-```
+```markdown
 ## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})

 **Status:** Approved after N round(s)
@@ -483,16 +615,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
 ### Phase 8: 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 9: Generate Plan Files (MANDATORY)

 Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
+
 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 (template-based).
@@ -523,6 +658,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.
@@ -531,12 +667,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
@@ -575,4 +713,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"
@@ -58,15 +58,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
 ## 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]

 ---
@@ -74,16 +78,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
 ## Key Specifications

 ### Type Definitions
+
 ```typescript
 // Copy-paste ready type definitions
 ```

 ### Enums & Constants
+
 ```typescript
 // All enums/constants needed
 ```

 ### API Endpoints
+
 ```typescript
 // Request/response shapes
 ```
@@ -101,16 +108,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
 ## 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>
 ```
@@ -1,6 +1,7 @@
 # [Plan Title]

 ## Overview
+
 - **Goal:** [One sentence describing the end state]
 - **Created:** YYYY-MM-DD
 - **Status:** In Progress | Complete
@@ -8,37 +9,46 @@
 ## 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.
@@ -48,15 +58,18 @@
 ---

 ### 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.
@@ -68,16 +81,19 @@
 ## Technical Specifications

 ### Types & Interfaces
+
 ```typescript
 // Key type definitions
 ```

 ### API Contracts
+
 ```typescript
 // Endpoint signatures, request/response shapes
 ```

 ### Constants & Enums
+
 ```typescript
 // Shared constants
 ```
@@ -94,6 +110,7 @@
 ## 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)
@@ -1,6 +1,7 @@
 # Story Tracker: [Plan Title]

 ## Progress Summary
+
 - **Current Milestone:** M1
 - **Stories Complete:** 0/N
 - **Milestones Approved:** 0/M
@@ -46,15 +47,18 @@
 ## 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
@@ -63,4 +67,5 @@ At milestone boundary:
 6. Continue only after approval

 After all milestones approved:
+
 - Ask permission to push and then mark plan completed.