From 147059f1ea5150bb9bdbf89d21d0bf5491b13a9a Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 27 Mar 2026 19:05:13 -0700 Subject: [PATCH] docs: update project documentation for v0.13.0.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- ARCHITECTURE.md | 4 +++- CHANGELOG.md | 4 +--- CLAUDE.md | 27 ++++++++++++++++++++------- README.md | 4 +++- 4 files changed, 27 insertions(+), 12 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3908a2ca..e9d63d83 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -206,6 +206,8 @@ Templates contain the workflows, tips, and examples that require human judgment. | `{{REVIEW_DASHBOARD}}` | `gen-skill-docs.ts` | Review Readiness Dashboard for /ship pre-flight | | `{{TEST_BOOTSTRAP}}` | `gen-skill-docs.ts` | Test framework detection, bootstrap, CI/CD setup for /qa, /ship, /design-review | | `{{CODEX_PLAN_REVIEW}}` | `gen-skill-docs.ts` | Optional cross-model plan review (Codex or Claude subagent fallback) for /plan-ceo-review and /plan-eng-review | +| `{{DESIGN_SETUP}}` | `resolvers/design.ts` | Discovery pattern for `$D` design binary, mirrors `{{BROWSE_SETUP}}` | +| `{{DESIGN_SHOTGUN_LOOP}}` | `resolvers/design.ts` | Shared comparison board feedback loop for /design-shotgun, /plan-design-review, /design-consultation | This is structurally sound — if a command exists in code, it appears in docs. If it doesn't exist, it can't appear. @@ -357,4 +359,4 @@ Tier 1 runs on every `bun test`. Tiers 2+3 are gated behind `EVALS=1`. The idea: - **No MCP protocol.** MCP adds JSON schema overhead per request and requires a persistent connection. Plain HTTP + plain text output is lighter on tokens and easier to debug. - **No multi-user support.** One server per workspace, one user. The token auth is defense-in-depth, not multi-tenancy. - **No Windows/Linux cookie decryption.** macOS Keychain is the only supported credential store. Linux (GNOME Keyring/kwallet) and Windows (DPAPI) are architecturally possible but not implemented. -- **No iframe support.** Playwright can handle iframes but the ref system doesn't cross frame boundaries yet. This is the most-requested missing feature. +- **No iframe auto-discovery.** `$B frame` supports cross-frame interaction (CSS selector, @ref, `--name`, `--url` matching), but the ref system does not auto-crawl iframes during `snapshot`. You must explicitly enter a frame context first. diff --git a/CHANGELOG.md b/CHANGELOG.md index 870705ca..58edb671 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,9 +16,6 @@ gstack can generate real UI mockups. Not ASCII art, not text descriptions of hex - **Screenshot evolution.** `$D evolve` takes a screenshot of your live site and generates a mockup showing how it should look based on your feedback. Starts from reality, not blank canvas. - **Responsive variants.** `$D variants --viewports desktop,tablet,mobile` generates mockups at multiple viewport sizes. - **Design-to-code prompt.** `$D prompt` extracts implementation instructions from an approved mockup: exact hex colors, font sizes, spacing values, component structure. Zero interpretation gap. -- **`{{DESIGN_SHOTGUN_LOOP}}` template resolver.** Shared comparison board feedback loop used by `/design-shotgun`, `/plan-design-review`, and `/design-consultation`. -- **`{{DESIGN_SETUP}}` template resolver.** Discovery pattern for `$D`, mirrors the existing `$B` browse setup. Includes critical path rule enforcing `~/.gstack/projects/$SLUG/designs/` for all design artifacts. - ### Changed - **/office-hours** now generates visual mockup explorations by default (skippable). Comparison board opens in your browser for feedback before generating HTML wireframes. @@ -32,6 +29,7 @@ gstack can generate real UI mockups. Not ASCII art, not text descriptions of hex - New files: `serve.ts` (stateful HTTP server), `gallery.ts` (timeline generation) - Tests: `design/test/serve.test.ts` (11 tests), `design/test/gallery.test.ts` (7 tests) - Full design doc: `docs/designs/DESIGN_TOOLS_V1.md` +- Template resolvers: `{{DESIGN_SETUP}}` (binary discovery), `{{DESIGN_SHOTGUN_LOOP}}` (shared comparison board loop for /design-shotgun, /plan-design-review, /design-consultation) ## [0.12.11.0] - 2026-03-27 — Skill Prefix is Now Your Choice diff --git a/CLAUDE.md b/CLAUDE.md index e1ae6c65..f73f5b94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,6 +65,7 @@ gstack/ │ └── dist/ # Compiled binary ├── scripts/ # Build + DX tooling │ ├── gen-skill-docs.ts # Template → SKILL.md generator +│ ├── resolvers/ # Template resolver modules (preamble, design, review, etc.) │ ├── skill-check.ts # Health dashboard │ └── dev-skill.ts # Watch mode ├── test/ # Skill validation + eval tests @@ -93,6 +94,15 @@ gstack/ ├── document-release/ # /document-release skill (post-ship doc updates) ├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit) ├── design-consultation/ # /design-consultation skill (design system from scratch) +├── design-shotgun/ # /design-shotgun skill (visual design exploration) +├── connect-chrome/ # /connect-chrome skill (headed Chrome with side panel) +├── design/ # Design binary CLI (GPT Image API) +│ ├── src/ # CLI + commands (generate, variants, compare, serve, etc.) +│ ├── test/ # Integration tests +│ └── dist/ # Compiled binary +├── extension/ # Chrome extension (side panel + activity feed) +├── lib/ # Shared libraries (worktree.ts) +├── docs/designs/ # Design documents ├── setup-deploy/ # /setup-deploy skill (one-time deploy config) ├── .github/ # CI workflows + Docker image │ ├── workflows/ # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml @@ -181,13 +191,14 @@ symlinking to create the per-skill symlinks with your preferred naming. Pass gen-skill-docs pipeline, consider whether the changes should be tested in isolation before going live (especially if the user is actively using gstack in other windows). -## Compiled binaries — NEVER commit browse/dist/ +## Compiled binaries — NEVER commit browse/dist/ or design/dist/ -The `browse/dist/` directory contains compiled Bun binaries (`browse`, `find-browse`, -~58MB each). These are Mach-O arm64 only — they do NOT work on Linux, Windows, or -Intel Macs. The `./setup` script already builds from source for every platform, so -the checked-in binaries are redundant. They are tracked by git due to a historical -mistake and should eventually be removed with `git rm --cached`. +The `browse/dist/` and `design/dist/` directories contain compiled Bun binaries +(`browse`, `find-browse`, `design`, ~58MB each). These are Mach-O arm64 only — they +do NOT work on Linux, Windows, or Intel Macs. The `./setup` script already builds +from source for every platform, so the checked-in binaries are redundant. They are +tracked by git due to a historical mistake and should eventually be removed with +`git rm --cached`. **NEVER stage or commit these files.** They show up as modified in `git status` because they're tracked despite `.gitignore` — ignore them. When staging files, @@ -336,4 +347,6 @@ The active skill lives at `~/.claude/skills/gstack/`. After making changes: 2. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main` 3. Rebuild: `cd ~/.claude/skills/gstack && bun run build` -Or copy the binary directly: `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse` +Or copy the binaries directly: +- `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse` +- `cp design/dist/design ~/.claude/skills/gstack/design/dist/design` diff --git a/README.md b/README.md index fa61e86d..9ede0450 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source Open Claude Code and paste this. Claude does the rest. -> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it. +> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it. ### Step 2: Add to your repo so teammates get it (optional) @@ -153,6 +153,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. | | `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. | | `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. | +| `/design-shotgun` | **Design Explorer** | Generate multiple AI design variants, open a comparison board in your browser, and iterate until you approve a direction. Taste memory biases toward your preferences. | | `/qa` | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. | | `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Pure bug report without code changes. | | `/cso` | **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 17 false positive exclusions, 8/10+ confidence gate, independent finding verification. Each finding includes a concrete exploit scenario. | @@ -175,6 +176,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. | | `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. | | `/unfreeze` | **Unlock** — remove the `/freeze` boundary. | +| `/connect-chrome` | **Chrome Controller** — launch your real Chrome controlled by gstack with the Side Panel extension. Watch every action live. | | `/setup-deploy` | **Deploy Configurator** — one-time setup for `/land-and-deploy`. Detects your platform, production URL, and deploy commands. | | `/gstack-upgrade` | **Self-Updater** — upgrade gstack to latest. Detects global vs vendored install, syncs both, shows what changed. |