From 3b0ba7fad18a8792902db5b2bc15712f39627d3d Mon Sep 17 00:00:00 2001 From: garrytan Date: Thu, 8 Oct 2026 15:00:04 +0000 Subject: [PATCH] feat(design-shotgun): generate with Codex's built-in $imagegen on Codex On the Codex host, /design-shotgun now generates and edits mockups with Codex's documented $imagegen skill in its default built-in mode (the image_gen tool), so users signed in with ChatGPT need no OPENAI_API_KEY. The design binary stays for the local comparison board only, images are published with gstack-design-claim as before, and screenshot evolution loads the captured page with view_image before an $imagegen edit. Step 3c-3d moved into a DESIGN_SHOTGUN_GENERATION resolver that returns the existing design-binary text unchanged for every other host; the Claude output differs only in two host-neutral rewordings of the evolve-from-screenshot pointers. DESIGN_SETUP and the regenerate step of the board loop gain matching Codex-only text for design-shotgun. Co-authored-by: Jinzhe Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- README.md | 4 +- design-shotgun/SKILL.md | 6 +- design-shotgun/SKILL.md.tmpl | 63 ++------------------ scripts/resolvers/design.ts | 108 ++++++++++++++++++++++++++++++++++- scripts/resolvers/index.ts | 3 +- test/gen-skill-docs.test.ts | 16 ++++++ 6 files changed, 133 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index c2e4afd43..4d387b6bb 100644 --- a/README.md +++ b/README.md @@ -203,7 +203,9 @@ key against the defaults with `bun run design/scripts/live-model-check.ts`, which always tests the default models and ignores both overrides; the weekly periodic census runs the same check. Set `OPENAI_BASE_URL` to send every `$D` call to an OpenAI-compatible gateway instead of `api.openai.com`; egress -receipts record the gateway host. +receipts record the gateway host. On Codex, `/design-shotgun` generates mockups +with Codex's built-in `$imagegen` skill instead, so it needs no +`OPENAI_API_KEY`; `$D` still builds and serves the comparison board. **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). Rendering a new agent is one TypeScript config file; installing it also needs a diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index 6ed709651..de64a76a5 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -516,8 +516,8 @@ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo ``` If the user referenced a URL or said something like "I don't like how this looks," -screenshot that page with Aside in Step 3c and use `$D evolve` instead of `$D variants` -to generate improvement variants from the existing design. If they didn't name the URL, +screenshot that page with Aside in Step 3c and generate improvement variants from that +screenshot instead of from text alone. If they didn't name the URL, ask for it — never guess which page they mean. If the probe above printed `200`, offer `http://localhost:3000` as the default in the AskUserQuestion below (still ask — never assume). @@ -662,7 +662,7 @@ If D: drop specified concepts, re-present, re-confirm. ### Step 3c: Parallel Generation **If evolving from a screenshot** (user said "I don't like THIS"), take ONE screenshot -of the page the user named, in Aside (PNG — `$D evolve` reads PNG): +of the page the user named, in Aside (PNG, the format the evolve step reads): ```bash aside repl ' diff --git a/design-shotgun/SKILL.md.tmpl b/design-shotgun/SKILL.md.tmpl index 767d544c8..1fc9ec2f3 100644 --- a/design-shotgun/SKILL.md.tmpl +++ b/design-shotgun/SKILL.md.tmpl @@ -138,8 +138,8 @@ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo ``` If the user referenced a URL or said something like "I don't like how this looks," -screenshot that page with Aside in Step 3c and use `$D evolve` instead of `$D variants` -to generate improvement variants from the existing design. If they didn't name the URL, +screenshot that page with Aside in Step 3c and generate improvement variants from that +screenshot instead of from text alone. If they didn't name the URL, ask for it — never guess which page they mean. If the probe above printed `200`, offer `http://localhost:3000` as the default in the AskUserQuestion below (still ask — never assume). @@ -244,7 +244,7 @@ If D: drop specified concepts, re-present, re-confirm. ### Step 3c: Parallel Generation **If evolving from a screenshot** (user said "I don't like THIS"), take ONE screenshot -of the page the user named, in Aside (PNG — `$D evolve` reads PNG): +of the page the user named, in Aside (PNG, the format the evolve step reads): ```bash aside repl ' @@ -259,62 +259,7 @@ console.log("GSTACK_STEP_OK"); Then `cp "/current.png" "$_DESIGN_DIR/current.png"` and Read it so the user sees what you're evolving from. -**Generate every variant with one `$D variants --briefs-file` call.** Write one entry per -confirmed concept to `$_DESIGN_DIR/briefs.json`: a JSON array of `{"brief": ""}` objects, in concept order (A, B, C, ...), at most 7. When -evolving, add `"screenshot": "<_DESIGN_DIR>/current.png"` to every entry. Then run this -Bash call with `timeout: 600000` and wait for it to return. It stages in a fresh per-run -directory: in sandboxed sessions `$D` output under `~/.gstack/` can abort ("The operation -was aborted"), while the temp dir works. - -```bash -_VARIANT_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-variants-XXXXXXXX") -_VARIANTS_JSON=$("$D" variants --briefs-file "$_DESIGN_DIR/briefs.json" --output-dir "$_VARIANT_TMP"); _RC=$? -echo "$_VARIANTS_JSON"; echo "EXIT: $_RC" -``` - -The command starts the variants 1.5s apart, retries rate limits with backoff, regenerates an -empty image once, runs the vision check on each image and regenerates once when it fails -(both images are kept), and starts no new work after 9 minutes. It never overwrites an -image. It prints one `VARIANT__DONE`, `_FAILED` or `_RATE_LIMITED` line per variant -on stderr and JSON on stdout. Each `variants[]` entry has `saved` (every image it saved, in -order; the last is its pick), `operation`, `status`, `error`, `retryable` and -`check.status` (`pass`, `fail` or `skipped`). Exit 0 means at least one variant was -generated (read each status), 2 means nothing was saved, and 1 means the briefs file was -invalid and nothing was billed (the error names the entry and field; fix it and rerun). - -**Publish without overwriting.** Never `cp` or `mv` an image. For each variant, publish every -path in its `saved` list, in order, with -`FINAL=$({{BIN_DIR}}/gstack-design-claim "" "$_DESIGN_DIR/variant-{letter}.png")`. -It never overwrites and prints the final (possibly bumped) path; use FINAL from here on and -report every published path. A variant's last FINAL is its pick. If a claim fails, report the -error; the staged image stays at its saved path. - -### Step 3d: Results - -After the command returns and its images are published: - - -1. Round accounting first: this round's images are exactly the published paths (never a - directory listing; older rounds stay on disk). Tell the user: "{saved} of {N} paid images - saved in ~{actual time}", listing every published path. A `skipped` check is missing - automated coverage, not a pass: say so. -2. For any failures: report explicitly with the error. Do NOT silently skip. Rerun each - failed variant with `retryable: true` once, using its own operation and its brief read - from `briefs.json` as data: - `_BRIEF=$(jq -r --arg v "" '.[($v | explode[0]) - 65].brief' "$_DESIGN_DIR/briefs.json")`, then - `"$D" generate --brief "$_BRIEF" --output "$_VARIANT_TMP/variant-.png"`, or for a - screenshot entry `"$D" evolve --screenshot "$_DESIGN_DIR/current.png" --brief "$_BRIEF" --output "$_VARIANT_TMP/variant-.png"`. - Capture its JSON and exit code, then publish its `outputPath` with the claim helper. -3. If zero variants succeeded: fall back to sequential generation, running `$D generate` - yourself one variant at a time into `$_VARIANT_TMP`, publishing each with the claim - helper and showing each as it lands. Tell the user: "Parallel generation failed (likely - rate limiting). Falling back to sequential..." If that also saves nothing, report the - failures and stop: no board. -4. Read each published image inline (Read tool, the published paths) so the user sees all - variants at once. -5. Proceed to Step 4 with each variant's pick (its last published path), in letter order, - as this round's board images. +{{DESIGN_SHOTGUN_GENERATION}} ## Step 4: Comparison Board + Feedback Loop diff --git a/scripts/resolvers/design.ts b/scripts/resolvers/design.ts index 32d90d871..37a579b9f 100644 --- a/scripts/resolvers/design.ts +++ b/scripts/resolvers/design.ts @@ -1184,6 +1184,15 @@ fi \`\`\``; } +const CODEX_SHOTGUN_SETUP = `On Codex, mockups come from the built-in \`$imagegen\` skill in its default built-in mode +(the host \`image_gen\` tool), which needs no \`OPENAI_API_KEY\`; never use its CLI fallback. +\`$D\` only builds and serves the comparison board (\`$D compare --images-file +/path/board-images.json --output /path/board.html --serve\`, \`$D serve --html /path/board.html\`). +Never run \`$D generate\`, \`variants\`, \`evolve\`, \`iterate\` or \`check\` here. + +If \`DESIGN_NOT_AVAILABLE\`: still generate with \`$imagegen\`, then show the images inline and +collect feedback with AskUserQuestion instead of a board.`; + export function generateDesignSetup(ctx: TemplateContext): string { return `## DESIGN SETUP (run this check BEFORE any design mockup command) @@ -1192,7 +1201,7 @@ ${binaryAssignment(ctx, 'design')} ${designReadyProbe(ctx)} \`\`\` -${ctx.skillName === 'design-consultation' ? `If \`DESIGN_NOT_AVAILABLE\`: use Phase 5 Path B (HTML preview). Mockups are optional. +${ctx.host === 'codex' && ctx.skillName === 'design-shotgun' ? CODEX_SHOTGUN_SETUP : `${ctx.skillName === 'design-consultation' ? `If \`DESIGN_NOT_AVAILABLE\`: use Phase 5 Path B (HTML preview). Mockups are optional. For interactive feedback, use \`compare --serve\` and its printed HTTP URL; opening board HTML directly is only a static preview.` : `If \`DESIGN_NOT_AVAILABLE\`: skip visual mockup generation and fall back to the existing HTML wireframe approach (\`DESIGN_SKETCH\`). Design mockups are a @@ -1213,7 +1222,7 @@ Commands: Image commands never overwrite (a taken name gets \`-2\`) and always print JSON (\`requested\`, \`saved\`, \`failures\`); exit 0 ready, 2 nothing saved, 3 stopped after saving some. Capture without \`set -e\`: \`_OUT=$($D ...); _RC=$?\`. Briefs and feedback are free text: write each into a private \`mktemp\` file under \`.gstack/tmp\` and pass \`"$(cat "$FILE")"\`, never inline.${ctx.skillName === 'design-consultation' ? ` - \`$D extract --image /absolute/path.png\` — print tokens and automatically update DESIGN.md in the current Git repository; no read-only flag -\`generate\` returns \`sessionFile\`; \`iterate\` requires that existing session. \`variants\` returns \`paths\` but creates no session: regenerate with an updated brief instead.` : ''} +\`generate\` returns \`sessionFile\`; \`iterate\` requires that existing session. \`variants\` returns \`paths\` but creates no session: regenerate with an updated brief instead.` : ''}`} **Path rule:** Design artifacts belong in \`$GSTACK_STATE_ROOT/projects/$SLUG/designs/\`. Use \`bin/gstack-paths\` (docs/state-root.md). Keep it even if temporary; never substitute @@ -1308,6 +1317,96 @@ ${designApprovalBlock('mockup', false)} Reference the printed \`APPROVED_IMAGE\` in the design doc or plan.`; } +/** + * /design-shotgun Step 3c-3d. Codex generates with its built-in $imagegen skill + * (no OpenAI API key); every other host uses the design binary. + */ +export function generateDesignShotgunGeneration(ctx: TemplateContext): string { + if (ctx.host === 'codex') return `**Generate each variant with Codex's built-in \`$imagegen\` skill.** Invoke it once per +confirmed concept, in concept order (A, B, C, ...), at most 7, in its default built-in mode +so it uses the host \`image_gen\` tool. Give each call the full variant-specific brief, starting +with \`Use case: ui-mockup\` and carrying the DESIGN.md or taste constraints. When evolving, +load \`$_DESIGN_DIR/current.png\` with \`view_image\` first and use \`$imagegen\` edit mode with +that screenshot as the input, keeping the product, content and purpose recognizable. Do not +run \`scripts/image_gen.py\`, ask for \`OPENAI_API_KEY\`, or run any \`$D\` generation command. +If the built-in tool is unavailable, report that and stop: Codex has no API fallback here. + +**Publish without overwriting.** \`$imagegen\` reports where it saved each image. Never \`cp\` or +\`mv\` one. Publish each with +\`FINAL=$(${ctx.paths.binDir}/gstack-design-claim "" "$_DESIGN_DIR/variant-{letter}.png")\`. +It never overwrites and prints the final (possibly bumped) path; use FINAL from here on. If a +claim fails, report the error; the image stays at its saved path. + +### Step 3d: Results + + +1. Round accounting first: this round's images are exactly the published paths (never a + directory listing; older rounds stay on disk). Tell the user "{saved} of {N} images + saved", listing every published path. There is no automated vision check on Codex: + compare each image with its brief yourself and say so. +2. For any failure: report it explicitly with the error, then retry that variant once with + \`$imagegen\`. Do NOT silently skip. If nothing was saved, report the failures and stop: no board. +3. Load each published image with \`view_image\` so the user sees all variants at once. +4. Proceed to Step 4 with each variant's published path, in letter order, as this round's + board images.`; + return `**Generate every variant with one \`$D variants --briefs-file\` call.** Write one entry per +confirmed concept to \`$_DESIGN_DIR/briefs.json\`: a JSON array of \`{"brief": ""}\` objects, in concept order (A, B, C, ...), at most 7. When +evolving, add \`"screenshot": "<_DESIGN_DIR>/current.png"\` to every entry. Then run this +Bash call with \`timeout: 600000\` and wait for it to return. It stages in a fresh per-run +directory: in sandboxed sessions \`$D\` output under \`~/.gstack/\` can abort ("The operation +was aborted"), while the temp dir works. + +\`\`\`bash +_VARIANT_TMP=$(mktemp -d "\${TMPDIR:-/tmp}/gstack-variants-XXXXXXXX") +_VARIANTS_JSON=$("$D" variants --briefs-file "$_DESIGN_DIR/briefs.json" --output-dir "$_VARIANT_TMP"); _RC=$? +echo "$_VARIANTS_JSON"; echo "EXIT: $_RC" +\`\`\` + +The command starts the variants 1.5s apart, retries rate limits with backoff, regenerates an +empty image once, runs the vision check on each image and regenerates once when it fails +(both images are kept), and starts no new work after 9 minutes. It never overwrites an +image. It prints one \`VARIANT__DONE\`, \`_FAILED\` or \`_RATE_LIMITED\` line per variant +on stderr and JSON on stdout. Each \`variants[]\` entry has \`saved\` (every image it saved, in +order; the last is its pick), \`operation\`, \`status\`, \`error\`, \`retryable\` and +\`check.status\` (\`pass\`, \`fail\` or \`skipped\`). Exit 0 means at least one variant was +generated (read each status), 2 means nothing was saved, and 1 means the briefs file was +invalid and nothing was billed (the error names the entry and field; fix it and rerun). + +**Publish without overwriting.** Never \`cp\` or \`mv\` an image. For each variant, publish every +path in its \`saved\` list, in order, with +\`FINAL=$(${ctx.paths.binDir}/gstack-design-claim "" "$_DESIGN_DIR/variant-{letter}.png")\`. +It never overwrites and prints the final (possibly bumped) path; use FINAL from here on and +report every published path. A variant's last FINAL is its pick. If a claim fails, report the +error; the staged image stays at its saved path. + +### Step 3d: Results + +After the command returns and its images are published: + + +1. Round accounting first: this round's images are exactly the published paths (never a + directory listing; older rounds stay on disk). Tell the user: "{saved} of {N} paid images + saved in ~{actual time}", listing every published path. A \`skipped\` check is missing + automated coverage, not a pass: say so. +2. For any failures: report explicitly with the error. Do NOT silently skip. Rerun each + failed variant with \`retryable: true\` once, using its own operation and its brief read + from \`briefs.json\` as data: + \`_BRIEF=$(jq -r --arg v "" '.[($v | explode[0]) - 65].brief' "$_DESIGN_DIR/briefs.json")\`, then + \`"$D" generate --brief "$_BRIEF" --output "$_VARIANT_TMP/variant-.png"\`, or for a + screenshot entry \`"$D" evolve --screenshot "$_DESIGN_DIR/current.png" --brief "$_BRIEF" --output "$_VARIANT_TMP/variant-.png"\`. + Capture its JSON and exit code, then publish its \`outputPath\` with the claim helper. +3. If zero variants succeeded: fall back to sequential generation, running \`$D generate\` + yourself one variant at a time into \`$_VARIANT_TMP\`, publishing each with the claim + helper and showing each as it lands. Tell the user: "Parallel generation failed (likely + rate limiting). Falling back to sequential..." If that also saves nothing, report the + failures and stop: no board. +4. Read each published image inline (Read tool, the published paths) so the user sees all + variants at once. +5. Proceed to Step 4 with each variant's pick (its last published path), in letter order, + as this round's board images.`; +} + export function generateDesignShotgunLoop(ctx: TemplateContext): string { if (ctx.skillName === 'design-consultation') return `### Comparison Board + Feedback Loop @@ -1342,6 +1441,9 @@ After the response, read current feedback next to the board HTML: **SERVER FALLBACK:** Nonzero exit or no readiness marker: show each variant inline with Read, then AskUserQuestion: "The comparison board server failed to start. Which variant? Any changes?" Route chat feedback as above. **After receiving feedback (any path):** summarize PREFERRED, RATINGS, YOUR NOTES, DIRECTION; AskUserQuestion "Is this right?" A confirmed final choice permits Write of \`$_DESIGN_DIR/approved.json\` with \`approved_variant\`, \`approved_path\` (file name of that letter's entry in this board's \`board-images.json\`, never the directory listing), \`feedback\`, \`date\` (UTC), \`screen\` (the product page depicted by the chosen mockup), and \`branch\` (the current \`git branch --show-current\` result, empty if detached). Use valid JSON, never shell interpolation. This approves the image only; Q-final gates project writes.`; + const regenerate = ctx.host === 'codex' && ctx.skillName === 'design-shotgun' + ? 'Generate new variants with `$imagegen` as in Step 3c, using edit mode on the chosen variant for `more_like_` or remix, then publish and do round accounting as for the first round' + : 'Generate new variants with `$D iterate` or `$D variants` using updated brief (capture the JSON and do round accounting as for the first round)'; return `### Comparison Board + Feedback Loop Create the comparison board and serve it over HTTP: @@ -1404,7 +1506,7 @@ the approved variant. 1. Read \`regenerateAction\` from the JSON (\`"different"\`, \`"match"\`, \`"more_like_B"\`, \`"remix"\`, or custom text) 2. If \`regenerateAction\` is \`"remix"\`, read \`remixSpec\` (e.g. \`{"layout":"A","colors":"B"}\`) -3. Generate new variants with \`$D iterate\` or \`$D variants\` using updated brief (capture the JSON and do round accounting as for the first round) +3. ${regenerate} 4. Rebuild with the board block above (it archives feedback.json and rewrites board-images.json), without \`--serve\` 5. Reload the board in the user's browser (same tab) — the URL is per-board under daemon mode, so use \`\` (from the \`BOARD_URL:\` stderr diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index 1d946b0ae..5a50d17f0 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -21,7 +21,7 @@ import { outsideVoiceFor, outsideVoiceGuard, outsideVoiceInvocation, outsideVoic // Domain modules import { generatePreamble } from './preamble'; import { generateTestFailureTriage } from './preamble'; -import { generateDesignMethodology, generateDesignHardRules, generateDesignOutsideVoices, generateDesignReviewLite, generateDesignSketch, generateDesignSetup, generateDesignMockup, generateDesignShotgunLoop, generateTasteProfile, generateUXPrinciples, generateOverusedFonts, generateDesignSlopBullets, generateDesignDetector, generateDesignMdCheck } from './design'; +import { generateDesignMethodology, generateDesignHardRules, generateDesignOutsideVoices, generateDesignReviewLite, generateDesignSketch, generateDesignSetup, generateDesignMockup, generateDesignShotgunGeneration, generateDesignShotgunLoop, generateTasteProfile, generateUXPrinciples, generateOverusedFonts, generateDesignSlopBullets, generateDesignDetector, generateDesignMdCheck } from './design'; import { generateTestBootstrap, generateTestCoverageAuditPlan, generateTestCoverageAuditShip, generateTestCoverageGateShip } from './testing'; import { generateReviewDashboard, generatePlanFileReviewReport } from './review-dashboard'; import { generatePlanReviewApprovalCheck, generateExitPlanModeGate, generatePlanCompletionAuditShip, generatePlanCompletionGateShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './plan-gates'; @@ -120,6 +120,7 @@ export const RESOLVERS: Record = { DESIGN_SKETCH: generateDesignSketch, DESIGN_SETUP: generateDesignSetup, DESIGN_MOCKUP: generateDesignMockup, + DESIGN_SHOTGUN_GENERATION: generateDesignShotgunGeneration, DESIGN_SHOTGUN_LOOP: generateDesignShotgunLoop, BENEFITS_FROM: generateBenefitsFrom, CODEX_SECOND_OPINION: generateCodexSecondOpinion, diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 5c645729e..0c216f9ef 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -3182,6 +3182,22 @@ describe('Codex generation (--host codex)', () => { expect(codexContent).toContain('gstack-claude-code'); }); + test('codex design-shotgun generates with built-in $imagegen and keeps $D for the board only', () => { + const codex = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-design-shotgun', 'SKILL.md'), 'utf-8'); + for (const phrase of ['`$imagegen`', 'default built-in mode', 'needs no `OPENAI_API_KEY`', 'view_image', 'gstack-design-claim', '$D compare --images-file']) { + expect(codex).toContain(phrase); + } + for (const generator of ['"$D" variants', '"$D" generate', '"$D" evolve', '$D iterate', '`$D variants --brief']) { + expect(codex).not.toContain(generator); + } + const claude = fs.readFileSync(path.join(ROOT, 'design-shotgun', 'SKILL.md'), 'utf-8'); + expect(claude).toContain('"$D" variants --briefs-file'); + expect(claude).not.toContain('$imagegen'); + for (const skill of ['plan-design-review', 'design-consultation']) { + expect(readExternalSkillUnion(EXTERNAL_OUT, '.agents', skill)).not.toContain('$imagegen'); + } + }); + test('codex host does not include Codex design block in ship', () => { const codexContent = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-ship', 'SKILL.md'), 'utf-8'); expect(codexContent).not.toContain('Codex design voice');