mirror of
https://github.com/garrytan/gstack.git
synced 2026-08-23 06:27:14 +02:00
Merge remote-tracking branch 'origin/main' into garrytan/zsh-glob-fix
# Conflicts: # .agents/skills/gstack-browse/SKILL.md # .agents/skills/gstack-design-consultation/SKILL.md # .agents/skills/gstack-design-review/SKILL.md # .agents/skills/gstack-document-release/SKILL.md # .agents/skills/gstack-investigate/SKILL.md # .agents/skills/gstack-office-hours/SKILL.md # .agents/skills/gstack-plan-ceo-review/SKILL.md # .agents/skills/gstack-plan-design-review/SKILL.md # .agents/skills/gstack-plan-eng-review/SKILL.md # .agents/skills/gstack-qa-only/SKILL.md # .agents/skills/gstack-qa/SKILL.md # .agents/skills/gstack-retro/SKILL.md # .agents/skills/gstack-review/SKILL.md # .agents/skills/gstack-setup-browser-cookies/SKILL.md # .agents/skills/gstack-ship/SKILL.md # .agents/skills/gstack/SKILL.md
This commit is contained in:
Garry Tan
+356
-10
@@ -17,6 +17,7 @@ allowed-tools:
|
||||
- Glob
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- WebSearch
|
||||
---
|
||||
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
@@ -35,6 +36,9 @@ _PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null
|
||||
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
|
||||
echo "BRANCH: $_BRANCH"
|
||||
echo "PROACTIVE: $_PROACTIVE"
|
||||
source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true
|
||||
REPO_MODE=${REPO_MODE:-unknown}
|
||||
echo "REPO_MODE: $REPO_MODE"
|
||||
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
|
||||
echo "LAKE_INTRO: $_LAKE_SEEN"
|
||||
_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true)
|
||||
@@ -136,6 +140,38 @@ AI-assisted coding makes the marginal cost of completeness near-zero. When you p
|
||||
- BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
|
||||
- BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")
|
||||
|
||||
## Repo Ownership Mode — See Something, Say Something
|
||||
|
||||
`REPO_MODE` from the preamble tells you who owns issues in this repo:
|
||||
|
||||
- **`solo`** — One person does 80%+ of the work. They own everything. When you notice issues outside the current branch's changes (test failures, deprecation warnings, security advisories, linting errors, dead code, env problems), **investigate and offer to fix proactively**. The solo dev is the only person who will fix it. Default to action.
|
||||
- **`collaborative`** — Multiple active contributors. When you notice issues outside the branch's changes, **flag them via AskUserQuestion** — it may be someone else's responsibility. Default to asking, not fixing.
|
||||
- **`unknown`** — Treat as collaborative (safer default — ask before fixing).
|
||||
|
||||
**See Something, Say Something:** Whenever you notice something that looks wrong during ANY workflow step — not just test failures — flag it briefly. One sentence: what you noticed and its impact. In solo mode, follow up with "Want me to fix it?" In collaborative mode, just flag it and move on.
|
||||
|
||||
Never let a noticed issue silently pass. The whole point is proactive communication.
|
||||
|
||||
## Search Before Building
|
||||
|
||||
Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — **search first.** Read `~/.claude/skills/gstack/ETHOS.md` for the full philosophy.
|
||||
|
||||
**Three layers of knowledge:**
|
||||
- **Layer 1** (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
|
||||
- **Layer 2** (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
|
||||
- **Layer 3** (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.
|
||||
|
||||
**Eureka moment:** When first-principles reasoning reveals conventional wisdom is wrong, name it:
|
||||
"EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
|
||||
|
||||
Log eureka moments:
|
||||
```bash
|
||||
jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
|
||||
```
|
||||
Replace SKILL_NAME and ONE_LINE_SUMMARY. Runs inline — don't stop the workflow.
|
||||
|
||||
**WebSearch fallback:** If WebSearch is unavailable, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
## Contributor Mode
|
||||
|
||||
If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
|
||||
@@ -226,6 +262,42 @@ success/error/abort, and `USED_BROWSE` with true/false based on whether `$B` was
|
||||
If you cannot determine the outcome, use "unknown". This runs in the background and
|
||||
never blocks the user.
|
||||
|
||||
## Plan Status Footer
|
||||
|
||||
When you are in plan mode and about to call ExitPlanMode:
|
||||
|
||||
1. Check if the plan file already has a `## GSTACK REVIEW REPORT` section.
|
||||
2. If it DOES — skip (a review skill already wrote a richer report).
|
||||
3. If it does NOT — run this command:
|
||||
|
||||
\`\`\`bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-read
|
||||
\`\`\`
|
||||
|
||||
Then write a `## GSTACK REVIEW REPORT` section to the end of the plan file:
|
||||
|
||||
- If the output contains review entries (JSONL lines before `---CONFIG---`): format the
|
||||
standard report table with runs/status/findings per skill, same format as the review
|
||||
skills use.
|
||||
- If the output is `NO_REVIEWS` or empty: write this placeholder table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | 0 | — | — |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | 0 | — | — |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | 0 | — | — |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | 0 | — | — |
|
||||
|
||||
**VERDICT:** NO REVIEWS YET — run \`/autoplan\` for full review pipeline, or individual reviews above.
|
||||
\`\`\`
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
## Step 0: Detect base branch
|
||||
|
||||
Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
|
||||
@@ -333,6 +405,21 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head
|
||||
```
|
||||
If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.
|
||||
|
||||
**Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above):
|
||||
```bash
|
||||
HANDOFF=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null | head -1)
|
||||
[ -n "$HANDOFF" ] && echo "HANDOFF_FOUND: $HANDOFF" || echo "NO_HANDOFF"
|
||||
```
|
||||
If this block runs in a separate shell from the design doc check, recompute $SLUG and $BRANCH first using the same commands from that block.
|
||||
If a handoff note is found: read it. This contains system audit findings and discussion
|
||||
from a prior CEO review session that paused so the user could run `/office-hours`. Use it
|
||||
as additional context alongside the design doc. The handoff note helps you avoid re-asking
|
||||
questions the user already answered. Do NOT skip any steps — run the full review, but use
|
||||
the handoff note to inform your analysis and avoid redundant questions.
|
||||
|
||||
Tell the user: "Found a handoff note from your prior CEO review session. I'll use that
|
||||
context to pick up where we left off."
|
||||
|
||||
## Prerequisite Skill Offer
|
||||
|
||||
When the design doc check above prints "No design doc found," offer the prerequisite
|
||||
@@ -346,24 +433,65 @@ Say to the user via AskUserQuestion:
|
||||
> not per-product — it captures the thinking behind this specific change."
|
||||
|
||||
Options:
|
||||
- A) Run /office-hours first (in another window, then come back)
|
||||
- A) Run /office-hours now (we'll pick up the review right after)
|
||||
- B) Skip — proceed with standard review
|
||||
|
||||
If they skip: "No worries — standard review. If you ever want sharper input, try
|
||||
/office-hours first next time." Then proceed normally. Do not re-offer later in the session.
|
||||
|
||||
If they choose A:
|
||||
|
||||
Say: "Running /office-hours inline. Once the design doc is ready, I'll pick up
|
||||
the review right where we left off."
|
||||
|
||||
Read the office-hours skill file from disk using the Read tool:
|
||||
`~/.claude/skills/gstack/office-hours/SKILL.md`
|
||||
|
||||
Follow it inline, **skipping these sections** (already handled by the parent skill):
|
||||
- Preamble (run first)
|
||||
- AskUserQuestion Format
|
||||
- Completeness Principle — Boil the Lake
|
||||
- Search Before Building
|
||||
- Contributor Mode
|
||||
- Completion Status Protocol
|
||||
- Telemetry (run last)
|
||||
|
||||
If the Read fails (file not found), say:
|
||||
"Could not load /office-hours — proceeding with standard review."
|
||||
|
||||
After /office-hours completes, re-run the design doc check:
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
|
||||
DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
|
||||
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
|
||||
```
|
||||
|
||||
If a design doc is now found, read it and continue the review.
|
||||
If none was produced (user may have cancelled), proceed with standard review.
|
||||
|
||||
**Mid-session detection:** During Step 0A (Premise Challenge), if the user can't
|
||||
articulate the problem, keeps changing the problem statement, answers with "I'm not
|
||||
sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
|
||||
|
||||
> "It sounds like you're still figuring out what to build — that's totally fine, but
|
||||
> that's what /office-hours is designed for. Want to pause this review and run
|
||||
> /office-hours first? It'll help you nail down the problem and approach, then come
|
||||
> back here for the strategic review."
|
||||
> that's what /office-hours is designed for. Want to run /office-hours right now?
|
||||
> We'll pick up right where we left off."
|
||||
|
||||
Options: A) Yes, run /office-hours first. B) No, keep going.
|
||||
Options: A) Yes, run /office-hours now. B) No, keep going.
|
||||
If they keep going, proceed normally — no guilt, no re-asking.
|
||||
|
||||
If they choose A: Read the office-hours skill file from disk:
|
||||
`~/.claude/skills/gstack/office-hours/SKILL.md`
|
||||
|
||||
Follow it inline, skipping these sections (already handled by parent skill):
|
||||
Preamble, AskUserQuestion Format, Completeness Principle, Search Before Building,
|
||||
Contributor Mode, Completion Status Protocol, Telemetry.
|
||||
|
||||
Note current Step 0A progress so you don't re-ask questions already answered.
|
||||
After completion, re-run the design doc check and resume the review.
|
||||
|
||||
When reading TODOS.md, specifically:
|
||||
* Note any TODOs this plan touches, blocks, or unlocks
|
||||
* Check if deferred work from prior reviews relates to this plan
|
||||
@@ -386,6 +514,22 @@ Analyze the plan. If it involves ANY of: new UI screens/pages, changes to existi
|
||||
Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating.
|
||||
Report findings before proceeding to Step 0.
|
||||
|
||||
### Landscape Check
|
||||
|
||||
Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for:
|
||||
- "[product category] landscape {current year}"
|
||||
- "[key feature] alternatives"
|
||||
- "why [incumbent/conventional approach] [succeeds/fails]"
|
||||
|
||||
If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
Run the three-layer synthesis:
|
||||
- **[Layer 1]** What's the tried-and-true approach in this space?
|
||||
- **[Layer 2]** What are the search results saying?
|
||||
- **[Layer 3]** First-principles reasoning — where might the conventional wisdom be wrong?
|
||||
|
||||
Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a eureka moment, surface it during the Expansion opt-in ceremony as a differentiation opportunity. Log it (see preamble).
|
||||
|
||||
## Step 0: Nuclear Scope Challenge + Mode Selection
|
||||
|
||||
### 0A. Premise Challenge
|
||||
@@ -463,7 +607,7 @@ Rules:
|
||||
After the opt-in/cherry-pick ceremony, write the plan to disk so the vision and decisions survive beyond this conversation. Only run this step for EXPANSION and SELECTIVE EXPANSION modes.
|
||||
|
||||
```bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
```
|
||||
|
||||
Before writing, check for existing CEO plans in the ceo-plans/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them:
|
||||
@@ -847,6 +991,125 @@ 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."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
|
||||
## 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:
|
||||
<plan content>"
|
||||
|
||||
**If CODEX_AVAILABLE:**
|
||||
|
||||
```bash
|
||||
TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
|
||||
codex exec "<prompt>" -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):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full codex output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
**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).
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -941,6 +1204,7 @@ List every ASCII diagram in files this plan touches. Still accurate?
|
||||
| TODOS.md updates | ___ items proposed |
|
||||
| Scope proposals | ___ proposed, ___ accepted (EXP + SEL) |
|
||||
| CEO plan | written / skipped (HOLD/REDUCTION) |
|
||||
| Outside voice | ran (codex/claude) / skipped |
|
||||
| Lake Score | X/Y recommendations chose complete option |
|
||||
| Diagrams produced | ___ (list types) |
|
||||
| Stale diagrams found | ___ |
|
||||
@@ -951,6 +1215,16 @@ List every ASCII diagram in files this plan touches. Still accurate?
|
||||
### Unresolved Decisions
|
||||
If any AskUserQuestion goes unanswered, note it here. Never silently default.
|
||||
|
||||
## Handoff Note Cleanup
|
||||
|
||||
After producing the Completion Summary, clean up any handoff notes for this branch —
|
||||
the review is complete and the context is no longer needed.
|
||||
|
||||
```bash
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
## Review Log
|
||||
|
||||
After producing the Completion Summary above, persist the review result.
|
||||
@@ -962,7 +1236,7 @@ the same pattern. The review dashboard depends on this data. Skipping this
|
||||
command breaks the review readiness dashboard in /ship.
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","commit":"COMMIT"}'
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Before running this command, substitute the placeholder values from the Completion Summary you just produced:
|
||||
@@ -971,6 +1245,9 @@ Before running this command, substitute the placeholder values from the Completi
|
||||
- **unresolved**: number from "Unresolved decisions" in the summary
|
||||
- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
|
||||
- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
|
||||
- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
|
||||
- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
|
||||
- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
## Review Readiness Dashboard
|
||||
@@ -981,7 +1258,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, codex-review). Ignore entries with timestamps older than 7 days. 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:
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
@@ -992,7 +1269,8 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
|
||||
| Eng Review | 1 | 2026-03-16 15:00 | CLEAR | YES |
|
||||
| CEO Review | 0 | — | — | no |
|
||||
| Design Review | 0 | — | — | no |
|
||||
| Codex Review | 0 | — | — | no |
|
||||
| Adversarial | 0 | — | — | no |
|
||||
| Outside Voice | 0 | — | — | no |
|
||||
+--------------------------------------------------------------------+
|
||||
| VERDICT: CLEARED — Eng Review passed |
|
||||
+====================================================================+
|
||||
@@ -1002,7 +1280,8 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **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.
|
||||
- **Codex Review (enabled by default when Codex CLI is installed):** Independent review + adversarial challenge from OpenAI Codex CLI. Shows pass/fail gate. Runs automatically when enabled — configure with \`gstack-config set codex_reviews enabled|disabled\`.
|
||||
- **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\`)
|
||||
@@ -1016,6 +1295,73 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
|
||||
- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
|
||||
- If all reviews match the current HEAD, do not display any staleness notes
|
||||
|
||||
## Plan File Review Report
|
||||
|
||||
After displaying the Review Readiness Dashboard in conversation output, also update the
|
||||
**plan file** itself so review status is visible to anyone reading the plan.
|
||||
|
||||
### Detect the plan file
|
||||
|
||||
1. Check if there is an active plan file in this conversation (the host provides plan file
|
||||
paths in system messages — look for plan file references in the conversation context).
|
||||
2. If not found, skip this section silently — not every review runs in plan mode.
|
||||
|
||||
### Generate the report
|
||||
|
||||
Read the review log output you already have from the Review Readiness Dashboard step above.
|
||||
Parse each JSONL entry. Each skill logs different fields:
|
||||
|
||||
- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
|
||||
→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
|
||||
→ If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
|
||||
- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
|
||||
→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"
|
||||
- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
|
||||
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
|
||||
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
|
||||
|
||||
All fields needed for the Findings column are now present in the JSONL entries.
|
||||
For the review you just completed, you may use richer details from your own Completion
|
||||
Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
|
||||
|
||||
Produce this markdown table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| 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} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines (omit any that are empty/not applicable):
|
||||
|
||||
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
|
||||
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
|
||||
- **UNRESOLVED:** total unresolved decisions across all reviews
|
||||
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
|
||||
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
|
||||
|
||||
### Write to the plan file
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file
|
||||
(not just at the end — content may have been added after it).
|
||||
- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\`
|
||||
through either the next \`## \` heading or end of file, whichever comes first. This ensures
|
||||
content added after the report section is preserved, not eaten. If the Edit fails
|
||||
(e.g., concurrent edit changed the content), re-read the plan file and retry once.
|
||||
- If no such section exists, **append it** to the end of the plan file.
|
||||
- Always place it as the very last section in the plan file. If it was found mid-file,
|
||||
move it: delete the old location and append at the end.
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
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.
|
||||
|
||||
@@ -17,6 +17,7 @@ allowed-tools:
|
||||
- Glob
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- WebSearch
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
@@ -111,6 +112,21 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head
|
||||
```
|
||||
If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.
|
||||
|
||||
**Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above):
|
||||
```bash
|
||||
HANDOFF=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null | head -1)
|
||||
[ -n "$HANDOFF" ] && echo "HANDOFF_FOUND: $HANDOFF" || echo "NO_HANDOFF"
|
||||
```
|
||||
If this block runs in a separate shell from the design doc check, recompute $SLUG and $BRANCH first using the same commands from that block.
|
||||
If a handoff note is found: read it. This contains system audit findings and discussion
|
||||
from a prior CEO review session that paused so the user could run `/office-hours`. Use it
|
||||
as additional context alongside the design doc. The handoff note helps you avoid re-asking
|
||||
questions the user already answered. Do NOT skip any steps — run the full review, but use
|
||||
the handoff note to inform your analysis and avoid redundant questions.
|
||||
|
||||
Tell the user: "Found a handoff note from your prior CEO review session. I'll use that
|
||||
context to pick up where we left off."
|
||||
|
||||
{{BENEFITS_FROM}}
|
||||
|
||||
**Mid-session detection:** During Step 0A (Premise Challenge), if the user can't
|
||||
@@ -118,13 +134,22 @@ articulate the problem, keeps changing the problem statement, answers with "I'm
|
||||
sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
|
||||
|
||||
> "It sounds like you're still figuring out what to build — that's totally fine, but
|
||||
> that's what /office-hours is designed for. Want to pause this review and run
|
||||
> /office-hours first? It'll help you nail down the problem and approach, then come
|
||||
> back here for the strategic review."
|
||||
> that's what /office-hours is designed for. Want to run /office-hours right now?
|
||||
> We'll pick up right where we left off."
|
||||
|
||||
Options: A) Yes, run /office-hours first. B) No, keep going.
|
||||
Options: A) Yes, run /office-hours now. B) No, keep going.
|
||||
If they keep going, proceed normally — no guilt, no re-asking.
|
||||
|
||||
If they choose A: Read the office-hours skill file from disk:
|
||||
`~/.claude/skills/gstack/office-hours/SKILL.md`
|
||||
|
||||
Follow it inline, skipping these sections (already handled by parent skill):
|
||||
Preamble, AskUserQuestion Format, Completeness Principle, Search Before Building,
|
||||
Contributor Mode, Completion Status Protocol, Telemetry.
|
||||
|
||||
Note current Step 0A progress so you don't re-ask questions already answered.
|
||||
After completion, re-run the design doc check and resume the review.
|
||||
|
||||
When reading TODOS.md, specifically:
|
||||
* Note any TODOs this plan touches, blocks, or unlocks
|
||||
* Check if deferred work from prior reviews relates to this plan
|
||||
@@ -147,6 +172,22 @@ Analyze the plan. If it involves ANY of: new UI screens/pages, changes to existi
|
||||
Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating.
|
||||
Report findings before proceeding to Step 0.
|
||||
|
||||
### Landscape Check
|
||||
|
||||
Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for:
|
||||
- "[product category] landscape {current year}"
|
||||
- "[key feature] alternatives"
|
||||
- "why [incumbent/conventional approach] [succeeds/fails]"
|
||||
|
||||
If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
Run the three-layer synthesis:
|
||||
- **[Layer 1]** What's the tried-and-true approach in this space?
|
||||
- **[Layer 2]** What are the search results saying?
|
||||
- **[Layer 3]** First-principles reasoning — where might the conventional wisdom be wrong?
|
||||
|
||||
Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a eureka moment, surface it during the Expansion opt-in ceremony as a differentiation opportunity. Log it (see preamble).
|
||||
|
||||
## Step 0: Nuclear Scope Challenge + Mode Selection
|
||||
|
||||
### 0A. Premise Challenge
|
||||
@@ -224,7 +265,7 @@ Rules:
|
||||
After the opt-in/cherry-pick ceremony, write the plan to disk so the vision and decisions survive beyond this conversation. Only run this step for EXPANSION and SELECTIVE EXPANSION modes.
|
||||
|
||||
```bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
```
|
||||
|
||||
Before writing, check for existing CEO plans in the ceo-plans/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them:
|
||||
@@ -548,6 +589,8 @@ 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."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
|
||||
{{CODEX_PLAN_REVIEW}}
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -642,6 +685,7 @@ List every ASCII diagram in files this plan touches. Still accurate?
|
||||
| TODOS.md updates | ___ items proposed |
|
||||
| Scope proposals | ___ proposed, ___ accepted (EXP + SEL) |
|
||||
| CEO plan | written / skipped (HOLD/REDUCTION) |
|
||||
| Outside voice | ran (codex/claude) / skipped |
|
||||
| Lake Score | X/Y recommendations chose complete option |
|
||||
| Diagrams produced | ___ (list types) |
|
||||
| Stale diagrams found | ___ |
|
||||
@@ -652,6 +696,16 @@ List every ASCII diagram in files this plan touches. Still accurate?
|
||||
### Unresolved Decisions
|
||||
If any AskUserQuestion goes unanswered, note it here. Never silently default.
|
||||
|
||||
## Handoff Note Cleanup
|
||||
|
||||
After producing the Completion Summary, clean up any handoff notes for this branch —
|
||||
the review is complete and the context is no longer needed.
|
||||
|
||||
```bash
|
||||
{{SLUG_EVAL}}
|
||||
rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
|
||||
```
|
||||
|
||||
## Review Log
|
||||
|
||||
After producing the Completion Summary above, persist the review result.
|
||||
@@ -663,7 +717,7 @@ the same pattern. The review dashboard depends on this data. Skipping this
|
||||
command breaks the review readiness dashboard in /ship.
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","commit":"COMMIT"}'
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Before running this command, substitute the placeholder values from the Completion Summary you just produced:
|
||||
@@ -672,10 +726,15 @@ Before running this command, substitute the placeholder values from the Completi
|
||||
- **unresolved**: number from "Unresolved decisions" in the summary
|
||||
- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
|
||||
- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
|
||||
- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
|
||||
- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
|
||||
- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
{{REVIEW_DASHBOARD}}
|
||||
|
||||
{{PLAN_FILE_REVIEW_REPORT}}
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user