diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 27718933..775ac417 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -1094,7 +1094,7 @@ After completing the review, read the review log and config to display the dashb ~/.claude/skills/gstack/bin/gstack-review-read \`\`\` -Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite, adversarial-review, codex-review). Ignore entries with timestamps older than 7 days. For the Adversarial row, show whichever is more recent between \`adversarial-review\` (new auto-scaled) and \`codex-review\` (legacy). For Design Review, show whichever is more recent between \`plan-design-review\` (full visual audit) and \`design-review-lite\` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display: +Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Adversarial row, show whichever is more recent between \`adversarial-review\` (new auto-scaled) and \`codex-review\` (legacy). For Design Review, show whichever is more recent between \`plan-design-review\` (full visual audit) and \`design-review-lite\` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display: \`\`\` +====================================================================+ @@ -1106,6 +1106,7 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl | CEO Review | 0 | — | — | no | | Design Review | 0 | — | — | no | | Adversarial | 0 | — | — | no | +| Outside Voice | 0 | — | — | no | +--------------------------------------------------------------------+ | VERDICT: CLEARED — Eng Review passed | +====================================================================+ @@ -1116,6 +1117,7 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl - **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup. - **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes. - **Adversarial Review (automatic):** Auto-scales by diff size. Small diffs (<50 lines) skip adversarial. Medium diffs (50–199) get cross-model adversarial. Large diffs (200+) get all 4 passes: Claude structured, Codex structured, Claude adversarial subagent, Codex adversarial. No configuration needed. +- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping. **Verdict logic:** - **CLEARED**: Eng Review has >= 1 entry within 7 days with status "clean" (or \\\`skip_eng_review\\\` is \\\`true\\\`) @@ -1648,6 +1650,130 @@ High-confidence findings (agreed on by multiple sources) should be prioritized f ---`; } +function generateCodexPlanReview(ctx: TemplateContext): string { + // Codex host: strip entirely — Codex should never invoke itself + if (ctx.host === 'codex') return ''; + + return `## Outside Voice — Independent Plan Challenge (optional, recommended) + +After all review sections are complete, offer an independent second opinion from a +different AI system. Two models agreeing on a plan is stronger signal than one model's +thorough review. + +**Check tool availability:** + +\`\`\`bash +which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE" +\`\`\` + +Use AskUserQuestion: + +> "All review sections are complete. Want an outside voice? A different AI system can +> give a brutally honest, independent challenge of this plan — logical gaps, feasibility +> risks, and blind spots that are hard to catch from inside the review. Takes about 2 +> minutes." +> +> RECOMMENDATION: Choose A — an independent second opinion catches structural blind +> spots. Two different AI models agreeing on a plan is stronger signal than one model's +> thorough review. Completeness: A=9/10, B=7/10. + +Options: +- A) Get the outside voice (recommended) +- B) Skip — proceed to outputs + +**If B:** Print "Skipping outside voice." and continue to the next section. + +**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file +the user pointed this review at, or the branch diff scope). If a CEO plan document +was written in Step 0D-POST, read that too — it contains the scope decisions and vision. + +Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB, +truncate to the first 30KB and note "Plan truncated for size"): + +"You are a brutally honest technical reviewer examining a development plan that has +already been through a multi-section review. Your job is NOT to repeat that review. +Instead, find what it missed. Look for: logical gaps and unstated assumptions that +survived the review scrutiny, overcomplexity (is there a fundamentally simpler +approach the review was too deep in the weeds to see?), feasibility risks the review +took for granted, missing dependencies or sequencing issues, and strategic +miscalibration (is this the right thing to build at all?). Be direct. Be terse. No +compliments. Just the problems. + +THE PLAN: +" + +**If CODEX_AVAILABLE:** + +\`\`\`bash +TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX) +codex exec "" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR_PV" +\`\`\` + +Use a 5-minute timeout (\`timeout: 300000\`). After the command completes, read stderr: +\`\`\`bash +cat "$TMPERR_PV" +\`\`\` + +Present the full output verbatim: + +\`\`\` +CODEX SAYS (plan review — outside voice): +════════════════════════════════════════════════════════════ + +════════════════════════════════════════════════════════════ +\`\`\` + +**Error handling:** All errors are non-blocking — the outside voice is informational. +- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \\\`codex login\\\` to authenticate." +- Timeout: "Codex timed out after 5 minutes." +- Empty response: "Codex returned no response." + +On any Codex error, fall back to the Claude adversarial subagent. + +**If CODEX_NOT_AVAILABLE (or Codex errored):** + +Dispatch via the Agent tool. The subagent has fresh context — genuine independence. + +Subagent prompt: same plan review prompt as above. + +Present findings under an \`OUTSIDE VOICE (Claude subagent):\` header. + +If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs." + +**Cross-model tension:** + +After presenting the outside voice findings, note any points where the outside voice +disagrees with the review findings from earlier sections. Flag these as: + +\`\`\` +CROSS-MODEL TENSION: + [Topic]: Review said X. Outside voice says Y. [Your assessment of who's right.] +\`\`\` + +For each substantive tension point, auto-propose as a TODO via AskUserQuestion: + +> "Cross-model disagreement on [topic]. The review found [X] but the outside voice +> argues [Y]. Worth investigating further?" + +Options: +- A) Add to TODOS.md +- B) Skip — not substantive + +If no tension points exist, note: "No cross-model tension — both reviewers agree." + +**Persist the result:** +\`\`\`bash +~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}' +\`\`\` + +Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist. +SOURCE = "codex" if Codex ran, "claude" if subagent ran. + +**Cleanup:** Run \`rm -f "$TMPERR_PV"\` after processing (if Codex was used). + +---`; +} + function generateDeployBootstrap(_ctx: TemplateContext): string { return `\`\`\`bash # Check for persisted deploy config in CLAUDE.md @@ -1702,6 +1828,7 @@ const RESOLVERS: Record string> = { CODEX_REVIEW_STEP: generateAdversarialStep, ADVERSARIAL_STEP: generateAdversarialStep, DEPLOY_BOOTSTRAP: generateDeployBootstrap, + CODEX_PLAN_REVIEW: generateCodexPlanReview, }; // ─── Codex Helpers ───────────────────────────────────────────