mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-21 20:30:47 +02:00
feat: componentize GStack 2 runtime and release integrity
This commit is contained in:
Sinabina
@@ -18,14 +18,14 @@ If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This
|
||||
Write to `"${GSTACK_HOME:-$HOME/.gstack}"/projects/<stable-project-id>/{user}-{branch}-design-{datetime}.md`.
|
||||
|
||||
After writing the design doc, tell the user:
|
||||
**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
|
||||
**"Design doc saved to: {full path}. Other skills ($plan --mode Product --module plan-ceo-review, $plan --mode Engineering --module plan-eng-review) will find it automatically."**
|
||||
|
||||
### Startup mode design doc template:
|
||||
|
||||
```markdown
|
||||
# Design: {title}
|
||||
|
||||
Generated by /office-hours on {date}
|
||||
Generated by $plan --mode Discovery --module office-hours on {date}
|
||||
Branch: {branch}
|
||||
Repo: {owner/repo}
|
||||
Status: DRAFT
|
||||
@@ -88,7 +88,7 @@ Supersedes: {prior filename — omit this line if first design on this branch}
|
||||
```markdown
|
||||
# Design: {title}
|
||||
|
||||
Generated by /office-hours on {date}
|
||||
Generated by $plan --mode Discovery --module office-hours on {date}
|
||||
Branch: {branch}
|
||||
Repo: {owner/repo}
|
||||
Status: DRAFT
|
||||
@@ -193,12 +193,7 @@ After the loop completes (PASS, max iterations, or convergence guard):
|
||||
2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns"
|
||||
section to the document listing each unresolved issue. Downstream skills will see this.
|
||||
|
||||
3. Append metrics:
|
||||
```bash
|
||||
mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/analytics
|
||||
echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> "${GSTACK_HOME:-$HOME/.gstack}"/analytics/spec-review.jsonl 2>/dev/null || true
|
||||
```
|
||||
Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review.
|
||||
3. Report the iteration counts and quality score in the user-facing result; do not persist engagement analytics.
|
||||
|
||||
---
|
||||
|
||||
@@ -509,10 +504,7 @@ $GSTACK_BIN/gstack-developer-profile --log-session '{"date":"'"$(date -u +%Y-%m-
|
||||
```
|
||||
|
||||
2. Log the selection to analytics:
|
||||
```bash
|
||||
mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/analytics
|
||||
echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> "${GSTACK_HOME:-$HOME/.gstack}"/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
```
|
||||
Canonical execution does not write engagement analytics or telemetry.
|
||||
|
||||
3. Use AskUserQuestion to offer opening the resources:
|
||||
|
||||
@@ -533,14 +525,14 @@ If E: proceed to next-skill recommendations.
|
||||
|
||||
Don't just list options. Offer to launch the next review NOW so the design doc flows
|
||||
straight into a structured review. Map the design-doc mode to the recommended option
|
||||
(default `/plan-eng-review` when ambiguous — it has the broadest real-world use and the
|
||||
(default `$plan --mode Engineering --module plan-eng-review` when ambiguous — it has the broadest real-world use and the
|
||||
strongest retention).
|
||||
|
||||
**If `PROACTIVE` is `false` OR `CONDUCTOR_SESSION: true`:** do NOT auto-launch. Recommend
|
||||
in one line and stop, letting the user invoke:
|
||||
- EXPANSION / ambitious → "Next: `/plan-ceo-review` to pressure-test scope and find the 10-star product."
|
||||
- well-scoped → "Next: `/plan-eng-review` to lock architecture, tests, and edge cases."
|
||||
- visual/UX-heavy → "Next: `/plan-design-review` for a visual/UX pass."
|
||||
- EXPANSION / ambitious → "Next: `$plan --mode Product --module plan-ceo-review` to pressure-test scope and find the 10-star product."
|
||||
- well-scoped → "Next: `$plan --mode Engineering --module plan-eng-review` to lock architecture, tests, and edge cases."
|
||||
- visual/UX-heavy → "Next: `$design --mode Critique --module plan-design-review` for a visual/UX pass."
|
||||
|
||||
**Otherwise**, offer via AskUserQuestion (D<N> format from the preamble):
|
||||
|
||||
@@ -550,17 +542,17 @@ ELI10: You just wrote a design doc. The natural next step is a structured review
|
||||
catches scope and architecture problems before you build. I can launch it right now, or
|
||||
you can run it later yourself.
|
||||
Stakes if we pick wrong: skipping review means problems surface mid-build, costing rework.
|
||||
Recommendation: the mode-mapped option (`/plan-eng-review` if unsure) because it locks the
|
||||
Recommendation: the mode-mapped option (`$plan --mode Engineering --module plan-eng-review` if unsure) because it locks the
|
||||
plan before any code is written.
|
||||
Completeness: A=10/10, B=9/10, C=8/10, D=3/10
|
||||
Pros / cons:
|
||||
A) Run /plan-eng-review now (recommended)
|
||||
A) Run $plan --mode Engineering --module plan-eng-review now (recommended)
|
||||
✅ Locks architecture, tests, and edge cases before a line of code is written
|
||||
❌ Adds ~15 min CC now (human: 1-2 hrs of review compressed)
|
||||
B) Run /plan-ceo-review now
|
||||
B) Run $plan --mode Product --module plan-ceo-review now
|
||||
✅ Pressure-tests ambition and scope — finds the 10-star version of the product
|
||||
❌ Lower value when the scope is already tight and well understood
|
||||
C) Run /plan-design-review now
|
||||
C) Run $design --mode Critique --module plan-design-review now
|
||||
✅ Catches visual/UX problems while they are still cheap plan-stage changes
|
||||
❌ Little value for backend-only or non-visual features
|
||||
D) Not now — I'll run a review later
|
||||
@@ -571,11 +563,9 @@ Net: 15 minutes of structured review now against rework risk later.
|
||||
On the user's SELECTION of A/B/C (not on invocation success), log the handoff, then invoke
|
||||
the chosen skill via the **Skill tool** (it auto-discovers the design doc):
|
||||
```bash
|
||||
$GSTACK_BIN/gstack-telemetry-log --event-type handoff --skill office-hours --outcome accepted --session-id "$_SESSION_ID" 2>/dev/null || true
|
||||
```
|
||||
On D, log declined and stop:
|
||||
```bash
|
||||
$GSTACK_BIN/gstack-telemetry-log --event-type handoff --skill office-hours --outcome declined --session-id "$_SESSION_ID" 2>/dev/null || true
|
||||
```
|
||||
|
||||
The design doc at `"${GSTACK_HOME:-$HOME/.gstack}"/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
|
||||
|
||||
@@ -229,7 +229,7 @@ Evaluate:
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 11: Design & UX Review (skip if no UI scope detected)
|
||||
The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
|
||||
The CEO calling in the designer. Not a pixel-level audit — that's $design --mode Critique --module plan-design-review and $design --mode Implement --module design-review. This is ensuring the plan has design intentionality.
|
||||
|
||||
Evaluate:
|
||||
* Information architecture — what does the user see first, second, third?
|
||||
@@ -247,7 +247,7 @@ Evaluate:
|
||||
|
||||
Required ASCII diagram: user flow showing screens/states and transitions.
|
||||
|
||||
If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
|
||||
If this plan has significant UI scope, recommend: "Consider running $design --mode Critique --module plan-design-review for a deep design review of this plan before implementation."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
@@ -262,7 +262,7 @@ agree with the outside voice. Cross-model consensus is a strong signal — prese
|
||||
such — but the user makes the decision.
|
||||
|
||||
## Post-Implementation Design Audit (if UI scope detected)
|
||||
After implementation, run `/design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
|
||||
After implementation, run `$design --mode Implement --module design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
|
||||
|
||||
## CRITICAL RULE — How to ask questions
|
||||
Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
|
||||
@@ -331,7 +331,7 @@ List every ASCII diagram in files this plan touches. Still accurate?
|
||||
|
||||
Before closing this review, synthesize the findings above into a flat list of
|
||||
build-actionable tasks. Each task derives from a specific finding — no padding.
|
||||
Emit the markdown section AND write a JSONL artifact that `/autoplan` can
|
||||
Emit the markdown section AND write a JSONL artifact that `$plan --mode Full chain --module autoplan` can
|
||||
aggregate across phases.
|
||||
|
||||
### Markdown section (always emit)
|
||||
@@ -356,7 +356,7 @@ Rules:
|
||||
|
||||
### JSONL artifact (always write, even if zero tasks)
|
||||
|
||||
`/autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`$plan --mode Full chain --module autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`jq -nc` so titles and source findings containing quotes, newlines, or
|
||||
backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
|
||||
|
||||
@@ -485,9 +485,9 @@ After completing the review, read the review log and config to display the dashb
|
||||
$GSTACK_BIN/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module plan-eng-review.
|
||||
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via $plan --mode Full chain --module autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
|
||||
Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
|
||||
|
||||
@@ -514,7 +514,7 @@ Display:
|
||||
- **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):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. 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.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module 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 from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
@@ -570,7 +570,7 @@ Produce this markdown table:
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`$review --mode Deep --module codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
@@ -628,15 +628,15 @@ there — the user then sees a plan whose review report is not at the bottom and
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
|
||||
**Recommend $plan --mode Engineering --module plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
|
||||
|
||||
**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
|
||||
**Recommend $design --mode Critique --module plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate), then design review.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-design-review next (only if UI scope detected)
|
||||
- **A)** Run $plan --mode Engineering --module plan-eng-review next (required gate)
|
||||
- **B)** Run $design --mode Critique --module plan-design-review next (only if UI scope detected)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
|
||||
## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
|
||||
|
||||
@@ -130,7 +130,7 @@ If visual mockups were generated in Step 0.5, evaluate them against the AI slop
|
||||
|
||||
### Pass 5: Design System Alignment
|
||||
Rate 0-10: Does the plan align with DESIGN.md?
|
||||
FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
|
||||
FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `$design --mode Generate --module design-consultation`.
|
||||
Flag any new component — does it fit the existing vocabulary?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
@@ -194,7 +194,7 @@ Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough
|
||||
|
||||
Before closing this review, synthesize the findings above into a flat list of
|
||||
build-actionable tasks. Each task derives from a specific finding — no padding.
|
||||
Emit the markdown section AND write a JSONL artifact that `/autoplan` can
|
||||
Emit the markdown section AND write a JSONL artifact that `$plan --mode Full chain --module autoplan` can
|
||||
aggregate across phases.
|
||||
|
||||
### Markdown section (always emit)
|
||||
@@ -219,7 +219,7 @@ Rules:
|
||||
|
||||
### JSONL artifact (always write, even if zero tasks)
|
||||
|
||||
`/autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`$plan --mode Full chain --module autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`jq -nc` so titles and source findings containing quotes, newlines, or
|
||||
backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
|
||||
|
||||
@@ -287,7 +287,7 @@ this run (an empty file means "ran, no findings" — distinct from "didn't run")
|
||||
+====================================================================+
|
||||
```
|
||||
|
||||
If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
|
||||
If all passes 8+: "Plan is design-complete. Run $design --mode Implement --module design-review after implementation for visual QA."
|
||||
If any below 8: note what's unresolved and why (user chose to defer).
|
||||
|
||||
### Unresolved Decisions
|
||||
@@ -338,9 +338,9 @@ After completing the review, read the review log and config to display the dashb
|
||||
$GSTACK_BIN/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module plan-eng-review.
|
||||
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via $plan --mode Full chain --module autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
|
||||
Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
|
||||
|
||||
@@ -367,7 +367,7 @@ Display:
|
||||
- **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):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. 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.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module 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 from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
@@ -423,7 +423,7 @@ Produce this markdown table:
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`$review --mode Deep --module codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
@@ -559,23 +559,23 @@ eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
|
||||
**Recommend $plan --mode Engineering --module plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
|
||||
|
||||
**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
|
||||
**Consider recommending $plan --mode Product --module plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate).
|
||||
|
||||
**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
|
||||
**Recommend design exploration skills when appropriate** — $design --mode Explore --module design-shotgun and $design --mode Implement --module design-html
|
||||
produce design artifacts (mockups, HTML previews), not application code. They belong in
|
||||
plan mode alongside reviews. If this design review found visual issues that would benefit
|
||||
from exploring new directions, recommend /design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend /design-html.
|
||||
from exploring new directions, recommend $design --mode Explore --module design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend $design --mode Implement --module design-html.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Run /design-shotgun — explore visual design variants for issues found
|
||||
- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
|
||||
- **A)** Run $plan --mode Engineering --module plan-eng-review next (required gate)
|
||||
- **B)** Run $plan --mode Product --module plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Run $design --mode Explore --module design-shotgun — explore visual design variants for issues found
|
||||
- **D)** Run $design --mode Implement --module design-html — generate Pretext-native HTML from approved mockups
|
||||
- **E)** Skip — I'll handle next steps manually
|
||||
|
||||
## Formatting Rules
|
||||
|
||||
@@ -193,7 +193,7 @@ Evaluate:
|
||||
- **Journey analytics**: Where do devs drop off?
|
||||
- **Feedback mechanisms**: Bug reports? NPS? Feedback button?
|
||||
- **Friction audits**: Periodic reviews planned?
|
||||
- **Boomerang readiness**: Will /devex-review be able to measure reality vs. plan?
|
||||
- **Boomerang readiness**: Will $qa --mode Report --module devex-review be able to measure reality vs. plan?
|
||||
|
||||
**STOP.** AskUserQuestion once per issue. Recommend + WHY.
|
||||
|
||||
@@ -342,7 +342,7 @@ DX IMPLEMENTATION CHECKLIST
|
||||
|
||||
Before closing this review, synthesize the findings above into a flat list of
|
||||
build-actionable tasks. Each task derives from a specific finding — no padding.
|
||||
Emit the markdown section AND write a JSONL artifact that `/autoplan` can
|
||||
Emit the markdown section AND write a JSONL artifact that `$plan --mode Full chain --module autoplan` can
|
||||
aggregate across phases.
|
||||
|
||||
### Markdown section (always emit)
|
||||
@@ -367,7 +367,7 @@ Rules:
|
||||
|
||||
### JSONL artifact (always write, even if zero tasks)
|
||||
|
||||
`/autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`$plan --mode Full chain --module autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`jq -nc` so titles and source findings containing quotes, newlines, or
|
||||
backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
|
||||
|
||||
@@ -432,9 +432,9 @@ After completing the review, read the review log and config to display the dashb
|
||||
$GSTACK_BIN/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module plan-eng-review.
|
||||
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via $plan --mode Full chain --module autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
|
||||
Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
|
||||
|
||||
@@ -461,7 +461,7 @@ Display:
|
||||
- **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):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. 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.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module 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 from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
@@ -517,7 +517,7 @@ Produce this markdown table:
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`$review --mode Deep --module codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
@@ -653,22 +653,22 @@ eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend next reviews:
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — DX issues often
|
||||
**Recommend $plan --mode Engineering --module plan-eng-review if eng review is not skipped globally** — DX issues often
|
||||
have architectural implications. If this DX review found API design problems, error
|
||||
handling gaps, or CLI ergonomics issues, eng review should validate the fixes.
|
||||
|
||||
**Suggest /plan-design-review if user-facing UI exists** — DX review focuses on
|
||||
**Suggest $design --mode Critique --module plan-design-review if user-facing UI exists** — DX review focuses on
|
||||
developer-facing surfaces; design review covers end-user-facing UI.
|
||||
|
||||
**Recommend /devex-review after implementation** — the boomerang. Plan said TTHW would
|
||||
be [target from 0C]. Did reality match? Run /devex-review on the live product to find
|
||||
**Recommend $qa --mode Report --module devex-review after implementation** — the boomerang. Plan said TTHW would
|
||||
be [target from 0C]. Did reality match? Run $qa --mode Report --module devex-review on the live product to find
|
||||
out. This is where the competitive benchmark pays off: you have a concrete target to
|
||||
measure against.
|
||||
|
||||
Use AskUserQuestion with applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-design-review (only if UI scope detected)
|
||||
- **C)** Ready to implement, run /devex-review after shipping
|
||||
- **A)** Run $plan --mode Engineering --module plan-eng-review next (required gate)
|
||||
- **B)** Run $design --mode Critique --module plan-design-review (only if UI scope detected)
|
||||
- **C)** Ready to implement, run $qa --mode Report --module devex-review after shipping
|
||||
- **D)** Skip, I'll handle next steps manually
|
||||
|
||||
## Mode Quick Reference
|
||||
|
||||
@@ -253,7 +253,7 @@ The plan should be complete enough that when implementation begins, every test i
|
||||
|
||||
### Test Plan Artifact
|
||||
|
||||
After producing the coverage diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input:
|
||||
After producing the coverage diagram, write a test plan artifact to the project directory so `/qa` and `$qa --mode Report --module qa-only` can consume it as primary test input:
|
||||
|
||||
```bash
|
||||
eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" && mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/projects/${PROJECT_ID:-unknown}
|
||||
@@ -265,7 +265,7 @@ Write to `"${GSTACK_HOME:-$HOME/.gstack}"/projects/<stable-project-id>/{user}-{b
|
||||
|
||||
```markdown
|
||||
# Test Plan
|
||||
Generated by /plan-eng-review on {date}
|
||||
Generated by $plan --mode Engineering --module plan-eng-review on {date}
|
||||
Branch: {branch}
|
||||
Repo: {owner/repo}
|
||||
|
||||
@@ -282,7 +282,7 @@ Repo: {owner/repo}
|
||||
- {end-to-end flow that must work}
|
||||
```
|
||||
|
||||
This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.
|
||||
This file is consumed by `/qa` and `$qa --mode Report --module qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.
|
||||
|
||||
For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
|
||||
|
||||
@@ -387,7 +387,7 @@ Format: `Lane A: step1 → step2 (sequential, shared models/)` / `Lane B: step3
|
||||
|
||||
Before closing this review, synthesize the findings above into a flat list of
|
||||
build-actionable tasks. Each task derives from a specific finding — no padding.
|
||||
Emit the markdown section AND write a JSONL artifact that `/autoplan` can
|
||||
Emit the markdown section AND write a JSONL artifact that `$plan --mode Full chain --module autoplan` can
|
||||
aggregate across phases.
|
||||
|
||||
### Markdown section (always emit)
|
||||
@@ -412,7 +412,7 @@ Rules:
|
||||
|
||||
### JSONL artifact (always write, even if zero tasks)
|
||||
|
||||
`/autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`$plan --mode Full chain --module autoplan` reads this file to aggregate across phases. Build each line with
|
||||
`jq -nc` so titles and source findings containing quotes, newlines, or
|
||||
backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
|
||||
|
||||
@@ -513,9 +513,9 @@ After completing the review, read the review log and config to display the dashb
|
||||
$GSTACK_BIN/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. 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. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module plan-eng-review.
|
||||
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via $plan --mode Full chain --module autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
|
||||
Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
|
||||
|
||||
@@ -542,7 +542,7 @@ Display:
|
||||
- **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):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. 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.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in $plan --mode Product --module plan-ceo-review and $plan --mode Engineering --module 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 from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
@@ -598,7 +598,7 @@ Produce this markdown table:
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`$review --mode Deep --module codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
@@ -734,17 +734,17 @@ eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
||||
|
||||
After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
|
||||
**Suggest $design --mode Critique --module plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
|
||||
|
||||
**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
|
||||
**Mention $plan --mode Product --module plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
|
||||
|
||||
**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
|
||||
|
||||
**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
|
||||
|
||||
Use AskUserQuestion with only the applicable options:
|
||||
- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
|
||||
- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
|
||||
- **A)** Run $design --mode Critique --module plan-design-review (only if UI scope detected and no design review exists)
|
||||
- **B)** Run $plan --mode Product --module plan-ceo-review (only if significant product change and no CEO review exists)
|
||||
- **C)** Ready to implement — run /ship when done
|
||||
|
||||
## Unresolved decisions
|
||||
|
||||
Reference in New Issue
Block a user