mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-05 00:03:15 +01:00
feat(office-hours): skill diet (GSTA-134 pilot 2)
Moves the Phase 3.5 Codex second opinion and the Phase 4.25 visual design (designer mockups / HTML sketch) out of the eager SKILL.md into on-demand sections behind STOP pointers; the CODEX_SECOND_OPINION, DESIGN_MOCKUP and DESIGN_SKETCH resolvers are untouched. Claude-host SKILL.md 73,248 -> 43,885 bytes. skill-diet before/after (Opus, 9 tasks x 3): success 26/27 -> 27/27, median tokens per successful run 170,197 -> 124,941; blind judge after 10, before 5 of 15. YC pitch, flattery and promo text unchanged (sections byte-identical to main). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
garrytanandcapy-ai[bot] committed
1 parent
7e2ad74b88
commit
c3093dcbe9
10 files changed
+490
-444
No files matched your search
+15
-434
@@ -351,6 +351,8 @@ sections. Read a section in full before doing its step; do not work from memory.
|
||||
|------|-------------------|
|
||||
| running the startup-mode diagnostic (Phase 2A: operating principles, pushback patterns, and the six forcing questions) | `sections/phase-2a-startup-diagnostic.md` |
|
||||
| giving any builder-mode response (Phase 2B: brainstorm questions and every suggestion, adjacent unlock or riff; holds the operating principles, the wild exemplar, the response posture and the generative questions) | `sections/phase-2b-builder-brainstorm.md` |
|
||||
| running the Phase 3.5 second opinion the user just accepted (provider preflight, cold-read prompt, dispatch and synthesis) | `sections/second-opinion.md` |
|
||||
| Phase 4.25 visual design for an approved approach with user-facing UI (designer mockups, or the HTML sketch when the designer is unavailable) | `sections/visual-design.md` |
|
||||
| writing the design doc and running the tiered relationship handoff (Phases 5-6, after the conversation and alternatives are done) | `sections/design-and-handoff.md` |
|
||||
---
|
||||
|
||||
@@ -445,13 +447,13 @@ Sanitize every query before it leaves the machine: strip hostnames, IPs, file pa
|
||||
|
||||
Read ETHOS.md for the full Search Before Building framework (three layers, eureka moments). The preamble's Search Before Building section has the ETHOS.md path.
|
||||
|
||||
After understanding the problem through questioning, search for what the world thinks. This is NOT competitive research (that's /design-consultation's job). This is understanding conventional wisdom so you can evaluate where it's wrong.
|
||||
After the questioning, learn the conventional wisdom (not competitive research) so you can judge where it's wrong.
|
||||
|
||||
**Privacy gate:** Before searching, use AskUserQuestion: "I'd like to search for what the world thinks about this space to inform our discussion. This sends generalized category terms (not your specific idea) to a search engine through your Aside browser (or the WebSearch tool if Aside is not running). OK to proceed?"
|
||||
Options: A) Yes, search away B) Skip — keep this session private
|
||||
If B: skip this phase entirely and proceed to Phase 3. Use only in-distribution knowledge.
|
||||
|
||||
When searching, use **generalized category terms** — never the user's specific product name, proprietary concept, or stealth idea. For example, search "task management app landscape" not "SuperTodo AI-powered task killer."
|
||||
Search **generalized category terms** only, never the user's product name, proprietary concept or stealth idea ("task management app landscape", not "SuperTodo AI-powered task killer").
|
||||
|
||||
If the Aside check did not print `READY`, run the same searches with the WebSearch tool when the host provides it; with neither, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
@@ -478,7 +480,7 @@ Read the top 2-3 sources it cites. Run the three-layer synthesis:
|
||||
|
||||
If no eureka moment exists, say: "The conventional wisdom seems sound here. Let's build on it." Proceed to Phase 3.
|
||||
|
||||
**Important:** This search feeds Phase 3 (Premise Challenge). If you found reasons the conventional approach fails, those become premises to challenge. If conventional wisdom is solid, that raises the bar for any premise that contradicts it.
|
||||
Findings feed Phase 3: reasons the conventional approach fails become premises to challenge; solid conventional wisdom raises the bar for any premise that contradicts it.
|
||||
|
||||
---
|
||||
|
||||
@@ -506,157 +508,12 @@ Use AskUserQuestion to confirm. If the user disagrees with a premise, revise und
|
||||
|
||||
## Phase 3.5: Cross-Model Second Opinion (optional)
|
||||
|
||||
**Provider preflight:**
|
||||
Use AskUserQuestion: "Want a second opinion from an independent AI perspective? It reviews your problem statement, key answers, premises and landscape findings from a structured summary, without this conversation. Usually 2-5 minutes." A) Yes, get a second opinion. B) No, proceed to alternatives.
|
||||
|
||||
```bash
|
||||
|
||||
if ! _OUTSIDE_CFG=$("$HOME/.claude/skills/gstack/bin/gstack-config" get --stored codex_reviews) || [ "$_OUTSIDE_CFG" = disabled ]; then
|
||||
echo 'CODEX_MODE: disabled'
|
||||
elif ( # GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
); then
|
||||
if command -v codex >/dev/null 2>&1; then echo 'CODEX_MODE: ready'; else echo 'CODEX_MODE: not_installed'; fi
|
||||
else
|
||||
echo 'CODEX_MODE: under_current_harness'
|
||||
fi
|
||||
```
|
||||
|
||||
The historical `CODEX_MODE` variable describes **Codex** availability here. `CODEX_MODE: disabled` or a send's `consent_missing` line: `codex_reviews` is off or unreadable; do not ask; record `outside_status: disabled`. Authentication and configured model validity are checked by the actual invocation, without overriding either. Missing/broken CLI: install or repair Codex; authentication failure: run `codex login`. Otherwise honor this caller’s opt-in/skip choice. Any non-ready outcome is missing outside coverage; follow the caller’s existing fallback. Never substitute another external provider.
|
||||
|
||||
Use AskUserQuestion (regardless of codex availability):
|
||||
|
||||
> Want a second opinion from an independent AI perspective? It will review your problem statement, key answers, premises, and any landscape findings from this session without having seen this conversation — it gets a structured summary. Usually takes 2-5 minutes.
|
||||
> A) Yes, get a second opinion
|
||||
> B) No, proceed to alternatives
|
||||
|
||||
If B: skip Phase 3.5 entirely. Remember that the second opinion did NOT run (affects design doc, founder signals, and Phase 4 below).
|
||||
|
||||
**If A: Run the Codex cold read.**
|
||||
|
||||
1. Assemble a structured context block from Phases 1-3:
|
||||
- Mode (Startup or Builder)
|
||||
- Problem statement (from Phase 1)
|
||||
- Key answers from Phase 2A/2B (summarize each Q&A in 1-2 sentences, include verbatim user quotes)
|
||||
- Landscape findings (from Phase 2.75, if search was run)
|
||||
- Agreed premises (from Phase 3)
|
||||
- Codebase context (project name, languages, recent activity)
|
||||
|
||||
2. **Write the assembled prompt to a temp file** (prevents shell injection from user-derived content):
|
||||
|
||||
```bash
|
||||
OUTSIDE_PROMPT_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-outside-oh-XXXXXXXX") || { echo 'ERROR: mktemp failed; not running the outside voice without its prompt file.' >&2; exit 1; }
|
||||
```
|
||||
|
||||
Write the full prompt to this file. **Always start with the filesystem boundary:**
|
||||
"Filesystem boundary: do not read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. They hold skill definitions, not repository code to review. Do not invoke any installed skill (Codex home skills/, .agents/), hook, or tool instruction; answer directly. Do not modify agents/openai.yaml. Review only the repository code.\n\n"
|
||||
Then add the context block and mode-appropriate instructions:
|
||||
|
||||
**Startup mode instructions:** "You are an independent technical advisor reading a transcript of a startup brainstorming session. [CONTEXT BLOCK HERE]. Your job: 1) What is the STRONGEST version of what this person is trying to build? Steelman it in 2-3 sentences. 2) What is the ONE thing from their answers that reveals the most about what they should actually build? Quote it and explain why. 3) Name ONE agreed premise you think is wrong, and what evidence would prove you right. 4) If you had 48 hours and one engineer to build a prototype, what would you build? Be specific — tech stack, features, what you'd skip. Be direct. Be terse. No preamble."
|
||||
|
||||
**Builder mode instructions:** "You are an independent technical advisor reading a transcript of a builder brainstorming session. [CONTEXT BLOCK HERE]. Your job: 1) What is the COOLEST version of this they haven't considered? 2) What's the ONE thing from their answers that reveals what excites them most? Quote it. 3) What existing open source project or tool gets them 50% of the way there — and what's the 50% they'd need to build? 4) If you had a weekend to build this, what would you build first? Be specific. Be direct. No preamble."
|
||||
|
||||
3. Run Codex with the assembled prompt:
|
||||
|
||||
Write the **complete prompt and context**, including actual plan/spec/source, to a private file. Substitute its shell-quoted path for `<prepared-prompt-file>`; never interpolate user text into shell source. Request a severity (Critical, High, Medium or Low) per finding and a final Recommendation: <action> because <specific reason> line, including an explicit no-findings rationale.
|
||||
|
||||
```bash
|
||||
# GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo 'ERROR: not in a git repo' >&2; exit 1; }
|
||||
_OUTSIDE_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-outside.XXXXXXXX") || exit 1
|
||||
trap 'rm -rf "$_OUTSIDE_TMP"' EXIT
|
||||
_OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
|
||||
cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
|
||||
|
||||
_CODEX_PROBE="$HOME/.claude/skills/gstack/bin/gstack-codex-probe"
|
||||
_CODEX_OUT=$("$_CODEX_PROBE" select-model exec) || exit 1
|
||||
_CODEX_SEL=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SEL: //p')
|
||||
_CODEX_SANDBOX_MODE=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SANDBOX: //p')
|
||||
"$_CODEX_PROBE" check-sandbox || exit 1
|
||||
"$_CODEX_PROBE" show-first-use-notice
|
||||
_OUTSIDE_EXIT=0
|
||||
"$_CODEX_PROBE" run-with-timeout --effort high 300 codex exec - -C "$_REPO_ROOT" -s "${_CODEX_SANDBOX_MODE:?}" -c "model=\"${_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
|
||||
cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
|
||||
|
||||
cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
|
||||
_OUTSIDE_RC=0
|
||||
bun --no-env-file --config=/dev/null "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
|
||||
case "$_OUTSIDE_RC" in
|
||||
0|3) ;;
|
||||
4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
|
||||
*) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
|
||||
esac
|
||||
echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
|
||||
```
|
||||
|
||||
Use Bash `timeout: 360000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
|
||||
|
||||
**Error handling:** All errors are non-blocking — second opinion is a quality enhancement, not a prerequisite.
|
||||
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run \`codex login\` to authenticate." Fall back to the Claude subagent below.
|
||||
- **Timeout:** "Codex timed out after 5 minutes." Fall back to the Claude subagent below.
|
||||
- **Empty response:** "Codex returned no response." Fall back to the Claude subagent below.
|
||||
|
||||
On any Codex error, fall back to the Claude subagent below.
|
||||
|
||||
**If preflight is not ready (or Codex errored):**
|
||||
|
||||
Dispatch via the Agent tool with `run_in_background: false` when available (subagents default to background since Claude Code v2.1.198; the findings must land before the workflow continues). A launch receipt means it went background: await its completion notice. The subagent has fresh context and no conversation bias — but it is the same harness; model identity stays unknown unless the runtime reports it; weigh its agreement accordingly.
|
||||
|
||||
Subagent prompt: same mode-appropriate prompt as above (Startup or Builder variant).
|
||||
|
||||
Present findings under a `SECOND OPINION (Claude subagent):` header.
|
||||
|
||||
If the subagent fails or times out: "Second opinion unavailable. Continuing to Phase 4."
|
||||
|
||||
Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"office-hours"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
|
||||
|
||||
4. **Presentation:**
|
||||
|
||||
If Codex ran:
|
||||
```
|
||||
SECOND OPINION (Codex):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full codex output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
If Claude subagent ran:
|
||||
```
|
||||
SECOND OPINION (Claude subagent):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full subagent output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
5. **Cross-model synthesis:** After presenting the second opinion output, provide 3-5 bullet synthesis:
|
||||
- Where Claude agrees with the second opinion
|
||||
- Where Claude disagrees and why
|
||||
- Whether the challenged premise changes Claude's recommendation
|
||||
|
||||
6. **Premise revision check:** If Codex challenged an agreed premise, use AskUserQuestion:
|
||||
|
||||
> Codex challenged premise #{N}: "{premise text}". Their argument: "{reasoning}".
|
||||
> A) Revise this premise based on Codex's input
|
||||
> B) Keep the original premise — proceed to alternatives
|
||||
|
||||
If A: revise the premise and note the revision. If B: proceed (and note that the user defended this premise with reasoning — this is a founder signal if they articulate WHY they disagree, not just dismiss).
|
||||
If B: skip Phase 3.5 and remember the second opinion did NOT run (the design doc, founder signals and Phase 4 depend on it).
|
||||
If A:
|
||||
> **STOP.** Before running the Phase 3.5 second opinion the user just accepted (provider preflight, cold-read prompt, dispatch and synthesis), Read `~/.claude/skills/gstack/office-hours/sections/second-opinion.md` and execute it
|
||||
> in full. Do not work from memory — that section is the source of truth for this step.
|
||||
|
||||
---
|
||||
|
||||
@@ -692,291 +549,15 @@ Rules:
|
||||
|
||||
Emit ONE AskUserQuestion that lists every alternative (A/B and optionally C) as numbered options, using the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — write the question text and call the tool.
|
||||
|
||||
**STOP.** Do NOT proceed to Phase 4.5 (Founder Signal Synthesis), Phase 5 (Design Doc), Phase 6 (Closing), or any design-doc generation until the user responds. A "clearly winning approach" is still an approach decision and still needs explicit user approval before it lands in the design doc. Writing the recommendation in chat prose and continuing forward is the failure mode this gate exists to prevent.
|
||||
**STOP.** Do NOT proceed to Phase 4.25, 4.5, 5 or 6, or write any design doc, until the user responds. A "clearly winning approach" still needs explicit approval; writing the recommendation in prose and continuing is the failure this gate prevents.
|
||||
|
||||
---
|
||||
|
||||
## Visual Design Exploration
|
||||
## Phase 4.25: Visual design (UI ideas only)
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
D=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/design/dist/design" ] && D="$_ROOT/.claude/skills/gstack/design/dist/design"
|
||||
[ -z "$D" ] && D="$HOME/.claude/skills/gstack/design/dist/design"
|
||||
_DS=$("$HOME/.claude/skills/gstack/bin/gstack-paths" --get GSTACK_STATE_ROOT 2>/dev/null); _DC=${_DS:+$_DS/design-ready}; _DK=$(ls -diL "$D" 2>/dev/null)
|
||||
_dt() { if command -v gtimeout >/dev/null; then gtimeout 10 "$@"; elif command -v timeout >/dev/null; then timeout 10 "$@"
|
||||
elif command -v perl >/dev/null; then perl -e 'alarm(shift);exec(@ARGV)' 10 "$@"; else return 125; fi; }
|
||||
_RC=0; _F="Fix: cd ${D%/design/dist/design} && ./setup"
|
||||
if [ ! -x "$D" ]; then _RC=missing
|
||||
elif [ ! "$_DC" -nt "$D" ] || [ "$(cat "$_DC")" != "$_DK" ]; then _dt "$D" --version >/dev/null 2>&1 </dev/null || _RC=$?
|
||||
fi
|
||||
case "$_RC" in
|
||||
0) echo "DESIGN_READY: $D"; [ -n "$_DC" ] && echo "$_DK" > "$_DC" 2>/dev/null ;;
|
||||
missing) echo "DESIGN_NOT_AVAILABLE: $D is not installed. $_F" ;;
|
||||
124|142) echo "DESIGN_NOT_AVAILABLE: $D --version timed out after 10s" ;;
|
||||
125) echo "DESIGN_NOT_AVAILABLE: no timeout/gtimeout/perl to bound $D" ;;
|
||||
137) echo "DESIGN_NOT_AVAILABLE: $D --version exited 137 (killed at launch; on macOS usually an invalid code signature). $_F" ;;
|
||||
*) echo "DESIGN_NOT_AVAILABLE: $D --version exited $_RC" ;;
|
||||
esac
|
||||
```
|
||||
|
||||
**If `DESIGN_NOT_AVAILABLE`:** Fall back to the HTML wireframe approach below
|
||||
(the existing DESIGN_SKETCH section). Visual mockups require the design binary.
|
||||
|
||||
**If `DESIGN_READY`:** Generate visual mockup explorations for the user.
|
||||
|
||||
Generating visual mockups of the proposed design... (say "skip" if you don't need visuals)
|
||||
|
||||
**Step 1: Set up the design directory**
|
||||
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
|
||||
GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
|
||||
_DESIGN_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/designs/mockup-$(date +%Y%m%d)"
|
||||
mkdir -p "$_DESIGN_DIR"
|
||||
echo "DESIGN_DIR: $_DESIGN_DIR"
|
||||
```
|
||||
|
||||
**Step 2: Construct the design brief**
|
||||
|
||||
Read DESIGN.md if it exists — use it to constrain the visual style. If no DESIGN.md,
|
||||
explore wide across diverse directions. The brief, and the user's feedback in Step 6, go in private files:
|
||||
|
||||
```bash
|
||||
_GT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp"
|
||||
mkdir -p "$_GT" && chmod 700 "$_GT" || { echo "Not sent: cannot create $_GT for the text file." >&2; exit 1; }
|
||||
_EX=$(git rev-parse --git-path info/exclude 2>/dev/null) && mkdir -p "$(dirname "$_EX")" && { grep -qxF '/.gstack/tmp/' "$_EX" 2>/dev/null || echo '/.gstack/tmp/' >> "$_EX"; }
|
||||
BRIEF_FILE=$(mktemp "${_GT:?}/brief.XXXXXX") || { echo "Not sent: mktemp failed in $_GT." >&2; exit 1; }; echo "BRIEF_FILE: $BRIEF_FILE (name: ${BRIEF_FILE##*/})"
|
||||
FEEDBACK_FILE=$(mktemp "${_GT:?}/feedback.XXXXXX") || { echo "Not sent: mktemp failed in $_GT." >&2; exit 1; }; echo "FEEDBACK_FILE: $FEEDBACK_FILE (name: ${FEEDBACK_FILE##*/})"
|
||||
```
|
||||
|
||||
Write the text into each printed file with your file-write tool (Claude Code's Write tool needs a Read of the empty file first), exactly as it should appear. The text never goes into a shell command, heredoc or quoted argument. If a write fails or is refused, do not send: print the cause, the file path and the command below for sending by hand.
|
||||
|
||||
**Step 3: Generate 3 variants** (substitute the printed name for `<brief-file-name>`)
|
||||
|
||||
```bash
|
||||
BRIEF_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<brief-file-name>"
|
||||
[ -s "$BRIEF_FILE" ] || { echo "Not run: $BRIEF_FILE is missing or empty. Write the brief, then rerun this block." >&2; exit 1; }
|
||||
_OUT=$($D variants --brief "$(cat "$BRIEF_FILE")" --count 3 --output-dir "$_DESIGN_DIR/"); _RC=$?
|
||||
printf '%s\n' "$_OUT"; echo "EXIT: $_RC"
|
||||
```
|
||||
|
||||
This generates 3 style variations of the same brief (~40 seconds total).
|
||||
|
||||
<!-- design:round-accounting -->
|
||||
**Round accounting (before any board, check or inline view):** `$D` never overwrites; a taken name is bumped (for example `-2`), so use only the paths its JSON printed and carry them as literal paths into later blocks (bash blocks do not share variables). Tell the user how many of `requested` paid images were saved (`saved`) and name each `failures` entry. Route on the exit code: 0 continue with `saved`; 3 continue with `saved` and say the run stopped early; 2 nothing was saved, so report `failures` and stop: do not run `$D compare` or `$D check`.
|
||||
|
||||
**Step 4: Show variants inline, then open comparison board**
|
||||
|
||||
Show each saved image to the user inline first (read the printed paths with Read tool), then
|
||||
create and serve the comparison board:
|
||||
|
||||
<!-- design:board -->
|
||||
Write this round's board images (printed paths that passed checks, in order) as a JSON array to `$_DESIGN_DIR/board-images.json` with the Write tool; board letters A, B, C follow that order. Then archive any earlier Submit so it cannot approve these images, and build the board:
|
||||
|
||||
```bash
|
||||
[ -f "${_DESIGN_DIR:?set _DESIGN_DIR to the design dir printed above}/feedback.json" ] && mv "${_DESIGN_DIR:?}/feedback.json" "${_DESIGN_DIR:?}/feedback-$(date -u +%Y%m%dT%H%M%SZ).json"
|
||||
$D compare --images-file "$_DESIGN_DIR/board-images.json" --output "$_DESIGN_DIR/design-board.html" --serve
|
||||
```
|
||||
|
||||
This publishes the board to the design daemon, opens it in the user's default
|
||||
browser, and exits; it does not wait for feedback. Read captured stderr for the
|
||||
`BOARD_URL: http://127.0.0.1:N/boards/<id>/` line, then wait with AskUserQuestion:
|
||||
"Review <BOARD_URL>, click Submit or Regenerate, then tell me (or paste your
|
||||
preferences here)." After the answer, read `feedback.json` or
|
||||
`feedback-pending.json` next to the board HTML.
|
||||
|
||||
If the command exits nonzero or prints no `BOARD_URL`, show each variant inline
|
||||
with Read and fall back to AskUserQuestion: "Which variant do you prefer? Any feedback?"
|
||||
|
||||
**Step 5: Handle feedback**
|
||||
|
||||
If the JSON contains `"regenerated": true`:
|
||||
1. Read `regenerateAction` (or `remixSpec` for remix requests)
|
||||
2. Generate new variants with `$D iterate` or `$D variants` using the updated brief, rewritten into the brief file (capture and round accounting as in Step 3)
|
||||
3. Rebuild the board with Step 4's board block, without `--serve`
|
||||
4. POST the new HTML to the running board. Parse the board URL from stderr
|
||||
(`BOARD_URL: http://127.0.0.1:N/boards/<id>/` — the daemon path) or fall
|
||||
back to the legacy port (`SERVE_STARTED: port=N` — only emitted under
|
||||
`--no-daemon`, hits `/api/reload` root). Daemon path:
|
||||
`jq -nc --arg html "$_DESIGN_DIR/design-board.html" '{html: $html}' | curl -sS -X POST "${BOARD_URL}api/reload" -H 'Content-Type: application/json' --data-binary @-`
|
||||
5. Board auto-refreshes in the same tab
|
||||
|
||||
If `"regenerated": false`: proceed with the approved variant.
|
||||
|
||||
**Step 6: Save approved choice**
|
||||
|
||||
Write the user's feedback (`none` when they gave none) into the feedback file from Step 2, then map the confirmed letter through this board's `board-images.json` (never the directory listing) and save it, substituting the printed name for `<feedback-file-name>`:
|
||||
|
||||
```bash
|
||||
_IMG=$(jq -r --arg v "<VARIANT>" '.[($v | explode[0]) - 65] // empty' "$_DESIGN_DIR/board-images.json")
|
||||
if [ -n "$_IMG" ]; then
|
||||
FEEDBACK_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<feedback-file-name>"
|
||||
[ -s "$FEEDBACK_FILE" ] || { echo "Not saved: $FEEDBACK_FILE is missing or empty. Write the feedback, then rerun this block." >&2; exit 1; }
|
||||
jq -n --arg approved_variant "<VARIANT>" --arg approved_path "$(basename "$_IMG")" --rawfile feedback "$FEEDBACK_FILE" --arg date "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg screen "mockup" --arg branch "$(git branch --show-current 2>/dev/null)" '$ARGS.named | .feedback |= rtrimstr("\n")' > "$_DESIGN_DIR/approved.json" && rm -f "$FEEDBACK_FILE"
|
||||
echo "APPROVED_IMAGE: $_IMG"
|
||||
else
|
||||
echo "NO_BOARD_IMAGE: <VARIANT> is not on this board; reselect from the board"
|
||||
fi
|
||||
```
|
||||
|
||||
Reference the printed `APPROVED_IMAGE` in the design doc or plan.
|
||||
|
||||
## Visual Sketch (UI ideas only)
|
||||
|
||||
If the chosen approach involves user-facing UI (screens, pages, forms, dashboards,
|
||||
or interactive elements), generate a rough wireframe to help the user visualize it.
|
||||
If the idea is backend-only, infrastructure, or has no UI component — skip this
|
||||
section silently.
|
||||
|
||||
**Step 1: Gather design context**
|
||||
|
||||
1. Check if `DESIGN.md` exists in the repo root. If it does, read it for design
|
||||
system constraints (colors, typography, spacing, component patterns). Use these
|
||||
constraints in the wireframe.
|
||||
2. Apply core design principles:
|
||||
- **Information hierarchy** — what does the user see first, second, third?
|
||||
- **Interaction states** — loading, empty, error, success, partial
|
||||
- **Edge case paranoia** — what if the name is 47 chars? Zero results? Network fails?
|
||||
- **Subtraction default** — "as little design as possible" (Rams). Every element earns its pixels.
|
||||
- **Design for trust** — every interface element builds or erodes user trust.
|
||||
|
||||
**Step 2: Generate wireframe HTML**
|
||||
|
||||
Generate a single-page HTML file with these constraints:
|
||||
- **Intentionally rough aesthetic** — use system fonts, thin gray borders, no color,
|
||||
hand-drawn-style elements. This is a sketch, not a polished mockup.
|
||||
- Self-contained — no external dependencies, no CDN links, inline CSS only
|
||||
- Show the core interaction flow (1-3 screens/states max)
|
||||
- Include realistic placeholder content (not "Lorem ipsum" — use content that
|
||||
matches the actual use case)
|
||||
- Add HTML comments explaining design decisions
|
||||
|
||||
Create a private directory for it first — the renderer serves that whole directory
|
||||
over loopback, so it must be yours alone and hold nothing else (never a fixed,
|
||||
shared /tmp name another user could pre-create):
|
||||
```bash
|
||||
mktemp -d "${TMPDIR:-/tmp}/gstack-sketch.XXXXXX"
|
||||
```
|
||||
Write the sketch to `<that directory>/sketch.html` (Write tool).
|
||||
|
||||
**Step 3: Render and capture**
|
||||
|
||||
`gstack-render` opens the sketch in the Aside browser when it is running — otherwise
|
||||
in gstack's own headless browser (its first line says which: `ENGINE=aside` or
|
||||
`ENGINE=browse`) — and screenshots it:
|
||||
|
||||
```bash
|
||||
bun --no-env-file --config=/dev/null run $HOME/.claude/skills/gstack/bin/gstack-render.ts <sketch-dir>/sketch.html --screenshot <sketch-dir>/sketch.png --width 1280
|
||||
```
|
||||
|
||||
Only if it prints `NEEDS_ASIDE` or `ASIDE_NOT_RUNNING` followed by `ERROR: no browser
|
||||
available` (Aside is not open AND gstack's own browser is not built), skip the render
|
||||
step. Tell the user: "The visual sketch renders through the Aside browser (macOS 15+,
|
||||
aside.com) or gstack's own browser. Open Aside, or run ./setup in the gstack repo, and
|
||||
I'll render the wireframe." Never install either for them.
|
||||
|
||||
**Step 4: Present and iterate**
|
||||
|
||||
Show the screenshot to the user. Ask: "Does this feel right? Want to iterate on the layout?"
|
||||
|
||||
If they want changes, regenerate the HTML with their feedback and re-render.
|
||||
If they approve or say "good enough," proceed.
|
||||
|
||||
**Step 5: Include in design doc**
|
||||
|
||||
Reference the wireframe screenshot in the design doc's "Recommended Approach" section.
|
||||
The screenshot file at `<sketch-dir>/sketch.png` (name the full path in the doc) can be referenced by downstream skills
|
||||
(`/plan-design-review`, `/design-review`) to see what was originally envisioned.
|
||||
|
||||
**Step 6: Outside design voices** (optional)
|
||||
|
||||
After the wireframe is approved, offer outside design perspectives:
|
||||
|
||||
```bash
|
||||
|
||||
if ! _OUTSIDE_CFG=$("$HOME/.claude/skills/gstack/bin/gstack-config" get --stored codex_reviews) || [ "$_OUTSIDE_CFG" = disabled ]; then
|
||||
echo 'CODEX_MODE: disabled'
|
||||
elif ( # GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
); then
|
||||
if command -v codex >/dev/null 2>&1; then echo 'CODEX_MODE: ready'; else echo 'CODEX_MODE: not_installed'; fi
|
||||
else
|
||||
echo 'CODEX_MODE: under_current_harness'
|
||||
fi
|
||||
```
|
||||
|
||||
The historical `CODEX_MODE` variable describes **Codex** availability here. `CODEX_MODE: disabled` or a send's `consent_missing` line: `codex_reviews` is off or unreadable; do not ask; record `outside_status: disabled`. Authentication and configured model validity are checked by the actual invocation, without overriding either. Missing/broken CLI: install or repair Codex; authentication failure: run `codex login`. Otherwise honor this caller’s opt-in/skip choice. Any non-ready outcome is missing outside coverage; follow the caller’s existing fallback. Never substitute another external provider.
|
||||
|
||||
If Codex is available, use AskUserQuestion:
|
||||
> "Want outside design perspectives on the chosen approach? Codex proposes a visual thesis, content plan, and interaction ideas. A Claude subagent proposes an alternative aesthetic direction."
|
||||
>
|
||||
> A) Yes — get outside design voices
|
||||
> B) No — proceed without
|
||||
|
||||
If user chooses A, run both independent voices below and wait for both results before synthesis. They may overlap when the host supports parallel tool calls; the native subagent call remains blocking.
|
||||
|
||||
1. **Codex** (via Bash, `model_reasoning_effort="medium"`):
|
||||
Prompt: "For this product approach, provide: a visual thesis (one sentence — mood, material, energy), a content plan (hero → support → detail → CTA), and 2 interaction ideas that change page feel. Apply beautiful defaults: composition-first, brand-first, cardless, poster not document. Be opinionated." Include the approved product approach and wireframe source in the prepared prompt.
|
||||
|
||||
Write the **complete prompt and context**, including actual plan/spec/source, to a private file. Substitute its shell-quoted path for `<prepared-prompt-file>`; never interpolate user text into shell source. Request a complete design proposal ending with Recommendation: <direction> because <product-specific reason>.
|
||||
|
||||
```bash
|
||||
# GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo 'ERROR: not in a git repo' >&2; exit 1; }
|
||||
_OUTSIDE_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-outside.XXXXXXXX") || exit 1
|
||||
trap 'rm -rf "$_OUTSIDE_TMP"' EXIT
|
||||
_OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
|
||||
cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
|
||||
|
||||
_CODEX_PROBE="$HOME/.claude/skills/gstack/bin/gstack-codex-probe"
|
||||
_CODEX_OUT=$("$_CODEX_PROBE" select-model exec) || exit 1
|
||||
_CODEX_SEL=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SEL: //p')
|
||||
_CODEX_SANDBOX_MODE=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SANDBOX: //p')
|
||||
"$_CODEX_PROBE" check-sandbox || exit 1
|
||||
"$_CODEX_PROBE" show-first-use-notice
|
||||
_OUTSIDE_EXIT=0
|
||||
"$_CODEX_PROBE" run-with-timeout --effort medium 300 codex exec - -C "$_REPO_ROOT" -s "${_CODEX_SANDBOX_MODE:?}" -c "model=\"${_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
|
||||
cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
|
||||
|
||||
cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
|
||||
_OUTSIDE_RC=0
|
||||
bun --no-env-file --config=/dev/null "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" proposal "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
|
||||
case "$_OUTSIDE_RC" in
|
||||
0|3) ;;
|
||||
4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
|
||||
*) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
|
||||
esac
|
||||
echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
|
||||
```
|
||||
|
||||
Use Bash `timeout: 360000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing Recommendation markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Continue completed proposals; native completion does not count as outside coverage. After either outcome, delete only your private prompt; scratch cleanup is automatic.
|
||||
|
||||
Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"design-sketch"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
|
||||
|
||||
2. **Claude subagent** (via Agent tool, `run_in_background: false` when available — subagents default to background since Claude Code v2.1.198; A launch receipt means it went background: await its completion notice.):
|
||||
"For this product approach, what design direction would you recommend? What aesthetic, typography, and interaction patterns fit? What would make this approach feel inevitable to the user? Be specific — font names, hex colors, spacing values. Do not fall back on these defaults: a cream ground with a high-contrast serif and terracotta accent; near-black with one neon accent and glowing edges; italic accent words inside headlines; numbered 01 / 02 / 03 section labels; tiny tracked monospace labels; pill-shaped buttons. If your first idea is one of these, name it and choose again."
|
||||
|
||||
Present Codex output under `CODEX SAYS (design sketch):` and subagent output under `CLAUDE SUBAGENT (design direction):`.
|
||||
Error handling: all non-blocking. On failure, skip and continue.
|
||||
If the approach approved in Phase 4 has no user-facing UI (screens, pages, forms, dashboards, interactive elements), skip to Phase 4.5.
|
||||
> **STOP.** Before Phase 4.25 visual design for an approved approach with user-facing UI (designer mockups, or the HTML sketch when the designer is unavailable), Read `~/.claude/skills/gstack/office-hours/sections/visual-design.md` and execute it
|
||||
> in full. Do not work from memory — that section is the source of truth for this step.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -169,13 +169,13 @@ If no matches found, proceed silently.
|
||||
|
||||
Read ETHOS.md for the full Search Before Building framework (three layers, eureka moments). The preamble's Search Before Building section has the ETHOS.md path.
|
||||
|
||||
After understanding the problem through questioning, search for what the world thinks. This is NOT competitive research (that's /design-consultation's job). This is understanding conventional wisdom so you can evaluate where it's wrong.
|
||||
After the questioning, learn the conventional wisdom (not competitive research) so you can judge where it's wrong.
|
||||
|
||||
**Privacy gate:** Before searching, use AskUserQuestion: "I'd like to search for what the world thinks about this space to inform our discussion. This sends generalized category terms (not your specific idea) to a search engine through your Aside browser (or the WebSearch tool if Aside is not running). OK to proceed?"
|
||||
Options: A) Yes, search away B) Skip — keep this session private
|
||||
If B: skip this phase entirely and proceed to Phase 3. Use only in-distribution knowledge.
|
||||
|
||||
When searching, use **generalized category terms** — never the user's specific product name, proprietary concept, or stealth idea. For example, search "task management app landscape" not "SuperTodo AI-powered task killer."
|
||||
Search **generalized category terms** only, never the user's product name, proprietary concept or stealth idea ("task management app landscape", not "SuperTodo AI-powered task killer").
|
||||
|
||||
If the Aside check did not print `READY`, run the same searches with the WebSearch tool when the host provides it; with neither, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
@@ -202,7 +202,7 @@ Read the top 2-3 sources it cites. Run the three-layer synthesis:
|
||||
|
||||
If no eureka moment exists, say: "The conventional wisdom seems sound here. Let's build on it." Proceed to Phase 3.
|
||||
|
||||
**Important:** This search feeds Phase 3 (Premise Challenge). If you found reasons the conventional approach fails, those become premises to challenge. If conventional wisdom is solid, that raises the bar for any premise that contradicts it.
|
||||
Findings feed Phase 3: reasons the conventional approach fails become premises to challenge; solid conventional wisdom raises the bar for any premise that contradicts it.
|
||||
|
||||
---
|
||||
|
||||
@@ -228,7 +228,13 @@ Use AskUserQuestion to confirm. If the user disagrees with a premise, revise und
|
||||
|
||||
---
|
||||
|
||||
{{CODEX_SECOND_OPINION}}
|
||||
## Phase 3.5: Cross-Model Second Opinion (optional)
|
||||
|
||||
Use AskUserQuestion: "Want a second opinion from an independent AI perspective? It reviews your problem statement, key answers, premises and landscape findings from a structured summary, without this conversation. Usually 2-5 minutes." A) Yes, get a second opinion. B) No, proceed to alternatives.
|
||||
|
||||
If B: skip Phase 3.5 and remember the second opinion did NOT run (the design doc, founder signals and Phase 4 depend on it).
|
||||
If A:
|
||||
{{SECTION:second-opinion}}
|
||||
|
||||
---
|
||||
|
||||
@@ -264,13 +270,14 @@ Rules:
|
||||
|
||||
Emit ONE AskUserQuestion that lists every alternative (A/B and optionally C) as numbered options, using the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — write the question text and call the tool.
|
||||
|
||||
**STOP.** Do NOT proceed to Phase 4.5 (Founder Signal Synthesis), Phase 5 (Design Doc), Phase 6 (Closing), or any design-doc generation until the user responds. A "clearly winning approach" is still an approach decision and still needs explicit user approval before it lands in the design doc. Writing the recommendation in chat prose and continuing forward is the failure mode this gate exists to prevent.
|
||||
**STOP.** Do NOT proceed to Phase 4.25, 4.5, 5 or 6, or write any design doc, until the user responds. A "clearly winning approach" still needs explicit approval; writing the recommendation in prose and continuing is the failure this gate prevents.
|
||||
|
||||
---
|
||||
|
||||
{{DESIGN_MOCKUP}}
|
||||
## Phase 4.25: Visual design (UI ideas only)
|
||||
|
||||
{{DESIGN_SKETCH}}
|
||||
If the approach approved in Phase 4 has no user-facing UI (screens, pages, forms, dashboards, interactive elements), skip to Phase 4.5.
|
||||
{{SECTION:visual-design}}
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -16,6 +16,18 @@
|
||||
"title": "Phase 2B builder-mode brainstorm",
|
||||
"trigger": "giving any builder-mode response (Phase 2B: brainstorm questions and every suggestion, adjacent unlock or riff; holds the operating principles, the wild exemplar, the response posture and the generative questions)"
|
||||
},
|
||||
{
|
||||
"id": "second-opinion",
|
||||
"file": "second-opinion.md",
|
||||
"title": "Phase 3.5 cross-model second opinion",
|
||||
"trigger": "running the Phase 3.5 second opinion the user just accepted (provider preflight, cold-read prompt, dispatch and synthesis)"
|
||||
},
|
||||
{
|
||||
"id": "visual-design",
|
||||
"file": "visual-design.md",
|
||||
"title": "Phase 4.25 visual mockups and sketch",
|
||||
"trigger": "Phase 4.25 visual design for an approved approach with user-facing UI (designer mockups, or the HTML sketch when the designer is unavailable)"
|
||||
},
|
||||
{
|
||||
"id": "design-and-handoff",
|
||||
"file": "design-and-handoff.md",
|
||||
|
||||
@@ -0,0 +1,157 @@
|
||||
<!-- AUTO-GENERATED from second-opinion.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
The user already answered the Phase 3.5 question in SKILL.md with A. Run the provider preflight below, skip its AskUserQuestion, and continue from "If A".
|
||||
|
||||
## Phase 3.5: Cross-Model Second Opinion (optional)
|
||||
|
||||
**Provider preflight:**
|
||||
|
||||
```bash
|
||||
|
||||
if ! _OUTSIDE_CFG=$("$HOME/.claude/skills/gstack/bin/gstack-config" get --stored codex_reviews) || [ "$_OUTSIDE_CFG" = disabled ]; then
|
||||
echo 'CODEX_MODE: disabled'
|
||||
elif ( # GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
); then
|
||||
if command -v codex >/dev/null 2>&1; then echo 'CODEX_MODE: ready'; else echo 'CODEX_MODE: not_installed'; fi
|
||||
else
|
||||
echo 'CODEX_MODE: under_current_harness'
|
||||
fi
|
||||
```
|
||||
|
||||
The historical `CODEX_MODE` variable describes **Codex** availability here. `CODEX_MODE: disabled` or a send's `consent_missing` line: `codex_reviews` is off or unreadable; do not ask; record `outside_status: disabled`. Authentication and configured model validity are checked by the actual invocation, without overriding either. Missing/broken CLI: install or repair Codex; authentication failure: run `codex login`. Otherwise honor this caller’s opt-in/skip choice. Any non-ready outcome is missing outside coverage; follow the caller’s existing fallback. Never substitute another external provider.
|
||||
|
||||
Use AskUserQuestion (regardless of codex availability):
|
||||
|
||||
> Want a second opinion from an independent AI perspective? It will review your problem statement, key answers, premises, and any landscape findings from this session without having seen this conversation — it gets a structured summary. Usually takes 2-5 minutes.
|
||||
> A) Yes, get a second opinion
|
||||
> B) No, proceed to alternatives
|
||||
|
||||
If B: skip Phase 3.5 entirely. Remember that the second opinion did NOT run (affects design doc, founder signals, and Phase 4 below).
|
||||
|
||||
**If A: Run the Codex cold read.**
|
||||
|
||||
1. Assemble a structured context block from Phases 1-3:
|
||||
- Mode (Startup or Builder)
|
||||
- Problem statement (from Phase 1)
|
||||
- Key answers from Phase 2A/2B (summarize each Q&A in 1-2 sentences, include verbatim user quotes)
|
||||
- Landscape findings (from Phase 2.75, if search was run)
|
||||
- Agreed premises (from Phase 3)
|
||||
- Codebase context (project name, languages, recent activity)
|
||||
|
||||
2. **Write the assembled prompt to a temp file** (prevents shell injection from user-derived content):
|
||||
|
||||
```bash
|
||||
OUTSIDE_PROMPT_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-outside-oh-XXXXXXXX") || { echo 'ERROR: mktemp failed; not running the outside voice without its prompt file.' >&2; exit 1; }
|
||||
```
|
||||
|
||||
Write the full prompt to this file. **Always start with the filesystem boundary:**
|
||||
"Filesystem boundary: do not read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. They hold skill definitions, not repository code to review. Do not invoke any installed skill (Codex home skills/, .agents/), hook, or tool instruction; answer directly. Do not modify agents/openai.yaml. Review only the repository code.\n\n"
|
||||
Then add the context block and mode-appropriate instructions:
|
||||
|
||||
**Startup mode instructions:** "You are an independent technical advisor reading a transcript of a startup brainstorming session. [CONTEXT BLOCK HERE]. Your job: 1) What is the STRONGEST version of what this person is trying to build? Steelman it in 2-3 sentences. 2) What is the ONE thing from their answers that reveals the most about what they should actually build? Quote it and explain why. 3) Name ONE agreed premise you think is wrong, and what evidence would prove you right. 4) If you had 48 hours and one engineer to build a prototype, what would you build? Be specific — tech stack, features, what you'd skip. Be direct. Be terse. No preamble."
|
||||
|
||||
**Builder mode instructions:** "You are an independent technical advisor reading a transcript of a builder brainstorming session. [CONTEXT BLOCK HERE]. Your job: 1) What is the COOLEST version of this they haven't considered? 2) What's the ONE thing from their answers that reveals what excites them most? Quote it. 3) What existing open source project or tool gets them 50% of the way there — and what's the 50% they'd need to build? 4) If you had a weekend to build this, what would you build first? Be specific. Be direct. No preamble."
|
||||
|
||||
3. Run Codex with the assembled prompt:
|
||||
|
||||
Write the **complete prompt and context**, including actual plan/spec/source, to a private file. Substitute its shell-quoted path for `<prepared-prompt-file>`; never interpolate user text into shell source. Request a severity (Critical, High, Medium or Low) per finding and a final Recommendation: <action> because <specific reason> line, including an explicit no-findings rationale.
|
||||
|
||||
```bash
|
||||
# GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo 'ERROR: not in a git repo' >&2; exit 1; }
|
||||
_OUTSIDE_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-outside.XXXXXXXX") || exit 1
|
||||
trap 'rm -rf "$_OUTSIDE_TMP"' EXIT
|
||||
_OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
|
||||
cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
|
||||
|
||||
_CODEX_PROBE="$HOME/.claude/skills/gstack/bin/gstack-codex-probe"
|
||||
_CODEX_OUT=$("$_CODEX_PROBE" select-model exec) || exit 1
|
||||
_CODEX_SEL=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SEL: //p')
|
||||
_CODEX_SANDBOX_MODE=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SANDBOX: //p')
|
||||
"$_CODEX_PROBE" check-sandbox || exit 1
|
||||
"$_CODEX_PROBE" show-first-use-notice
|
||||
_OUTSIDE_EXIT=0
|
||||
"$_CODEX_PROBE" run-with-timeout --effort high 300 codex exec - -C "$_REPO_ROOT" -s "${_CODEX_SANDBOX_MODE:?}" -c "model=\"${_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
|
||||
cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
|
||||
|
||||
cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
|
||||
_OUTSIDE_RC=0
|
||||
bun --no-env-file --config=/dev/null "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" review "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
|
||||
case "$_OUTSIDE_RC" in
|
||||
0|3) ;;
|
||||
4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
|
||||
*) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
|
||||
esac
|
||||
echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
|
||||
```
|
||||
|
||||
Use Bash `timeout: 360000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Use the caller's fallback; missing coverage is never clean/PASS. After either outcome, delete only your private prompt; scratch cleanup is automatic.
|
||||
|
||||
**Error handling:** All errors are non-blocking — second opinion is a quality enhancement, not a prerequisite.
|
||||
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run \`codex login\` to authenticate." Fall back to the Claude subagent below.
|
||||
- **Timeout:** "Codex timed out after 5 minutes." Fall back to the Claude subagent below.
|
||||
- **Empty response:** "Codex returned no response." Fall back to the Claude subagent below.
|
||||
|
||||
On any Codex error, fall back to the Claude subagent below.
|
||||
|
||||
**If preflight is not ready (or Codex errored):**
|
||||
|
||||
Dispatch via the Agent tool with `run_in_background: false` when available (subagents default to background since Claude Code v2.1.198; the findings must land before the workflow continues). A launch receipt means it went background: await its completion notice. The subagent has fresh context and no conversation bias — but it is the same harness; model identity stays unknown unless the runtime reports it; weigh its agreement accordingly.
|
||||
|
||||
Subagent prompt: same mode-appropriate prompt as above (Startup or Builder variant).
|
||||
|
||||
Present findings under a `SECOND OPINION (Claude subagent):` header.
|
||||
|
||||
If the subagent fails or times out: "Second opinion unavailable. Continuing to Phase 4."
|
||||
|
||||
Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"office-hours"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
|
||||
|
||||
4. **Presentation:**
|
||||
|
||||
If Codex ran:
|
||||
```
|
||||
SECOND OPINION (Codex):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full codex output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
If Claude subagent ran:
|
||||
```
|
||||
SECOND OPINION (Claude subagent):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full subagent output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
5. **Cross-model synthesis:** After presenting the second opinion output, provide 3-5 bullet synthesis:
|
||||
- Where Claude agrees with the second opinion
|
||||
- Where Claude disagrees and why
|
||||
- Whether the challenged premise changes Claude's recommendation
|
||||
|
||||
6. **Premise revision check:** If Codex challenged an agreed premise, use AskUserQuestion:
|
||||
|
||||
> Codex challenged premise #{N}: "{premise text}". Their argument: "{reasoning}".
|
||||
> A) Revise this premise based on Codex's input
|
||||
> B) Keep the original premise — proceed to alternatives
|
||||
|
||||
If A: revise the premise and note the revision. If B: proceed (and note that the user defended this premise with reasoning — this is a founder signal if they articulate WHY they disagree, not just dismiss).
|
||||
@@ -0,0 +1,3 @@
|
||||
The user already answered the Phase 3.5 question in SKILL.md with A. Run the provider preflight below, skip its AskUserQuestion, and continue from "If A".
|
||||
|
||||
{{CODEX_SECOND_OPINION}}
|
||||
@@ -0,0 +1,283 @@
|
||||
<!-- AUTO-GENERATED from visual-design.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
## Visual Design Exploration
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
D=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/design/dist/design" ] && D="$_ROOT/.claude/skills/gstack/design/dist/design"
|
||||
[ -z "$D" ] && D="$HOME/.claude/skills/gstack/design/dist/design"
|
||||
_DS=$("$HOME/.claude/skills/gstack/bin/gstack-paths" --get GSTACK_STATE_ROOT 2>/dev/null); _DC=${_DS:+$_DS/design-ready}; _DK=$(ls -diL "$D" 2>/dev/null)
|
||||
_dt() { if command -v gtimeout >/dev/null; then gtimeout 10 "$@"; elif command -v timeout >/dev/null; then timeout 10 "$@"
|
||||
elif command -v perl >/dev/null; then perl -e 'alarm(shift);exec(@ARGV)' 10 "$@"; else return 125; fi; }
|
||||
_RC=0; _F="Fix: cd ${D%/design/dist/design} && ./setup"
|
||||
if [ ! -x "$D" ]; then _RC=missing
|
||||
elif [ ! "$_DC" -nt "$D" ] || [ "$(cat "$_DC")" != "$_DK" ]; then _dt "$D" --version >/dev/null 2>&1 </dev/null || _RC=$?
|
||||
fi
|
||||
case "$_RC" in
|
||||
0) echo "DESIGN_READY: $D"; [ -n "$_DC" ] && echo "$_DK" > "$_DC" 2>/dev/null ;;
|
||||
missing) echo "DESIGN_NOT_AVAILABLE: $D is not installed. $_F" ;;
|
||||
124|142) echo "DESIGN_NOT_AVAILABLE: $D --version timed out after 10s" ;;
|
||||
125) echo "DESIGN_NOT_AVAILABLE: no timeout/gtimeout/perl to bound $D" ;;
|
||||
137) echo "DESIGN_NOT_AVAILABLE: $D --version exited 137 (killed at launch; on macOS usually an invalid code signature). $_F" ;;
|
||||
*) echo "DESIGN_NOT_AVAILABLE: $D --version exited $_RC" ;;
|
||||
esac
|
||||
```
|
||||
|
||||
**If `DESIGN_NOT_AVAILABLE`:** Fall back to the HTML wireframe approach below
|
||||
(the existing DESIGN_SKETCH section). Visual mockups require the design binary.
|
||||
|
||||
**If `DESIGN_READY`:** Generate visual mockup explorations for the user.
|
||||
|
||||
Generating visual mockups of the proposed design... (say "skip" if you don't need visuals)
|
||||
|
||||
**Step 1: Set up the design directory**
|
||||
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
|
||||
GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
|
||||
_DESIGN_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/designs/mockup-$(date +%Y%m%d)"
|
||||
mkdir -p "$_DESIGN_DIR"
|
||||
echo "DESIGN_DIR: $_DESIGN_DIR"
|
||||
```
|
||||
|
||||
**Step 2: Construct the design brief**
|
||||
|
||||
Read DESIGN.md if it exists — use it to constrain the visual style. If no DESIGN.md,
|
||||
explore wide across diverse directions. The brief, and the user's feedback in Step 6, go in private files:
|
||||
|
||||
```bash
|
||||
_GT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp"
|
||||
mkdir -p "$_GT" && chmod 700 "$_GT" || { echo "Not sent: cannot create $_GT for the text file." >&2; exit 1; }
|
||||
_EX=$(git rev-parse --git-path info/exclude 2>/dev/null) && mkdir -p "$(dirname "$_EX")" && { grep -qxF '/.gstack/tmp/' "$_EX" 2>/dev/null || echo '/.gstack/tmp/' >> "$_EX"; }
|
||||
BRIEF_FILE=$(mktemp "${_GT:?}/brief.XXXXXX") || { echo "Not sent: mktemp failed in $_GT." >&2; exit 1; }; echo "BRIEF_FILE: $BRIEF_FILE (name: ${BRIEF_FILE##*/})"
|
||||
FEEDBACK_FILE=$(mktemp "${_GT:?}/feedback.XXXXXX") || { echo "Not sent: mktemp failed in $_GT." >&2; exit 1; }; echo "FEEDBACK_FILE: $FEEDBACK_FILE (name: ${FEEDBACK_FILE##*/})"
|
||||
```
|
||||
|
||||
Write the text into each printed file with your file-write tool (Claude Code's Write tool needs a Read of the empty file first), exactly as it should appear. The text never goes into a shell command, heredoc or quoted argument. If a write fails or is refused, do not send: print the cause, the file path and the command below for sending by hand.
|
||||
|
||||
**Step 3: Generate 3 variants** (substitute the printed name for `<brief-file-name>`)
|
||||
|
||||
```bash
|
||||
BRIEF_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<brief-file-name>"
|
||||
[ -s "$BRIEF_FILE" ] || { echo "Not run: $BRIEF_FILE is missing or empty. Write the brief, then rerun this block." >&2; exit 1; }
|
||||
_OUT=$($D variants --brief "$(cat "$BRIEF_FILE")" --count 3 --output-dir "$_DESIGN_DIR/"); _RC=$?
|
||||
printf '%s\n' "$_OUT"; echo "EXIT: $_RC"
|
||||
```
|
||||
|
||||
This generates 3 style variations of the same brief (~40 seconds total).
|
||||
|
||||
<!-- design:round-accounting -->
|
||||
**Round accounting (before any board, check or inline view):** `$D` never overwrites; a taken name is bumped (for example `-2`), so use only the paths its JSON printed and carry them as literal paths into later blocks (bash blocks do not share variables). Tell the user how many of `requested` paid images were saved (`saved`) and name each `failures` entry. Route on the exit code: 0 continue with `saved`; 3 continue with `saved` and say the run stopped early; 2 nothing was saved, so report `failures` and stop: do not run `$D compare` or `$D check`.
|
||||
|
||||
**Step 4: Show variants inline, then open comparison board**
|
||||
|
||||
Show each saved image to the user inline first (read the printed paths with Read tool), then
|
||||
create and serve the comparison board:
|
||||
|
||||
<!-- design:board -->
|
||||
Write this round's board images (printed paths that passed checks, in order) as a JSON array to `$_DESIGN_DIR/board-images.json` with the Write tool; board letters A, B, C follow that order. Then archive any earlier Submit so it cannot approve these images, and build the board:
|
||||
|
||||
```bash
|
||||
[ -f "${_DESIGN_DIR:?set _DESIGN_DIR to the design dir printed above}/feedback.json" ] && mv "${_DESIGN_DIR:?}/feedback.json" "${_DESIGN_DIR:?}/feedback-$(date -u +%Y%m%dT%H%M%SZ).json"
|
||||
$D compare --images-file "$_DESIGN_DIR/board-images.json" --output "$_DESIGN_DIR/design-board.html" --serve
|
||||
```
|
||||
|
||||
This publishes the board to the design daemon, opens it in the user's default
|
||||
browser, and exits; it does not wait for feedback. Read captured stderr for the
|
||||
`BOARD_URL: http://127.0.0.1:N/boards/<id>/` line, then wait with AskUserQuestion:
|
||||
"Review <BOARD_URL>, click Submit or Regenerate, then tell me (or paste your
|
||||
preferences here)." After the answer, read `feedback.json` or
|
||||
`feedback-pending.json` next to the board HTML.
|
||||
|
||||
If the command exits nonzero or prints no `BOARD_URL`, show each variant inline
|
||||
with Read and fall back to AskUserQuestion: "Which variant do you prefer? Any feedback?"
|
||||
|
||||
**Step 5: Handle feedback**
|
||||
|
||||
If the JSON contains `"regenerated": true`:
|
||||
1. Read `regenerateAction` (or `remixSpec` for remix requests)
|
||||
2. Generate new variants with `$D iterate` or `$D variants` using the updated brief, rewritten into the brief file (capture and round accounting as in Step 3)
|
||||
3. Rebuild the board with Step 4's board block, without `--serve`
|
||||
4. POST the new HTML to the running board. Parse the board URL from stderr
|
||||
(`BOARD_URL: http://127.0.0.1:N/boards/<id>/` — the daemon path) or fall
|
||||
back to the legacy port (`SERVE_STARTED: port=N` — only emitted under
|
||||
`--no-daemon`, hits `/api/reload` root). Daemon path:
|
||||
`jq -nc --arg html "$_DESIGN_DIR/design-board.html" '{html: $html}' | curl -sS -X POST "${BOARD_URL}api/reload" -H 'Content-Type: application/json' --data-binary @-`
|
||||
5. Board auto-refreshes in the same tab
|
||||
|
||||
If `"regenerated": false`: proceed with the approved variant.
|
||||
|
||||
**Step 6: Save approved choice**
|
||||
|
||||
Write the user's feedback (`none` when they gave none) into the feedback file from Step 2, then map the confirmed letter through this board's `board-images.json` (never the directory listing) and save it, substituting the printed name for `<feedback-file-name>`:
|
||||
|
||||
```bash
|
||||
_IMG=$(jq -r --arg v "<VARIANT>" '.[($v | explode[0]) - 65] // empty' "$_DESIGN_DIR/board-images.json")
|
||||
if [ -n "$_IMG" ]; then
|
||||
FEEDBACK_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<feedback-file-name>"
|
||||
[ -s "$FEEDBACK_FILE" ] || { echo "Not saved: $FEEDBACK_FILE is missing or empty. Write the feedback, then rerun this block." >&2; exit 1; }
|
||||
jq -n --arg approved_variant "<VARIANT>" --arg approved_path "$(basename "$_IMG")" --rawfile feedback "$FEEDBACK_FILE" --arg date "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg screen "mockup" --arg branch "$(git branch --show-current 2>/dev/null)" '$ARGS.named | .feedback |= rtrimstr("\n")' > "$_DESIGN_DIR/approved.json" && rm -f "$FEEDBACK_FILE"
|
||||
echo "APPROVED_IMAGE: $_IMG"
|
||||
else
|
||||
echo "NO_BOARD_IMAGE: <VARIANT> is not on this board; reselect from the board"
|
||||
fi
|
||||
```
|
||||
|
||||
Reference the printed `APPROVED_IMAGE` in the design doc or plan.
|
||||
|
||||
## Visual Sketch (UI ideas only)
|
||||
|
||||
If the chosen approach involves user-facing UI (screens, pages, forms, dashboards,
|
||||
or interactive elements), generate a rough wireframe to help the user visualize it.
|
||||
If the idea is backend-only, infrastructure, or has no UI component — skip this
|
||||
section silently.
|
||||
|
||||
**Step 1: Gather design context**
|
||||
|
||||
1. Check if `DESIGN.md` exists in the repo root. If it does, read it for design
|
||||
system constraints (colors, typography, spacing, component patterns). Use these
|
||||
constraints in the wireframe.
|
||||
2. Apply core design principles:
|
||||
- **Information hierarchy** — what does the user see first, second, third?
|
||||
- **Interaction states** — loading, empty, error, success, partial
|
||||
- **Edge case paranoia** — what if the name is 47 chars? Zero results? Network fails?
|
||||
- **Subtraction default** — "as little design as possible" (Rams). Every element earns its pixels.
|
||||
- **Design for trust** — every interface element builds or erodes user trust.
|
||||
|
||||
**Step 2: Generate wireframe HTML**
|
||||
|
||||
Generate a single-page HTML file with these constraints:
|
||||
- **Intentionally rough aesthetic** — use system fonts, thin gray borders, no color,
|
||||
hand-drawn-style elements. This is a sketch, not a polished mockup.
|
||||
- Self-contained — no external dependencies, no CDN links, inline CSS only
|
||||
- Show the core interaction flow (1-3 screens/states max)
|
||||
- Include realistic placeholder content (not "Lorem ipsum" — use content that
|
||||
matches the actual use case)
|
||||
- Add HTML comments explaining design decisions
|
||||
|
||||
Create a private directory for it first — the renderer serves that whole directory
|
||||
over loopback, so it must be yours alone and hold nothing else (never a fixed,
|
||||
shared /tmp name another user could pre-create):
|
||||
```bash
|
||||
mktemp -d "${TMPDIR:-/tmp}/gstack-sketch.XXXXXX"
|
||||
```
|
||||
Write the sketch to `<that directory>/sketch.html` (Write tool).
|
||||
|
||||
**Step 3: Render and capture**
|
||||
|
||||
`gstack-render` opens the sketch in the Aside browser when it is running — otherwise
|
||||
in gstack's own headless browser (its first line says which: `ENGINE=aside` or
|
||||
`ENGINE=browse`) — and screenshots it:
|
||||
|
||||
```bash
|
||||
bun --no-env-file --config=/dev/null run $HOME/.claude/skills/gstack/bin/gstack-render.ts <sketch-dir>/sketch.html --screenshot <sketch-dir>/sketch.png --width 1280
|
||||
```
|
||||
|
||||
Only if it prints `NEEDS_ASIDE` or `ASIDE_NOT_RUNNING` followed by `ERROR: no browser
|
||||
available` (Aside is not open AND gstack's own browser is not built), skip the render
|
||||
step. Tell the user: "The visual sketch renders through the Aside browser (macOS 15+,
|
||||
aside.com) or gstack's own browser. Open Aside, or run ./setup in the gstack repo, and
|
||||
I'll render the wireframe." Never install either for them.
|
||||
|
||||
**Step 4: Present and iterate**
|
||||
|
||||
Show the screenshot to the user. Ask: "Does this feel right? Want to iterate on the layout?"
|
||||
|
||||
If they want changes, regenerate the HTML with their feedback and re-render.
|
||||
If they approve or say "good enough," proceed.
|
||||
|
||||
**Step 5: Include in design doc**
|
||||
|
||||
Reference the wireframe screenshot in the design doc's "Recommended Approach" section.
|
||||
The screenshot file at `<sketch-dir>/sketch.png` (name the full path in the doc) can be referenced by downstream skills
|
||||
(`/plan-design-review`, `/design-review`) to see what was originally envisioned.
|
||||
|
||||
**Step 6: Outside design voices** (optional)
|
||||
|
||||
After the wireframe is approved, offer outside design perspectives:
|
||||
|
||||
```bash
|
||||
|
||||
if ! _OUTSIDE_CFG=$("$HOME/.claude/skills/gstack/bin/gstack-config" get --stored codex_reviews) || [ "$_OUTSIDE_CFG" = disabled ]; then
|
||||
echo 'CODEX_MODE: disabled'
|
||||
elif ( # GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
); then
|
||||
if command -v codex >/dev/null 2>&1; then echo 'CODEX_MODE: ready'; else echo 'CODEX_MODE: not_installed'; fi
|
||||
else
|
||||
echo 'CODEX_MODE: under_current_harness'
|
||||
fi
|
||||
```
|
||||
|
||||
The historical `CODEX_MODE` variable describes **Codex** availability here. `CODEX_MODE: disabled` or a send's `consent_missing` line: `codex_reviews` is off or unreadable; do not ask; record `outside_status: disabled`. Authentication and configured model validity are checked by the actual invocation, without overriding either. Missing/broken CLI: install or repair Codex; authentication failure: run `codex login`. Otherwise honor this caller’s opt-in/skip choice. Any non-ready outcome is missing outside coverage; follow the caller’s existing fallback. Never substitute another external provider.
|
||||
|
||||
If Codex is available, use AskUserQuestion:
|
||||
> "Want outside design perspectives on the chosen approach? Codex proposes a visual thesis, content plan, and interaction ideas. A Claude subagent proposes an alternative aesthetic direction."
|
||||
>
|
||||
> A) Yes — get outside design voices
|
||||
> B) No — proceed without
|
||||
|
||||
If user chooses A, run both independent voices below and wait for both results before synthesis. They may overlap when the host supports parallel tool calls; the native subagent call remains blocking.
|
||||
|
||||
1. **Codex** (via Bash, `model_reasoning_effort="medium"`):
|
||||
Prompt: "For this product approach, provide: a visual thesis (one sentence — mood, material, energy), a content plan (hero → support → detail → CTA), and 2 interaction ideas that change page feel. Apply beautiful defaults: composition-first, brand-first, cardless, poster not document. Be opinionated." Include the approved product approach and wireframe source in the prepared prompt.
|
||||
|
||||
Write the **complete prompt and context**, including actual plan/spec/source, to a private file. Substitute its shell-quoted path for `<prepared-prompt-file>`; never interpolate user text into shell source. Request a complete design proposal ending with Recommendation: <direction> because <product-specific reason>.
|
||||
|
||||
```bash
|
||||
# GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo 'ERROR: not in a git repo' >&2; exit 1; }
|
||||
_OUTSIDE_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-outside.XXXXXXXX") || exit 1
|
||||
trap 'rm -rf "$_OUTSIDE_TMP"' EXIT
|
||||
_OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
|
||||
cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
|
||||
|
||||
_CODEX_PROBE="$HOME/.claude/skills/gstack/bin/gstack-codex-probe"
|
||||
_CODEX_OUT=$("$_CODEX_PROBE" select-model exec) || exit 1
|
||||
_CODEX_SEL=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SEL: //p')
|
||||
_CODEX_SANDBOX_MODE=$(echo "$_CODEX_OUT" | sed -n 's/^CODEX_SANDBOX: //p')
|
||||
"$_CODEX_PROBE" check-sandbox || exit 1
|
||||
"$_CODEX_PROBE" show-first-use-notice
|
||||
_OUTSIDE_EXIT=0
|
||||
"$_CODEX_PROBE" run-with-timeout --effort medium 300 codex exec - -C "$_REPO_ROOT" -s "${_CODEX_SANDBOX_MODE:?}" -c "model=\"${_CODEX_SEL:?}\"" -c skills.include_instructions=false -c 'web_search="cached"' --json -o "$_OUTSIDE_TMP/text" <"$_OUTSIDE_INPUT" >"$_OUTSIDE_TMP/events" 2>"$_OUTSIDE_TMP/stderr" || _OUTSIDE_EXIT=$?
|
||||
cat "$_OUTSIDE_TMP/text" 2>/dev/null || tail -n 20 "$_OUTSIDE_TMP/events"
|
||||
|
||||
cat "$_OUTSIDE_TMP/stderr" >&2 || { [ "$_OUTSIDE_EXIT" -ne 0 ] || _OUTSIDE_EXIT=1; }
|
||||
_OUTSIDE_RC=0
|
||||
bun --no-env-file --config=/dev/null "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" --label 'Codex outside review' --exit "$_OUTSIDE_EXIT" --stderr "$_OUTSIDE_TMP/stderr" --events "$_OUTSIDE_TMP/events" proposal "$_OUTSIDE_TMP/text" || _OUTSIDE_RC=$?
|
||||
case "$_OUTSIDE_RC" in
|
||||
0|3) ;;
|
||||
4) echo 'OUTSIDE_STATUS: unverified provider=codex host=claude'; exit 4 ;;
|
||||
*) [ "$_OUTSIDE_EXIT" -ne 0 ] && exit "$_OUTSIDE_EXIT"; exit 1 ;;
|
||||
esac
|
||||
echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
|
||||
```
|
||||
|
||||
Use Bash `timeout: 360000`; show the full response in a `tool-output` fence. Require successful execution and valid markers. Refusal, empty/malformed output, missing Recommendation markers, timeout or CLI failure means `outside_status: unavailable`. P0/P1 findings block like native ones; `OUTSIDE_STATUS: unverified` is missing coverage. Continue completed proposals; native completion does not count as outside coverage. After either outcome, delete only your private prompt; scratch cleanup is automatic.
|
||||
|
||||
Retain the historical review-log skill ID; add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"design-sketch"`. Record differing attempt outcomes separately. `source:"codex"` requires completed CLI output; native uses `source:"in-host"` (historical `source:"claude"`: native Claude). Availability/native fallback is not outside completion. Preserve all reported modelUsage; unknown model identity stays unknown. Under `GSTACK_CODEX_NO_SANDBOX=1` add `"codex_sandbox":"danger-full-access"`.
|
||||
|
||||
2. **Claude subagent** (via Agent tool, `run_in_background: false` when available — subagents default to background since Claude Code v2.1.198; A launch receipt means it went background: await its completion notice.):
|
||||
"For this product approach, what design direction would you recommend? What aesthetic, typography, and interaction patterns fit? What would make this approach feel inevitable to the user? Be specific — font names, hex colors, spacing values. Do not fall back on these defaults: a cream ground with a high-contrast serif and terracotta accent; near-black with one neon accent and glowing edges; italic accent words inside headlines; numbered 01 / 02 / 03 section labels; tiny tracked monospace labels; pill-shaped buttons. If your first idea is one of these, name it and choose again."
|
||||
|
||||
Present Codex output under `CODEX SAYS (design sketch):` and subagent output under `CLAUDE SUBAGENT (design direction):`.
|
||||
Error handling: all non-blocking. On failure, skip and continue.
|
||||
@@ -0,0 +1,3 @@
|
||||
{{DESIGN_MOCKUP}}
|
||||
|
||||
{{DESIGN_SKETCH}}
|
||||
@@ -110,7 +110,7 @@ describe('design printed-paths tripwire', () => {
|
||||
|
||||
describe('design generating flows', () => {
|
||||
const flows: Record<string, string[]> = {
|
||||
'office-hours': ['office-hours/SKILL.md'],
|
||||
'office-hours': ['office-hours/sections/visual-design.md'],
|
||||
'plan-design-review': ['plan-design-review/SKILL.md'],
|
||||
'design-consultation': ['design-consultation/sections/proposal-and-preview.md'],
|
||||
'design-shotgun': ['design-shotgun/SKILL.md'],
|
||||
|
||||
@@ -105,7 +105,7 @@ describe('B4: DESIGN_READY requires a binary that starts', () => {
|
||||
|
||||
test('office-hours visual exploration uses the same probe', () => {
|
||||
const w = world(HOSTS[0].root, 'kill -9 $$');
|
||||
const r = run(fenceAfter(path.join(HOSTS[0].dir('office-hours'), 'SKILL.md'), '## Visual Design Exploration'), w);
|
||||
const r = run(fenceAfter(path.join(HOSTS[0].dir('office-hours'), 'sections', 'visual-design.md'), '## Visual Design Exploration'), w);
|
||||
expect(r.stdout.trim()).toStartWith('DESIGN_NOT_AVAILABLE: ');
|
||||
expect(r.stdout).toContain('exited 137 (killed at launch');
|
||||
});
|
||||
|
||||
@@ -332,7 +332,7 @@ const GENERATED_WITH_GUIDANCE = [
|
||||
'design-consultation/sections/proposal-and-preview.md',
|
||||
'design-review/SKILL.md',
|
||||
'document-release/sections/release-body.md',
|
||||
'office-hours/SKILL.md',
|
||||
'office-hours/sections/second-opinion.md',
|
||||
'office-hours/sections/design-and-handoff.md',
|
||||
'plan-ceo-review/SKILL.md',
|
||||
'plan-ceo-review/sections/review-sections.md',
|
||||
|
||||
Reference in new issue
Block a user