first commit
This commit is contained in:
王性驊
commit
0daffeb8c2
|
|
@ -0,0 +1,271 @@
|
|||
# Browser — technical details
|
||||
|
||||
This document covers the command reference and internals of gstack's headless browser.
|
||||
|
||||
## Command reference
|
||||
|
||||
| Category | Commands | What for |
|
||||
|----------|----------|----------|
|
||||
| Navigate | `goto`, `back`, `forward`, `reload`, `url` | Get to a page |
|
||||
| Read | `text`, `html`, `links`, `forms`, `accessibility` | Extract content |
|
||||
| Snapshot | `snapshot [-i] [-c] [-d N] [-s sel] [-D] [-a] [-o] [-C]` | Get refs, diff, annotate |
|
||||
| Interact | `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll`, `wait`, `viewport`, `upload` | Use the page |
|
||||
| Inspect | `js`, `eval`, `css`, `attrs`, `is`, `console`, `network`, `dialog`, `cookies`, `storage`, `perf` | Debug and verify |
|
||||
| Visual | `screenshot [--viewport] [--clip x,y,w,h] [sel\|@ref] [path]`, `pdf`, `responsive` | See what Claude sees |
|
||||
| Compare | `diff <url1> <url2>` | Spot differences between environments |
|
||||
| Dialogs | `dialog-accept [text]`, `dialog-dismiss` | Control alert/confirm/prompt handling |
|
||||
| Tabs | `tabs`, `tab`, `newtab`, `closetab` | Multi-page workflows |
|
||||
| Cookies | `cookie-import`, `cookie-import-browser` | Import cookies from file or real browser |
|
||||
| Multi-step | `chain` (JSON from stdin) | Batch commands in one call |
|
||||
| Handoff | `handoff [reason]`, `resume` | Switch to visible Chrome for user takeover |
|
||||
|
||||
All selector arguments accept CSS selectors, `@e` refs after `snapshot`, or `@c` refs after `snapshot -C`. 50+ commands total plus cookie import.
|
||||
|
||||
## How it works
|
||||
|
||||
gstack's browser is a compiled CLI binary that talks to a persistent local Chromium daemon over HTTP. The CLI is a thin client — it reads a state file, sends a command, and prints the response to stdout. The server does the real work via [Playwright](https://playwright.dev/).
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Claude Code │
|
||||
│ │
|
||||
│ "browse goto https://staging.myapp.com" │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────┐ HTTP POST ┌──────────────┐ │
|
||||
│ │ browse │ ──────────────── │ Bun HTTP │ │
|
||||
│ │ CLI │ localhost:rand │ server │ │
|
||||
│ │ │ Bearer token │ │ │
|
||||
│ │ compiled │ ◄────────────── │ Playwright │──── Chromium │
|
||||
│ │ binary │ plain text │ API calls │ (headless) │
|
||||
│ └──────────┘ └──────────────┘ │
|
||||
│ ~1ms startup persistent daemon │
|
||||
│ auto-starts on first call │
|
||||
│ auto-stops after 30 min idle │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Lifecycle
|
||||
|
||||
1. **First call**: CLI checks `.gstack/browse.json` (in the project root) for a running server. None found — it spawns `bun run browse/src/server.ts` in the background. The server launches headless Chromium via Playwright, picks a random port (10000-60000), generates a bearer token, writes the state file, and starts accepting HTTP requests. This takes ~3 seconds.
|
||||
|
||||
2. **Subsequent calls**: CLI reads the state file, sends an HTTP POST with the bearer token, prints the response. ~100-200ms round trip.
|
||||
|
||||
3. **Idle shutdown**: After 30 minutes with no commands, the server shuts down and cleans up the state file. Next call restarts it automatically.
|
||||
|
||||
4. **Crash recovery**: If Chromium crashes, the server exits immediately (no self-healing — don't hide failure). The CLI detects the dead server on the next call and starts a fresh one.
|
||||
|
||||
### Key components
|
||||
|
||||
```
|
||||
browse/
|
||||
├── src/
|
||||
│ ├── cli.ts # Thin client — reads state file, sends HTTP, prints response
|
||||
│ ├── server.ts # Bun.serve HTTP server — routes commands to Playwright
|
||||
│ ├── browser-manager.ts # Chromium lifecycle — launch, tabs, ref map, crash handling
|
||||
│ ├── snapshot.ts # Accessibility tree → @ref assignment → Locator map + diff/annotate/-C
|
||||
│ ├── read-commands.ts # Non-mutating commands (text, html, links, js, css, is, dialog, etc.)
|
||||
│ ├── write-commands.ts # Mutating commands (click, fill, select, upload, dialog-accept, etc.)
|
||||
│ ├── meta-commands.ts # Server management, chain, diff, snapshot routing
|
||||
│ ├── cookie-import-browser.ts # Decrypt + import cookies from real Chromium browsers
|
||||
│ ├── cookie-picker-routes.ts # HTTP routes for interactive cookie picker UI
|
||||
│ ├── cookie-picker-ui.ts # Self-contained HTML/CSS/JS for cookie picker
|
||||
│ └── buffers.ts # CircularBuffer<T> + console/network/dialog capture
|
||||
├── test/ # Integration tests + HTML fixtures
|
||||
└── dist/
|
||||
└── browse # Compiled binary (~58MB, Bun --compile)
|
||||
```
|
||||
|
||||
### The snapshot system
|
||||
|
||||
The browser's key innovation is ref-based element selection, built on Playwright's accessibility tree API:
|
||||
|
||||
1. `page.locator(scope).ariaSnapshot()` returns a YAML-like accessibility tree
|
||||
2. The snapshot parser assigns refs (`@e1`, `@e2`, ...) to each element
|
||||
3. For each ref, it builds a Playwright `Locator` (using `getByRole` + nth-child)
|
||||
4. The ref-to-Locator map is stored on `BrowserManager`
|
||||
5. Later commands like `click @e3` look up the Locator and call `locator.click()`
|
||||
|
||||
No DOM mutation. No injected scripts. Just Playwright's native accessibility API.
|
||||
|
||||
**Ref staleness detection:** SPAs can mutate the DOM without navigation (React router, tab switches, modals). When this happens, refs collected from a previous `snapshot` may point to elements that no longer exist. To handle this, `resolveRef()` runs an async `count()` check before using any ref — if the element count is 0, it throws immediately with a message telling the agent to re-run `snapshot`. This fails fast (~5ms) instead of waiting for Playwright's 30-second action timeout.
|
||||
|
||||
**Extended snapshot features:**
|
||||
- `--diff` (`-D`): Stores each snapshot as a baseline. On the next `-D` call, returns a unified diff showing what changed. Use this to verify that an action (click, fill, etc.) actually worked.
|
||||
- `--annotate` (`-a`): Injects temporary overlay divs at each ref's bounding box, takes a screenshot with ref labels visible, then removes the overlays. Use `-o <path>` to control the output path.
|
||||
- `--cursor-interactive` (`-C`): Scans for non-ARIA interactive elements (divs with `cursor:pointer`, `onclick`, `tabindex>=0`) using `page.evaluate`. Assigns `@c1`, `@c2`... refs with deterministic `nth-child` CSS selectors. These are elements the ARIA tree misses but users can still click.
|
||||
|
||||
### Screenshot modes
|
||||
|
||||
The `screenshot` command supports four modes:
|
||||
|
||||
| Mode | Syntax | Playwright API |
|
||||
|------|--------|----------------|
|
||||
| Full page (default) | `screenshot [path]` | `page.screenshot({ fullPage: true })` |
|
||||
| Viewport only | `screenshot --viewport [path]` | `page.screenshot({ fullPage: false })` |
|
||||
| Element crop | `screenshot "#sel" [path]` or `screenshot @e3 [path]` | `locator.screenshot()` |
|
||||
| Region clip | `screenshot --clip x,y,w,h [path]` | `page.screenshot({ clip })` |
|
||||
|
||||
Element crop accepts CSS selectors (`.class`, `#id`, `[attr]`) or `@e`/`@c` refs from `snapshot`. Auto-detection: `@e`/`@c` prefix = ref, `.`/`#`/`[` prefix = CSS selector, `--` prefix = flag, everything else = output path.
|
||||
|
||||
Mutual exclusion: `--clip` + selector and `--viewport` + `--clip` both throw errors. Unknown flags (e.g. `--bogus`) also throw.
|
||||
|
||||
### Authentication
|
||||
|
||||
Each server session generates a random UUID as a bearer token. The token is written to the state file (`.gstack/browse.json`) with chmod 600. Every HTTP request must include `Authorization: Bearer <token>`. This prevents other processes on the machine from controlling the browser.
|
||||
|
||||
### Console, network, and dialog capture
|
||||
|
||||
The server hooks into Playwright's `page.on('console')`, `page.on('response')`, and `page.on('dialog')` events. All entries are kept in O(1) circular buffers (50,000 capacity each) and flushed to disk asynchronously via `Bun.write()`:
|
||||
|
||||
- Console: `.gstack/browse-console.log`
|
||||
- Network: `.gstack/browse-network.log`
|
||||
- Dialog: `.gstack/browse-dialog.log`
|
||||
|
||||
The `console`, `network`, and `dialog` commands read from the in-memory buffers, not disk.
|
||||
|
||||
### User handoff
|
||||
|
||||
When the headless browser can't proceed (CAPTCHA, MFA, complex auth), `handoff` opens a visible Chrome window at the exact same page with all cookies, localStorage, and tabs preserved. The user solves the problem manually, then `resume` returns control to the agent with a fresh snapshot.
|
||||
|
||||
```bash
|
||||
$B handoff "Stuck on CAPTCHA at login page" # opens visible Chrome
|
||||
# User solves CAPTCHA...
|
||||
$B resume # returns to headless with fresh snapshot
|
||||
```
|
||||
|
||||
The browser auto-suggests `handoff` after 3 consecutive failures. State is fully preserved across the switch — no re-login needed.
|
||||
|
||||
### Dialog handling
|
||||
|
||||
Dialogs (alert, confirm, prompt) are auto-accepted by default to prevent browser lockup. The `dialog-accept` and `dialog-dismiss` commands control this behavior. For prompts, `dialog-accept <text>` provides the response text. All dialogs are logged to the dialog buffer with type, message, and action taken.
|
||||
|
||||
### JavaScript execution (`js` and `eval`)
|
||||
|
||||
`js` runs a single expression, `eval` runs a JS file. Both support `await` — expressions containing `await` are automatically wrapped in an async context:
|
||||
|
||||
```bash
|
||||
$B js "await fetch('/api/data').then(r => r.json())" # works
|
||||
$B js "document.title" # also works (no wrapping needed)
|
||||
$B eval my-script.js # file with await works too
|
||||
```
|
||||
|
||||
For `eval` files, single-line files return the expression value directly. Multi-line files need explicit `return` when using `await`. Comments containing "await" don't trigger wrapping.
|
||||
|
||||
### Multi-workspace support
|
||||
|
||||
Each workspace gets its own isolated browser instance with its own Chromium process, tabs, cookies, and logs. State is stored in `.gstack/` inside the project root (detected via `git rev-parse --show-toplevel`).
|
||||
|
||||
| Workspace | State file | Port |
|
||||
|-----------|------------|------|
|
||||
| `/code/project-a` | `/code/project-a/.gstack/browse.json` | random (10000-60000) |
|
||||
| `/code/project-b` | `/code/project-b/.gstack/browse.json` | random (10000-60000) |
|
||||
|
||||
No port collisions. No shared state. Each project is fully isolated.
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `BROWSE_PORT` | 0 (random 10000-60000) | Fixed port for the HTTP server (debug override) |
|
||||
| `BROWSE_IDLE_TIMEOUT` | 1800000 (30 min) | Idle shutdown timeout in ms |
|
||||
| `BROWSE_STATE_FILE` | `.gstack/browse.json` | Path to state file (CLI passes to server) |
|
||||
| `BROWSE_SERVER_SCRIPT` | auto-detected | Path to server.ts |
|
||||
|
||||
### Performance
|
||||
|
||||
| Tool | First call | Subsequent calls | Context overhead per call |
|
||||
|------|-----------|-----------------|--------------------------|
|
||||
| Chrome MCP | ~5s | ~2-5s | ~2000 tokens (schema + protocol) |
|
||||
| Playwright MCP | ~3s | ~1-3s | ~1500 tokens (schema + protocol) |
|
||||
| **gstack browse** | **~3s** | **~100-200ms** | **0 tokens** (plain text stdout) |
|
||||
|
||||
The context overhead difference compounds fast. In a 20-command browser session, MCP tools burn 30,000-40,000 tokens on protocol framing alone. gstack burns zero.
|
||||
|
||||
### Why CLI over MCP?
|
||||
|
||||
MCP (Model Context Protocol) works well for remote services, but for local browser automation it adds pure overhead:
|
||||
|
||||
- **Context bloat**: every MCP call includes full JSON schemas and protocol framing. A simple "get the page text" costs 10x more context tokens than it should.
|
||||
- **Connection fragility**: persistent WebSocket/stdio connections drop and fail to reconnect.
|
||||
- **Unnecessary abstraction**: Claude Code already has a Bash tool. A CLI that prints to stdout is the simplest possible interface.
|
||||
|
||||
gstack skips all of this. Compiled binary. Plain text in, plain text out. No protocol. No schema. No connection management.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
The browser automation layer is built on [Playwright](https://playwright.dev/) by Microsoft. Playwright's accessibility tree API, locator system, and headless Chromium management are what make ref-based interaction possible. The snapshot system — assigning `@ref` labels to accessibility tree nodes and mapping them back to Playwright Locators — is built entirely on top of Playwright's primitives. Thank you to the Playwright team for building such a solid foundation.
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Bun](https://bun.sh/) v1.0+
|
||||
- Playwright's Chromium (installed automatically by `bun install`)
|
||||
|
||||
### Quick start
|
||||
|
||||
```bash
|
||||
bun install # install dependencies + Playwright Chromium
|
||||
bun test # run integration tests (~3s)
|
||||
bun run dev <cmd> # run CLI from source (no compile)
|
||||
bun run build # compile to browse/dist/browse
|
||||
```
|
||||
|
||||
### Dev mode vs compiled binary
|
||||
|
||||
During development, use `bun run dev` instead of the compiled binary. It runs `browse/src/cli.ts` directly with Bun, so you get instant feedback without a compile step:
|
||||
|
||||
```bash
|
||||
bun run dev goto https://example.com
|
||||
bun run dev text
|
||||
bun run dev snapshot -i
|
||||
bun run dev click @e3
|
||||
```
|
||||
|
||||
The compiled binary (`bun run build`) is only needed for distribution. It produces a single ~58MB executable at `browse/dist/browse` using Bun's `--compile` flag.
|
||||
|
||||
### Running tests
|
||||
|
||||
```bash
|
||||
bun test # run all tests
|
||||
bun test browse/test/commands # run command integration tests only
|
||||
bun test browse/test/snapshot # run snapshot tests only
|
||||
bun test browse/test/cookie-import-browser # run cookie import unit tests only
|
||||
```
|
||||
|
||||
Tests spin up a local HTTP server (`browse/test/test-server.ts`) serving HTML fixtures from `browse/test/fixtures/`, then exercise the CLI commands against those pages. 203 tests across 3 files, ~15 seconds total.
|
||||
|
||||
### Source map
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `browse/src/cli.ts` | Entry point. Reads `.gstack/browse.json`, sends HTTP to the server, prints response. |
|
||||
| `browse/src/server.ts` | Bun HTTP server. Routes commands to the right handler. Manages idle timeout. |
|
||||
| `browse/src/browser-manager.ts` | Chromium lifecycle — launch, tab management, ref map, crash detection. |
|
||||
| `browse/src/snapshot.ts` | Parses accessibility tree, assigns `@e`/`@c` refs, builds Locator map. Handles `--diff`, `--annotate`, `-C`. |
|
||||
| `browse/src/read-commands.ts` | Non-mutating commands: `text`, `html`, `links`, `js`, `css`, `is`, `dialog`, `forms`, etc. Exports `getCleanText()`. |
|
||||
| `browse/src/write-commands.ts` | Mutating commands: `goto`, `click`, `fill`, `upload`, `dialog-accept`, `useragent` (with context recreation), etc. |
|
||||
| `browse/src/meta-commands.ts` | Server management, chain routing, diff (DRY via `getCleanText`), snapshot delegation. |
|
||||
| `browse/src/cookie-import-browser.ts` | Decrypt Chromium cookies via macOS Keychain + PBKDF2/AES-128-CBC. Auto-detects installed browsers. |
|
||||
| `browse/src/cookie-picker-routes.ts` | HTTP routes for `/cookie-picker/*` — browser list, domain search, import, remove. |
|
||||
| `browse/src/cookie-picker-ui.ts` | Self-contained HTML generator for the interactive cookie picker (dark theme, no frameworks). |
|
||||
| `browse/src/buffers.ts` | `CircularBuffer<T>` (O(1) ring buffer) + console/network/dialog capture with async disk flush. |
|
||||
|
||||
### Deploying to the active skill
|
||||
|
||||
The active skill lives at `~/.claude/skills/gstack/`. After making changes:
|
||||
|
||||
1. Push your branch
|
||||
2. Pull in the skill directory: `cd ~/.claude/skills/gstack && git pull`
|
||||
3. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
|
||||
|
||||
Or copy the binary directly: `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
|
||||
|
||||
### Adding a new command
|
||||
|
||||
1. Add the handler in `read-commands.ts` (non-mutating) or `write-commands.ts` (mutating)
|
||||
2. Register the route in `server.ts`
|
||||
3. Add a test case in `browse/test/commands.test.ts` with an HTML fixture if needed
|
||||
4. Run `bun test` to verify
|
||||
5. Run `bun run build` to compile
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
# gstack Builder Ethos
|
||||
|
||||
These are the principles that shape how gstack thinks, recommends, and builds.
|
||||
They are injected into every workflow skill's preamble automatically. They
|
||||
reflect what we believe about building software in 2026.
|
||||
|
||||
---
|
||||
|
||||
## The Golden Age
|
||||
|
||||
A single person with AI can now build what used to take a team of twenty.
|
||||
The engineering barrier is gone. What remains is taste, judgment, and the
|
||||
willingness to do the complete thing.
|
||||
|
||||
This is not a prediction — it's happening right now. 10,000+ usable lines of
|
||||
code per day. 100+ commits per week. Not by a team. By one person, part-time,
|
||||
using the right tools. The compression ratio between human-team time and
|
||||
AI-assisted time ranges from 3x (research) to 100x (boilerplate):
|
||||
|
||||
| Task type | Human team | AI-assisted | Compression |
|
||||
|-----------------------------|-----------|-------------|-------------|
|
||||
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
|
||||
| Test writing | 1 day | 15 min | ~50x |
|
||||
| Feature implementation | 1 week | 30 min | ~30x |
|
||||
| Bug fix + regression test | 4 hours | 15 min | ~20x |
|
||||
| Architecture / design | 2 days | 4 hours | ~5x |
|
||||
| Research / exploration | 1 day | 3 hours | ~3x |
|
||||
|
||||
This table changes everything about how you make build-vs-skip decisions.
|
||||
The last 10% of completeness that teams used to skip? It costs seconds now.
|
||||
|
||||
---
|
||||
|
||||
## 1. Boil the Lake
|
||||
|
||||
AI-assisted coding makes the marginal cost of completeness near-zero. When
|
||||
the complete implementation costs minutes more than the shortcut — do the
|
||||
complete thing. Every time.
|
||||
|
||||
**Lake vs. ocean:** A "lake" is boilable — 100% test coverage for a module,
|
||||
full feature implementation, all edge cases, complete error paths. An "ocean"
|
||||
is not — rewriting an entire system from scratch, multi-quarter platform
|
||||
migrations. Boil lakes. Flag oceans as out of scope.
|
||||
|
||||
**Completeness is cheap.** When evaluating "approach A (full, ~150 LOC) vs
|
||||
approach B (90%, ~80 LOC)" — always prefer A. The 70-line delta costs
|
||||
seconds with AI coding. "Ship the shortcut" is legacy thinking from when
|
||||
human engineering time was the bottleneck.
|
||||
|
||||
**Anti-patterns:**
|
||||
- "Choose B — it covers 90% with less code." (If A is 70 lines more, choose A.)
|
||||
- "Let's defer tests to a follow-up PR." (Tests are the cheapest lake to boil.)
|
||||
- "This would take 2 weeks." (Say: "2 weeks human / ~1 hour AI-assisted.")
|
||||
|
||||
Read more: https://garryslist.org/posts/boil-the-ocean
|
||||
|
||||
---
|
||||
|
||||
## 2. Search Before Building
|
||||
|
||||
The 1000x engineer's first instinct is "has someone already solved this?" not
|
||||
"let me design it from scratch." Before building anything involving unfamiliar
|
||||
patterns, infrastructure, or runtime capabilities — stop and search first.
|
||||
The cost of checking is near-zero. The cost of not checking is reinventing
|
||||
something worse.
|
||||
|
||||
### Three Layers of Knowledge
|
||||
|
||||
There are three distinct sources of truth when building anything. Understand
|
||||
which layer you're operating in:
|
||||
|
||||
**Layer 1: Tried and true.** Standard patterns, battle-tested approaches,
|
||||
things deeply in distribution. You probably already know these. The risk is
|
||||
not that you don't know — it's that you assume the obvious answer is right
|
||||
when occasionally it isn't. The cost of checking is near-zero. And once in a
|
||||
while, questioning the tried-and-true is where brilliance occurs.
|
||||
|
||||
**Layer 2: New and popular.** Current best practices, blog posts, ecosystem
|
||||
trends. Search for these. But scrutinize what you find — humans are subject
|
||||
to mania. Mr. Market is either too fearful or too greedy. The crowd can be
|
||||
wrong about new things just as easily as old things. Search results are inputs
|
||||
to your thinking, not answers.
|
||||
|
||||
**Layer 3: First principles.** Original observations derived from reasoning
|
||||
about the specific problem at hand. These are the most valuable of all. Prize
|
||||
them above everything else. The best projects both avoid mistakes (don't
|
||||
reinvent the wheel — Layer 1) while also making brilliant observations that
|
||||
are out of distribution (Layer 3).
|
||||
|
||||
### The Eureka Moment
|
||||
|
||||
The most valuable outcome of searching is not finding a solution to copy.
|
||||
It is:
|
||||
|
||||
1. Understanding what everyone is doing and WHY (Layers 1 + 2)
|
||||
2. Applying first-principles reasoning to their assumptions (Layer 3)
|
||||
3. Discovering a clear reason why the conventional approach is wrong
|
||||
|
||||
This is the 11 out of 10. The truly superlative projects are full of these
|
||||
moments — zig while others zag. When you find one, name it. Celebrate it.
|
||||
Build on it.
|
||||
|
||||
**Anti-patterns:**
|
||||
- Rolling a custom solution when the runtime has a built-in. (Layer 1 miss)
|
||||
- Accepting blog posts uncritically in novel territory. (Layer 2 mania)
|
||||
- Assuming tried-and-true is right without questioning premises. (Layer 3 blindness)
|
||||
|
||||
---
|
||||
|
||||
## How They Work Together
|
||||
|
||||
Boil the Lake says: **do the complete thing.**
|
||||
Search Before Building says: **know what exists before you decide what to build.**
|
||||
|
||||
Together: search first, then build the complete version of the right thing.
|
||||
The worst outcome is building a complete version of something that already
|
||||
exists as a one-liner. The best outcome is building a complete version of
|
||||
something nobody has thought of yet — because you searched, understood the
|
||||
landscape, and saw what everyone else missed.
|
||||
|
||||
---
|
||||
|
||||
## Build for Yourself
|
||||
|
||||
The best tools solve your own problem. gstack exists because its creator
|
||||
wanted it. Every feature was built because it was needed, not because it
|
||||
was requested. If you're building something for yourself, trust that instinct.
|
||||
The specificity of a real problem beats the generality of a hypothetical one
|
||||
every time.
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
# gstack-opencode
|
||||
|
||||
Garry Tan's gstack ported to OpenCode. Complete AI engineering workflow with 27 skills.
|
||||
|
||||
## What's Included
|
||||
|
||||
### Sprint Skills (20)
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `/office-hours` | YC Office Hours — reframes your product idea |
|
||||
| `/plan-ceo-review` | CEO review — find the 10-star product |
|
||||
| `/plan-eng-review` | Eng manager — lock architecture, data flow, tests |
|
||||
| `/plan-design-review` | Designer review — rate each dimension 0-10 |
|
||||
| `/design-consultation` | Build a design system from scratch |
|
||||
| `/review` | Staff engineer — find bugs that pass CI |
|
||||
| `/ship` | Release engineer — tests, push, PR |
|
||||
| `/land-and-deploy` | Merge PR, CI, deploy, verify |
|
||||
| `/qa` | QA lead — browser testing, fix bugs |
|
||||
| `/qa-only` | QA reporter — bug report only |
|
||||
| `/design-review` | Designer audit + auto-fix |
|
||||
| `/canary` | SRE — post-deploy monitoring |
|
||||
| `/benchmark` | Performance engineer — Core Web Vitals |
|
||||
| `/document-release` | Technical writer — update docs |
|
||||
| `/retro` | Eng manager — weekly retro |
|
||||
| `/investigate` | Debugger — systematic root-cause |
|
||||
| `/cso` | Security officer — OWASP + STRIDE |
|
||||
| `/codex` | Second opinion — OpenAI Codex review |
|
||||
| `/autoplan` | Auto-review pipeline |
|
||||
| `/setup-deploy` | Deploy configurator |
|
||||
|
||||
### Safety Skills (4)
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `/careful` | Warn before destructive commands |
|
||||
| `/freeze` | Lock edits to one directory |
|
||||
| `/guard` | Full safety: careful + freeze |
|
||||
| `/unfreeze` | Remove freeze restriction |
|
||||
|
||||
### Browse Skills (8)
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `/browse` | Headless Chromium — ~100ms/command |
|
||||
| `/setup-browser-cookies` | Import cookies from real browser |
|
||||
| `/qa` | Browser-based QA testing |
|
||||
| `/design-review` | Visual audit with screenshots |
|
||||
| `/canary` | Monitor deployed app |
|
||||
| `/benchmark` | Performance baselines |
|
||||
| `/land-and-deploy` | Post-deploy verification |
|
||||
| `/setup-browser-cookies` | Session management |
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
- [OpenCode](https://opencode.ai)
|
||||
- [Bun](https://bun.sh) v1.0+
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
### Quick Install
|
||||
|
||||
```bash
|
||||
# Clone this repo
|
||||
git clone https://github.com/your-username/gstack-opencode.git ~/gstack-opencode
|
||||
|
||||
# Run setup
|
||||
cd ~/gstack-opencode && ./setup
|
||||
|
||||
# Add to your shell profile
|
||||
echo 'source ~/gstack-opencode/bin/gstack-env.sh' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
### Manual Install
|
||||
|
||||
```bash
|
||||
# 1. Clone gstack
|
||||
git clone https://github.com/garrytan/gstack.git ~/gstack-opencode/source
|
||||
|
||||
# 2. Build browse
|
||||
cd ~/gstack-opencode/source
|
||||
bun install
|
||||
bun build --compile browse/src/cli.ts --outfile ~/gstack-opencode/browse/dist/browse
|
||||
|
||||
# 3. Link skills to OpenCode
|
||||
mkdir -p ~/.config/opencode/skills/gstack
|
||||
ln -sf ~/gstack-opencode/skills/* ~/.config/opencode/skills/gstack/
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
~/gstack-opencode/
|
||||
├── skills/ # 27 OpenCode skills
|
||||
│ ├── office-hours/SKILL.md
|
||||
│ ├── review/SKILL.md
|
||||
│ ├── browse/SKILL.md
|
||||
│ └── ...
|
||||
├── browse/ # Headless browser engine
|
||||
│ └── dist/browse # Compiled binary (63MB)
|
||||
├── bin/ # Tool scripts
|
||||
│ ├── gstack-env.sh # Environment setup
|
||||
│ ├── gstack-slug # Generate repo slug
|
||||
│ └── ...
|
||||
├── plugin/ # OpenCode plugin
|
||||
│ └── gstack-guardian.js # Safety mechanism
|
||||
├── review/ # Shared assets
|
||||
│ ├── checklist.md
|
||||
│ └── ...
|
||||
├── ETHOS.md # Builder philosophy
|
||||
├── BROWSER.md # Browser command reference
|
||||
├── setup # Installation script
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `GSTACK_OPENCODE_DIR` | Path to gstack-opencode directory |
|
||||
| `GSTACK_BROWSE` | Path to browse binary |
|
||||
|
||||
## Safety Mechanism
|
||||
|
||||
The `/careful`, `/freeze`, and `/guard` skills are implemented as an OpenCode plugin (`plugin/gstack-guardian.js`). It intercepts:
|
||||
|
||||
- **Destructive commands:** `rm -rf`, `DROP TABLE`, `git push --force`, etc.
|
||||
- **Freeze violations:** Edits outside the locked directory
|
||||
|
||||
## Differences from Original gstack
|
||||
|
||||
| Aspect | Claude Code | OpenCode |
|
||||
|--------|-------------|----------|
|
||||
| Hook mechanism | PreToolUse hooks | Plugin `tool.execute.before` |
|
||||
| Environment vars | `${CLAUDE_SKILL_DIR}` | `${GSTACK_OPENCODE_DIR}` |
|
||||
| Safety skills | Shell scripts | JavaScript plugin |
|
||||
| Skill format | YAML + Markdown | YAML + Markdown (simplified) |
|
||||
|
||||
## Credits
|
||||
|
||||
Original gstack by [Garry Tan](https://github.com/garrytan/gstack) — MIT License
|
||||
|
||||
OpenCode port by gstack-opencode contributors
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
# gstack-opencode
|
||||
|
||||
Garry Tan 的 gstack 移植至 OpenCode。完整的 AI 工程工作流程，內含 27 項技能。
|
||||
|
||||
## 內容總覽
|
||||
|
||||
### 衝刺技能（20 項）
|
||||
| 技能 | 功能說明 |
|
||||
|------|----------|
|
||||
| `/office-hours` | YC 辦公時間 — 重新定義你的產品概念 |
|
||||
| `/plan-ceo-review` | CEO 審查 — 找出 10 星級產品 |
|
||||
| `/plan-eng-review` | 工程經理 — 鎖定架構、資料流、測試 |
|
||||
| `/plan-design-review` | 設計師審查 — 各維度評分 0-10 |
|
||||
| `/design-consultation` | 從零建立設計系統 |
|
||||
| `/review` | 資深工程師 — 找出能通過 CI 的錯誤 |
|
||||
| `/ship` | 發佈工程師 — 測試、推送、建立 PR |
|
||||
| `/land-and-deploy` | 合併 PR、CI、部署、驗證 |
|
||||
| `/qa` | QA 主管 — 瀏覽器測試、修復錯誤 |
|
||||
| `/qa-only` | QA 報告員 — 僅產生錯誤報告 |
|
||||
| `/design-review` | 設計師稽核 + 自動修復 |
|
||||
| `/canary` | SRE — 部署後監控 |
|
||||
| `/benchmark` | 效能工程師 — Core Web Vitals |
|
||||
| `/document-release` | 技術文件撰寫 — 更新文件 |
|
||||
| `/retro` | 工程經理 — 每週回顧 |
|
||||
| `/investigate` | 除錯器 — 系統性根因分析 |
|
||||
| `/cso` | 資安長 — OWASP + STRIDE |
|
||||
| `/codex` | 第二意見 — OpenAI Codex 審查 |
|
||||
| `/autoplan` | 自動審查流水線 |
|
||||
| `/setup-deploy` | 部署設定器 |
|
||||
|
||||
### 安全技能（4 項）
|
||||
| 技能 | 功能說明 |
|
||||
|------|----------|
|
||||
| `/careful` | 破壞性指令前發出警告 |
|
||||
| `/freeze` | 鎖定編輯範圍至單一目錄 |
|
||||
| `/guard` | 完整安全防護：careful + freeze |
|
||||
| `/unfreeze` | 解除 freeze 限制 |
|
||||
|
||||
### 瀏覽技能（8 項）
|
||||
| 技能 | 功能說明 |
|
||||
|------|----------|
|
||||
| `/browse` | 無頭 Chromium — 約 100 毫秒/指令 |
|
||||
| `/setup-browser-cookies` | 從真實瀏覽器匯入 Cookie |
|
||||
| `/qa` | 瀏覽器基礎的 QA 測試 |
|
||||
| `/design-review` | 使用截圖進行視覺稽核 |
|
||||
| `/canary` | 監控已部署的應用程式 |
|
||||
| `/benchmark` | 效能基準測試 |
|
||||
| `/land-and-deploy` | 部署後驗證 |
|
||||
| `/setup-browser-cookies` | 工作階段管理 |
|
||||
|
||||
## 安裝說明
|
||||
|
||||
### 系統需求
|
||||
- [OpenCode](https://opencode.ai)
|
||||
- [Bun](https://bun.sh) v1.0+
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
### 快速安裝
|
||||
|
||||
```bash
|
||||
# 複製此儲存庫
|
||||
git clone https://github.com/your-username/gstack-opencode.git ~/gstack-opencode
|
||||
|
||||
# 執行安裝腳本
|
||||
cd ~/gstack-opencode && ./setup
|
||||
|
||||
# 加入至你的 Shell 設定檔
|
||||
echo 'source ~/gstack-opencode/bin/gstack-env.sh' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
### 手動安裝
|
||||
|
||||
```bash
|
||||
# 1. 複製 gstack
|
||||
git clone https://github.com/garrytan/gstack.git ~/gstack-opencode/source
|
||||
|
||||
# 2. 編譯 browse
|
||||
cd ~/gstack-opencode/source
|
||||
bun install
|
||||
bun build --compile browse/src/cli.ts --outfile ~/gstack-opencode/browse/dist/browse
|
||||
|
||||
# 3. 將技能連結至 OpenCode
|
||||
mkdir -p ~/.config/opencode/skills/gstack
|
||||
ln -sf ~/gstack-opencode/skills/* ~/.config/opencode/skills/gstack/
|
||||
```
|
||||
|
||||
## 目錄結構
|
||||
|
||||
```
|
||||
~/gstack-opencode/
|
||||
├── skills/ # 27 項 OpenCode 技能
|
||||
│ ├── office-hours/SKILL.md
|
||||
│ ├── review/SKILL.md
|
||||
│ ├── browse/SKILL.md
|
||||
│ └── ...
|
||||
├── browse/ # 無頭瀏覽器引擎
|
||||
│ └── dist/browse # 已編譯的二進位檔（63MB）
|
||||
├── bin/ # 工具指令稿
|
||||
│ ├── gstack-env.sh # 環境設定
|
||||
│ ├── gstack-slug # 產生儲存庫 slug
|
||||
│ └── ...
|
||||
├── plugin/ # OpenCode 外掛
|
||||
│ └── gstack-guardian.js # 安全機制
|
||||
├── review/ # 共用資產
|
||||
│ ├── checklist.md
|
||||
│ └── ...
|
||||
├── ETHOS.md # 建構者理念
|
||||
├── BROWSER.md # 瀏覽器指令參考
|
||||
├── setup # 安裝指令稿
|
||||
└── README.md # 本檔案
|
||||
```
|
||||
|
||||
## 環境變數
|
||||
|
||||
| 變數名稱 | 說明 |
|
||||
|----------|------|
|
||||
| `GSTACK_OPENCODE_DIR` | gstack-opencode 目錄的路徑 |
|
||||
| `GSTACK_BROWSE` | browse 二進位檔的路徑 |
|
||||
|
||||
## 安全機制
|
||||
|
||||
`/careful`、`/freeze` 和 `/guard` 技能透過 OpenCode 外掛（`plugin/gstack-guardian.js`）實作。它會攔截：
|
||||
|
||||
- **破壞性指令：** `rm -rf`、`DROP TABLE`、`git push --force` 等。
|
||||
- **Freeze 違規：** 在鎖定目錄外的編輯操作。
|
||||
|
||||
## 與原版 gstack 的差異
|
||||
|
||||
| 面向 | Claude Code | OpenCode |
|
||||
|------|-------------|----------|
|
||||
| 鉤子機制 | PreToolUse hooks | 外掛 `tool.execute.before` |
|
||||
| 環境變數 | `${CLAUDE_SKILL_DIR}` | `${GSTACK_OPENCODE_DIR}` |
|
||||
| 安全技能 | Shell 指令稿 | JavaScript 外掛 |
|
||||
| 技能格式 | YAML + Markdown | YAML + Markdown（簡化版） |
|
||||
|
||||
## 致謝
|
||||
|
||||
原版 gstack 由 [Garry Tan](https://github.com/garrytan/gstack) 開發 — MIT 授權條款
|
||||
|
||||
OpenCode 移植由 gstack-opencode 貢獻者完成
|
||||
|
||||
## 授權條款
|
||||
|
||||
MIT
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
#!/usr/bin/env bash
|
||||
# Set up gstack for local development — test skills from within this repo.
|
||||
#
|
||||
# Creates .claude/skills/gstack → (symlink to repo root) so Claude Code
|
||||
# discovers skills from your working tree. Changes take effect immediately.
|
||||
#
|
||||
# Also copies .env from the main worktree if this is a Conductor workspace
|
||||
# or git worktree (so API keys carry over automatically).
|
||||
#
|
||||
# Usage: bin/dev-setup # set up
|
||||
# bin/dev-teardown # clean up
|
||||
set -e
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
# 1. Copy .env from main worktree (if we're a worktree and don't have one)
|
||||
if [ ! -f "$REPO_ROOT/.env" ]; then
|
||||
MAIN_WORKTREE="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | head -1 | sed 's/^worktree //')"
|
||||
if [ -n "$MAIN_WORKTREE" ] && [ "$MAIN_WORKTREE" != "$REPO_ROOT" ] && [ -f "$MAIN_WORKTREE/.env" ]; then
|
||||
cp "$MAIN_WORKTREE/.env" "$REPO_ROOT/.env"
|
||||
echo "Copied .env from main worktree ($MAIN_WORKTREE)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# 2. Install dependencies
|
||||
if [ ! -d "$REPO_ROOT/node_modules" ]; then
|
||||
echo "Installing dependencies..."
|
||||
(cd "$REPO_ROOT" && bun install)
|
||||
fi
|
||||
|
||||
# 3. Create .claude/skills/ inside the repo
|
||||
mkdir -p "$REPO_ROOT/.claude/skills"
|
||||
|
||||
# 4. Symlink .claude/skills/gstack → repo root
|
||||
# This makes setup think it's inside a real .claude/skills/ directory
|
||||
GSTACK_LINK="$REPO_ROOT/.claude/skills/gstack"
|
||||
if [ -L "$GSTACK_LINK" ]; then
|
||||
echo "Updating existing symlink..."
|
||||
rm "$GSTACK_LINK"
|
||||
elif [ -d "$GSTACK_LINK" ]; then
|
||||
echo "Error: .claude/skills/gstack is a real directory, not a symlink." >&2
|
||||
echo "Remove it manually if you want to use dev mode." >&2
|
||||
exit 1
|
||||
fi
|
||||
ln -s "$REPO_ROOT" "$GSTACK_LINK"
|
||||
|
||||
# 5. Create .agents/skills/gstack → repo root (for Codex/Gemini/Cursor)
|
||||
mkdir -p "$REPO_ROOT/.agents/skills"
|
||||
AGENTS_LINK="$REPO_ROOT/.agents/skills/gstack"
|
||||
if [ -L "$AGENTS_LINK" ]; then
|
||||
rm "$AGENTS_LINK"
|
||||
elif [ -d "$AGENTS_LINK" ]; then
|
||||
echo "Warning: .agents/skills/gstack is a real directory, skipping." >&2
|
||||
fi
|
||||
if [ ! -e "$AGENTS_LINK" ]; then
|
||||
ln -s "$REPO_ROOT" "$AGENTS_LINK"
|
||||
fi
|
||||
|
||||
# 6. Run setup via the symlink so it detects .claude/skills/ as its parent
|
||||
"$GSTACK_LINK/setup"
|
||||
|
||||
echo ""
|
||||
echo "Dev mode active. Skills resolve from this working tree."
|
||||
echo " .claude/skills/gstack → $REPO_ROOT"
|
||||
echo " .agents/skills/gstack → $REPO_ROOT"
|
||||
echo "Edit any SKILL.md and test immediately — no copy/deploy needed."
|
||||
echo ""
|
||||
echo "To tear down: bin/dev-teardown"
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
#!/usr/bin/env bash
|
||||
# Remove local dev skill symlinks. Restores global gstack as the active install.
|
||||
set -e
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
|
||||
removed=()
|
||||
|
||||
# ─── Clean up .claude/skills/ ─────────────────────────────────
|
||||
CLAUDE_SKILLS="$REPO_ROOT/.claude/skills"
|
||||
if [ -d "$CLAUDE_SKILLS" ]; then
|
||||
for link in "$CLAUDE_SKILLS"/*/; do
|
||||
name="$(basename "$link")"
|
||||
[ "$name" = "gstack" ] && continue
|
||||
if [ -L "${link%/}" ]; then
|
||||
rm "${link%/}"
|
||||
removed+=("claude/$name")
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -L "$CLAUDE_SKILLS/gstack" ]; then
|
||||
rm "$CLAUDE_SKILLS/gstack"
|
||||
removed+=("claude/gstack")
|
||||
fi
|
||||
|
||||
rmdir "$CLAUDE_SKILLS" 2>/dev/null || true
|
||||
rmdir "$REPO_ROOT/.claude" 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# ─── Clean up .agents/skills/ ────────────────────────────────
|
||||
AGENTS_SKILLS="$REPO_ROOT/.agents/skills"
|
||||
if [ -d "$AGENTS_SKILLS" ]; then
|
||||
for link in "$AGENTS_SKILLS"/*/; do
|
||||
name="$(basename "$link")"
|
||||
[ "$name" = "gstack" ] && continue
|
||||
if [ -L "${link%/}" ]; then
|
||||
rm "${link%/}"
|
||||
removed+=("agents/$name")
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -L "$AGENTS_SKILLS/gstack" ]; then
|
||||
rm "$AGENTS_SKILLS/gstack"
|
||||
removed+=("agents/gstack")
|
||||
fi
|
||||
|
||||
rmdir "$AGENTS_SKILLS" 2>/dev/null || true
|
||||
rmdir "$REPO_ROOT/.agents" 2>/dev/null || true
|
||||
fi
|
||||
|
||||
if [ ${#removed[@]} -gt 0 ]; then
|
||||
echo "Removed: ${removed[*]}"
|
||||
else
|
||||
echo "No symlinks found."
|
||||
fi
|
||||
echo "Dev mode deactivated. Global gstack (~/.claude/skills/gstack) is now active."
|
||||
|
|
@ -0,0 +1,191 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-analytics — personal usage dashboard from local JSONL
|
||||
#
|
||||
# Usage:
|
||||
# gstack-analytics # default: last 7 days
|
||||
# gstack-analytics 7d # last 7 days
|
||||
# gstack-analytics 30d # last 30 days
|
||||
# gstack-analytics all # all time
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_STATE_DIR — override ~/.gstack state directory
|
||||
set -uo pipefail
|
||||
|
||||
STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
|
||||
JSONL_FILE="$STATE_DIR/analytics/skill-usage.jsonl"
|
||||
|
||||
# ─── Parse time window ───────────────────────────────────────
|
||||
WINDOW="${1:-7d}"
|
||||
case "$WINDOW" in
|
||||
7d) DAYS=7; LABEL="last 7 days" ;;
|
||||
30d) DAYS=30; LABEL="last 30 days" ;;
|
||||
all) DAYS=0; LABEL="all time" ;;
|
||||
*) DAYS=7; LABEL="last 7 days" ;;
|
||||
esac
|
||||
|
||||
# ─── Check for data ──────────────────────────────────────────
|
||||
if [ ! -f "$JSONL_FILE" ]; then
|
||||
echo "gstack usage — no data yet"
|
||||
echo ""
|
||||
echo "Usage data will appear here after you use gstack skills"
|
||||
echo "with telemetry enabled (gstack-config set telemetry anonymous)."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
TOTAL_LINES="$(wc -l < "$JSONL_FILE" | tr -d ' ')"
|
||||
if [ "$TOTAL_LINES" = "0" ]; then
|
||||
echo "gstack usage — no data yet"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Filter by time window ───────────────────────────────────
|
||||
if [ "$DAYS" -gt 0 ] 2>/dev/null; then
|
||||
# Calculate cutoff date
|
||||
if date -v-1d +%Y-%m-%d >/dev/null 2>&1; then
|
||||
# macOS date
|
||||
CUTOFF="$(date -v-${DAYS}d -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
else
|
||||
# GNU date
|
||||
CUTOFF="$(date -u -d "$DAYS days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "2000-01-01T00:00:00Z")"
|
||||
fi
|
||||
# Filter: skill_run events (new format) OR basic skill events (old format, no event_type)
|
||||
# Old format: {"skill":"X","ts":"Y","repo":"Z"} (no event_type field)
|
||||
# New format: {"event_type":"skill_run","skill":"X","ts":"Y",...}
|
||||
FILTERED="$(awk -F'"' -v cutoff="$CUTOFF" '
|
||||
/"ts":"/ {
|
||||
# Skip hook_fire events
|
||||
if (/"event":"hook_fire"/) next
|
||||
# Skip non-skill_run new-format events
|
||||
if (/"event_type":"/ && !/"event_type":"skill_run"/) next
|
||||
for (i=1; i<=NF; i++) {
|
||||
if ($i == "ts" && $(i+1) ~ /^:/) {
|
||||
ts = $(i+2)
|
||||
if (ts >= cutoff) { print; break }
|
||||
}
|
||||
}
|
||||
}
|
||||
' "$JSONL_FILE")"
|
||||
else
|
||||
# All time: include skill_run events + old-format basic events, exclude hook_fire
|
||||
FILTERED="$(awk '/"ts":"/ && !/"event":"hook_fire"/' "$JSONL_FILE" | grep -v '"event_type":"upgrade_' 2>/dev/null || true)"
|
||||
fi
|
||||
|
||||
if [ -z "$FILTERED" ]; then
|
||||
echo "gstack usage ($LABEL) — no skill runs found"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Aggregate by skill ──────────────────────────────────────
|
||||
# Extract skill names and count
|
||||
SKILL_COUNTS="$(echo "$FILTERED" | awk -F'"' '
|
||||
/"skill":"/ {
|
||||
for (i=1; i<=NF; i++) {
|
||||
if ($i == "skill" && $(i+1) ~ /^:/) {
|
||||
skill = $(i+2)
|
||||
counts[skill]++
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
END {
|
||||
for (s in counts) print counts[s], s
|
||||
}
|
||||
' | sort -rn)"
|
||||
|
||||
# Count outcomes
|
||||
TOTAL="$(echo "$FILTERED" | wc -l | tr -d ' ')"
|
||||
SUCCESS="$(echo "$FILTERED" | grep -c '"outcome":"success"' || true)"
|
||||
SUCCESS="${SUCCESS:-0}"; SUCCESS="$(echo "$SUCCESS" | tr -d ' \n\r\t')"
|
||||
ERRORS="$(echo "$FILTERED" | grep -c '"outcome":"error"' || true)"
|
||||
ERRORS="${ERRORS:-0}"; ERRORS="$(echo "$ERRORS" | tr -d ' \n\r\t')"
|
||||
# Old format events have no outcome field — count them as successful
|
||||
NO_OUTCOME="$(echo "$FILTERED" | grep -vc '"outcome":' || true)"
|
||||
NO_OUTCOME="${NO_OUTCOME:-0}"; NO_OUTCOME="$(echo "$NO_OUTCOME" | tr -d ' \n\r\t')"
|
||||
SUCCESS=$(( SUCCESS + NO_OUTCOME ))
|
||||
|
||||
# Calculate success rate
|
||||
if [ "$TOTAL" -gt 0 ] 2>/dev/null; then
|
||||
SUCCESS_RATE=$(( SUCCESS * 100 / TOTAL ))
|
||||
else
|
||||
SUCCESS_RATE=100
|
||||
fi
|
||||
|
||||
# ─── Calculate total duration ────────────────────────────────
|
||||
TOTAL_DURATION="$(echo "$FILTERED" | awk -F'[:,]' '
|
||||
/"duration_s"/ {
|
||||
for (i=1; i<=NF; i++) {
|
||||
if ($i ~ /"duration_s"/) {
|
||||
val = $(i+1)
|
||||
gsub(/[^0-9.]/, "", val)
|
||||
if (val+0 > 0) total += val
|
||||
}
|
||||
}
|
||||
}
|
||||
END { printf "%.0f", total }
|
||||
')"
|
||||
|
||||
# Format duration
|
||||
TOTAL_DURATION="${TOTAL_DURATION:-0}"
|
||||
if [ "$TOTAL_DURATION" -ge 3600 ] 2>/dev/null; then
|
||||
HOURS=$(( TOTAL_DURATION / 3600 ))
|
||||
MINS=$(( (TOTAL_DURATION % 3600) / 60 ))
|
||||
DUR_DISPLAY="${HOURS}h ${MINS}m"
|
||||
elif [ "$TOTAL_DURATION" -ge 60 ] 2>/dev/null; then
|
||||
MINS=$(( TOTAL_DURATION / 60 ))
|
||||
DUR_DISPLAY="${MINS}m"
|
||||
else
|
||||
DUR_DISPLAY="${TOTAL_DURATION}s"
|
||||
fi
|
||||
|
||||
# ─── Render output ───────────────────────────────────────────
|
||||
echo "gstack usage ($LABEL)"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
|
||||
# Find max count for bar scaling
|
||||
MAX_COUNT="$(echo "$SKILL_COUNTS" | head -1 | awk '{print $1}')"
|
||||
BAR_WIDTH=20
|
||||
|
||||
echo "$SKILL_COUNTS" | while read -r COUNT SKILL; do
|
||||
# Scale bar
|
||||
if [ "$MAX_COUNT" -gt 0 ] 2>/dev/null; then
|
||||
BAR_LEN=$(( COUNT * BAR_WIDTH / MAX_COUNT ))
|
||||
else
|
||||
BAR_LEN=1
|
||||
fi
|
||||
[ "$BAR_LEN" -lt 1 ] && BAR_LEN=1
|
||||
|
||||
# Build bar
|
||||
BAR=""
|
||||
i=0
|
||||
while [ "$i" -lt "$BAR_LEN" ]; do
|
||||
BAR="${BAR}█"
|
||||
i=$(( i + 1 ))
|
||||
done
|
||||
|
||||
# Calculate avg duration for this skill
|
||||
AVG_DUR="$(echo "$FILTERED" | awk -v skill="$SKILL" '
|
||||
index($0, "\"skill\":\"" skill "\"") > 0 {
|
||||
# Extract duration_s value using split on "duration_s":
|
||||
n = split($0, parts, "\"duration_s\":")
|
||||
if (n >= 2) {
|
||||
# parts[2] starts with the value, e.g. "142,"
|
||||
gsub(/[^0-9.].*/, "", parts[2])
|
||||
if (parts[2]+0 > 0) { total += parts[2]; count++ }
|
||||
}
|
||||
}
|
||||
END { if (count > 0) printf "%.0f", total/count; else print "0" }
|
||||
')"
|
||||
|
||||
# Format avg duration
|
||||
if [ "$AVG_DUR" -ge 60 ] 2>/dev/null; then
|
||||
AVG_DISPLAY="$(( AVG_DUR / 60 ))m"
|
||||
else
|
||||
AVG_DISPLAY="${AVG_DUR}s"
|
||||
fi
|
||||
|
||||
printf " /%-20s %s %d runs (avg %s)\n" "$SKILL" "$BAR" "$COUNT" "$AVG_DISPLAY"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Success rate: ${SUCCESS_RATE}% | Errors: ${ERRORS} | Total time: ${DUR_DISPLAY}"
|
||||
echo "Events: ${TOTAL} skill runs"
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-community-dashboard — community usage stats from Supabase
|
||||
#
|
||||
# Queries the Supabase REST API to show community-wide gstack usage:
|
||||
# skill popularity, crash clusters, version distribution, retention.
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_DIR — override auto-detected gstack root
|
||||
# GSTACK_SUPABASE_URL — override Supabase project URL
|
||||
# GSTACK_SUPABASE_ANON_KEY — override Supabase anon key
|
||||
set -uo pipefail
|
||||
|
||||
GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
|
||||
|
||||
# Source Supabase config if not overridden by env
|
||||
if [ -z "${GSTACK_SUPABASE_URL:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
|
||||
. "$GSTACK_DIR/supabase/config.sh"
|
||||
fi
|
||||
SUPABASE_URL="${GSTACK_SUPABASE_URL:-}"
|
||||
ANON_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
|
||||
|
||||
if [ -z "$SUPABASE_URL" ] || [ -z "$ANON_KEY" ]; then
|
||||
echo "gstack community dashboard"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
echo "Supabase not configured yet. The community dashboard will be"
|
||||
echo "available once the gstack Supabase project is set up."
|
||||
echo ""
|
||||
echo "For local analytics, run: gstack-analytics"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Helper: query Supabase REST API ─────────────────────────
|
||||
query() {
|
||||
local table="$1"
|
||||
local params="${2:-}"
|
||||
curl -sf --max-time 10 \
|
||||
"${SUPABASE_URL}/rest/v1/${table}?${params}" \
|
||||
-H "apikey: ${ANON_KEY}" \
|
||||
-H "Authorization: Bearer ${ANON_KEY}" \
|
||||
2>/dev/null || echo "[]"
|
||||
}
|
||||
|
||||
echo "gstack community dashboard"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
# ─── Weekly active installs ──────────────────────────────────
|
||||
WEEK_AGO="$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")"
|
||||
if [ -n "$WEEK_AGO" ]; then
|
||||
PULSE="$(curl -sf --max-time 10 \
|
||||
"${SUPABASE_URL}/functions/v1/community-pulse" \
|
||||
-H "Authorization: Bearer ${ANON_KEY}" \
|
||||
2>/dev/null || echo '{"weekly_active":0}')"
|
||||
|
||||
WEEKLY="$(echo "$PULSE" | grep -o '"weekly_active":[0-9]*' | grep -o '[0-9]*' || echo "0")"
|
||||
CHANGE="$(echo "$PULSE" | grep -o '"change_pct":[0-9-]*' | grep -o '[0-9-]*' || echo "0")"
|
||||
|
||||
echo "Weekly active installs: ${WEEKLY}"
|
||||
if [ "$CHANGE" -gt 0 ] 2>/dev/null; then
|
||||
echo " Change: +${CHANGE}%"
|
||||
elif [ "$CHANGE" -lt 0 ] 2>/dev/null; then
|
||||
echo " Change: ${CHANGE}%"
|
||||
fi
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# ─── Skill popularity (top 10) ───────────────────────────────
|
||||
echo "Top skills (last 7 days)"
|
||||
echo "────────────────────────"
|
||||
|
||||
# Query telemetry_events, group by skill
|
||||
EVENTS="$(query "telemetry_events" "select=skill,gstack_version&event_type=eq.skill_run&event_timestamp=gte.${WEEK_AGO}&limit=1000" 2>/dev/null || echo "[]")"
|
||||
|
||||
if [ "$EVENTS" != "[]" ] && [ -n "$EVENTS" ]; then
|
||||
echo "$EVENTS" | grep -o '"skill":"[^"]*"' | awk -F'"' '{print $4}' | sort | uniq -c | sort -rn | head -10 | while read -r COUNT SKILL; do
|
||||
printf " /%-20s %d runs\n" "$SKILL" "$COUNT"
|
||||
done
|
||||
else
|
||||
echo " No data yet"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# ─── Crash clusters ──────────────────────────────────────────
|
||||
echo "Top crash clusters"
|
||||
echo "──────────────────"
|
||||
|
||||
CRASHES="$(query "crash_clusters" "select=error_class,gstack_version,total_occurrences,identified_users&limit=5" 2>/dev/null || echo "[]")"
|
||||
|
||||
if [ "$CRASHES" != "[]" ] && [ -n "$CRASHES" ]; then
|
||||
echo "$CRASHES" | grep -o '"error_class":"[^"]*"' | awk -F'"' '{print $4}' | head -5 | while read -r ERR; do
|
||||
C="$(echo "$CRASHES" | grep -o "\"error_class\":\"$ERR\"[^}]*\"total_occurrences\":[0-9]*" | grep -o '"total_occurrences":[0-9]*' | head -1 | grep -o '[0-9]*')"
|
||||
printf " %-30s %s occurrences\n" "$ERR" "${C:-?}"
|
||||
done
|
||||
else
|
||||
echo " No crashes reported"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# ─── Version distribution ────────────────────────────────────
|
||||
echo "Version distribution (last 7 days)"
|
||||
echo "───────────────────────────────────"
|
||||
|
||||
if [ "$EVENTS" != "[]" ] && [ -n "$EVENTS" ]; then
|
||||
echo "$EVENTS" | grep -o '"gstack_version":"[^"]*"' | awk -F'"' '{print $4}' | sort | uniq -c | sort -rn | head -5 | while read -r COUNT VER; do
|
||||
printf " v%-15s %d events\n" "$VER" "$COUNT"
|
||||
done
|
||||
else
|
||||
echo " No data yet"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "For local analytics: gstack-analytics"
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-config — read/write ~/.gstack/config.yaml
|
||||
#
|
||||
# Usage:
|
||||
# gstack-config get <key> — read a config value
|
||||
# gstack-config set <key> <value> — write a config value
|
||||
# gstack-config list — show all config
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_STATE_DIR — override ~/.gstack state directory
|
||||
set -euo pipefail
|
||||
|
||||
STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
|
||||
CONFIG_FILE="$STATE_DIR/config.yaml"
|
||||
|
||||
case "${1:-}" in
|
||||
get)
|
||||
KEY="${2:?Usage: gstack-config get <key>}"
|
||||
grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true
|
||||
;;
|
||||
set)
|
||||
KEY="${2:?Usage: gstack-config set <key> <value>}"
|
||||
VALUE="${3:?Usage: gstack-config set <key> <value>}"
|
||||
mkdir -p "$STATE_DIR"
|
||||
if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then
|
||||
sed -i '' "s/^${KEY}:.*/${KEY}: ${VALUE}/" "$CONFIG_FILE"
|
||||
else
|
||||
echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE"
|
||||
fi
|
||||
;;
|
||||
list)
|
||||
cat "$CONFIG_FILE" 2>/dev/null || true
|
||||
;;
|
||||
*)
|
||||
echo "Usage: gstack-config {get|set|list} [key] [value]"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-diff-scope — categorize what changed in the diff against a base branch
|
||||
# Usage: source <(gstack-diff-scope main) → sets SCOPE_FRONTEND=true SCOPE_BACKEND=false ...
|
||||
# Or: gstack-diff-scope main → prints SCOPE_*=... lines
|
||||
set -euo pipefail
|
||||
|
||||
BASE="${1:-main}"
|
||||
|
||||
# Get changed file list
|
||||
FILES=$(git diff "${BASE}...HEAD" --name-only 2>/dev/null || git diff "${BASE}" --name-only 2>/dev/null || echo "")
|
||||
|
||||
if [ -z "$FILES" ]; then
|
||||
echo "SCOPE_FRONTEND=false"
|
||||
echo "SCOPE_BACKEND=false"
|
||||
echo "SCOPE_PROMPTS=false"
|
||||
echo "SCOPE_TESTS=false"
|
||||
echo "SCOPE_DOCS=false"
|
||||
echo "SCOPE_CONFIG=false"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
FRONTEND=false
|
||||
BACKEND=false
|
||||
PROMPTS=false
|
||||
TESTS=false
|
||||
DOCS=false
|
||||
CONFIG=false
|
||||
|
||||
while IFS= read -r f; do
|
||||
case "$f" in
|
||||
# Frontend: CSS, views, components, templates
|
||||
*.css|*.scss|*.less|*.sass|*.pcss|*.module.css|*.module.scss) FRONTEND=true ;;
|
||||
*.tsx|*.jsx|*.vue|*.svelte|*.astro) FRONTEND=true ;;
|
||||
*.erb|*.haml|*.slim|*.hbs|*.ejs) FRONTEND=true ;;
|
||||
*.html) FRONTEND=true ;;
|
||||
tailwind.config.*|postcss.config.*) FRONTEND=true ;;
|
||||
app/views/*|*/components/*|styles/*|css/*|app/assets/stylesheets/*) FRONTEND=true ;;
|
||||
|
||||
# Prompts: prompt builders, system prompts, generation services
|
||||
*prompt_builder*|*generation_service*|*writer_service*|*designer_service*) PROMPTS=true ;;
|
||||
*evaluator*|*scorer*|*classifier_service*|*analyzer*) PROMPTS=true ;;
|
||||
*voice*.rb|*writing*.rb|*prompt*.rb|*token*.rb) PROMPTS=true ;;
|
||||
app/services/chat_tools/*|app/services/x_thread_tools/*) PROMPTS=true ;;
|
||||
config/system_prompts/*) PROMPTS=true ;;
|
||||
|
||||
# Tests
|
||||
*.test.*|*.spec.*|*_test.*|*_spec.*) TESTS=true ;;
|
||||
test/*|tests/*|spec/*|__tests__/*|cypress/*|e2e/*) TESTS=true ;;
|
||||
|
||||
# Docs
|
||||
*.md) DOCS=true ;;
|
||||
|
||||
# Config
|
||||
package.json|package-lock.json|yarn.lock|bun.lockb) CONFIG=true ;;
|
||||
Gemfile|Gemfile.lock) CONFIG=true ;;
|
||||
*.yml|*.yaml) CONFIG=true ;;
|
||||
.github/*) CONFIG=true ;;
|
||||
requirements.txt|pyproject.toml|go.mod|Cargo.toml|composer.json) CONFIG=true ;;
|
||||
|
||||
# Backend: everything else that's code (excluding views/components already matched)
|
||||
*.rb|*.py|*.go|*.rs|*.java|*.php|*.ex|*.exs) BACKEND=true ;;
|
||||
*.ts|*.js) BACKEND=true ;; # Non-component TS/JS is backend
|
||||
esac
|
||||
done <<< "$FILES"
|
||||
|
||||
echo "SCOPE_FRONTEND=$FRONTEND"
|
||||
echo "SCOPE_BACKEND=$BACKEND"
|
||||
echo "SCOPE_PROMPTS=$PROMPTS"
|
||||
echo "SCOPE_TESTS=$TESTS"
|
||||
echo "SCOPE_DOCS=$DOCS"
|
||||
echo "SCOPE_CONFIG=$CONFIG"
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
#!/bin/bash
|
||||
# gstack-env.sh — Set environment variables for gstack-opencode
|
||||
# Source this file to set up the environment:
|
||||
# source ~/gstack-opencode/bin/gstack-env.sh
|
||||
|
||||
export GSTACK_OPENCODE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
export GSTACK_BROWSE="${GSTACK_OPENCODE_DIR}/browse/dist/browse"
|
||||
export PATH="${GSTACK_OPENCODE_DIR}/bin:$PATH"
|
||||
|
||||
# Create ~/.gstack directory if it doesn't exist
|
||||
mkdir -p ~/.gstack/{sessions,projects,analytics}
|
||||
|
|
@ -0,0 +1,591 @@
|
|||
#!/usr/bin/env bun
|
||||
/**
|
||||
* gstack-global-discover — Discover AI coding sessions across Claude Code, Codex CLI, and Gemini CLI.
|
||||
* Resolves each session's working directory to a git repo, deduplicates by normalized remote URL,
|
||||
* and outputs structured JSON to stdout.
|
||||
*
|
||||
* Usage:
|
||||
* gstack-global-discover --since 7d [--format json|summary]
|
||||
* gstack-global-discover --help
|
||||
*/
|
||||
|
||||
import { existsSync, readdirSync, statSync, readFileSync, openSync, readSync, closeSync } from "fs";
|
||||
import { join, basename } from "path";
|
||||
import { execSync } from "child_process";
|
||||
import { homedir } from "os";
|
||||
|
||||
// ── Types ──────────────────────────────────────────────────────────────────
|
||||
|
||||
interface Session {
|
||||
tool: "claude_code" | "codex" | "gemini";
|
||||
cwd: string;
|
||||
}
|
||||
|
||||
interface Repo {
|
||||
name: string;
|
||||
remote: string;
|
||||
paths: string[];
|
||||
sessions: { claude_code: number; codex: number; gemini: number };
|
||||
}
|
||||
|
||||
interface DiscoveryResult {
|
||||
window: string;
|
||||
start_date: string;
|
||||
repos: Repo[];
|
||||
tools: {
|
||||
claude_code: { total_sessions: number; repos: number };
|
||||
codex: { total_sessions: number; repos: number };
|
||||
gemini: { total_sessions: number; repos: number };
|
||||
};
|
||||
total_sessions: number;
|
||||
total_repos: number;
|
||||
}
|
||||
|
||||
// ── CLI parsing ────────────────────────────────────────────────────────────
|
||||
|
||||
function printUsage(): void {
|
||||
console.error(`Usage: gstack-global-discover --since <window> [--format json|summary]
|
||||
|
||||
--since <window> Time window: e.g. 7d, 14d, 30d, 24h
|
||||
--format <fmt> Output format: json (default) or summary
|
||||
--help Show this help
|
||||
|
||||
Examples:
|
||||
gstack-global-discover --since 7d
|
||||
gstack-global-discover --since 14d --format summary`);
|
||||
}
|
||||
|
||||
function parseArgs(): { since: string; format: "json" | "summary" } {
|
||||
const args = process.argv.slice(2);
|
||||
let since = "";
|
||||
let format: "json" | "summary" = "json";
|
||||
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === "--help" || args[i] === "-h") {
|
||||
printUsage();
|
||||
process.exit(0);
|
||||
} else if (args[i] === "--since" && args[i + 1]) {
|
||||
since = args[++i];
|
||||
} else if (args[i] === "--format" && args[i + 1]) {
|
||||
const f = args[++i];
|
||||
if (f !== "json" && f !== "summary") {
|
||||
console.error(`Invalid format: ${f}. Use 'json' or 'summary'.`);
|
||||
printUsage();
|
||||
process.exit(1);
|
||||
}
|
||||
format = f;
|
||||
} else {
|
||||
console.error(`Unknown argument: ${args[i]}`);
|
||||
printUsage();
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
if (!since) {
|
||||
console.error("Error: --since is required.");
|
||||
printUsage();
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (!/^\d+(d|h|w)$/.test(since)) {
|
||||
console.error(`Invalid window format: ${since}. Use e.g. 7d, 24h, 2w.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
return { since, format };
|
||||
}
|
||||
|
||||
function windowToDate(window: string): Date {
|
||||
const match = window.match(/^(\d+)(d|h|w)$/);
|
||||
if (!match) throw new Error(`Invalid window: ${window}`);
|
||||
const [, numStr, unit] = match;
|
||||
const num = parseInt(numStr, 10);
|
||||
const now = new Date();
|
||||
|
||||
if (unit === "h") {
|
||||
return new Date(now.getTime() - num * 60 * 60 * 1000);
|
||||
} else if (unit === "w") {
|
||||
// weeks — midnight-aligned like days
|
||||
const d = new Date(now);
|
||||
d.setDate(d.getDate() - num * 7);
|
||||
d.setHours(0, 0, 0, 0);
|
||||
return d;
|
||||
} else {
|
||||
// days — midnight-aligned
|
||||
const d = new Date(now);
|
||||
d.setDate(d.getDate() - num);
|
||||
d.setHours(0, 0, 0, 0);
|
||||
return d;
|
||||
}
|
||||
}
|
||||
|
||||
// ── URL normalization ──────────────────────────────────────────────────────
|
||||
|
||||
export function normalizeRemoteUrl(url: string): string {
|
||||
let normalized = url.trim();
|
||||
|
||||
// SSH → HTTPS: git@github.com:user/repo → https://github.com/user/repo
|
||||
const sshMatch = normalized.match(/^(?:ssh:\/\/)?git@([^:]+):(.+)$/);
|
||||
if (sshMatch) {
|
||||
normalized = `https://${sshMatch[1]}/${sshMatch[2]}`;
|
||||
}
|
||||
|
||||
// Strip .git suffix
|
||||
if (normalized.endsWith(".git")) {
|
||||
normalized = normalized.slice(0, -4);
|
||||
}
|
||||
|
||||
// Lowercase the host portion
|
||||
try {
|
||||
const parsed = new URL(normalized);
|
||||
parsed.hostname = parsed.hostname.toLowerCase();
|
||||
normalized = parsed.toString();
|
||||
// Remove trailing slash
|
||||
if (normalized.endsWith("/")) {
|
||||
normalized = normalized.slice(0, -1);
|
||||
}
|
||||
} catch {
|
||||
// Not a valid URL (e.g., local:<path>), return as-is
|
||||
}
|
||||
|
||||
return normalized;
|
||||
}
|
||||
|
||||
// ── Git helpers ────────────────────────────────────────────────────────────
|
||||
|
||||
function isGitRepo(dir: string): boolean {
|
||||
return existsSync(join(dir, ".git"));
|
||||
}
|
||||
|
||||
function getGitRemote(cwd: string): string | null {
|
||||
if (!existsSync(cwd) || !isGitRepo(cwd)) return null;
|
||||
try {
|
||||
const remote = execSync("git remote get-url origin", {
|
||||
cwd,
|
||||
encoding: "utf-8",
|
||||
timeout: 5000,
|
||||
stdio: ["pipe", "pipe", "pipe"],
|
||||
}).trim();
|
||||
return remote || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// ── Scanners ───────────────────────────────────────────────────────────────
|
||||
|
||||
function scanClaudeCode(since: Date): Session[] {
|
||||
const projectsDir = join(homedir(), ".claude", "projects");
|
||||
if (!existsSync(projectsDir)) return [];
|
||||
|
||||
const sessions: Session[] = [];
|
||||
|
||||
let dirs: string[];
|
||||
try {
|
||||
dirs = readdirSync(projectsDir);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
|
||||
for (const dirName of dirs) {
|
||||
const dirPath = join(projectsDir, dirName);
|
||||
try {
|
||||
const stat = statSync(dirPath);
|
||||
if (!stat.isDirectory()) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Find JSONL files
|
||||
let jsonlFiles: string[];
|
||||
try {
|
||||
jsonlFiles = readdirSync(dirPath).filter((f) => f.endsWith(".jsonl"));
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
if (jsonlFiles.length === 0) continue;
|
||||
|
||||
// Coarse mtime pre-filter: check if any JSONL file is recent
|
||||
const hasRecentFile = jsonlFiles.some((f) => {
|
||||
try {
|
||||
return statSync(join(dirPath, f)).mtime >= since;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
if (!hasRecentFile) continue;
|
||||
|
||||
// Resolve cwd
|
||||
let cwd = resolveClaudeCodeCwd(dirPath, dirName, jsonlFiles);
|
||||
if (!cwd) continue;
|
||||
|
||||
// Count only JSONL files modified within the window as sessions
|
||||
const recentFiles = jsonlFiles.filter((f) => {
|
||||
try {
|
||||
return statSync(join(dirPath, f)).mtime >= since;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
for (let i = 0; i < recentFiles.length; i++) {
|
||||
sessions.push({ tool: "claude_code", cwd });
|
||||
}
|
||||
}
|
||||
|
||||
return sessions;
|
||||
}
|
||||
|
||||
function resolveClaudeCodeCwd(
|
||||
dirPath: string,
|
||||
dirName: string,
|
||||
jsonlFiles: string[]
|
||||
): string | null {
|
||||
// Fast-path: decode directory name
|
||||
// e.g., -Users-garrytan-git-repo → /Users/garrytan/git/repo
|
||||
const decoded = dirName.replace(/^-/, "/").replace(/-/g, "/");
|
||||
if (existsSync(decoded)) return decoded;
|
||||
|
||||
// Fallback: read cwd from first JSONL file
|
||||
// Sort by mtime descending, pick most recent
|
||||
const sorted = jsonlFiles
|
||||
.map((f) => {
|
||||
try {
|
||||
return { name: f, mtime: statSync(join(dirPath, f)).mtime.getTime() };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
})
|
||||
.filter(Boolean)
|
||||
.sort((a, b) => b!.mtime - a!.mtime) as { name: string; mtime: number }[];
|
||||
|
||||
for (const file of sorted.slice(0, 3)) {
|
||||
const cwd = extractCwdFromJsonl(join(dirPath, file.name));
|
||||
if (cwd && existsSync(cwd)) return cwd;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
function extractCwdFromJsonl(filePath: string): string | null {
|
||||
try {
|
||||
// Read only the first 8KB to avoid loading huge JSONL files into memory
|
||||
const fd = openSync(filePath, "r");
|
||||
const buf = Buffer.alloc(8192);
|
||||
const bytesRead = readSync(fd, buf, 0, 8192, 0);
|
||||
closeSync(fd);
|
||||
const text = buf.toString("utf-8", 0, bytesRead);
|
||||
const lines = text.split("\n").slice(0, 15);
|
||||
for (const line of lines) {
|
||||
if (!line.trim()) continue;
|
||||
try {
|
||||
const obj = JSON.parse(line);
|
||||
if (obj.cwd) return obj.cwd;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// File read error
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function scanCodex(since: Date): Session[] {
|
||||
const sessionsDir = join(homedir(), ".codex", "sessions");
|
||||
if (!existsSync(sessionsDir)) return [];
|
||||
|
||||
const sessions: Session[] = [];
|
||||
|
||||
// Walk YYYY/MM/DD directory structure
|
||||
try {
|
||||
const years = readdirSync(sessionsDir);
|
||||
for (const year of years) {
|
||||
const yearPath = join(sessionsDir, year);
|
||||
if (!statSync(yearPath).isDirectory()) continue;
|
||||
|
||||
const months = readdirSync(yearPath);
|
||||
for (const month of months) {
|
||||
const monthPath = join(yearPath, month);
|
||||
if (!statSync(monthPath).isDirectory()) continue;
|
||||
|
||||
const days = readdirSync(monthPath);
|
||||
for (const day of days) {
|
||||
const dayPath = join(monthPath, day);
|
||||
if (!statSync(dayPath).isDirectory()) continue;
|
||||
|
||||
const files = readdirSync(dayPath).filter((f) =>
|
||||
f.startsWith("rollout-") && f.endsWith(".jsonl")
|
||||
);
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(dayPath, file);
|
||||
try {
|
||||
const stat = statSync(filePath);
|
||||
if (stat.mtime < since) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Read first line for session_meta (only first 4KB)
|
||||
try {
|
||||
const fd = openSync(filePath, "r");
|
||||
const buf = Buffer.alloc(4096);
|
||||
const bytesRead = readSync(fd, buf, 0, 4096, 0);
|
||||
closeSync(fd);
|
||||
const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n")[0];
|
||||
if (!firstLine) continue;
|
||||
const meta = JSON.parse(firstLine);
|
||||
if (meta.type === "session_meta" && meta.payload?.cwd) {
|
||||
sessions.push({ tool: "codex", cwd: meta.payload.cwd });
|
||||
}
|
||||
} catch {
|
||||
console.error(`Warning: could not parse Codex session ${filePath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Directory read error
|
||||
}
|
||||
|
||||
return sessions;
|
||||
}
|
||||
|
||||
function scanGemini(since: Date): Session[] {
|
||||
const tmpDir = join(homedir(), ".gemini", "tmp");
|
||||
if (!existsSync(tmpDir)) return [];
|
||||
|
||||
// Load projects.json for path mapping
|
||||
const projectsPath = join(homedir(), ".gemini", "projects.json");
|
||||
let projectsMap: Record<string, string> = {}; // name → path
|
||||
if (existsSync(projectsPath)) {
|
||||
try {
|
||||
const data = JSON.parse(readFileSync(projectsPath, { encoding: "utf-8" }));
|
||||
// Format: { projects: { "/path": "name" } } — we want name → path
|
||||
const projects = data.projects || {};
|
||||
for (const [path, name] of Object.entries(projects)) {
|
||||
projectsMap[name as string] = path;
|
||||
}
|
||||
} catch {
|
||||
console.error("Warning: could not parse ~/.gemini/projects.json");
|
||||
}
|
||||
}
|
||||
|
||||
const sessions: Session[] = [];
|
||||
const seenTimestamps = new Map<string, Set<string>>(); // projectName → Set<startTime>
|
||||
|
||||
let projectDirs: string[];
|
||||
try {
|
||||
projectDirs = readdirSync(tmpDir);
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
|
||||
for (const projectName of projectDirs) {
|
||||
const chatsDir = join(tmpDir, projectName, "chats");
|
||||
if (!existsSync(chatsDir)) continue;
|
||||
|
||||
// Resolve cwd from projects.json
|
||||
let cwd = projectsMap[projectName] || null;
|
||||
|
||||
// Fallback: check .project_root
|
||||
if (!cwd) {
|
||||
const projectRootFile = join(tmpDir, projectName, ".project_root");
|
||||
if (existsSync(projectRootFile)) {
|
||||
try {
|
||||
cwd = readFileSync(projectRootFile, { encoding: "utf-8" }).trim();
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
|
||||
if (!cwd || !existsSync(cwd)) continue;
|
||||
|
||||
const seen = seenTimestamps.get(projectName) || new Set<string>();
|
||||
seenTimestamps.set(projectName, seen);
|
||||
|
||||
let files: string[];
|
||||
try {
|
||||
files = readdirSync(chatsDir).filter((f) =>
|
||||
f.startsWith("session-") && f.endsWith(".json")
|
||||
);
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(chatsDir, file);
|
||||
try {
|
||||
const stat = statSync(filePath);
|
||||
if (stat.mtime < since) continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
const data = JSON.parse(readFileSync(filePath, { encoding: "utf-8" }));
|
||||
const startTime = data.startTime || "";
|
||||
|
||||
// Deduplicate by startTime within project
|
||||
if (startTime && seen.has(startTime)) continue;
|
||||
if (startTime) seen.add(startTime);
|
||||
|
||||
sessions.push({ tool: "gemini", cwd });
|
||||
} catch {
|
||||
console.error(`Warning: could not parse Gemini session ${filePath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return sessions;
|
||||
}
|
||||
|
||||
// ── Deduplication ──────────────────────────────────────────────────────────
|
||||
|
||||
async function resolveAndDeduplicate(sessions: Session[]): Promise<Repo[]> {
|
||||
// Group sessions by cwd
|
||||
const byCwd = new Map<string, Session[]>();
|
||||
for (const s of sessions) {
|
||||
const existing = byCwd.get(s.cwd) || [];
|
||||
existing.push(s);
|
||||
byCwd.set(s.cwd, existing);
|
||||
}
|
||||
|
||||
// Resolve git remotes for each cwd
|
||||
const cwds = Array.from(byCwd.keys());
|
||||
const remoteMap = new Map<string, string>(); // cwd → normalized remote
|
||||
|
||||
for (const cwd of cwds) {
|
||||
const raw = getGitRemote(cwd);
|
||||
if (raw) {
|
||||
remoteMap.set(cwd, normalizeRemoteUrl(raw));
|
||||
} else if (existsSync(cwd) && isGitRepo(cwd)) {
|
||||
remoteMap.set(cwd, `local:${cwd}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Group by normalized remote
|
||||
const byRemote = new Map<string, { paths: string[]; sessions: Session[] }>();
|
||||
for (const [cwd, cwdSessions] of byCwd) {
|
||||
const remote = remoteMap.get(cwd);
|
||||
if (!remote) continue;
|
||||
|
||||
const existing = byRemote.get(remote) || { paths: [], sessions: [] };
|
||||
if (!existing.paths.includes(cwd)) existing.paths.push(cwd);
|
||||
existing.sessions.push(...cwdSessions);
|
||||
byRemote.set(remote, existing);
|
||||
}
|
||||
|
||||
// Build Repo objects
|
||||
const repos: Repo[] = [];
|
||||
for (const [remote, data] of byRemote) {
|
||||
// Find first valid path
|
||||
const validPath = data.paths.find((p) => existsSync(p) && isGitRepo(p));
|
||||
if (!validPath) continue;
|
||||
|
||||
// Derive name from remote URL
|
||||
let name: string;
|
||||
if (remote.startsWith("local:")) {
|
||||
name = basename(remote.replace("local:", ""));
|
||||
} else {
|
||||
try {
|
||||
const url = new URL(remote);
|
||||
name = basename(url.pathname);
|
||||
} catch {
|
||||
name = basename(remote);
|
||||
}
|
||||
}
|
||||
|
||||
const sessionCounts = { claude_code: 0, codex: 0, gemini: 0 };
|
||||
for (const s of data.sessions) {
|
||||
sessionCounts[s.tool]++;
|
||||
}
|
||||
|
||||
repos.push({
|
||||
name,
|
||||
remote,
|
||||
paths: data.paths,
|
||||
sessions: sessionCounts,
|
||||
});
|
||||
}
|
||||
|
||||
// Sort by total sessions descending
|
||||
repos.sort(
|
||||
(a, b) =>
|
||||
b.sessions.claude_code + b.sessions.codex + b.sessions.gemini -
|
||||
(a.sessions.claude_code + a.sessions.codex + a.sessions.gemini)
|
||||
);
|
||||
|
||||
return repos;
|
||||
}
|
||||
|
||||
// ── Main ───────────────────────────────────────────────────────────────────
|
||||
|
||||
async function main() {
|
||||
const { since, format } = parseArgs();
|
||||
const sinceDate = windowToDate(since);
|
||||
const startDate = sinceDate.toISOString().split("T")[0];
|
||||
|
||||
// Run all scanners
|
||||
const ccSessions = scanClaudeCode(sinceDate);
|
||||
const codexSessions = scanCodex(sinceDate);
|
||||
const geminiSessions = scanGemini(sinceDate);
|
||||
|
||||
const allSessions = [...ccSessions, ...codexSessions, ...geminiSessions];
|
||||
|
||||
// Summary to stderr
|
||||
console.error(
|
||||
`Discovered: ${ccSessions.length} CC sessions, ${codexSessions.length} Codex sessions, ${geminiSessions.length} Gemini sessions`
|
||||
);
|
||||
|
||||
// Deduplicate
|
||||
const repos = await resolveAndDeduplicate(allSessions);
|
||||
|
||||
console.error(`→ ${repos.length} unique repos`);
|
||||
|
||||
// Count per-tool repo counts
|
||||
const ccRepos = new Set(repos.filter((r) => r.sessions.claude_code > 0).map((r) => r.remote)).size;
|
||||
const codexRepos = new Set(repos.filter((r) => r.sessions.codex > 0).map((r) => r.remote)).size;
|
||||
const geminiRepos = new Set(repos.filter((r) => r.sessions.gemini > 0).map((r) => r.remote)).size;
|
||||
|
||||
const result: DiscoveryResult = {
|
||||
window: since,
|
||||
start_date: startDate,
|
||||
repos,
|
||||
tools: {
|
||||
claude_code: { total_sessions: ccSessions.length, repos: ccRepos },
|
||||
codex: { total_sessions: codexSessions.length, repos: codexRepos },
|
||||
gemini: { total_sessions: geminiSessions.length, repos: geminiRepos },
|
||||
},
|
||||
total_sessions: allSessions.length,
|
||||
total_repos: repos.length,
|
||||
};
|
||||
|
||||
if (format === "json") {
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
} else {
|
||||
// Summary format
|
||||
console.log(`Window: ${since} (since ${startDate})`);
|
||||
console.log(`Sessions: ${allSessions.length} total (CC: ${ccSessions.length}, Codex: ${codexSessions.length}, Gemini: ${geminiSessions.length})`);
|
||||
console.log(`Repos: ${repos.length} unique`);
|
||||
console.log("");
|
||||
for (const repo of repos) {
|
||||
const total = repo.sessions.claude_code + repo.sessions.codex + repo.sessions.gemini;
|
||||
const tools = [];
|
||||
if (repo.sessions.claude_code > 0) tools.push(`CC:${repo.sessions.claude_code}`);
|
||||
if (repo.sessions.codex > 0) tools.push(`Codex:${repo.sessions.codex}`);
|
||||
if (repo.sessions.gemini > 0) tools.push(`Gemini:${repo.sessions.gemini}`);
|
||||
console.log(` ${repo.name} (${total} sessions) — ${tools.join(", ")}`);
|
||||
console.log(` Remote: ${repo.remote}`);
|
||||
console.log(` Paths: ${repo.paths.join(", ")}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Only run main when executed directly (not when imported for testing)
|
||||
if (import.meta.main) {
|
||||
main().catch((err) => {
|
||||
console.error(`Fatal error: ${err.message}`);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-repo-mode — detect solo vs collaborative repo mode
|
||||
# Usage: source <(gstack-repo-mode) → sets REPO_MODE variable
|
||||
# Or: gstack-repo-mode → prints REPO_MODE=... line
|
||||
#
|
||||
# Detection heuristic (90-day window):
|
||||
# Solo: top author >= 80% of commits
|
||||
# Collaborative: top author < 80%
|
||||
#
|
||||
# Override: gstack-config set repo_mode solo|collaborative
|
||||
# Cache: ~/.gstack/projects/$SLUG/repo-mode.json (7-day TTL)
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
# Compute SLUG directly (avoid eval of gstack-slug — branch names can contain shell metacharacters)
|
||||
REMOTE_URL=$(git remote get-url origin 2>/dev/null || true)
|
||||
if [ -z "$REMOTE_URL" ]; then
|
||||
echo "REPO_MODE=unknown"
|
||||
exit 0
|
||||
fi
|
||||
SLUG=$(echo "$REMOTE_URL" | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
|
||||
[ -z "${SLUG:-}" ] && { echo "REPO_MODE=unknown"; exit 0; }
|
||||
|
||||
# Validate: only allow known values (prevent shell injection via source <(...))
|
||||
validate_mode() {
|
||||
case "$1" in solo|collaborative|unknown) echo "$1" ;; *) echo "unknown" ;; esac
|
||||
}
|
||||
|
||||
# Config override takes precedence
|
||||
OVERRIDE=$("$SCRIPT_DIR/gstack-config" get repo_mode 2>/dev/null || true)
|
||||
if [ -n "$OVERRIDE" ] && [ "$OVERRIDE" != "null" ]; then
|
||||
echo "REPO_MODE=$(validate_mode "$OVERRIDE")"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check cache (7-day TTL)
|
||||
CACHE_DIR="$HOME/.gstack/projects/$SLUG"
|
||||
CACHE_FILE="$CACHE_DIR/repo-mode.json"
|
||||
if [ -f "$CACHE_FILE" ]; then
|
||||
CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0) ))
|
||||
if [ "$CACHE_AGE" -lt 604800 ]; then # 7 days in seconds
|
||||
MODE=$(grep -o '"mode":"[^"]*"' "$CACHE_FILE" | head -1 | cut -d'"' -f4)
|
||||
[ -n "$MODE" ] && echo "REPO_MODE=$(validate_mode "$MODE")" && exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# Compute from git history (90-day window)
|
||||
# Use default branch (not HEAD) to avoid feature-branch sampling bias
|
||||
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/||' || true)
|
||||
# Fallback: try origin/main, then origin/master, then HEAD
|
||||
if [ -z "$DEFAULT_BRANCH" ]; then
|
||||
if git rev-parse --verify origin/main &>/dev/null; then
|
||||
DEFAULT_BRANCH="origin/main"
|
||||
elif git rev-parse --verify origin/master &>/dev/null; then
|
||||
DEFAULT_BRANCH="origin/master"
|
||||
else
|
||||
DEFAULT_BRANCH="HEAD"
|
||||
fi
|
||||
fi
|
||||
SHORTLOG=$(git shortlog -sn --since="90 days ago" --no-merges "$DEFAULT_BRANCH" 2>/dev/null)
|
||||
if [ -z "$SHORTLOG" ]; then
|
||||
echo "REPO_MODE=unknown"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Compute TOTAL from ALL authors (not truncated) to avoid solo bias
|
||||
TOTAL=$(echo "$SHORTLOG" | awk '{s+=$1} END {print s}')
|
||||
TOP=$(echo "$SHORTLOG" | head -1 | awk '{print $1}')
|
||||
AUTHORS=$(echo "$SHORTLOG" | wc -l | tr -d ' ')
|
||||
|
||||
# Minimum sample: need at least 5 commits to classify
|
||||
if [ "$TOTAL" -lt 5 ]; then
|
||||
echo "REPO_MODE=unknown"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
TOP_PCT=$(( TOP * 100 / TOTAL ))
|
||||
|
||||
# Solo: top author >= 80% of commits (occasional outside PRs don't change mode)
|
||||
if [ "$TOP_PCT" -ge 80 ]; then
|
||||
MODE=solo
|
||||
else
|
||||
MODE=collaborative
|
||||
fi
|
||||
|
||||
# Cache result atomically (fail silently if ~/.gstack is unwritable)
|
||||
mkdir -p "$CACHE_DIR" 2>/dev/null || true
|
||||
CACHE_TMP=$(mktemp "$CACHE_DIR/.repo-mode-XXXXXX" 2>/dev/null || true)
|
||||
if [ -n "$CACHE_TMP" ]; then
|
||||
echo "{\"mode\":\"$MODE\",\"top_pct\":$TOP_PCT,\"authors\":$AUTHORS,\"total\":$TOTAL,\"computed\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > "$CACHE_TMP" 2>/dev/null && mv "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
|
||||
fi
|
||||
|
||||
echo "REPO_MODE=$MODE"
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-review-log — atomically log a review result
|
||||
# Usage: gstack-review-log '{"skill":"...","timestamp":"...","status":"..."}'
|
||||
set -euo pipefail
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
|
||||
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
mkdir -p "$GSTACK_HOME/projects/$SLUG"
|
||||
echo "$1" >> "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl"
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-review-read — read review log and config for dashboard
|
||||
# Usage: gstack-review-read
|
||||
set -euo pipefail
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
|
||||
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
cat "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl" 2>/dev/null || echo "NO_REVIEWS"
|
||||
echo "---CONFIG---"
|
||||
"$SCRIPT_DIR/gstack-config" get skip_eng_review 2>/dev/null || echo "false"
|
||||
echo "---HEAD---"
|
||||
git rev-parse --short HEAD 2>/dev/null || echo "unknown"
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-slug — output project slug and sanitized branch name
|
||||
# Usage: eval "$(gstack-slug)" → sets SLUG and BRANCH variables
|
||||
# Or: gstack-slug → prints SLUG=... and BRANCH=... lines
|
||||
#
|
||||
# Security: output is sanitized to [a-zA-Z0-9._-] only, preventing
|
||||
# shell injection when consumed via source or eval.
|
||||
set -euo pipefail
|
||||
RAW_SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
|
||||
RAW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-')
|
||||
# Strip any characters that aren't alphanumeric, dot, hyphen, or underscore
|
||||
SLUG=$(printf '%s' "$RAW_SLUG" | tr -cd 'a-zA-Z0-9._-')
|
||||
BRANCH=$(printf '%s' "$RAW_BRANCH" | tr -cd 'a-zA-Z0-9._-')
|
||||
echo "SLUG=$SLUG"
|
||||
echo "BRANCH=$BRANCH"
|
||||
|
|
@ -0,0 +1,158 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-telemetry-log — append a telemetry event to local JSONL
|
||||
#
|
||||
# Data flow:
|
||||
# preamble (start) ──▶ .pending marker
|
||||
# preamble (epilogue) ──▶ gstack-telemetry-log ──▶ skill-usage.jsonl
|
||||
# └──▶ gstack-telemetry-sync (bg)
|
||||
#
|
||||
# Usage:
|
||||
# gstack-telemetry-log --skill qa --duration 142 --outcome success \
|
||||
# --used-browse true --session-id "12345-1710756600"
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_STATE_DIR — override ~/.gstack state directory
|
||||
# GSTACK_DIR — override auto-detected gstack root
|
||||
#
|
||||
# NOTE: Uses set -uo pipefail (no -e) — telemetry must never exit non-zero
|
||||
set -uo pipefail
|
||||
|
||||
GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
|
||||
STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
|
||||
ANALYTICS_DIR="$STATE_DIR/analytics"
|
||||
JSONL_FILE="$ANALYTICS_DIR/skill-usage.jsonl"
|
||||
PENDING_DIR="$ANALYTICS_DIR" # .pending-* files live here
|
||||
CONFIG_CMD="$GSTACK_DIR/bin/gstack-config"
|
||||
VERSION_FILE="$GSTACK_DIR/VERSION"
|
||||
|
||||
# ─── Parse flags ─────────────────────────────────────────────
|
||||
SKILL=""
|
||||
DURATION=""
|
||||
OUTCOME="unknown"
|
||||
USED_BROWSE="false"
|
||||
SESSION_ID=""
|
||||
ERROR_CLASS=""
|
||||
EVENT_TYPE="skill_run"
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--skill) SKILL="$2"; shift 2 ;;
|
||||
--duration) DURATION="$2"; shift 2 ;;
|
||||
--outcome) OUTCOME="$2"; shift 2 ;;
|
||||
--used-browse) USED_BROWSE="$2"; shift 2 ;;
|
||||
--session-id) SESSION_ID="$2"; shift 2 ;;
|
||||
--error-class) ERROR_CLASS="$2"; shift 2 ;;
|
||||
--event-type) EVENT_TYPE="$2"; shift 2 ;;
|
||||
*) shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# ─── Read telemetry tier ─────────────────────────────────────
|
||||
TIER="$("$CONFIG_CMD" get telemetry 2>/dev/null || true)"
|
||||
TIER="${TIER:-off}"
|
||||
|
||||
# Validate tier
|
||||
case "$TIER" in
|
||||
off|anonymous|community) ;;
|
||||
*) TIER="off" ;; # invalid value → default to off
|
||||
esac
|
||||
|
||||
if [ "$TIER" = "off" ]; then
|
||||
# Still clear pending markers for this session even if telemetry is off
|
||||
[ -n "$SESSION_ID" ] && rm -f "$PENDING_DIR/.pending-$SESSION_ID" 2>/dev/null || true
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Finalize stale .pending markers ────────────────────────
|
||||
# Each session gets its own .pending-$SESSION_ID file to avoid races
|
||||
# between concurrent sessions. Finalize any that don't match our session.
|
||||
for PFILE in "$PENDING_DIR"/.pending-*; do
|
||||
[ -f "$PFILE" ] || continue
|
||||
# Skip our own session's marker (it's still in-flight)
|
||||
PFILE_BASE="$(basename "$PFILE")"
|
||||
PFILE_SID="${PFILE_BASE#.pending-}"
|
||||
[ "$PFILE_SID" = "$SESSION_ID" ] && continue
|
||||
|
||||
PENDING_DATA="$(cat "$PFILE" 2>/dev/null || true)"
|
||||
rm -f "$PFILE" 2>/dev/null || true
|
||||
if [ -n "$PENDING_DATA" ]; then
|
||||
# Extract fields from pending marker using grep -o + awk
|
||||
P_SKILL="$(echo "$PENDING_DATA" | grep -o '"skill":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
|
||||
P_TS="$(echo "$PENDING_DATA" | grep -o '"ts":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
|
||||
P_SID="$(echo "$PENDING_DATA" | grep -o '"session_id":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
|
||||
P_VER="$(echo "$PENDING_DATA" | grep -o '"gstack_version":"[^"]*"' | head -1 | awk -F'"' '{print $4}')"
|
||||
P_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
|
||||
P_ARCH="$(uname -m)"
|
||||
|
||||
# Write the stale event as outcome: unknown
|
||||
mkdir -p "$ANALYTICS_DIR"
|
||||
printf '{"v":1,"ts":"%s","event_type":"skill_run","skill":"%s","session_id":"%s","gstack_version":"%s","os":"%s","arch":"%s","duration_s":null,"outcome":"unknown","error_class":null,"used_browse":false,"sessions":1}\n' \
|
||||
"$P_TS" "$P_SKILL" "$P_SID" "$P_VER" "$P_OS" "$P_ARCH" >> "$JSONL_FILE" 2>/dev/null || true
|
||||
fi
|
||||
done
|
||||
|
||||
# Clear our own session's pending marker (we're about to log the real event)
|
||||
[ -n "$SESSION_ID" ] && rm -f "$PENDING_DIR/.pending-$SESSION_ID" 2>/dev/null || true
|
||||
|
||||
# ─── Collect metadata ────────────────────────────────────────
|
||||
TS="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%dT%H:%M:%S 2>/dev/null || echo "")"
|
||||
GSTACK_VERSION="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]' || echo "unknown")"
|
||||
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
|
||||
ARCH="$(uname -m)"
|
||||
SESSIONS="1"
|
||||
if [ -d "$STATE_DIR/sessions" ]; then
|
||||
_SC="$(find "$STATE_DIR/sessions" -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' \n\r\t')"
|
||||
[ -n "$_SC" ] && [ "$_SC" -gt 0 ] 2>/dev/null && SESSIONS="$_SC"
|
||||
fi
|
||||
|
||||
# Generate installation_id for community tier
|
||||
INSTALL_ID=""
|
||||
if [ "$TIER" = "community" ]; then
|
||||
HOST="$(hostname 2>/dev/null || echo "unknown")"
|
||||
USER="$(whoami 2>/dev/null || echo "unknown")"
|
||||
if command -v shasum >/dev/null 2>&1; then
|
||||
INSTALL_ID="$(printf '%s-%s' "$HOST" "$USER" | shasum -a 256 | awk '{print $1}')"
|
||||
elif command -v sha256sum >/dev/null 2>&1; then
|
||||
INSTALL_ID="$(printf '%s-%s' "$HOST" "$USER" | sha256sum | awk '{print $1}')"
|
||||
elif command -v openssl >/dev/null 2>&1; then
|
||||
INSTALL_ID="$(printf '%s-%s' "$HOST" "$USER" | openssl dgst -sha256 | awk '{print $NF}')"
|
||||
fi
|
||||
# If no SHA-256 command available, install_id stays empty
|
||||
fi
|
||||
|
||||
# Local-only fields (never sent remotely)
|
||||
REPO_SLUG=""
|
||||
BRANCH=""
|
||||
if command -v git >/dev/null 2>&1; then
|
||||
REPO_SLUG="$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-' 2>/dev/null || true)"
|
||||
BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
|
||||
fi
|
||||
|
||||
# ─── Construct and append JSON ───────────────────────────────
|
||||
mkdir -p "$ANALYTICS_DIR"
|
||||
|
||||
# Escape null fields
|
||||
ERR_FIELD="null"
|
||||
[ -n "$ERROR_CLASS" ] && ERR_FIELD="\"$ERROR_CLASS\""
|
||||
|
||||
DUR_FIELD="null"
|
||||
[ -n "$DURATION" ] && DUR_FIELD="$DURATION"
|
||||
|
||||
INSTALL_FIELD="null"
|
||||
[ -n "$INSTALL_ID" ] && INSTALL_FIELD="\"$INSTALL_ID\""
|
||||
|
||||
BROWSE_BOOL="false"
|
||||
[ "$USED_BROWSE" = "true" ] && BROWSE_BOOL="true"
|
||||
|
||||
printf '{"v":1,"ts":"%s","event_type":"%s","skill":"%s","session_id":"%s","gstack_version":"%s","os":"%s","arch":"%s","duration_s":%s,"outcome":"%s","error_class":%s,"used_browse":%s,"sessions":%s,"installation_id":%s,"_repo_slug":"%s","_branch":"%s"}\n' \
|
||||
"$TS" "$EVENT_TYPE" "$SKILL" "$SESSION_ID" "$GSTACK_VERSION" "$OS" "$ARCH" \
|
||||
"$DUR_FIELD" "$OUTCOME" "$ERR_FIELD" "$BROWSE_BOOL" "${SESSIONS:-1}" \
|
||||
"$INSTALL_FIELD" "$REPO_SLUG" "$BRANCH" >> "$JSONL_FILE" 2>/dev/null || true
|
||||
|
||||
# ─── Trigger sync if tier is not off ─────────────────────────
|
||||
SYNC_CMD="$GSTACK_DIR/bin/gstack-telemetry-sync"
|
||||
if [ -x "$SYNC_CMD" ]; then
|
||||
"$SYNC_CMD" 2>/dev/null &
|
||||
fi
|
||||
|
||||
exit 0
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-telemetry-sync — sync local JSONL events to Supabase
|
||||
#
|
||||
# Fire-and-forget, backgrounded, rate-limited to once per 5 minutes.
|
||||
# Strips local-only fields before sending. Respects privacy tiers.
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_STATE_DIR — override ~/.gstack state directory
|
||||
# GSTACK_DIR — override auto-detected gstack root
|
||||
# GSTACK_TELEMETRY_ENDPOINT — override Supabase endpoint URL
|
||||
set -uo pipefail
|
||||
|
||||
GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
|
||||
STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
|
||||
ANALYTICS_DIR="$STATE_DIR/analytics"
|
||||
JSONL_FILE="$ANALYTICS_DIR/skill-usage.jsonl"
|
||||
CURSOR_FILE="$ANALYTICS_DIR/.last-sync-line"
|
||||
RATE_FILE="$ANALYTICS_DIR/.last-sync-time"
|
||||
CONFIG_CMD="$GSTACK_DIR/bin/gstack-config"
|
||||
|
||||
# Source Supabase config if not overridden by env
|
||||
if [ -z "${GSTACK_TELEMETRY_ENDPOINT:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
|
||||
. "$GSTACK_DIR/supabase/config.sh"
|
||||
fi
|
||||
ENDPOINT="${GSTACK_TELEMETRY_ENDPOINT:-}"
|
||||
ANON_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
|
||||
|
||||
# ─── Pre-checks ──────────────────────────────────────────────
|
||||
# No endpoint configured yet → exit silently
|
||||
[ -z "$ENDPOINT" ] && exit 0
|
||||
|
||||
# No JSONL file → nothing to sync
|
||||
[ -f "$JSONL_FILE" ] || exit 0
|
||||
|
||||
# Rate limit: once per 5 minutes
|
||||
if [ -f "$RATE_FILE" ]; then
|
||||
STALE=$(find "$RATE_FILE" -mmin +5 2>/dev/null || true)
|
||||
[ -z "$STALE" ] && exit 0
|
||||
fi
|
||||
|
||||
# ─── Read tier ───────────────────────────────────────────────
|
||||
TIER="$("$CONFIG_CMD" get telemetry 2>/dev/null || true)"
|
||||
TIER="${TIER:-off}"
|
||||
[ "$TIER" = "off" ] && exit 0
|
||||
|
||||
# ─── Read cursor ─────────────────────────────────────────────
|
||||
CURSOR=0
|
||||
if [ -f "$CURSOR_FILE" ]; then
|
||||
CURSOR="$(cat "$CURSOR_FILE" 2>/dev/null | tr -d ' \n\r\t')"
|
||||
# Validate: must be a non-negative integer
|
||||
case "$CURSOR" in *[!0-9]*) CURSOR=0 ;; esac
|
||||
fi
|
||||
|
||||
# Safety: if cursor exceeds file length, reset
|
||||
TOTAL_LINES="$(wc -l < "$JSONL_FILE" | tr -d ' \n\r\t')"
|
||||
if [ "$CURSOR" -gt "$TOTAL_LINES" ] 2>/dev/null; then
|
||||
CURSOR=0
|
||||
fi
|
||||
|
||||
# Nothing new to sync
|
||||
[ "$CURSOR" -ge "$TOTAL_LINES" ] 2>/dev/null && exit 0
|
||||
|
||||
# ─── Read unsent lines ───────────────────────────────────────
|
||||
SKIP=$(( CURSOR + 1 ))
|
||||
UNSENT="$(tail -n "+$SKIP" "$JSONL_FILE" 2>/dev/null || true)"
|
||||
[ -z "$UNSENT" ] && exit 0
|
||||
|
||||
# ─── Strip local-only fields and build batch ─────────────────
|
||||
BATCH="["
|
||||
FIRST=true
|
||||
COUNT=0
|
||||
|
||||
while IFS= read -r LINE; do
|
||||
# Skip empty or malformed lines
|
||||
[ -z "$LINE" ] && continue
|
||||
echo "$LINE" | grep -q '^{' || continue
|
||||
|
||||
# Strip local-only fields + map JSONL field names to Postgres column names
|
||||
CLEAN="$(echo "$LINE" | sed \
|
||||
-e 's/,"_repo_slug":"[^"]*"//g' \
|
||||
-e 's/,"_branch":"[^"]*"//g' \
|
||||
-e 's/"v":/"schema_version":/g' \
|
||||
-e 's/"ts":/"event_timestamp":/g' \
|
||||
-e 's/"sessions":/"concurrent_sessions":/g' \
|
||||
-e 's/,"repo":"[^"]*"//g')"
|
||||
|
||||
# If anonymous tier, strip installation_id
|
||||
if [ "$TIER" = "anonymous" ]; then
|
||||
CLEAN="$(echo "$CLEAN" | sed 's/,"installation_id":"[^"]*"//g; s/,"installation_id":null//g')"
|
||||
fi
|
||||
|
||||
if [ "$FIRST" = "true" ]; then
|
||||
FIRST=false
|
||||
else
|
||||
BATCH="$BATCH,"
|
||||
fi
|
||||
BATCH="$BATCH$CLEAN"
|
||||
COUNT=$(( COUNT + 1 ))
|
||||
|
||||
# Batch size limit
|
||||
[ "$COUNT" -ge 100 ] && break
|
||||
done <<< "$UNSENT"
|
||||
|
||||
BATCH="$BATCH]"
|
||||
|
||||
# Nothing to send after filtering
|
||||
[ "$COUNT" -eq 0 ] && exit 0
|
||||
|
||||
# ─── POST to Supabase ────────────────────────────────────────
|
||||
HTTP_CODE="$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 \
|
||||
-X POST "${ENDPOINT}/telemetry_events" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "apikey: ${ANON_KEY}" \
|
||||
-H "Authorization: Bearer ${ANON_KEY}" \
|
||||
-H "Prefer: return=minimal" \
|
||||
-d "$BATCH" 2>/dev/null || echo "000")"
|
||||
|
||||
# ─── Update cursor on success (2xx) ─────────────────────────
|
||||
case "$HTTP_CODE" in
|
||||
2*) NEW_CURSOR=$(( CURSOR + COUNT ))
|
||||
echo "$NEW_CURSOR" > "$CURSOR_FILE" 2>/dev/null || true ;;
|
||||
esac
|
||||
|
||||
# Update rate limit marker
|
||||
touch "$RATE_FILE" 2>/dev/null || true
|
||||
|
||||
exit 0
|
||||
|
|
@ -0,0 +1,196 @@
|
|||
#!/usr/bin/env bash
|
||||
# gstack-update-check — periodic version check for all skills.
|
||||
#
|
||||
# Output (one line, or nothing):
|
||||
# JUST_UPGRADED <old> <new> — marker found from recent upgrade
|
||||
# UPGRADE_AVAILABLE <old> <new> — remote VERSION differs from local
|
||||
# (nothing) — up to date, snoozed, disabled, or check skipped
|
||||
#
|
||||
# Env overrides (for testing):
|
||||
# GSTACK_DIR — override auto-detected gstack root
|
||||
# GSTACK_REMOTE_URL — override remote VERSION URL
|
||||
# GSTACK_STATE_DIR — override ~/.gstack state directory
|
||||
set -euo pipefail
|
||||
|
||||
GSTACK_DIR="${GSTACK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
|
||||
STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
|
||||
CACHE_FILE="$STATE_DIR/last-update-check"
|
||||
MARKER_FILE="$STATE_DIR/just-upgraded-from"
|
||||
SNOOZE_FILE="$STATE_DIR/update-snoozed"
|
||||
VERSION_FILE="$GSTACK_DIR/VERSION"
|
||||
REMOTE_URL="${GSTACK_REMOTE_URL:-https://raw.githubusercontent.com/garrytan/gstack/main/VERSION}"
|
||||
|
||||
# ─── Force flag (busts cache for standalone /gstack-upgrade) ──
|
||||
if [ "${1:-}" = "--force" ]; then
|
||||
rm -f "$CACHE_FILE"
|
||||
fi
|
||||
|
||||
# ─── Step 0: Check if updates are disabled ────────────────────
|
||||
_UC=$("$GSTACK_DIR/bin/gstack-config" get update_check 2>/dev/null || true)
|
||||
if [ "$_UC" = "false" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Snooze helper ──────────────────────────────────────────
|
||||
# check_snooze <remote_version>
|
||||
# Returns 0 if snoozed (should stay quiet), 1 if not snoozed (should output).
|
||||
#
|
||||
# Snooze file format: <version> <level> <epoch>
|
||||
# Level durations: 1=24h, 2=48h, 3+=7d
|
||||
# New version (version mismatch) resets snooze.
|
||||
check_snooze() {
|
||||
local remote_ver="$1"
|
||||
if [ ! -f "$SNOOZE_FILE" ]; then
|
||||
return 1 # no snooze file → not snoozed
|
||||
fi
|
||||
local snoozed_ver snoozed_level snoozed_epoch
|
||||
snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
|
||||
snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
|
||||
snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
|
||||
|
||||
# Validate: all three fields must be non-empty
|
||||
if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
|
||||
return 1 # corrupt file → not snoozed
|
||||
fi
|
||||
|
||||
# Validate: level and epoch must be integers
|
||||
case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
|
||||
case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
|
||||
|
||||
# New version dropped? Ignore snooze.
|
||||
if [ "$snoozed_ver" != "$remote_ver" ]; then
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Compute snooze duration based on level
|
||||
local duration
|
||||
case "$snoozed_level" in
|
||||
1) duration=86400 ;; # 24 hours
|
||||
2) duration=172800 ;; # 48 hours
|
||||
*) duration=604800 ;; # 7 days (level 3+)
|
||||
esac
|
||||
|
||||
local now
|
||||
now="$(date +%s)"
|
||||
local expires=$(( snoozed_epoch + duration ))
|
||||
if [ "$now" -lt "$expires" ]; then
|
||||
return 0 # still snoozed
|
||||
fi
|
||||
|
||||
return 1 # snooze expired
|
||||
}
|
||||
|
||||
# ─── Step 1: Read local version ──────────────────────────────
|
||||
LOCAL=""
|
||||
if [ -f "$VERSION_FILE" ]; then
|
||||
LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
|
||||
fi
|
||||
if [ -z "$LOCAL" ]; then
|
||||
exit 0 # No VERSION file → skip check
|
||||
fi
|
||||
|
||||
# ─── Step 2: Check "just upgraded" marker ─────────────────────
|
||||
if [ -f "$MARKER_FILE" ]; then
|
||||
OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
|
||||
rm -f "$MARKER_FILE"
|
||||
rm -f "$SNOOZE_FILE"
|
||||
mkdir -p "$STATE_DIR"
|
||||
echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
|
||||
if [ -n "$OLD" ]; then
|
||||
echo "JUST_UPGRADED $OLD $LOCAL"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ─── Step 3: Check cache freshness ──────────────────────────
|
||||
# UP_TO_DATE: 60 min TTL (detect new releases quickly)
|
||||
# UPGRADE_AVAILABLE: 720 min TTL (keep nagging)
|
||||
if [ -f "$CACHE_FILE" ]; then
|
||||
CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
|
||||
case "$CACHED" in
|
||||
UP_TO_DATE*) CACHE_TTL=60 ;;
|
||||
UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
|
||||
*) CACHE_TTL=0 ;; # corrupt → force re-fetch
|
||||
esac
|
||||
|
||||
STALE=$(find "$CACHE_FILE" -mmin +$CACHE_TTL 2>/dev/null || true)
|
||||
if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
|
||||
case "$CACHED" in
|
||||
UP_TO_DATE*)
|
||||
CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
|
||||
if [ "$CACHED_VER" = "$LOCAL" ]; then
|
||||
exit 0
|
||||
fi
|
||||
;;
|
||||
UPGRADE_AVAILABLE*)
|
||||
CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
|
||||
if [ "$CACHED_OLD" = "$LOCAL" ]; then
|
||||
CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
|
||||
if check_snooze "$CACHED_NEW"; then
|
||||
exit 0 # snoozed — stay quiet
|
||||
fi
|
||||
echo "$CACHED"
|
||||
exit 0
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
fi
|
||||
|
||||
# ─── Step 4: Slow path — fetch remote version ────────────────
|
||||
mkdir -p "$STATE_DIR"
|
||||
|
||||
# Fire Supabase install ping in background (parallel, non-blocking)
|
||||
# This logs an update check event for community health metrics.
|
||||
# If the endpoint isn't configured or Supabase is down, this is a no-op.
|
||||
# Source Supabase config for install ping
|
||||
if [ -z "${GSTACK_TELEMETRY_ENDPOINT:-}" ] && [ -f "$GSTACK_DIR/supabase/config.sh" ]; then
|
||||
. "$GSTACK_DIR/supabase/config.sh"
|
||||
fi
|
||||
_SUPA_ENDPOINT="${GSTACK_TELEMETRY_ENDPOINT:-}"
|
||||
_SUPA_KEY="${GSTACK_SUPABASE_ANON_KEY:-}"
|
||||
# Respect telemetry opt-out — don't ping Supabase if user set telemetry: off
|
||||
_TEL_TIER="$("$GSTACK_DIR/bin/gstack-config" get telemetry 2>/dev/null || true)"
|
||||
if [ -n "$_SUPA_ENDPOINT" ] && [ -n "$_SUPA_KEY" ] && [ "${_TEL_TIER:-off}" != "off" ]; then
|
||||
_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
|
||||
curl -sf --max-time 5 \
|
||||
-X POST "${_SUPA_ENDPOINT}/update_checks" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "apikey: ${_SUPA_KEY}" \
|
||||
-H "Authorization: Bearer ${_SUPA_KEY}" \
|
||||
-H "Prefer: return=minimal" \
|
||||
-d "{\"gstack_version\":\"$LOCAL\",\"os\":\"$_OS\"}" \
|
||||
>/dev/null 2>&1 &
|
||||
fi
|
||||
|
||||
# GitHub raw fetch (primary, always reliable)
|
||||
REMOTE=""
|
||||
REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
|
||||
REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
|
||||
|
||||
# Validate: must look like a version number (reject HTML error pages)
|
||||
if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9.]+$'; then
|
||||
# Invalid or empty response — assume up to date
|
||||
echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [ "$LOCAL" = "$REMOTE" ]; then
|
||||
echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Versions differ — upgrade available
|
||||
echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$CACHE_FILE"
|
||||
if check_snooze "$REMOTE"; then
|
||||
exit 0 # snoozed — stay quiet
|
||||
fi
|
||||
|
||||
# Log upgrade_prompted event (only on slow-path fetch, not cached replays)
|
||||
TEL_CMD="$GSTACK_DIR/bin/gstack-telemetry-log"
|
||||
if [ -x "$TEL_CMD" ]; then
|
||||
"$TEL_CMD" --event-type upgrade_prompted --skill "" --duration 0 \
|
||||
--outcome success --session-id "update-$$-$(date +%s)" 2>/dev/null &
|
||||
fi
|
||||
|
||||
echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"
|
||||
|
|
@ -0,0 +1,553 @@
|
|||
---
|
||||
name: browse
|
||||
version: 1.1.0
|
||||
description: |
|
||||
Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
|
||||
elements, verify page state, diff before/after actions, take annotated screenshots, check
|
||||
responsive layouts, test forms and uploads, handle dialogs, and assert element states.
|
||||
~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
|
||||
user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
|
||||
site", "take a screenshot", or "dogfood this".
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- AskUserQuestion
|
||||
|
||||
---
|
||||
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
|
||||
## Preamble (run first)
|
||||
|
||||
```bash
|
||||
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
|
||||
[ -n "$_UPD" ] && echo "$_UPD" || true
|
||||
mkdir -p ~/.gstack/sessions
|
||||
touch ~/.gstack/sessions/"$PPID"
|
||||
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
|
||||
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
|
||||
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
|
||||
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
|
||||
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
|
||||
echo "BRANCH: $_BRANCH"
|
||||
echo "PROACTIVE: $_PROACTIVE"
|
||||
source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true
|
||||
REPO_MODE=${REPO_MODE:-unknown}
|
||||
echo "REPO_MODE: $REPO_MODE"
|
||||
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
|
||||
echo "LAKE_INTRO: $_LAKE_SEEN"
|
||||
_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true)
|
||||
_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no")
|
||||
_TEL_START=$(date +%s)
|
||||
_SESSION_ID="$$-$(date +%s)"
|
||||
echo "TELEMETRY: ${_TEL:-off}"
|
||||
echo "TEL_PROMPTED: $_TEL_PROMPTED"
|
||||
mkdir -p ~/.gstack/analytics
|
||||
echo '{"skill":"browse","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done
|
||||
```
|
||||
|
||||
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills — only invoke
|
||||
them when the user explicitly asks. The user opted out of proactive suggestions.
|
||||
|
||||
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
|
||||
|
||||
If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle.
|
||||
Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete
|
||||
thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean"
|
||||
Then offer to open the essay in their default browser:
|
||||
|
||||
```bash
|
||||
open https://garryslist.org/posts/boil-the-ocean
|
||||
touch ~/.gstack/.completeness-intro-seen
|
||||
```
|
||||
|
||||
Only run `open` if the user says yes. Always run `touch` to mark as seen. This only happens once.
|
||||
|
||||
If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: After the lake intro is handled,
|
||||
ask the user about telemetry. Use AskUserQuestion:
|
||||
|
||||
> Help gstack get better! Community mode shares usage data (which skills you use, how long
|
||||
> they take, crash info) with a stable device ID so we can track trends and fix bugs faster.
|
||||
> No code, file paths, or repo names are ever sent.
|
||||
> Change anytime with `gstack-config set telemetry off`.
|
||||
|
||||
Options:
|
||||
- A) Help gstack get better! (recommended)
|
||||
- B) No thanks
|
||||
|
||||
If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community`
|
||||
|
||||
If B: ask a follow-up AskUserQuestion:
|
||||
|
||||
> How about anonymous mode? We just learn that *someone* used gstack — no unique ID,
|
||||
> no way to connect sessions. Just a counter that helps us know if anyone's out there.
|
||||
|
||||
Options:
|
||||
- A) Sure, anonymous is fine
|
||||
- B) No thanks, fully off
|
||||
|
||||
If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous`
|
||||
If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off`
|
||||
|
||||
Always run:
|
||||
```bash
|
||||
touch ~/.gstack/.telemetry-prompted
|
||||
```
|
||||
|
||||
This only happens once. If `TEL_PROMPTED` is `yes`, skip this entirely.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call:**
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
|
||||
3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` — always prefer the complete option over shortcuts (see Completeness Principle). Include `Completeness: X/10` for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
|
||||
4. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Completeness Principle — Boil the Lake
|
||||
|
||||
AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
|
||||
|
||||
- If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — **always recommend A**. The delta between 80 lines and 150 lines is meaningless with CC+gstack. "Good enough" is the wrong instinct when "complete" costs minutes more.
|
||||
- **Lake vs. ocean:** A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
|
||||
- **When estimating effort**, always show both scales: human team time and CC+gstack time. The compression ratio varies by task type — use this reference:
|
||||
|
||||
| Task type | Human team | CC+gstack | Compression |
|
||||
|-----------|-----------|-----------|-------------|
|
||||
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
|
||||
| Test writing | 1 day | 15 min | ~50x |
|
||||
| Feature implementation | 1 week | 30 min | ~30x |
|
||||
| Bug fix + regression test | 4 hours | 15 min | ~20x |
|
||||
| Architecture / design | 2 days | 4 hours | ~5x |
|
||||
| Research / exploration | 1 day | 3 hours | ~3x |
|
||||
|
||||
- This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds.
|
||||
|
||||
**Anti-patterns — DON'T do this:**
|
||||
- BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.)
|
||||
- BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with CC.)
|
||||
- BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
|
||||
- BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")
|
||||
|
||||
## Repo Ownership Mode — See Something, Say Something
|
||||
|
||||
`REPO_MODE` from the preamble tells you who owns issues in this repo:
|
||||
|
||||
- **`solo`** — One person does 80%+ of the work. They own everything. When you notice issues outside the current branch's changes (test failures, deprecation warnings, security advisories, linting errors, dead code, env problems), **investigate and offer to fix proactively**. The solo dev is the only person who will fix it. Default to action.
|
||||
- **`collaborative`** — Multiple active contributors. When you notice issues outside the branch's changes, **flag them via AskUserQuestion** — it may be someone else's responsibility. Default to asking, not fixing.
|
||||
- **`unknown`** — Treat as collaborative (safer default — ask before fixing).
|
||||
|
||||
**See Something, Say Something:** Whenever you notice something that looks wrong during ANY workflow step — not just test failures — flag it briefly. One sentence: what you noticed and its impact. In solo mode, follow up with "Want me to fix it?" In collaborative mode, just flag it and move on.
|
||||
|
||||
Never let a noticed issue silently pass. The whole point is proactive communication.
|
||||
|
||||
## Search Before Building
|
||||
|
||||
Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — **search first.** Read `~/.claude/skills/gstack/ETHOS.md` for the full philosophy.
|
||||
|
||||
**Three layers of knowledge:**
|
||||
- **Layer 1** (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
|
||||
- **Layer 2** (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
|
||||
- **Layer 3** (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.
|
||||
|
||||
**Eureka moment:** When first-principles reasoning reveals conventional wisdom is wrong, name it:
|
||||
"EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
|
||||
|
||||
Log eureka moments:
|
||||
```bash
|
||||
jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
|
||||
```
|
||||
Replace SKILL_NAME and ONE_LINE_SUMMARY. Runs inline — don't stop the workflow.
|
||||
|
||||
**WebSearch fallback:** If WebSearch is unavailable, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
## Contributor Mode
|
||||
|
||||
If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
|
||||
|
||||
**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better!
|
||||
|
||||
**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore.
|
||||
|
||||
**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs.
|
||||
|
||||
**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer):
|
||||
|
||||
```
|
||||
# {Title}
|
||||
|
||||
Hey gstack team — ran into this while using /{skill-name}:
|
||||
|
||||
**What I was trying to do:** {what the user/agent was attempting}
|
||||
**What happened instead:** {what actually happened}
|
||||
**My rating:** {0-10} — {one sentence on why it wasn't a 10}
|
||||
|
||||
## Steps to reproduce
|
||||
1. {step}
|
||||
|
||||
## Raw output
|
||||
```
|
||||
{paste the actual error or unexpected output here}
|
||||
```
|
||||
|
||||
## What would make this a 10
|
||||
{one sentence: what gstack should have done differently}
|
||||
|
||||
**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill}
|
||||
```
|
||||
|
||||
Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
|
||||
|
||||
## Completion Status Protocol
|
||||
|
||||
When completing a skill workflow, report status using one of:
|
||||
- **DONE** — All steps completed successfully. Evidence provided for each claim.
|
||||
- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern.
|
||||
- **BLOCKED** — Cannot proceed. State what is blocking and what was tried.
|
||||
- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need.
|
||||
|
||||
### Escalation
|
||||
|
||||
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
|
||||
|
||||
Bad work is worse than no work. You will not be penalized for escalating.
|
||||
- If you have attempted a task 3 times without success, STOP and escalate.
|
||||
- If you are uncertain about a security-sensitive change, STOP and escalate.
|
||||
- If the scope of work exceeds what you can verify, STOP and escalate.
|
||||
|
||||
Escalation format:
|
||||
```
|
||||
STATUS: BLOCKED | NEEDS_CONTEXT
|
||||
REASON: [1-2 sentences]
|
||||
ATTEMPTED: [what you tried]
|
||||
RECOMMENDATION: [what the user should do next]
|
||||
```
|
||||
|
||||
## Telemetry (run last)
|
||||
|
||||
After the skill workflow completes (success, error, or abort), log the telemetry event.
|
||||
Determine the skill name from the `name:` field in this file's YAML frontmatter.
|
||||
Determine the outcome from the workflow result (success if completed normally, error
|
||||
if it failed, abort if the user interrupted).
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes telemetry to
|
||||
`~/.gstack/analytics/` (user config directory, not project files). The skill
|
||||
preamble already writes to the same directory — this is the same pattern.
|
||||
Skipping this command loses session duration and outcome data.
|
||||
|
||||
Run this bash:
|
||||
|
||||
```bash
|
||||
_TEL_END=$(date +%s)
|
||||
_TEL_DUR=$(( _TEL_END - _TEL_START ))
|
||||
rm -f ~/.gstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
|
||||
~/.claude/skills/gstack/bin/gstack-telemetry-log \
|
||||
--skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
|
||||
--used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &
|
||||
```
|
||||
|
||||
Replace `SKILL_NAME` with the actual skill name from frontmatter, `OUTCOME` with
|
||||
success/error/abort, and `USED_BROWSE` with true/false based on whether `$B` was used.
|
||||
If you cannot determine the outcome, use "unknown". This runs in the background and
|
||||
never blocks the user.
|
||||
|
||||
## Plan Status Footer
|
||||
|
||||
When you are in plan mode and about to call ExitPlanMode:
|
||||
|
||||
1. Check if the plan file already has a `## GSTACK REVIEW REPORT` section.
|
||||
2. If it DOES — skip (a review skill already wrote a richer report).
|
||||
3. If it does NOT — run this command:
|
||||
|
||||
\`\`\`bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-read
|
||||
\`\`\`
|
||||
|
||||
Then write a `## GSTACK REVIEW REPORT` section to the end of the plan file:
|
||||
|
||||
- If the output contains review entries (JSONL lines before `---CONFIG---`): format the
|
||||
standard report table with runs/status/findings per skill, same format as the review
|
||||
skills use.
|
||||
- If the output is `NO_REVIEWS` or empty: write this placeholder table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | 0 | — | — |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | 0 | — | — |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | 0 | — | — |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | 0 | — | — |
|
||||
|
||||
**VERDICT:** NO REVIEWS YET — run \`/autoplan\` for full review pipeline, or individual reviews above.
|
||||
\`\`\`
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
# browse: QA Testing & Dogfooding
|
||||
|
||||
Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.
|
||||
State persists between calls (cookies, tabs, login sessions).
|
||||
|
||||
## SETUP (run this check BEFORE any browse command)
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
B=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
|
||||
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
|
||||
if [ -x "$B" ]; then
|
||||
echo "READY: $B"
|
||||
else
|
||||
echo "NEEDS_SETUP"
|
||||
fi
|
||||
```
|
||||
|
||||
If `NEEDS_SETUP`:
|
||||
1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
|
||||
2. Run: `cd <SKILL_DIR> && ./setup`
|
||||
3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
|
||||
|
||||
## Core QA Patterns
|
||||
|
||||
### 1. Verify a page loads correctly
|
||||
```bash
|
||||
$B goto https://yourapp.com
|
||||
$B text # content loads?
|
||||
$B console # JS errors?
|
||||
$B network # failed requests?
|
||||
$B is visible ".main-content" # key elements present?
|
||||
```
|
||||
|
||||
### 2. Test a user flow
|
||||
```bash
|
||||
$B goto https://app.com/login
|
||||
$B snapshot -i # see all interactive elements
|
||||
$B fill @e3 "user@test.com"
|
||||
$B fill @e4 "password"
|
||||
$B click @e5 # submit
|
||||
$B snapshot -D # diff: what changed after submit?
|
||||
$B is visible ".dashboard" # success state present?
|
||||
```
|
||||
|
||||
### 3. Verify an action worked
|
||||
```bash
|
||||
$B snapshot # baseline
|
||||
$B click @e3 # do something
|
||||
$B snapshot -D # unified diff shows exactly what changed
|
||||
```
|
||||
|
||||
### 4. Visual evidence for bug reports
|
||||
```bash
|
||||
$B snapshot -i -a -o /tmp/annotated.png # labeled screenshot
|
||||
$B screenshot /tmp/bug.png # plain screenshot
|
||||
$B console # error log
|
||||
```
|
||||
|
||||
### 5. Find all clickable elements (including non-ARIA)
|
||||
```bash
|
||||
$B snapshot -C # finds divs with cursor:pointer, onclick, tabindex
|
||||
$B click @c1 # interact with them
|
||||
```
|
||||
|
||||
### 6. Assert element states
|
||||
```bash
|
||||
$B is visible ".modal"
|
||||
$B is enabled "#submit-btn"
|
||||
$B is disabled "#submit-btn"
|
||||
$B is checked "#agree-checkbox"
|
||||
$B is editable "#name-field"
|
||||
$B is focused "#search-input"
|
||||
$B js "document.body.textContent.includes('Success')"
|
||||
```
|
||||
|
||||
### 7. Test responsive layouts
|
||||
```bash
|
||||
$B responsive /tmp/layout # mobile + tablet + desktop screenshots
|
||||
$B viewport 375x812 # or set specific viewport
|
||||
$B screenshot /tmp/mobile.png
|
||||
```
|
||||
|
||||
### 8. Test file uploads
|
||||
```bash
|
||||
$B upload "#file-input" /path/to/file.pdf
|
||||
$B is visible ".upload-success"
|
||||
```
|
||||
|
||||
### 9. Test dialogs
|
||||
```bash
|
||||
$B dialog-accept "yes" # set up handler
|
||||
$B click "#delete-button" # trigger dialog
|
||||
$B dialog # see what appeared
|
||||
$B snapshot -D # verify deletion happened
|
||||
```
|
||||
|
||||
### 10. Compare environments
|
||||
```bash
|
||||
$B diff https://staging.app.com https://prod.app.com
|
||||
```
|
||||
|
||||
### 11. Show screenshots to the user
|
||||
After `$B screenshot`, `$B snapshot -a -o`, or `$B responsive`, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible.
|
||||
|
||||
## User Handoff
|
||||
|
||||
When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor
|
||||
login), hand off to the user:
|
||||
|
||||
```bash
|
||||
# 1. Open a visible Chrome at the current page
|
||||
$B handoff "Stuck on CAPTCHA at login page"
|
||||
|
||||
# 2. Tell the user what happened (via AskUserQuestion)
|
||||
# "I've opened Chrome at the login page. Please solve the CAPTCHA
|
||||
# and let me know when you're done."
|
||||
|
||||
# 3. When user says "done", re-snapshot and continue
|
||||
$B resume
|
||||
```
|
||||
|
||||
**When to use handoff:**
|
||||
- CAPTCHAs or bot detection
|
||||
- Multi-factor authentication (SMS, authenticator app)
|
||||
- OAuth flows that require user interaction
|
||||
- Complex interactions the AI can't handle after 3 attempts
|
||||
|
||||
The browser preserves all state (cookies, localStorage, tabs) across the handoff.
|
||||
After `resume`, you get a fresh snapshot of wherever the user left off.
|
||||
|
||||
## Snapshot Flags
|
||||
|
||||
The snapshot is your primary tool for understanding and interacting with pages.
|
||||
|
||||
```
|
||||
-i --interactive Interactive elements only (buttons, links, inputs) with @e refs
|
||||
-c --compact Compact (no empty structural nodes)
|
||||
-d <N> --depth Limit tree depth (0 = root only, default: unlimited)
|
||||
-s <sel> --selector Scope to CSS selector
|
||||
-D --diff Unified diff against previous snapshot (first call stores baseline)
|
||||
-a --annotate Annotated screenshot with red overlay boxes and ref labels
|
||||
-o <path> --output Output path for annotated screenshot (default: <temp>/browse-annotated.png)
|
||||
-C --cursor-interactive Cursor-interactive elements (@c refs — divs with pointer, onclick)
|
||||
```
|
||||
|
||||
All flags can be combined freely. `-o` only applies when `-a` is also used.
|
||||
Example: `$B snapshot -i -a -C -o /tmp/annotated.png`
|
||||
|
||||
**Ref numbering:** @e refs are assigned sequentially (@e1, @e2, ...) in tree order.
|
||||
@c refs from `-C` are numbered separately (@c1, @c2, ...).
|
||||
|
||||
After snapshot, use @refs as selectors in any command:
|
||||
```bash
|
||||
$B click @e3 $B fill @e4 "value" $B hover @e1
|
||||
$B html @e2 $B css @e5 "color" $B attrs @e6
|
||||
$B click @c1 # cursor-interactive ref (from -C)
|
||||
```
|
||||
|
||||
**Output format:** indented accessibility tree with @ref IDs, one element per line.
|
||||
```
|
||||
@e1 [heading] "Welcome" [level=1]
|
||||
@e2 [textbox] "Email"
|
||||
@e3 [button] "Submit"
|
||||
```
|
||||
|
||||
Refs are invalidated on navigation — run `snapshot` again after `goto`.
|
||||
|
||||
## Full Command List
|
||||
|
||||
### Navigation
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `back` | History back |
|
||||
| `forward` | History forward |
|
||||
| `goto <url>` | Navigate to URL |
|
||||
| `reload` | Reload page |
|
||||
| `url` | Print current URL |
|
||||
|
||||
### Reading
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `accessibility` | Full ARIA tree |
|
||||
| `forms` | Form fields as JSON |
|
||||
| `html [selector]` | innerHTML of selector (throws if not found), or full page HTML if no selector given |
|
||||
| `links` | All links as "text → href" |
|
||||
| `text` | Cleaned page text |
|
||||
|
||||
### Interaction
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `click <sel>` | Click element |
|
||||
| `cookie <name>=<value>` | Set cookie on current page domain |
|
||||
| `cookie-import <json>` | Import cookies from JSON file |
|
||||
| `cookie-import-browser [browser] [--domain d]` | Import cookies from Comet, Chrome, Arc, Brave, or Edge (opens picker, or use --domain for direct import) |
|
||||
| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response |
|
||||
| `dialog-dismiss` | Auto-dismiss next dialog |
|
||||
| `fill <sel> <val>` | Fill input |
|
||||
| `header <name>:<value>` | Set custom request header (colon-separated, sensitive values auto-redacted) |
|
||||
| `hover <sel>` | Hover element |
|
||||
| `press <key>` | Press key — Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown, or modifiers like Shift+Enter |
|
||||
| `scroll [sel]` | Scroll element into view, or scroll to page bottom if no selector |
|
||||
| `select <sel> <val>` | Select dropdown option by value, label, or visible text |
|
||||
| `type <text>` | Type into focused element |
|
||||
| `upload <sel> <file> [file2...]` | Upload file(s) |
|
||||
| `useragent <string>` | Set user agent |
|
||||
| `viewport <WxH>` | Set viewport size |
|
||||
| `wait <sel|--networkidle|--load>` | Wait for element, network idle, or page load (timeout: 15s) |
|
||||
|
||||
### Inspection
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `attrs <sel|@ref>` | Element attributes as JSON |
|
||||
| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) |
|
||||
| `cookies` | All cookies as JSON |
|
||||
| `css <sel> <prop>` | Computed CSS value |
|
||||
| `dialog [--clear]` | Dialog messages |
|
||||
| `eval <file>` | Run JavaScript from file and return result as string (path must be under /tmp or cwd) |
|
||||
| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
|
||||
| `js <expr>` | Run JavaScript expression and return result as string |
|
||||
| `network [--clear]` | Network requests |
|
||||
| `perf` | Page load timings |
|
||||
| `storage [set k v]` | Read all localStorage + sessionStorage as JSON, or set <key> <value> to write localStorage |
|
||||
|
||||
### Visual
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `diff <url1> <url2>` | Text diff between pages |
|
||||
| `pdf [path]` | Save as PDF |
|
||||
| `responsive [prefix]` | Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc. |
|
||||
| `screenshot [--viewport] [--clip x,y,w,h] [selector|@ref] [path]` | Save screenshot (supports element crop via CSS/@ref, --clip region, --viewport) |
|
||||
|
||||
### Snapshot
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `snapshot [flags]` | Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs |
|
||||
|
||||
### Meta
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `chain` | Run commands from JSON stdin. Format: [["cmd","arg1",...],...] |
|
||||
|
||||
### Tabs
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `closetab [id]` | Close tab |
|
||||
| `newtab [url]` | Open new tab |
|
||||
| `tab <id>` | Switch to tab |
|
||||
| `tabs` | List open tabs |
|
||||
|
||||
### Server
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `handoff [message]` | Open visible Chrome at current page for user takeover |
|
||||
| `restart` | Restart server |
|
||||
| `resume` | Re-snapshot after user takeover, return control to AI |
|
||||
| `status` | Health check |
|
||||
| `stop` | Shutdown server |
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
name: browse
|
||||
version: 1.1.0
|
||||
description: |
|
||||
Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
|
||||
elements, verify page state, diff before/after actions, take annotated screenshots, check
|
||||
responsive layouts, test forms and uploads, handle dialogs, and assert element states.
|
||||
~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
|
||||
user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
|
||||
site", "take a screenshot", or "dogfood this".
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- AskUserQuestion
|
||||
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
|
||||
# browse: QA Testing & Dogfooding
|
||||
|
||||
Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.
|
||||
State persists between calls (cookies, tabs, login sessions).
|
||||
|
||||
{{BROWSE_SETUP}}
|
||||
|
||||
## Core QA Patterns
|
||||
|
||||
### 1. Verify a page loads correctly
|
||||
```bash
|
||||
$B goto https://yourapp.com
|
||||
$B text # content loads?
|
||||
$B console # JS errors?
|
||||
$B network # failed requests?
|
||||
$B is visible ".main-content" # key elements present?
|
||||
```
|
||||
|
||||
### 2. Test a user flow
|
||||
```bash
|
||||
$B goto https://app.com/login
|
||||
$B snapshot -i # see all interactive elements
|
||||
$B fill @e3 "user@test.com"
|
||||
$B fill @e4 "password"
|
||||
$B click @e5 # submit
|
||||
$B snapshot -D # diff: what changed after submit?
|
||||
$B is visible ".dashboard" # success state present?
|
||||
```
|
||||
|
||||
### 3. Verify an action worked
|
||||
```bash
|
||||
$B snapshot # baseline
|
||||
$B click @e3 # do something
|
||||
$B snapshot -D # unified diff shows exactly what changed
|
||||
```
|
||||
|
||||
### 4. Visual evidence for bug reports
|
||||
```bash
|
||||
$B snapshot -i -a -o /tmp/annotated.png # labeled screenshot
|
||||
$B screenshot /tmp/bug.png # plain screenshot
|
||||
$B console # error log
|
||||
```
|
||||
|
||||
### 5. Find all clickable elements (including non-ARIA)
|
||||
```bash
|
||||
$B snapshot -C # finds divs with cursor:pointer, onclick, tabindex
|
||||
$B click @c1 # interact with them
|
||||
```
|
||||
|
||||
### 6. Assert element states
|
||||
```bash
|
||||
$B is visible ".modal"
|
||||
$B is enabled "#submit-btn"
|
||||
$B is disabled "#submit-btn"
|
||||
$B is checked "#agree-checkbox"
|
||||
$B is editable "#name-field"
|
||||
$B is focused "#search-input"
|
||||
$B js "document.body.textContent.includes('Success')"
|
||||
```
|
||||
|
||||
### 7. Test responsive layouts
|
||||
```bash
|
||||
$B responsive /tmp/layout # mobile + tablet + desktop screenshots
|
||||
$B viewport 375x812 # or set specific viewport
|
||||
$B screenshot /tmp/mobile.png
|
||||
```
|
||||
|
||||
### 8. Test file uploads
|
||||
```bash
|
||||
$B upload "#file-input" /path/to/file.pdf
|
||||
$B is visible ".upload-success"
|
||||
```
|
||||
|
||||
### 9. Test dialogs
|
||||
```bash
|
||||
$B dialog-accept "yes" # set up handler
|
||||
$B click "#delete-button" # trigger dialog
|
||||
$B dialog # see what appeared
|
||||
$B snapshot -D # verify deletion happened
|
||||
```
|
||||
|
||||
### 10. Compare environments
|
||||
```bash
|
||||
$B diff https://staging.app.com https://prod.app.com
|
||||
```
|
||||
|
||||
### 11. Show screenshots to the user
|
||||
After `$B screenshot`, `$B snapshot -a -o`, or `$B responsive`, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible.
|
||||
|
||||
## User Handoff
|
||||
|
||||
When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor
|
||||
login), hand off to the user:
|
||||
|
||||
```bash
|
||||
# 1. Open a visible Chrome at the current page
|
||||
$B handoff "Stuck on CAPTCHA at login page"
|
||||
|
||||
# 2. Tell the user what happened (via AskUserQuestion)
|
||||
# "I've opened Chrome at the login page. Please solve the CAPTCHA
|
||||
# and let me know when you're done."
|
||||
|
||||
# 3. When user says "done", re-snapshot and continue
|
||||
$B resume
|
||||
```
|
||||
|
||||
**When to use handoff:**
|
||||
- CAPTCHAs or bot detection
|
||||
- Multi-factor authentication (SMS, authenticator app)
|
||||
- OAuth flows that require user interaction
|
||||
- Complex interactions the AI can't handle after 3 attempts
|
||||
|
||||
The browser preserves all state (cookies, localStorage, tabs) across the handoff.
|
||||
After `resume`, you get a fresh snapshot of wherever the user left off.
|
||||
|
||||
## Snapshot Flags
|
||||
|
||||
{{SNAPSHOT_FLAGS}}
|
||||
|
||||
## Full Command List
|
||||
|
||||
{{COMMAND_REFERENCE}}
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
#!/bin/bash
|
||||
# Shim: delegates to compiled find-browse binary, falls back to basic discovery.
|
||||
# The compiled binary handles git root detection for workspace-local installs.
|
||||
DIR="$(cd "$(dirname "$0")/.." && pwd)/dist"
|
||||
if test -x "$DIR/find-browse"; then
|
||||
exec "$DIR/find-browse" "$@"
|
||||
fi
|
||||
# Fallback: basic discovery with priority chain
|
||||
ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
for MARKER in .codex .agents .claude; do
|
||||
if [ -n "$ROOT" ] && test -x "$ROOT/$MARKER/skills/gstack/browse/dist/browse"; then
|
||||
echo "$ROOT/$MARKER/skills/gstack/browse/dist/browse"
|
||||
exit 0
|
||||
fi
|
||||
if test -x "$HOME/$MARKER/skills/gstack/browse/dist/browse"; then
|
||||
echo "$HOME/$MARKER/skills/gstack/browse/dist/browse"
|
||||
exit 0
|
||||
fi
|
||||
done
|
||||
echo "ERROR: browse binary not found. Run: cd <skill-dir> && ./setup" >&2
|
||||
exit 1
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
#!/usr/bin/env bash
|
||||
# Output the remote slug (owner-repo) for the current git repo.
|
||||
# Used by SKILL.md files to derive project-specific paths in ~/.gstack/projects/.
|
||||
set -e
|
||||
URL=$(git remote get-url origin 2>/dev/null || true)
|
||||
if [ -n "$URL" ]; then
|
||||
# Strip trailing .git if present, then extract owner/repo
|
||||
URL="${URL%.git}"
|
||||
# Handle both SSH (git@host:owner/repo) and HTTPS (https://host/owner/repo)
|
||||
OWNER_REPO=$(echo "$URL" | sed -E 's#.*[:/]([^/]+)/([^/]+)$#\1-\2#')
|
||||
echo "$OWNER_REPO"
|
||||
else
|
||||
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
|
||||
fi
|
||||
Binary file not shown.
|
|
@ -0,0 +1,48 @@
|
|||
#!/usr/bin/env bash
|
||||
# Build a Node.js-compatible server bundle for Windows.
|
||||
#
|
||||
# On Windows, Bun can't launch or connect to Playwright's Chromium
|
||||
# (oven-sh/bun#4253, #9911). This script produces a server bundle
|
||||
# that runs under Node.js with Bun API polyfills.
|
||||
|
||||
set -e
|
||||
|
||||
GSTACK_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
|
||||
SRC_DIR="$GSTACK_DIR/browse/src"
|
||||
DIST_DIR="$GSTACK_DIR/browse/dist"
|
||||
|
||||
echo "Building Node-compatible server bundle..."
|
||||
|
||||
# Step 1: Transpile server.ts to a single .mjs bundle (externalize runtime deps)
|
||||
bun build "$SRC_DIR/server.ts" \
|
||||
--target=node \
|
||||
--outfile "$DIST_DIR/server-node.mjs" \
|
||||
--external playwright \
|
||||
--external playwright-core \
|
||||
--external diff \
|
||||
--external "bun:sqlite"
|
||||
|
||||
# Step 2: Post-process
|
||||
# Replace import.meta.dir with a resolvable reference
|
||||
perl -pi -e 's/import\.meta\.dir/__browseNodeSrcDir/g' "$DIST_DIR/server-node.mjs"
|
||||
# Stub out bun:sqlite (macOS-only cookie import, not needed on Windows)
|
||||
perl -pi -e 's|import { Database } from "bun:sqlite";|const Database = null; // bun:sqlite stubbed on Node|g' "$DIST_DIR/server-node.mjs"
|
||||
|
||||
# Step 3: Create the final file with polyfill header injected after the first line
|
||||
{
|
||||
head -1 "$DIST_DIR/server-node.mjs"
|
||||
echo '// ── Windows Node.js compatibility (auto-generated) ──'
|
||||
echo 'import { fileURLToPath as _ftp } from "node:url";'
|
||||
echo 'import { dirname as _dn } from "node:path";'
|
||||
echo 'const __browseNodeSrcDir = _dn(_dn(_ftp(import.meta.url))) + "/src";'
|
||||
echo '{ const _r = createRequire(import.meta.url); _r("./bun-polyfill.cjs"); }'
|
||||
echo '// ── end compatibility ──'
|
||||
tail -n +2 "$DIST_DIR/server-node.mjs"
|
||||
} > "$DIST_DIR/server-node.tmp.mjs"
|
||||
|
||||
mv "$DIST_DIR/server-node.tmp.mjs" "$DIST_DIR/server-node.mjs"
|
||||
|
||||
# Step 4: Copy polyfill to dist/
|
||||
cp "$SRC_DIR/bun-polyfill.cjs" "$DIST_DIR/bun-polyfill.cjs"
|
||||
|
||||
echo "Node server bundle ready: $DIST_DIR/server-node.mjs"
|
||||
|
|
@ -0,0 +1,634 @@
|
|||
/**
|
||||
* Browser lifecycle manager
|
||||
*
|
||||
* Chromium crash handling:
|
||||
* browser.on('disconnected') → log error → process.exit(1)
|
||||
* CLI detects dead server → auto-restarts on next command
|
||||
* We do NOT try to self-heal — don't hide failure.
|
||||
*
|
||||
* Dialog handling:
|
||||
* page.on('dialog') → auto-accept by default → store in dialog buffer
|
||||
* Prevents browser lockup from alert/confirm/prompt
|
||||
*
|
||||
* Context recreation (useragent):
|
||||
* recreateContext() saves cookies/storage/URLs, creates new context,
|
||||
* restores state. Falls back to clean slate on any failure.
|
||||
*/
|
||||
|
||||
import { chromium, type Browser, type BrowserContext, type BrowserContextOptions, type Page, type Locator, type Cookie } from 'playwright';
|
||||
import { addConsoleEntry, addNetworkEntry, addDialogEntry, networkBuffer, type DialogEntry } from './buffers';
|
||||
import { validateNavigationUrl } from './url-validation';
|
||||
|
||||
export interface RefEntry {
|
||||
locator: Locator;
|
||||
role: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
export interface BrowserState {
|
||||
cookies: Cookie[];
|
||||
pages: Array<{
|
||||
url: string;
|
||||
isActive: boolean;
|
||||
storage: { localStorage: Record<string, string>; sessionStorage: Record<string, string> } | null;
|
||||
}>;
|
||||
}
|
||||
|
||||
export class BrowserManager {
|
||||
private browser: Browser | null = null;
|
||||
private context: BrowserContext | null = null;
|
||||
private pages: Map<number, Page> = new Map();
|
||||
private activeTabId: number = 0;
|
||||
private nextTabId: number = 1;
|
||||
private extraHeaders: Record<string, string> = {};
|
||||
private customUserAgent: string | null = null;
|
||||
|
||||
/** Server port — set after server starts, used by cookie-import-browser command */
|
||||
public serverPort: number = 0;
|
||||
|
||||
// ─── Ref Map (snapshot → @e1, @e2, @c1, @c2, ...) ────────
|
||||
private refMap: Map<string, RefEntry> = new Map();
|
||||
|
||||
// ─── Snapshot Diffing ─────────────────────────────────────
|
||||
// NOT cleared on navigation — it's a text baseline for diffing
|
||||
private lastSnapshot: string | null = null;
|
||||
|
||||
// ─── Dialog Handling ──────────────────────────────────────
|
||||
private dialogAutoAccept: boolean = true;
|
||||
private dialogPromptText: string | null = null;
|
||||
|
||||
// ─── Handoff State ─────────────────────────────────────────
|
||||
private isHeaded: boolean = false;
|
||||
private consecutiveFailures: number = 0;
|
||||
|
||||
async launch() {
|
||||
this.browser = await chromium.launch({ headless: true });
|
||||
|
||||
// Chromium crash → exit with clear message
|
||||
this.browser.on('disconnected', () => {
|
||||
console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting.');
|
||||
console.error('[browse] Console/network logs flushed to .gstack/browse-*.log');
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
const contextOptions: BrowserContextOptions = {
|
||||
viewport: { width: 1280, height: 720 },
|
||||
};
|
||||
if (this.customUserAgent) {
|
||||
contextOptions.userAgent = this.customUserAgent;
|
||||
}
|
||||
this.context = await this.browser.newContext(contextOptions);
|
||||
|
||||
if (Object.keys(this.extraHeaders).length > 0) {
|
||||
await this.context.setExtraHTTPHeaders(this.extraHeaders);
|
||||
}
|
||||
|
||||
// Create first tab
|
||||
await this.newTab();
|
||||
}
|
||||
|
||||
async close() {
|
||||
if (this.browser) {
|
||||
// Remove disconnect handler to avoid exit during intentional close
|
||||
this.browser.removeAllListeners('disconnected');
|
||||
// Timeout: headed browser.close() can hang on macOS
|
||||
await Promise.race([
|
||||
this.browser.close(),
|
||||
new Promise(resolve => setTimeout(resolve, 5000)),
|
||||
]).catch(() => {});
|
||||
this.browser = null;
|
||||
}
|
||||
}
|
||||
|
||||
/** Health check — verifies Chromium is connected AND responsive */
|
||||
async isHealthy(): Promise<boolean> {
|
||||
if (!this.browser || !this.browser.isConnected()) return false;
|
||||
try {
|
||||
const page = this.pages.get(this.activeTabId);
|
||||
if (!page) return true; // connected but no pages — still healthy
|
||||
await Promise.race([
|
||||
page.evaluate('1'),
|
||||
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
|
||||
]);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Tab Management ────────────────────────────────────────
|
||||
async newTab(url?: string): Promise<number> {
|
||||
if (!this.context) throw new Error('Browser not launched');
|
||||
|
||||
// Validate URL before allocating page to avoid zombie tabs on rejection
|
||||
if (url) {
|
||||
await validateNavigationUrl(url);
|
||||
}
|
||||
|
||||
const page = await this.context.newPage();
|
||||
const id = this.nextTabId++;
|
||||
this.pages.set(id, page);
|
||||
this.activeTabId = id;
|
||||
|
||||
// Wire up console/network/dialog capture
|
||||
this.wirePageEvents(page);
|
||||
|
||||
if (url) {
|
||||
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
}
|
||||
|
||||
return id;
|
||||
}
|
||||
|
||||
async closeTab(id?: number): Promise<void> {
|
||||
const tabId = id ?? this.activeTabId;
|
||||
const page = this.pages.get(tabId);
|
||||
if (!page) throw new Error(`Tab ${tabId} not found`);
|
||||
|
||||
await page.close();
|
||||
this.pages.delete(tabId);
|
||||
|
||||
// Switch to another tab if we closed the active one
|
||||
if (tabId === this.activeTabId) {
|
||||
const remaining = [...this.pages.keys()];
|
||||
if (remaining.length > 0) {
|
||||
this.activeTabId = remaining[remaining.length - 1];
|
||||
} else {
|
||||
// No tabs left — create a new blank one
|
||||
await this.newTab();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
switchTab(id: number): void {
|
||||
if (!this.pages.has(id)) throw new Error(`Tab ${id} not found`);
|
||||
this.activeTabId = id;
|
||||
}
|
||||
|
||||
getTabCount(): number {
|
||||
return this.pages.size;
|
||||
}
|
||||
|
||||
async getTabListWithTitles(): Promise<Array<{ id: number; url: string; title: string; active: boolean }>> {
|
||||
const tabs: Array<{ id: number; url: string; title: string; active: boolean }> = [];
|
||||
for (const [id, page] of this.pages) {
|
||||
tabs.push({
|
||||
id,
|
||||
url: page.url(),
|
||||
title: await page.title().catch(() => ''),
|
||||
active: id === this.activeTabId,
|
||||
});
|
||||
}
|
||||
return tabs;
|
||||
}
|
||||
|
||||
// ─── Page Access ───────────────────────────────────────────
|
||||
getPage(): Page {
|
||||
const page = this.pages.get(this.activeTabId);
|
||||
if (!page) throw new Error('No active page. Use "browse goto <url>" first.');
|
||||
return page;
|
||||
}
|
||||
|
||||
getCurrentUrl(): string {
|
||||
try {
|
||||
return this.getPage().url();
|
||||
} catch {
|
||||
return 'about:blank';
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Ref Map ──────────────────────────────────────────────
|
||||
setRefMap(refs: Map<string, RefEntry>) {
|
||||
this.refMap = refs;
|
||||
}
|
||||
|
||||
clearRefs() {
|
||||
this.refMap.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a selector that may be a @ref (e.g., "@e3", "@c1") or a CSS selector.
|
||||
* Returns { locator } for refs or { selector } for CSS selectors.
|
||||
*/
|
||||
async resolveRef(selector: string): Promise<{ locator: Locator } | { selector: string }> {
|
||||
if (selector.startsWith('@e') || selector.startsWith('@c')) {
|
||||
const ref = selector.slice(1); // "e3" or "c1"
|
||||
const entry = this.refMap.get(ref);
|
||||
if (!entry) {
|
||||
throw new Error(
|
||||
`Ref ${selector} not found. Run 'snapshot' to get fresh refs.`
|
||||
);
|
||||
}
|
||||
const count = await entry.locator.count();
|
||||
if (count === 0) {
|
||||
throw new Error(
|
||||
`Ref ${selector} (${entry.role} "${entry.name}") is stale — element no longer exists. ` +
|
||||
`Run 'snapshot' for fresh refs.`
|
||||
);
|
||||
}
|
||||
return { locator: entry.locator };
|
||||
}
|
||||
return { selector };
|
||||
}
|
||||
|
||||
/** Get the ARIA role for a ref selector, or null for CSS selectors / unknown refs. */
|
||||
getRefRole(selector: string): string | null {
|
||||
if (selector.startsWith('@e') || selector.startsWith('@c')) {
|
||||
const entry = this.refMap.get(selector.slice(1));
|
||||
return entry?.role ?? null;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
getRefCount(): number {
|
||||
return this.refMap.size;
|
||||
}
|
||||
|
||||
// ─── Snapshot Diffing ─────────────────────────────────────
|
||||
setLastSnapshot(text: string | null) {
|
||||
this.lastSnapshot = text;
|
||||
}
|
||||
|
||||
getLastSnapshot(): string | null {
|
||||
return this.lastSnapshot;
|
||||
}
|
||||
|
||||
// ─── Dialog Control ───────────────────────────────────────
|
||||
setDialogAutoAccept(accept: boolean) {
|
||||
this.dialogAutoAccept = accept;
|
||||
}
|
||||
|
||||
getDialogAutoAccept(): boolean {
|
||||
return this.dialogAutoAccept;
|
||||
}
|
||||
|
||||
setDialogPromptText(text: string | null) {
|
||||
this.dialogPromptText = text;
|
||||
}
|
||||
|
||||
getDialogPromptText(): string | null {
|
||||
return this.dialogPromptText;
|
||||
}
|
||||
|
||||
// ─── Viewport ──────────────────────────────────────────────
|
||||
async setViewport(width: number, height: number) {
|
||||
await this.getPage().setViewportSize({ width, height });
|
||||
}
|
||||
|
||||
// ─── Extra Headers ─────────────────────────────────────────
|
||||
async setExtraHeader(name: string, value: string) {
|
||||
this.extraHeaders[name] = value;
|
||||
if (this.context) {
|
||||
await this.context.setExtraHTTPHeaders(this.extraHeaders);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── User Agent ────────────────────────────────────────────
|
||||
setUserAgent(ua: string) {
|
||||
this.customUserAgent = ua;
|
||||
}
|
||||
|
||||
getUserAgent(): string | null {
|
||||
return this.customUserAgent;
|
||||
}
|
||||
|
||||
// ─── State Save/Restore (shared by recreateContext + handoff) ─
|
||||
/**
|
||||
* Capture browser state: cookies, localStorage, sessionStorage, URLs, active tab.
|
||||
* Skips pages that fail storage reads (e.g., already closed).
|
||||
*/
|
||||
async saveState(): Promise<BrowserState> {
|
||||
if (!this.context) throw new Error('Browser not launched');
|
||||
|
||||
const cookies = await this.context.cookies();
|
||||
const pages: BrowserState['pages'] = [];
|
||||
|
||||
for (const [id, page] of this.pages) {
|
||||
const url = page.url();
|
||||
let storage = null;
|
||||
try {
|
||||
storage = await page.evaluate(() => ({
|
||||
localStorage: { ...localStorage },
|
||||
sessionStorage: { ...sessionStorage },
|
||||
}));
|
||||
} catch {}
|
||||
pages.push({
|
||||
url: url === 'about:blank' ? '' : url,
|
||||
isActive: id === this.activeTabId,
|
||||
storage,
|
||||
});
|
||||
}
|
||||
|
||||
return { cookies, pages };
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore browser state into the current context: cookies, pages, storage.
|
||||
* Navigates to saved URLs, restores storage, wires page events.
|
||||
* Failures on individual pages are swallowed — partial restore is better than none.
|
||||
*/
|
||||
async restoreState(state: BrowserState): Promise<void> {
|
||||
if (!this.context) throw new Error('Browser not launched');
|
||||
|
||||
// Restore cookies
|
||||
if (state.cookies.length > 0) {
|
||||
await this.context.addCookies(state.cookies);
|
||||
}
|
||||
|
||||
// Re-create pages
|
||||
let activeId: number | null = null;
|
||||
for (const saved of state.pages) {
|
||||
const page = await this.context.newPage();
|
||||
const id = this.nextTabId++;
|
||||
this.pages.set(id, page);
|
||||
this.wirePageEvents(page);
|
||||
|
||||
if (saved.url) {
|
||||
await page.goto(saved.url, { waitUntil: 'domcontentloaded', timeout: 15000 }).catch(() => {});
|
||||
}
|
||||
|
||||
if (saved.storage) {
|
||||
try {
|
||||
await page.evaluate((s: { localStorage: Record<string, string>; sessionStorage: Record<string, string> }) => {
|
||||
if (s.localStorage) {
|
||||
for (const [k, v] of Object.entries(s.localStorage)) {
|
||||
localStorage.setItem(k, v);
|
||||
}
|
||||
}
|
||||
if (s.sessionStorage) {
|
||||
for (const [k, v] of Object.entries(s.sessionStorage)) {
|
||||
sessionStorage.setItem(k, v);
|
||||
}
|
||||
}
|
||||
}, saved.storage);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
if (saved.isActive) activeId = id;
|
||||
}
|
||||
|
||||
// If no pages were saved, create a blank one
|
||||
if (this.pages.size === 0) {
|
||||
await this.newTab();
|
||||
} else {
|
||||
this.activeTabId = activeId ?? [...this.pages.keys()][0];
|
||||
}
|
||||
|
||||
// Clear refs — pages are new, locators are stale
|
||||
this.clearRefs();
|
||||
}
|
||||
|
||||
/**
|
||||
* Recreate the browser context to apply user agent changes.
|
||||
* Saves and restores cookies, localStorage, sessionStorage, and open pages.
|
||||
* Falls back to a clean slate on any failure.
|
||||
*/
|
||||
async recreateContext(): Promise<string | null> {
|
||||
if (!this.browser || !this.context) {
|
||||
throw new Error('Browser not launched');
|
||||
}
|
||||
|
||||
try {
|
||||
// 1. Save state
|
||||
const state = await this.saveState();
|
||||
|
||||
// 2. Close old pages and context
|
||||
for (const page of this.pages.values()) {
|
||||
await page.close().catch(() => {});
|
||||
}
|
||||
this.pages.clear();
|
||||
await this.context.close().catch(() => {});
|
||||
|
||||
// 3. Create new context with updated settings
|
||||
const contextOptions: BrowserContextOptions = {
|
||||
viewport: { width: 1280, height: 720 },
|
||||
};
|
||||
if (this.customUserAgent) {
|
||||
contextOptions.userAgent = this.customUserAgent;
|
||||
}
|
||||
this.context = await this.browser.newContext(contextOptions);
|
||||
|
||||
if (Object.keys(this.extraHeaders).length > 0) {
|
||||
await this.context.setExtraHTTPHeaders(this.extraHeaders);
|
||||
}
|
||||
|
||||
// 4. Restore state
|
||||
await this.restoreState(state);
|
||||
|
||||
return null; // success
|
||||
} catch (err: unknown) {
|
||||
// Fallback: create a clean context + blank tab
|
||||
try {
|
||||
this.pages.clear();
|
||||
if (this.context) await this.context.close().catch(() => {});
|
||||
|
||||
const contextOptions: BrowserContextOptions = {
|
||||
viewport: { width: 1280, height: 720 },
|
||||
};
|
||||
if (this.customUserAgent) {
|
||||
contextOptions.userAgent = this.customUserAgent;
|
||||
}
|
||||
this.context = await this.browser!.newContext(contextOptions);
|
||||
await this.newTab();
|
||||
this.clearRefs();
|
||||
} catch {
|
||||
// If even the fallback fails, we're in trouble — but browser is still alive
|
||||
}
|
||||
return `Context recreation failed: ${err instanceof Error ? err.message : String(err)}. Browser reset to blank tab.`;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Handoff: Headless → Headed ─────────────────────────────
|
||||
/**
|
||||
* Hand off browser control to the user by relaunching in headed mode.
|
||||
*
|
||||
* Flow (launch-first-close-second for safe rollback):
|
||||
* 1. Save state from current headless browser
|
||||
* 2. Launch NEW headed browser
|
||||
* 3. Restore state into new browser
|
||||
* 4. Close OLD headless browser
|
||||
* If step 2 fails → return error, headless browser untouched
|
||||
*/
|
||||
async handoff(message: string): Promise<string> {
|
||||
if (this.isHeaded) {
|
||||
return `HANDOFF: Already in headed mode at ${this.getCurrentUrl()}`;
|
||||
}
|
||||
if (!this.browser || !this.context) {
|
||||
throw new Error('Browser not launched');
|
||||
}
|
||||
|
||||
// 1. Save state from current browser
|
||||
const state = await this.saveState();
|
||||
const currentUrl = this.getCurrentUrl();
|
||||
|
||||
// 2. Launch new headed browser (try-catch — if this fails, headless stays running)
|
||||
let newBrowser: Browser;
|
||||
try {
|
||||
newBrowser = await chromium.launch({ headless: false, timeout: 15000 });
|
||||
} catch (err: unknown) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
return `ERROR: Cannot open headed browser — ${msg}. Headless browser still running.`;
|
||||
}
|
||||
|
||||
// 3. Create context and restore state into new headed browser
|
||||
try {
|
||||
const contextOptions: BrowserContextOptions = {
|
||||
viewport: { width: 1280, height: 720 },
|
||||
};
|
||||
if (this.customUserAgent) {
|
||||
contextOptions.userAgent = this.customUserAgent;
|
||||
}
|
||||
const newContext = await newBrowser.newContext(contextOptions);
|
||||
|
||||
if (Object.keys(this.extraHeaders).length > 0) {
|
||||
await newContext.setExtraHTTPHeaders(this.extraHeaders);
|
||||
}
|
||||
|
||||
// Swap to new browser/context before restoreState (it uses this.context)
|
||||
const oldBrowser = this.browser;
|
||||
const oldContext = this.context;
|
||||
|
||||
this.browser = newBrowser;
|
||||
this.context = newContext;
|
||||
this.pages.clear();
|
||||
|
||||
// Register crash handler on new browser
|
||||
this.browser.on('disconnected', () => {
|
||||
console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting.');
|
||||
console.error('[browse] Console/network logs flushed to .gstack/browse-*.log');
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
await this.restoreState(state);
|
||||
this.isHeaded = true;
|
||||
|
||||
// 4. Close old headless browser (fire-and-forget — close() can hang
|
||||
// when another Playwright instance is active, so we don't await it)
|
||||
oldBrowser.removeAllListeners('disconnected');
|
||||
oldBrowser.close().catch(() => {});
|
||||
|
||||
return [
|
||||
`HANDOFF: Browser opened at ${currentUrl}`,
|
||||
`MESSAGE: ${message}`,
|
||||
`STATUS: Waiting for user. Run 'resume' when done.`,
|
||||
].join('\n');
|
||||
} catch (err: unknown) {
|
||||
// Restore failed — close the new browser, keep old one
|
||||
await newBrowser.close().catch(() => {});
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
return `ERROR: Handoff failed during state restore — ${msg}. Headless browser still running.`;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resume AI control after user handoff.
|
||||
* Clears stale refs and resets failure counter.
|
||||
* The meta-command handler calls handleSnapshot() after this.
|
||||
*/
|
||||
resume(): void {
|
||||
this.clearRefs();
|
||||
this.resetFailures();
|
||||
}
|
||||
|
||||
getIsHeaded(): boolean {
|
||||
return this.isHeaded;
|
||||
}
|
||||
|
||||
// ─── Auto-handoff Hint (consecutive failure tracking) ───────
|
||||
incrementFailures(): void {
|
||||
this.consecutiveFailures++;
|
||||
}
|
||||
|
||||
resetFailures(): void {
|
||||
this.consecutiveFailures = 0;
|
||||
}
|
||||
|
||||
getFailureHint(): string | null {
|
||||
if (this.consecutiveFailures >= 3 && !this.isHeaded) {
|
||||
return `HINT: ${this.consecutiveFailures} consecutive failures. Consider using 'handoff' to let the user help.`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
// ─── Console/Network/Dialog/Ref Wiring ────────────────────
|
||||
private wirePageEvents(page: Page) {
|
||||
// Clear ref map on navigation — refs point to stale elements after page change
|
||||
// (lastSnapshot is NOT cleared — it's a text baseline for diffing)
|
||||
page.on('framenavigated', (frame) => {
|
||||
if (frame === page.mainFrame()) {
|
||||
this.clearRefs();
|
||||
}
|
||||
});
|
||||
|
||||
// ─── Dialog auto-handling (prevents browser lockup) ─────
|
||||
page.on('dialog', async (dialog) => {
|
||||
const entry: DialogEntry = {
|
||||
timestamp: Date.now(),
|
||||
type: dialog.type(),
|
||||
message: dialog.message(),
|
||||
defaultValue: dialog.defaultValue() || undefined,
|
||||
action: this.dialogAutoAccept ? 'accepted' : 'dismissed',
|
||||
response: this.dialogAutoAccept ? (this.dialogPromptText ?? undefined) : undefined,
|
||||
};
|
||||
addDialogEntry(entry);
|
||||
|
||||
try {
|
||||
if (this.dialogAutoAccept) {
|
||||
await dialog.accept(this.dialogPromptText ?? undefined);
|
||||
} else {
|
||||
await dialog.dismiss();
|
||||
}
|
||||
} catch {
|
||||
// Dialog may have been dismissed by navigation — ignore
|
||||
}
|
||||
});
|
||||
|
||||
page.on('console', (msg) => {
|
||||
addConsoleEntry({
|
||||
timestamp: Date.now(),
|
||||
level: msg.type(),
|
||||
text: msg.text(),
|
||||
});
|
||||
});
|
||||
|
||||
page.on('request', (req) => {
|
||||
addNetworkEntry({
|
||||
timestamp: Date.now(),
|
||||
method: req.method(),
|
||||
url: req.url(),
|
||||
});
|
||||
});
|
||||
|
||||
page.on('response', (res) => {
|
||||
// Find matching request entry and update it (backward scan)
|
||||
const url = res.url();
|
||||
const status = res.status();
|
||||
for (let i = networkBuffer.length - 1; i >= 0; i--) {
|
||||
const entry = networkBuffer.get(i);
|
||||
if (entry && entry.url === url && !entry.status) {
|
||||
networkBuffer.set(i, { ...entry, status, duration: Date.now() - entry.timestamp });
|
||||
break;
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Capture response sizes via response finished
|
||||
page.on('requestfinished', async (req) => {
|
||||
try {
|
||||
const res = await req.response();
|
||||
if (res) {
|
||||
const url = req.url();
|
||||
const body = await res.body().catch(() => null);
|
||||
const size = body ? body.length : 0;
|
||||
for (let i = networkBuffer.length - 1; i >= 0; i--) {
|
||||
const entry = networkBuffer.get(i);
|
||||
if (entry && entry.url === url && !entry.size) {
|
||||
networkBuffer.set(i, { ...entry, size });
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,137 @@
|
|||
/**
|
||||
* Shared buffers and types — extracted to break circular dependency
|
||||
* between server.ts and browser-manager.ts
|
||||
*
|
||||
* CircularBuffer<T>: O(1) insert ring buffer with fixed capacity.
|
||||
*
|
||||
* ┌───┬───┬───┬───┬───┬───┐
|
||||
* │ 3 │ 4 │ 5 │ │ 1 │ 2 │ capacity=6, head=4, size=5
|
||||
* └───┴───┴───┴───┴─▲─┴───┘
|
||||
* │
|
||||
* head (oldest entry)
|
||||
*
|
||||
* push() writes at (head+size) % capacity, O(1)
|
||||
* toArray() returns entries in insertion order, O(n)
|
||||
* totalAdded keeps incrementing past capacity (flush cursor)
|
||||
*/
|
||||
|
||||
// ─── CircularBuffer ─────────────────────────────────────────
|
||||
|
||||
export class CircularBuffer<T> {
|
||||
private buffer: (T | undefined)[];
|
||||
private head: number = 0;
|
||||
private _size: number = 0;
|
||||
private _totalAdded: number = 0;
|
||||
readonly capacity: number;
|
||||
|
||||
constructor(capacity: number) {
|
||||
this.capacity = capacity;
|
||||
this.buffer = new Array(capacity);
|
||||
}
|
||||
|
||||
push(entry: T): void {
|
||||
const index = (this.head + this._size) % this.capacity;
|
||||
this.buffer[index] = entry;
|
||||
if (this._size < this.capacity) {
|
||||
this._size++;
|
||||
} else {
|
||||
// Buffer full — advance head (overwrites oldest)
|
||||
this.head = (this.head + 1) % this.capacity;
|
||||
}
|
||||
this._totalAdded++;
|
||||
}
|
||||
|
||||
/** Return entries in insertion order (oldest first) */
|
||||
toArray(): T[] {
|
||||
const result: T[] = [];
|
||||
for (let i = 0; i < this._size; i++) {
|
||||
result.push(this.buffer[(this.head + i) % this.capacity] as T);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/** Return the last N entries (most recent first → reversed to oldest first) */
|
||||
last(n: number): T[] {
|
||||
const count = Math.min(n, this._size);
|
||||
const result: T[] = [];
|
||||
const start = (this.head + this._size - count) % this.capacity;
|
||||
for (let i = 0; i < count; i++) {
|
||||
result.push(this.buffer[(start + i) % this.capacity] as T);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
get length(): number {
|
||||
return this._size;
|
||||
}
|
||||
|
||||
get totalAdded(): number {
|
||||
return this._totalAdded;
|
||||
}
|
||||
|
||||
clear(): void {
|
||||
this.head = 0;
|
||||
this._size = 0;
|
||||
// Don't reset totalAdded — flush cursor depends on it
|
||||
}
|
||||
|
||||
/** Get entry by index (0 = oldest) — used by network response matching */
|
||||
get(index: number): T | undefined {
|
||||
if (index < 0 || index >= this._size) return undefined;
|
||||
return this.buffer[(this.head + index) % this.capacity];
|
||||
}
|
||||
|
||||
/** Set entry by index (0 = oldest) — used by network response matching */
|
||||
set(index: number, entry: T): void {
|
||||
if (index < 0 || index >= this._size) return;
|
||||
this.buffer[(this.head + index) % this.capacity] = entry;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Entry Types ────────────────────────────────────────────
|
||||
|
||||
export interface LogEntry {
|
||||
timestamp: number;
|
||||
level: string;
|
||||
text: string;
|
||||
}
|
||||
|
||||
export interface NetworkEntry {
|
||||
timestamp: number;
|
||||
method: string;
|
||||
url: string;
|
||||
status?: number;
|
||||
duration?: number;
|
||||
size?: number;
|
||||
}
|
||||
|
||||
export interface DialogEntry {
|
||||
timestamp: number;
|
||||
type: string; // 'alert' | 'confirm' | 'prompt' | 'beforeunload'
|
||||
message: string;
|
||||
defaultValue?: string;
|
||||
action: string; // 'accepted' | 'dismissed'
|
||||
response?: string; // text provided for prompt
|
||||
}
|
||||
|
||||
// ─── Buffer Instances ───────────────────────────────────────
|
||||
|
||||
const HIGH_WATER_MARK = 50_000;
|
||||
|
||||
export const consoleBuffer = new CircularBuffer<LogEntry>(HIGH_WATER_MARK);
|
||||
export const networkBuffer = new CircularBuffer<NetworkEntry>(HIGH_WATER_MARK);
|
||||
export const dialogBuffer = new CircularBuffer<DialogEntry>(HIGH_WATER_MARK);
|
||||
|
||||
// ─── Convenience add functions ──────────────────────────────
|
||||
|
||||
export function addConsoleEntry(entry: LogEntry) {
|
||||
consoleBuffer.push(entry);
|
||||
}
|
||||
|
||||
export function addNetworkEntry(entry: NetworkEntry) {
|
||||
networkBuffer.push(entry);
|
||||
}
|
||||
|
||||
export function addDialogEntry(entry: DialogEntry) {
|
||||
dialogBuffer.push(entry);
|
||||
}
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
/**
|
||||
* Bun API polyfill for Node.js — Windows compatibility layer.
|
||||
*
|
||||
* On Windows, Bun can't launch or connect to Playwright's Chromium
|
||||
* (oven-sh/bun#4253, #9911). The browse server falls back to running
|
||||
* under Node.js with this polyfill providing Bun API equivalents.
|
||||
*
|
||||
* Loaded via --require before the transpiled server bundle.
|
||||
*/
|
||||
|
||||
'use strict';
|
||||
|
||||
const http = require('http');
|
||||
const { spawnSync, spawn } = require('child_process');
|
||||
|
||||
globalThis.Bun = {
|
||||
serve(options) {
|
||||
const { port, hostname = '127.0.0.1', fetch } = options;
|
||||
|
||||
const server = http.createServer(async (nodeReq, nodeRes) => {
|
||||
try {
|
||||
const url = `http://${hostname}:${port}${nodeReq.url}`;
|
||||
const headers = new Headers();
|
||||
for (const [key, val] of Object.entries(nodeReq.headers)) {
|
||||
if (val) headers.set(key, Array.isArray(val) ? val[0] : val);
|
||||
}
|
||||
|
||||
let body = null;
|
||||
if (nodeReq.method !== 'GET' && nodeReq.method !== 'HEAD') {
|
||||
body = await new Promise((resolve) => {
|
||||
const chunks = [];
|
||||
nodeReq.on('data', (chunk) => chunks.push(chunk));
|
||||
nodeReq.on('end', () => resolve(Buffer.concat(chunks)));
|
||||
});
|
||||
}
|
||||
|
||||
const webReq = new Request(url, {
|
||||
method: nodeReq.method,
|
||||
headers,
|
||||
body,
|
||||
});
|
||||
|
||||
const webRes = await fetch(webReq);
|
||||
|
||||
nodeRes.statusCode = webRes.status;
|
||||
webRes.headers.forEach((val, key) => {
|
||||
nodeRes.setHeader(key, val);
|
||||
});
|
||||
|
||||
const resBody = await webRes.arrayBuffer();
|
||||
nodeRes.end(Buffer.from(resBody));
|
||||
} catch (err) {
|
||||
nodeRes.statusCode = 500;
|
||||
nodeRes.end(JSON.stringify({ error: err.message }));
|
||||
}
|
||||
});
|
||||
|
||||
server.listen(port, hostname);
|
||||
|
||||
return {
|
||||
stop() { server.close(); },
|
||||
port,
|
||||
hostname,
|
||||
};
|
||||
},
|
||||
|
||||
spawnSync(cmd, options = {}) {
|
||||
const [command, ...args] = cmd;
|
||||
const result = spawnSync(command, args, {
|
||||
stdio: [
|
||||
options.stdin || 'pipe',
|
||||
options.stdout === 'pipe' ? 'pipe' : 'ignore',
|
||||
options.stderr === 'pipe' ? 'pipe' : 'ignore',
|
||||
],
|
||||
timeout: options.timeout,
|
||||
env: options.env,
|
||||
cwd: options.cwd,
|
||||
});
|
||||
|
||||
return {
|
||||
exitCode: result.status,
|
||||
stdout: result.stdout || Buffer.from(''),
|
||||
stderr: result.stderr || Buffer.from(''),
|
||||
};
|
||||
},
|
||||
|
||||
spawn(cmd, options = {}) {
|
||||
const [command, ...args] = cmd;
|
||||
const stdio = options.stdio || ['pipe', 'pipe', 'pipe'];
|
||||
const proc = spawn(command, args, {
|
||||
stdio,
|
||||
env: options.env,
|
||||
cwd: options.cwd,
|
||||
});
|
||||
|
||||
return {
|
||||
pid: proc.pid,
|
||||
stdout: proc.stdout,
|
||||
stderr: proc.stderr,
|
||||
stdin: proc.stdin,
|
||||
unref() { proc.unref(); },
|
||||
kill(signal) { proc.kill(signal); },
|
||||
};
|
||||
},
|
||||
|
||||
sleep(ms) {
|
||||
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||
},
|
||||
};
|
||||
|
|
@ -0,0 +1,420 @@
|
|||
/**
|
||||
* gstack CLI — thin wrapper that talks to the persistent server
|
||||
*
|
||||
* Flow:
|
||||
* 1. Read .gstack/browse.json for port + token
|
||||
* 2. If missing or stale PID → start server in background
|
||||
* 3. Health check + version mismatch detection
|
||||
* 4. Send command via HTTP POST
|
||||
* 5. Print response to stdout (or stderr for errors)
|
||||
*/
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { resolveConfig, ensureStateDir, readVersionHash } from './config';
|
||||
|
||||
const config = resolveConfig();
|
||||
const IS_WINDOWS = process.platform === 'win32';
|
||||
const MAX_START_WAIT = IS_WINDOWS ? 15000 : 8000; // Node+Chromium takes longer on Windows
|
||||
|
||||
export function resolveServerScript(
|
||||
env: Record<string, string | undefined> = process.env,
|
||||
metaDir: string = import.meta.dir,
|
||||
execPath: string = process.execPath
|
||||
): string {
|
||||
if (env.BROWSE_SERVER_SCRIPT) {
|
||||
return env.BROWSE_SERVER_SCRIPT;
|
||||
}
|
||||
|
||||
// Dev mode: cli.ts runs directly from browse/src
|
||||
// On macOS/Linux, import.meta.dir starts with /
|
||||
// On Windows, it starts with a drive letter (e.g., C:\...)
|
||||
if (!metaDir.includes('$bunfs')) {
|
||||
const direct = path.resolve(metaDir, 'server.ts');
|
||||
if (fs.existsSync(direct)) {
|
||||
return direct;
|
||||
}
|
||||
}
|
||||
|
||||
// Compiled binary: derive the source tree from browse/dist/browse
|
||||
if (execPath) {
|
||||
const adjacent = path.resolve(path.dirname(execPath), '..', 'src', 'server.ts');
|
||||
if (fs.existsSync(adjacent)) {
|
||||
return adjacent;
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(
|
||||
'Cannot find server.ts. Set BROWSE_SERVER_SCRIPT env or run from the browse source tree.'
|
||||
);
|
||||
}
|
||||
|
||||
const SERVER_SCRIPT = resolveServerScript();
|
||||
|
||||
/**
|
||||
* On Windows, resolve the Node.js-compatible server bundle.
|
||||
* Falls back to null if not found (server will use Bun instead).
|
||||
*/
|
||||
export function resolveNodeServerScript(
|
||||
metaDir: string = import.meta.dir,
|
||||
execPath: string = process.execPath
|
||||
): string | null {
|
||||
// Dev mode
|
||||
if (!metaDir.includes('$bunfs')) {
|
||||
const distScript = path.resolve(metaDir, '..', 'dist', 'server-node.mjs');
|
||||
if (fs.existsSync(distScript)) return distScript;
|
||||
}
|
||||
|
||||
// Compiled binary: browse/dist/browse → browse/dist/server-node.mjs
|
||||
if (execPath) {
|
||||
const adjacent = path.resolve(path.dirname(execPath), 'server-node.mjs');
|
||||
if (fs.existsSync(adjacent)) return adjacent;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
const NODE_SERVER_SCRIPT = IS_WINDOWS ? resolveNodeServerScript() : null;
|
||||
|
||||
interface ServerState {
|
||||
pid: number;
|
||||
port: number;
|
||||
token: string;
|
||||
startedAt: string;
|
||||
serverPath: string;
|
||||
binaryVersion?: string;
|
||||
}
|
||||
|
||||
// ─── State File ────────────────────────────────────────────────
|
||||
function readState(): ServerState | null {
|
||||
try {
|
||||
const data = fs.readFileSync(config.stateFile, 'utf-8');
|
||||
return JSON.parse(data);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function isProcessAlive(pid: number): boolean {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Process Management ─────────────────────────────────────────
|
||||
async function killServer(pid: number): Promise<void> {
|
||||
if (!isProcessAlive(pid)) return;
|
||||
|
||||
try { process.kill(pid, 'SIGTERM'); } catch { return; }
|
||||
|
||||
// Wait up to 2s for graceful shutdown
|
||||
const deadline = Date.now() + 2000;
|
||||
while (Date.now() < deadline && isProcessAlive(pid)) {
|
||||
await Bun.sleep(100);
|
||||
}
|
||||
|
||||
// Force kill if still alive
|
||||
if (isProcessAlive(pid)) {
|
||||
try { process.kill(pid, 'SIGKILL'); } catch {}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Clean up legacy /tmp/browse-server*.json files from before project-local state.
|
||||
* Verifies PID ownership before sending signals.
|
||||
*/
|
||||
function cleanupLegacyState(): void {
|
||||
try {
|
||||
const files = fs.readdirSync('/tmp').filter(f => f.startsWith('browse-server') && f.endsWith('.json'));
|
||||
for (const file of files) {
|
||||
const fullPath = `/tmp/${file}`;
|
||||
try {
|
||||
const data = JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
|
||||
if (data.pid && isProcessAlive(data.pid)) {
|
||||
// Verify this is actually a browse server before killing
|
||||
const check = Bun.spawnSync(['ps', '-p', String(data.pid), '-o', 'command='], {
|
||||
stdout: 'pipe', stderr: 'pipe', timeout: 2000,
|
||||
});
|
||||
const cmd = check.stdout.toString().trim();
|
||||
if (cmd.includes('bun') || cmd.includes('server.ts')) {
|
||||
try { process.kill(data.pid, 'SIGTERM'); } catch {}
|
||||
}
|
||||
}
|
||||
fs.unlinkSync(fullPath);
|
||||
} catch {
|
||||
// Best effort — skip files we can't parse or clean up
|
||||
}
|
||||
}
|
||||
// Clean up legacy log files too
|
||||
const logFiles = fs.readdirSync('/tmp').filter(f =>
|
||||
f.startsWith('browse-console') || f.startsWith('browse-network') || f.startsWith('browse-dialog')
|
||||
);
|
||||
for (const file of logFiles) {
|
||||
try { fs.unlinkSync(`/tmp/${file}`); } catch {}
|
||||
}
|
||||
} catch {
|
||||
// /tmp read failed — skip legacy cleanup
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Server Lifecycle ──────────────────────────────────────────
|
||||
async function startServer(): Promise<ServerState> {
|
||||
ensureStateDir(config);
|
||||
|
||||
// Clean up stale state file
|
||||
try { fs.unlinkSync(config.stateFile); } catch {}
|
||||
|
||||
// Start server as detached background process.
|
||||
// On Windows, Bun can't launch/connect to Playwright's Chromium (oven-sh/bun#4253, #9911).
|
||||
// Fall back to running the server under Node.js with Bun API polyfills.
|
||||
const useNode = IS_WINDOWS && NODE_SERVER_SCRIPT;
|
||||
const serverCmd = useNode
|
||||
? ['node', NODE_SERVER_SCRIPT]
|
||||
: ['bun', 'run', SERVER_SCRIPT];
|
||||
const proc = Bun.spawn(serverCmd, {
|
||||
stdio: ['ignore', 'pipe', 'pipe'],
|
||||
env: { ...process.env, BROWSE_STATE_FILE: config.stateFile },
|
||||
});
|
||||
|
||||
// Don't hold the CLI open
|
||||
proc.unref();
|
||||
|
||||
// Wait for state file to appear
|
||||
const start = Date.now();
|
||||
while (Date.now() - start < MAX_START_WAIT) {
|
||||
const state = readState();
|
||||
if (state && isProcessAlive(state.pid)) {
|
||||
return state;
|
||||
}
|
||||
await Bun.sleep(100);
|
||||
}
|
||||
|
||||
// If we get here, server didn't start in time
|
||||
// Try to read stderr for error message
|
||||
const stderr = proc.stderr;
|
||||
if (stderr) {
|
||||
const reader = stderr.getReader();
|
||||
const { value } = await reader.read();
|
||||
if (value) {
|
||||
const errText = new TextDecoder().decode(value);
|
||||
throw new Error(`Server failed to start:\n${errText}`);
|
||||
}
|
||||
}
|
||||
throw new Error(`Server failed to start within ${MAX_START_WAIT / 1000}s`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Acquire an exclusive lockfile to prevent concurrent ensureServer() races (TOCTOU).
|
||||
* Returns a cleanup function that releases the lock.
|
||||
*/
|
||||
function acquireServerLock(): (() => void) | null {
|
||||
const lockPath = `${config.stateFile}.lock`;
|
||||
try {
|
||||
// O_CREAT | O_EXCL — fails if file already exists (atomic check-and-create)
|
||||
const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
|
||||
fs.writeSync(fd, `${process.pid}\n`);
|
||||
fs.closeSync(fd);
|
||||
return () => { try { fs.unlinkSync(lockPath); } catch {} };
|
||||
} catch {
|
||||
// Lock already held — check if the holder is still alive
|
||||
try {
|
||||
const holderPid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
|
||||
if (holderPid && isProcessAlive(holderPid)) {
|
||||
return null; // Another live process holds the lock
|
||||
}
|
||||
// Stale lock — remove and retry
|
||||
fs.unlinkSync(lockPath);
|
||||
return acquireServerLock();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function ensureServer(): Promise<ServerState> {
|
||||
const state = readState();
|
||||
|
||||
if (state && isProcessAlive(state.pid)) {
|
||||
// Check for binary version mismatch (auto-restart on update)
|
||||
const currentVersion = readVersionHash();
|
||||
if (currentVersion && state.binaryVersion && currentVersion !== state.binaryVersion) {
|
||||
console.error('[browse] Binary updated, restarting server...');
|
||||
await killServer(state.pid);
|
||||
return startServer();
|
||||
}
|
||||
|
||||
// Server appears alive — do a health check
|
||||
try {
|
||||
const resp = await fetch(`http://127.0.0.1:${state.port}/health`, {
|
||||
signal: AbortSignal.timeout(2000),
|
||||
});
|
||||
if (resp.ok) {
|
||||
const health = await resp.json() as any;
|
||||
if (health.status === 'healthy') {
|
||||
return state;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Health check failed — server is dead or unhealthy
|
||||
}
|
||||
}
|
||||
|
||||
// Acquire lock to prevent concurrent restart races (TOCTOU)
|
||||
const releaseLock = acquireServerLock();
|
||||
if (!releaseLock) {
|
||||
// Another process is starting the server — wait for it
|
||||
console.error('[browse] Another instance is starting the server, waiting...');
|
||||
const start = Date.now();
|
||||
while (Date.now() - start < MAX_START_WAIT) {
|
||||
const freshState = readState();
|
||||
if (freshState && isProcessAlive(freshState.pid)) return freshState;
|
||||
await Bun.sleep(200);
|
||||
}
|
||||
throw new Error('Timed out waiting for another instance to start the server');
|
||||
}
|
||||
|
||||
try {
|
||||
// Re-read state under lock in case another process just started the server
|
||||
const freshState = readState();
|
||||
if (freshState && isProcessAlive(freshState.pid)) {
|
||||
return freshState;
|
||||
}
|
||||
|
||||
// Kill the old server to avoid orphaned chromium processes
|
||||
if (state && state.pid) {
|
||||
await killServer(state.pid);
|
||||
}
|
||||
console.error('[browse] Starting server...');
|
||||
return await startServer();
|
||||
} finally {
|
||||
releaseLock();
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Command Dispatch ──────────────────────────────────────────
|
||||
async function sendCommand(state: ServerState, command: string, args: string[], retries = 0): Promise<void> {
|
||||
const body = JSON.stringify({ command, args });
|
||||
|
||||
try {
|
||||
const resp = await fetch(`http://127.0.0.1:${state.port}/command`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${state.token}`,
|
||||
},
|
||||
body,
|
||||
signal: AbortSignal.timeout(30000),
|
||||
});
|
||||
|
||||
if (resp.status === 401) {
|
||||
// Token mismatch — server may have restarted
|
||||
console.error('[browse] Auth failed — server may have restarted. Retrying...');
|
||||
const newState = readState();
|
||||
if (newState && newState.token !== state.token) {
|
||||
return sendCommand(newState, command, args);
|
||||
}
|
||||
throw new Error('Authentication failed');
|
||||
}
|
||||
|
||||
const text = await resp.text();
|
||||
|
||||
if (resp.ok) {
|
||||
process.stdout.write(text);
|
||||
if (!text.endsWith('\n')) process.stdout.write('\n');
|
||||
} else {
|
||||
// Try to parse as JSON error
|
||||
try {
|
||||
const err = JSON.parse(text);
|
||||
console.error(err.error || text);
|
||||
if (err.hint) console.error(err.hint);
|
||||
} catch {
|
||||
console.error(text);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
} catch (err: any) {
|
||||
if (err.name === 'AbortError') {
|
||||
console.error('[browse] Command timed out after 30s');
|
||||
process.exit(1);
|
||||
}
|
||||
// Connection error — server may have crashed
|
||||
if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET' || err.message?.includes('fetch failed')) {
|
||||
if (retries >= 1) throw new Error('[browse] Server crashed twice in a row — aborting');
|
||||
console.error('[browse] Server connection lost. Restarting...');
|
||||
// Kill the old server to avoid orphaned chromium processes
|
||||
const oldState = readState();
|
||||
if (oldState && oldState.pid) {
|
||||
await killServer(oldState.pid);
|
||||
}
|
||||
const newState = await startServer();
|
||||
return sendCommand(newState, command, args, retries + 1);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Main ──────────────────────────────────────────────────────
|
||||
async function main() {
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
|
||||
console.log(`gstack browse — Fast headless browser for AI coding agents
|
||||
|
||||
Usage: browse <command> [args...]
|
||||
|
||||
Navigation: goto <url> | back | forward | reload | url
|
||||
Content: text | html [sel] | links | forms | accessibility
|
||||
Interaction: click <sel> | fill <sel> <val> | select <sel> <val>
|
||||
hover <sel> | type <text> | press <key>
|
||||
scroll [sel] | wait <sel|--networkidle|--load> | viewport <WxH>
|
||||
upload <sel> <file1> [file2...]
|
||||
cookie-import <json-file>
|
||||
cookie-import-browser [browser] [--domain <d>]
|
||||
Inspection: js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
|
||||
console [--clear|--errors] | network [--clear] | dialog [--clear]
|
||||
cookies | storage [set <k> <v>] | perf
|
||||
is <prop> <sel> (visible|hidden|enabled|disabled|checked|editable|focused)
|
||||
Visual: screenshot [--viewport] [--clip x,y,w,h] [@ref|sel] [path]
|
||||
pdf [path] | responsive [prefix]
|
||||
Snapshot: snapshot [-i] [-c] [-d N] [-s sel] [-D] [-a] [-o path] [-C]
|
||||
-D/--diff: diff against previous snapshot
|
||||
-a/--annotate: annotated screenshot with ref labels
|
||||
-C/--cursor-interactive: find non-ARIA clickable elements
|
||||
Compare: diff <url1> <url2>
|
||||
Multi-step: chain (reads JSON from stdin)
|
||||
Tabs: tabs | tab <id> | newtab [url] | closetab [id]
|
||||
Server: status | cookie <n>=<v> | header <n>:<v>
|
||||
useragent <str> | stop | restart
|
||||
Dialogs: dialog-accept [text] | dialog-dismiss
|
||||
|
||||
Refs: After 'snapshot', use @e1, @e2... as selectors:
|
||||
click @e3 | fill @e4 "value" | hover @e1
|
||||
@c refs from -C: click @c1`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// One-time cleanup of legacy /tmp state files
|
||||
cleanupLegacyState();
|
||||
|
||||
const command = args[0];
|
||||
const commandArgs = args.slice(1);
|
||||
|
||||
// Special case: chain reads from stdin
|
||||
if (command === 'chain' && commandArgs.length === 0) {
|
||||
const stdin = await Bun.stdin.text();
|
||||
commandArgs.push(stdin.trim());
|
||||
}
|
||||
|
||||
const state = await ensureServer();
|
||||
await sendCommand(state, command, commandArgs);
|
||||
}
|
||||
|
||||
if (import.meta.main) {
|
||||
main().catch((err) => {
|
||||
console.error(`[browse] ${err.message}`);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
/**
|
||||
* Command registry — single source of truth for all browse commands.
|
||||
*
|
||||
* Dependency graph:
|
||||
* commands.ts ──▶ server.ts (runtime dispatch)
|
||||
* ──▶ gen-skill-docs.ts (doc generation)
|
||||
* ──▶ skill-parser.ts (validation)
|
||||
* ──▶ skill-check.ts (health reporting)
|
||||
*
|
||||
* Zero side effects. Safe to import from build scripts and tests.
|
||||
*/
|
||||
|
||||
export const READ_COMMANDS = new Set([
|
||||
'text', 'html', 'links', 'forms', 'accessibility',
|
||||
'js', 'eval', 'css', 'attrs',
|
||||
'console', 'network', 'cookies', 'storage', 'perf',
|
||||
'dialog', 'is',
|
||||
]);
|
||||
|
||||
export const WRITE_COMMANDS = new Set([
|
||||
'goto', 'back', 'forward', 'reload',
|
||||
'click', 'fill', 'select', 'hover', 'type', 'press', 'scroll', 'wait',
|
||||
'viewport', 'cookie', 'cookie-import', 'cookie-import-browser', 'header', 'useragent',
|
||||
'upload', 'dialog-accept', 'dialog-dismiss',
|
||||
]);
|
||||
|
||||
export const META_COMMANDS = new Set([
|
||||
'tabs', 'tab', 'newtab', 'closetab',
|
||||
'status', 'stop', 'restart',
|
||||
'screenshot', 'pdf', 'responsive',
|
||||
'chain', 'diff',
|
||||
'url', 'snapshot',
|
||||
'handoff', 'resume',
|
||||
]);
|
||||
|
||||
export const ALL_COMMANDS = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
|
||||
|
||||
export const COMMAND_DESCRIPTIONS: Record<string, { category: string; description: string; usage?: string }> = {
|
||||
// Navigation
|
||||
'goto': { category: 'Navigation', description: 'Navigate to URL', usage: 'goto <url>' },
|
||||
'back': { category: 'Navigation', description: 'History back' },
|
||||
'forward': { category: 'Navigation', description: 'History forward' },
|
||||
'reload': { category: 'Navigation', description: 'Reload page' },
|
||||
'url': { category: 'Navigation', description: 'Print current URL' },
|
||||
// Reading
|
||||
'text': { category: 'Reading', description: 'Cleaned page text' },
|
||||
'html': { category: 'Reading', description: 'innerHTML of selector (throws if not found), or full page HTML if no selector given', usage: 'html [selector]' },
|
||||
'links': { category: 'Reading', description: 'All links as "text → href"' },
|
||||
'forms': { category: 'Reading', description: 'Form fields as JSON' },
|
||||
'accessibility': { category: 'Reading', description: 'Full ARIA tree' },
|
||||
// Inspection
|
||||
'js': { category: 'Inspection', description: 'Run JavaScript expression and return result as string', usage: 'js <expr>' },
|
||||
'eval': { category: 'Inspection', description: 'Run JavaScript from file and return result as string (path must be under /tmp or cwd)', usage: 'eval <file>' },
|
||||
'css': { category: 'Inspection', description: 'Computed CSS value', usage: 'css <sel> <prop>' },
|
||||
'attrs': { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel|@ref>' },
|
||||
'is': { category: 'Inspection', description: 'State check (visible/hidden/enabled/disabled/checked/editable/focused)', usage: 'is <prop> <sel>' },
|
||||
'console': { category: 'Inspection', description: 'Console messages (--errors filters to error/warning)', usage: 'console [--clear|--errors]' },
|
||||
'network': { category: 'Inspection', description: 'Network requests', usage: 'network [--clear]' },
|
||||
'dialog': { category: 'Inspection', description: 'Dialog messages', usage: 'dialog [--clear]' },
|
||||
'cookies': { category: 'Inspection', description: 'All cookies as JSON' },
|
||||
'storage': { category: 'Inspection', description: 'Read all localStorage + sessionStorage as JSON, or set <key> <value> to write localStorage', usage: 'storage [set k v]' },
|
||||
'perf': { category: 'Inspection', description: 'Page load timings' },
|
||||
// Interaction
|
||||
'click': { category: 'Interaction', description: 'Click element', usage: 'click <sel>' },
|
||||
'fill': { category: 'Interaction', description: 'Fill input', usage: 'fill <sel> <val>' },
|
||||
'select': { category: 'Interaction', description: 'Select dropdown option by value, label, or visible text', usage: 'select <sel> <val>' },
|
||||
'hover': { category: 'Interaction', description: 'Hover element', usage: 'hover <sel>' },
|
||||
'type': { category: 'Interaction', description: 'Type into focused element', usage: 'type <text>' },
|
||||
'press': { category: 'Interaction', description: 'Press key — Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown, or modifiers like Shift+Enter', usage: 'press <key>' },
|
||||
'scroll': { category: 'Interaction', description: 'Scroll element into view, or scroll to page bottom if no selector', usage: 'scroll [sel]' },
|
||||
'wait': { category: 'Interaction', description: 'Wait for element, network idle, or page load (timeout: 15s)', usage: 'wait <sel|--networkidle|--load>' },
|
||||
'upload': { category: 'Interaction', description: 'Upload file(s)', usage: 'upload <sel> <file> [file2...]' },
|
||||
'viewport':{ category: 'Interaction', description: 'Set viewport size', usage: 'viewport <WxH>' },
|
||||
'cookie': { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie <name>=<value>' },
|
||||
'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import <json>' },
|
||||
'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from Comet, Chrome, Arc, Brave, or Edge (opens picker, or use --domain for direct import)', usage: 'cookie-import-browser [browser] [--domain d]' },
|
||||
'header': { category: 'Interaction', description: 'Set custom request header (colon-separated, sensitive values auto-redacted)', usage: 'header <name>:<value>' },
|
||||
'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent <string>' },
|
||||
'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response', usage: 'dialog-accept [text]' },
|
||||
'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' },
|
||||
// Visual
|
||||
'screenshot': { category: 'Visual', description: 'Save screenshot (supports element crop via CSS/@ref, --clip region, --viewport)', usage: 'screenshot [--viewport] [--clip x,y,w,h] [selector|@ref] [path]' },
|
||||
'pdf': { category: 'Visual', description: 'Save as PDF', usage: 'pdf [path]' },
|
||||
'responsive': { category: 'Visual', description: 'Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc.', usage: 'responsive [prefix]' },
|
||||
'diff': { category: 'Visual', description: 'Text diff between pages', usage: 'diff <url1> <url2>' },
|
||||
// Tabs
|
||||
'tabs': { category: 'Tabs', description: 'List open tabs' },
|
||||
'tab': { category: 'Tabs', description: 'Switch to tab', usage: 'tab <id>' },
|
||||
'newtab': { category: 'Tabs', description: 'Open new tab', usage: 'newtab [url]' },
|
||||
'closetab':{ category: 'Tabs', description: 'Close tab', usage: 'closetab [id]' },
|
||||
// Server
|
||||
'status': { category: 'Server', description: 'Health check' },
|
||||
'stop': { category: 'Server', description: 'Shutdown server' },
|
||||
'restart': { category: 'Server', description: 'Restart server' },
|
||||
// Meta
|
||||
'snapshot':{ category: 'Snapshot', description: 'Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs', usage: 'snapshot [flags]' },
|
||||
'chain': { category: 'Meta', description: 'Run commands from JSON stdin. Format: [["cmd","arg1",...],...]' },
|
||||
// Handoff
|
||||
'handoff': { category: 'Server', description: 'Open visible Chrome at current page for user takeover', usage: 'handoff [message]' },
|
||||
'resume': { category: 'Server', description: 'Re-snapshot after user takeover, return control to AI', usage: 'resume' },
|
||||
};
|
||||
|
||||
// Load-time validation: descriptions must cover exactly the command sets
|
||||
const allCmds = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
|
||||
const descKeys = new Set(Object.keys(COMMAND_DESCRIPTIONS));
|
||||
for (const cmd of allCmds) {
|
||||
if (!descKeys.has(cmd)) throw new Error(`COMMAND_DESCRIPTIONS missing entry for: ${cmd}`);
|
||||
}
|
||||
for (const key of descKeys) {
|
||||
if (!allCmds.has(key)) throw new Error(`COMMAND_DESCRIPTIONS has unknown command: ${key}`);
|
||||
}
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
/**
|
||||
* Shared config for browse CLI + server.
|
||||
*
|
||||
* Resolution:
|
||||
* 1. BROWSE_STATE_FILE env → derive stateDir from parent
|
||||
* 2. git rev-parse --show-toplevel → projectDir/.gstack/
|
||||
* 3. process.cwd() fallback (non-git environments)
|
||||
*
|
||||
* The CLI computes the config and passes BROWSE_STATE_FILE to the
|
||||
* spawned server. The server derives all paths from that env var.
|
||||
*/
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
|
||||
export interface BrowseConfig {
|
||||
projectDir: string;
|
||||
stateDir: string;
|
||||
stateFile: string;
|
||||
consoleLog: string;
|
||||
networkLog: string;
|
||||
dialogLog: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Detect the git repository root, or null if not in a repo / git unavailable.
|
||||
*/
|
||||
export function getGitRoot(): string | null {
|
||||
try {
|
||||
const proc = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], {
|
||||
stdout: 'pipe',
|
||||
stderr: 'pipe',
|
||||
timeout: 2_000, // Don't hang if .git is broken
|
||||
});
|
||||
if (proc.exitCode !== 0) return null;
|
||||
return proc.stdout.toString().trim() || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve all browse config paths.
|
||||
*
|
||||
* If BROWSE_STATE_FILE is set (e.g. by CLI when spawning server, or by
|
||||
* tests for isolation), all paths are derived from it. Otherwise, the
|
||||
* project root is detected via git or cwd.
|
||||
*/
|
||||
export function resolveConfig(
|
||||
env: Record<string, string | undefined> = process.env,
|
||||
): BrowseConfig {
|
||||
let stateFile: string;
|
||||
let stateDir: string;
|
||||
let projectDir: string;
|
||||
|
||||
if (env.BROWSE_STATE_FILE) {
|
||||
stateFile = env.BROWSE_STATE_FILE;
|
||||
stateDir = path.dirname(stateFile);
|
||||
projectDir = path.dirname(stateDir); // parent of .gstack/
|
||||
} else {
|
||||
projectDir = getGitRoot() || process.cwd();
|
||||
stateDir = path.join(projectDir, '.gstack');
|
||||
stateFile = path.join(stateDir, 'browse.json');
|
||||
}
|
||||
|
||||
return {
|
||||
projectDir,
|
||||
stateDir,
|
||||
stateFile,
|
||||
consoleLog: path.join(stateDir, 'browse-console.log'),
|
||||
networkLog: path.join(stateDir, 'browse-network.log'),
|
||||
dialogLog: path.join(stateDir, 'browse-dialog.log'),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Create the .gstack/ state directory if it doesn't exist.
|
||||
* Throws with a clear message on permission errors.
|
||||
*/
|
||||
export function ensureStateDir(config: BrowseConfig): void {
|
||||
try {
|
||||
fs.mkdirSync(config.stateDir, { recursive: true });
|
||||
} catch (err: any) {
|
||||
if (err.code === 'EACCES') {
|
||||
throw new Error(`Cannot create state directory ${config.stateDir}: permission denied`);
|
||||
}
|
||||
if (err.code === 'ENOTDIR') {
|
||||
throw new Error(`Cannot create state directory ${config.stateDir}: a file exists at that path`);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
// Ensure .gstack/ is in the project's .gitignore
|
||||
const gitignorePath = path.join(config.projectDir, '.gitignore');
|
||||
try {
|
||||
const content = fs.readFileSync(gitignorePath, 'utf-8');
|
||||
if (!content.match(/^\.gstack\/?$/m)) {
|
||||
const separator = content.endsWith('\n') ? '' : '\n';
|
||||
fs.appendFileSync(gitignorePath, `${separator}.gstack/\n`);
|
||||
}
|
||||
} catch (err: any) {
|
||||
if (err.code !== 'ENOENT') {
|
||||
// Write warning to server log (visible even in daemon mode)
|
||||
const logPath = path.join(config.stateDir, 'browse-server.log');
|
||||
try {
|
||||
fs.appendFileSync(logPath, `[${new Date().toISOString()}] Warning: could not update .gitignore at ${gitignorePath}: ${err.message}\n`);
|
||||
} catch {
|
||||
// stateDir write failed too — nothing more we can do
|
||||
}
|
||||
}
|
||||
// ENOENT (no .gitignore) — skip silently
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Derive a slug from the git remote origin URL (owner-repo format).
|
||||
* Falls back to the directory basename if no remote is configured.
|
||||
*/
|
||||
export function getRemoteSlug(): string {
|
||||
try {
|
||||
const proc = Bun.spawnSync(['git', 'remote', 'get-url', 'origin'], {
|
||||
stdout: 'pipe',
|
||||
stderr: 'pipe',
|
||||
timeout: 2_000,
|
||||
});
|
||||
if (proc.exitCode !== 0) throw new Error('no remote');
|
||||
const url = proc.stdout.toString().trim();
|
||||
// SSH: git@github.com:owner/repo.git → owner-repo
|
||||
// HTTPS: https://github.com/owner/repo.git → owner-repo
|
||||
const match = url.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
|
||||
if (match) return `${match[1]}-${match[2]}`;
|
||||
throw new Error('unparseable');
|
||||
} catch {
|
||||
const root = getGitRoot();
|
||||
return path.basename(root || process.cwd());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the binary version (git SHA) from browse/dist/.version.
|
||||
* Returns null if the file doesn't exist or can't be read.
|
||||
*/
|
||||
export function readVersionHash(execPath: string = process.execPath): string | null {
|
||||
try {
|
||||
const versionFile = path.resolve(path.dirname(execPath), '.version');
|
||||
return fs.readFileSync(versionFile, 'utf-8').trim() || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,417 @@
|
|||
/**
|
||||
* Chromium browser cookie import — read and decrypt cookies from real browsers
|
||||
*
|
||||
* Supports macOS Chromium-based browsers: Comet, Chrome, Arc, Brave, Edge.
|
||||
* Pure logic module — no Playwright dependency, no HTTP concerns.
|
||||
*
|
||||
* Decryption pipeline (Chromium macOS "v10" format):
|
||||
*
|
||||
* ┌──────────────────────────────────────────────────────────────────┐
|
||||
* │ 1. Keychain: `security find-generic-password -s "<svc>" -w` │
|
||||
* │ → base64 password string │
|
||||
* │ │
|
||||
* │ 2. Key derivation: │
|
||||
* │ PBKDF2(password, salt="saltysalt", iter=1003, len=16, sha1) │
|
||||
* │ → 16-byte AES key │
|
||||
* │ │
|
||||
* │ 3. For each cookie with encrypted_value starting with "v10": │
|
||||
* │ - Ciphertext = encrypted_value[3:] │
|
||||
* │ - IV = 16 bytes of 0x20 (space character) │
|
||||
* │ - Plaintext = AES-128-CBC-decrypt(key, iv, ciphertext) │
|
||||
* │ - Remove PKCS7 padding │
|
||||
* │ - Skip first 32 bytes (HMAC-SHA256 authentication tag) │
|
||||
* │ - Remaining bytes = cookie value (UTF-8) │
|
||||
* │ │
|
||||
* │ 4. If encrypted_value is empty but `value` field is set, │
|
||||
* │ use value directly (unencrypted cookie) │
|
||||
* │ │
|
||||
* │ 5. Chromium epoch: microseconds since 1601-01-01 │
|
||||
* │ Unix seconds = (epoch - 11644473600000000) / 1000000 │
|
||||
* │ │
|
||||
* │ 6. sameSite: 0→"None", 1→"Lax", 2→"Strict", else→"Lax" │
|
||||
* └──────────────────────────────────────────────────────────────────┘
|
||||
*/
|
||||
|
||||
import { Database } from 'bun:sqlite';
|
||||
import * as crypto from 'crypto';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import * as os from 'os';
|
||||
|
||||
// ─── Types ──────────────────────────────────────────────────────
|
||||
|
||||
export interface BrowserInfo {
|
||||
name: string;
|
||||
dataDir: string; // relative to ~/Library/Application Support/
|
||||
keychainService: string;
|
||||
aliases: string[];
|
||||
}
|
||||
|
||||
export interface DomainEntry {
|
||||
domain: string;
|
||||
count: number;
|
||||
}
|
||||
|
||||
export interface ImportResult {
|
||||
cookies: PlaywrightCookie[];
|
||||
count: number;
|
||||
failed: number;
|
||||
domainCounts: Record<string, number>;
|
||||
}
|
||||
|
||||
export interface PlaywrightCookie {
|
||||
name: string;
|
||||
value: string;
|
||||
domain: string;
|
||||
path: string;
|
||||
expires: number;
|
||||
secure: boolean;
|
||||
httpOnly: boolean;
|
||||
sameSite: 'Strict' | 'Lax' | 'None';
|
||||
}
|
||||
|
||||
export class CookieImportError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public code: string,
|
||||
public action?: 'retry',
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'CookieImportError';
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Browser Registry ───────────────────────────────────────────
|
||||
// Hardcoded — NEVER interpolate user input into shell commands.
|
||||
|
||||
const BROWSER_REGISTRY: BrowserInfo[] = [
|
||||
{ name: 'Comet', dataDir: 'Comet/', keychainService: 'Comet Safe Storage', aliases: ['comet', 'perplexity'] },
|
||||
{ name: 'Chrome', dataDir: 'Google/Chrome/', keychainService: 'Chrome Safe Storage', aliases: ['chrome', 'google-chrome'] },
|
||||
{ name: 'Arc', dataDir: 'Arc/User Data/', keychainService: 'Arc Safe Storage', aliases: ['arc'] },
|
||||
{ name: 'Brave', dataDir: 'BraveSoftware/Brave-Browser/', keychainService: 'Brave Safe Storage', aliases: ['brave'] },
|
||||
{ name: 'Edge', dataDir: 'Microsoft Edge/', keychainService: 'Microsoft Edge Safe Storage', aliases: ['edge'] },
|
||||
];
|
||||
|
||||
// ─── Key Cache ──────────────────────────────────────────────────
|
||||
// Cache derived AES keys per browser. First import per browser does
|
||||
// Keychain + PBKDF2. Subsequent imports reuse the cached key.
|
||||
|
||||
const keyCache = new Map<string, Buffer>();
|
||||
|
||||
// ─── Public API ─────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Find which browsers are installed (have a cookie DB on disk).
|
||||
*/
|
||||
export function findInstalledBrowsers(): BrowserInfo[] {
|
||||
const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
|
||||
return BROWSER_REGISTRY.filter(b => {
|
||||
const dbPath = path.join(appSupport, b.dataDir, 'Default', 'Cookies');
|
||||
try { return fs.existsSync(dbPath); } catch { return false; }
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* List unique cookie domains + counts from a browser's DB. No decryption.
|
||||
*/
|
||||
export function listDomains(browserName: string, profile = 'Default'): { domains: DomainEntry[]; browser: string } {
|
||||
const browser = resolveBrowser(browserName);
|
||||
const dbPath = getCookieDbPath(browser, profile);
|
||||
const db = openDb(dbPath, browser.name);
|
||||
try {
|
||||
const now = chromiumNow();
|
||||
const rows = db.query(
|
||||
`SELECT host_key AS domain, COUNT(*) AS count
|
||||
FROM cookies
|
||||
WHERE has_expires = 0 OR expires_utc > ?
|
||||
GROUP BY host_key
|
||||
ORDER BY count DESC`
|
||||
).all(now) as DomainEntry[];
|
||||
return { domains: rows, browser: browser.name };
|
||||
} finally {
|
||||
db.close();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Decrypt and return Playwright-compatible cookies for specific domains.
|
||||
*/
|
||||
export async function importCookies(
|
||||
browserName: string,
|
||||
domains: string[],
|
||||
profile = 'Default',
|
||||
): Promise<ImportResult> {
|
||||
if (domains.length === 0) return { cookies: [], count: 0, failed: 0, domainCounts: {} };
|
||||
|
||||
const browser = resolveBrowser(browserName);
|
||||
const derivedKey = await getDerivedKey(browser);
|
||||
const dbPath = getCookieDbPath(browser, profile);
|
||||
const db = openDb(dbPath, browser.name);
|
||||
|
||||
try {
|
||||
const now = chromiumNow();
|
||||
// Parameterized query — no SQL injection
|
||||
const placeholders = domains.map(() => '?').join(',');
|
||||
const rows = db.query(
|
||||
`SELECT host_key, name, value, encrypted_value, path, expires_utc,
|
||||
is_secure, is_httponly, has_expires, samesite
|
||||
FROM cookies
|
||||
WHERE host_key IN (${placeholders})
|
||||
AND (has_expires = 0 OR expires_utc > ?)
|
||||
ORDER BY host_key, name`
|
||||
).all(...domains, now) as RawCookie[];
|
||||
|
||||
const cookies: PlaywrightCookie[] = [];
|
||||
let failed = 0;
|
||||
const domainCounts: Record<string, number> = {};
|
||||
|
||||
for (const row of rows) {
|
||||
try {
|
||||
const value = decryptCookieValue(row, derivedKey);
|
||||
const cookie = toPlaywrightCookie(row, value);
|
||||
cookies.push(cookie);
|
||||
domainCounts[row.host_key] = (domainCounts[row.host_key] || 0) + 1;
|
||||
} catch {
|
||||
failed++;
|
||||
}
|
||||
}
|
||||
|
||||
return { cookies, count: cookies.length, failed, domainCounts };
|
||||
} finally {
|
||||
db.close();
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Internal: Browser Resolution ───────────────────────────────
|
||||
|
||||
function resolveBrowser(nameOrAlias: string): BrowserInfo {
|
||||
const needle = nameOrAlias.toLowerCase().trim();
|
||||
const found = BROWSER_REGISTRY.find(b =>
|
||||
b.aliases.includes(needle) || b.name.toLowerCase() === needle
|
||||
);
|
||||
if (!found) {
|
||||
const supported = BROWSER_REGISTRY.flatMap(b => b.aliases).join(', ');
|
||||
throw new CookieImportError(
|
||||
`Unknown browser '${nameOrAlias}'. Supported: ${supported}`,
|
||||
'unknown_browser',
|
||||
);
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
function validateProfile(profile: string): void {
|
||||
if (/[/\\]|\.\./.test(profile) || /[\x00-\x1f]/.test(profile)) {
|
||||
throw new CookieImportError(
|
||||
`Invalid profile name: '${profile}'`,
|
||||
'bad_request',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function getCookieDbPath(browser: BrowserInfo, profile: string): string {
|
||||
validateProfile(profile);
|
||||
const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
|
||||
const dbPath = path.join(appSupport, browser.dataDir, profile, 'Cookies');
|
||||
if (!fs.existsSync(dbPath)) {
|
||||
throw new CookieImportError(
|
||||
`${browser.name} is not installed (no cookie database at ${dbPath})`,
|
||||
'not_installed',
|
||||
);
|
||||
}
|
||||
return dbPath;
|
||||
}
|
||||
|
||||
// ─── Internal: SQLite Access ────────────────────────────────────
|
||||
|
||||
function openDb(dbPath: string, browserName: string): Database {
|
||||
try {
|
||||
return new Database(dbPath, { readonly: true });
|
||||
} catch (err: any) {
|
||||
if (err.message?.includes('SQLITE_BUSY') || err.message?.includes('database is locked')) {
|
||||
return openDbFromCopy(dbPath, browserName);
|
||||
}
|
||||
if (err.message?.includes('SQLITE_CORRUPT') || err.message?.includes('malformed')) {
|
||||
throw new CookieImportError(
|
||||
`Cookie database for ${browserName} is corrupt`,
|
||||
'db_corrupt',
|
||||
);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
function openDbFromCopy(dbPath: string, browserName: string): Database {
|
||||
const tmpPath = `/tmp/browse-cookies-${browserName.toLowerCase()}-${crypto.randomUUID()}.db`;
|
||||
try {
|
||||
fs.copyFileSync(dbPath, tmpPath);
|
||||
// Also copy WAL and SHM if they exist (for consistent reads)
|
||||
const walPath = dbPath + '-wal';
|
||||
const shmPath = dbPath + '-shm';
|
||||
if (fs.existsSync(walPath)) fs.copyFileSync(walPath, tmpPath + '-wal');
|
||||
if (fs.existsSync(shmPath)) fs.copyFileSync(shmPath, tmpPath + '-shm');
|
||||
|
||||
const db = new Database(tmpPath, { readonly: true });
|
||||
// Schedule cleanup after the DB is closed
|
||||
const origClose = db.close.bind(db);
|
||||
db.close = () => {
|
||||
origClose();
|
||||
try { fs.unlinkSync(tmpPath); } catch {}
|
||||
try { fs.unlinkSync(tmpPath + '-wal'); } catch {}
|
||||
try { fs.unlinkSync(tmpPath + '-shm'); } catch {}
|
||||
};
|
||||
return db;
|
||||
} catch {
|
||||
// Clean up on failure
|
||||
try { fs.unlinkSync(tmpPath); } catch {}
|
||||
throw new CookieImportError(
|
||||
`Cookie database is locked (${browserName} may be running). Try closing ${browserName} first.`,
|
||||
'db_locked',
|
||||
'retry',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Internal: Keychain Access (async, 10s timeout) ─────────────
|
||||
|
||||
async function getDerivedKey(browser: BrowserInfo): Promise<Buffer> {
|
||||
const cached = keyCache.get(browser.keychainService);
|
||||
if (cached) return cached;
|
||||
|
||||
const password = await getKeychainPassword(browser.keychainService);
|
||||
const derived = crypto.pbkdf2Sync(password, 'saltysalt', 1003, 16, 'sha1');
|
||||
keyCache.set(browser.keychainService, derived);
|
||||
return derived;
|
||||
}
|
||||
|
||||
async function getKeychainPassword(service: string): Promise<string> {
|
||||
// Use async Bun.spawn with timeout to avoid blocking the event loop.
|
||||
// macOS may show an Allow/Deny dialog that blocks until the user responds.
|
||||
const proc = Bun.spawn(
|
||||
['security', 'find-generic-password', '-s', service, '-w'],
|
||||
{ stdout: 'pipe', stderr: 'pipe' },
|
||||
);
|
||||
|
||||
const timeout = new Promise<never>((_, reject) =>
|
||||
setTimeout(() => {
|
||||
proc.kill();
|
||||
reject(new CookieImportError(
|
||||
`macOS is waiting for Keychain permission. Look for a dialog asking to allow access to "${service}".`,
|
||||
'keychain_timeout',
|
||||
'retry',
|
||||
));
|
||||
}, 10_000),
|
||||
);
|
||||
|
||||
try {
|
||||
const exitCode = await Promise.race([proc.exited, timeout]);
|
||||
const stdout = await new Response(proc.stdout).text();
|
||||
const stderr = await new Response(proc.stderr).text();
|
||||
|
||||
if (exitCode !== 0) {
|
||||
// Distinguish denied vs not found vs other
|
||||
const errText = stderr.trim().toLowerCase();
|
||||
if (errText.includes('user canceled') || errText.includes('denied') || errText.includes('interaction not allowed')) {
|
||||
throw new CookieImportError(
|
||||
`Keychain access denied. Click "Allow" in the macOS dialog for "${service}".`,
|
||||
'keychain_denied',
|
||||
'retry',
|
||||
);
|
||||
}
|
||||
if (errText.includes('could not be found') || errText.includes('not found')) {
|
||||
throw new CookieImportError(
|
||||
`No Keychain entry for "${service}". Is this a Chromium-based browser?`,
|
||||
'keychain_not_found',
|
||||
);
|
||||
}
|
||||
throw new CookieImportError(
|
||||
`Could not read Keychain: ${stderr.trim()}`,
|
||||
'keychain_error',
|
||||
'retry',
|
||||
);
|
||||
}
|
||||
|
||||
return stdout.trim();
|
||||
} catch (err) {
|
||||
if (err instanceof CookieImportError) throw err;
|
||||
throw new CookieImportError(
|
||||
`Could not read Keychain: ${(err as Error).message}`,
|
||||
'keychain_error',
|
||||
'retry',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Internal: Cookie Decryption ────────────────────────────────
|
||||
|
||||
interface RawCookie {
|
||||
host_key: string;
|
||||
name: string;
|
||||
value: string;
|
||||
encrypted_value: Buffer | Uint8Array;
|
||||
path: string;
|
||||
expires_utc: number | bigint;
|
||||
is_secure: number;
|
||||
is_httponly: number;
|
||||
has_expires: number;
|
||||
samesite: number;
|
||||
}
|
||||
|
||||
function decryptCookieValue(row: RawCookie, key: Buffer): string {
|
||||
// Prefer unencrypted value if present
|
||||
if (row.value && row.value.length > 0) return row.value;
|
||||
|
||||
const ev = Buffer.from(row.encrypted_value);
|
||||
if (ev.length === 0) return '';
|
||||
|
||||
const prefix = ev.slice(0, 3).toString('utf-8');
|
||||
if (prefix !== 'v10') {
|
||||
throw new Error(`Unknown encryption prefix: ${prefix}`);
|
||||
}
|
||||
|
||||
const ciphertext = ev.slice(3);
|
||||
const iv = Buffer.alloc(16, 0x20); // 16 space characters
|
||||
const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
|
||||
const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
|
||||
|
||||
// First 32 bytes are HMAC-SHA256 authentication tag; actual value follows
|
||||
if (plaintext.length <= 32) return '';
|
||||
return plaintext.slice(32).toString('utf-8');
|
||||
}
|
||||
|
||||
function toPlaywrightCookie(row: RawCookie, value: string): PlaywrightCookie {
|
||||
return {
|
||||
name: row.name,
|
||||
value,
|
||||
domain: row.host_key,
|
||||
path: row.path || '/',
|
||||
expires: chromiumEpochToUnix(row.expires_utc, row.has_expires),
|
||||
secure: row.is_secure === 1,
|
||||
httpOnly: row.is_httponly === 1,
|
||||
sameSite: mapSameSite(row.samesite),
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Internal: Chromium Epoch Conversion ────────────────────────
|
||||
|
||||
const CHROMIUM_EPOCH_OFFSET = 11644473600000000n;
|
||||
|
||||
function chromiumNow(): bigint {
|
||||
// Current time in Chromium epoch (microseconds since 1601-01-01)
|
||||
return BigInt(Date.now()) * 1000n + CHROMIUM_EPOCH_OFFSET;
|
||||
}
|
||||
|
||||
function chromiumEpochToUnix(epoch: number | bigint, hasExpires: number): number {
|
||||
if (hasExpires === 0 || epoch === 0 || epoch === 0n) return -1; // session cookie
|
||||
const epochBig = BigInt(epoch);
|
||||
const unixMicro = epochBig - CHROMIUM_EPOCH_OFFSET;
|
||||
return Number(unixMicro / 1000000n);
|
||||
}
|
||||
|
||||
function mapSameSite(value: number): 'Strict' | 'Lax' | 'None' {
|
||||
switch (value) {
|
||||
case 0: return 'None';
|
||||
case 1: return 'Lax';
|
||||
case 2: return 'Strict';
|
||||
default: return 'Lax';
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
/**
|
||||
* Cookie picker route handler — HTTP + Playwright glue
|
||||
*
|
||||
* Handles all /cookie-picker/* routes. Imports from cookie-import-browser.ts
|
||||
* (decryption) and cookie-picker-ui.ts (HTML generation).
|
||||
*
|
||||
* Routes (no auth — localhost-only, accepted risk):
|
||||
* GET /cookie-picker → serves the picker HTML page
|
||||
* GET /cookie-picker/browsers → list installed browsers
|
||||
* GET /cookie-picker/domains → list domains + counts for a browser
|
||||
* POST /cookie-picker/import → decrypt + import cookies to Playwright
|
||||
* POST /cookie-picker/remove → clear cookies for domains
|
||||
* GET /cookie-picker/imported → currently imported domains + counts
|
||||
*/
|
||||
|
||||
import type { BrowserManager } from './browser-manager';
|
||||
import { findInstalledBrowsers, listDomains, importCookies, CookieImportError, type PlaywrightCookie } from './cookie-import-browser';
|
||||
import { getCookiePickerHTML } from './cookie-picker-ui';
|
||||
|
||||
// ─── State ──────────────────────────────────────────────────────
|
||||
// Tracks which domains were imported via the picker.
|
||||
// /imported only returns cookies for domains in this Set.
|
||||
// /remove clears from this Set.
|
||||
const importedDomains = new Set<string>();
|
||||
const importedCounts = new Map<string, number>();
|
||||
|
||||
// ─── JSON Helpers ───────────────────────────────────────────────
|
||||
|
||||
function corsOrigin(port: number): string {
|
||||
return `http://127.0.0.1:${port}`;
|
||||
}
|
||||
|
||||
function jsonResponse(data: any, opts: { port: number; status?: number }): Response {
|
||||
return new Response(JSON.stringify(data), {
|
||||
status: opts.status ?? 200,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Access-Control-Allow-Origin': corsOrigin(opts.port),
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function errorResponse(message: string, code: string, opts: { port: number; status?: number; action?: string }): Response {
|
||||
return jsonResponse(
|
||||
{ error: message, code, ...(opts.action ? { action: opts.action } : {}) },
|
||||
{ port: opts.port, status: opts.status ?? 400 },
|
||||
);
|
||||
}
|
||||
|
||||
// ─── Route Handler ──────────────────────────────────────────────
|
||||
|
||||
export async function handleCookiePickerRoute(
|
||||
url: URL,
|
||||
req: Request,
|
||||
bm: BrowserManager,
|
||||
): Promise<Response> {
|
||||
const pathname = url.pathname;
|
||||
const port = parseInt(url.port, 10) || 9400;
|
||||
|
||||
// CORS preflight
|
||||
if (req.method === 'OPTIONS') {
|
||||
return new Response(null, {
|
||||
status: 204,
|
||||
headers: {
|
||||
'Access-Control-Allow-Origin': corsOrigin(port),
|
||||
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
|
||||
'Access-Control-Allow-Headers': 'Content-Type',
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
try {
|
||||
// GET /cookie-picker — serve the picker UI
|
||||
if (pathname === '/cookie-picker' && req.method === 'GET') {
|
||||
const html = getCookiePickerHTML(port);
|
||||
return new Response(html, {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'text/html; charset=utf-8' },
|
||||
});
|
||||
}
|
||||
|
||||
// GET /cookie-picker/browsers — list installed browsers
|
||||
if (pathname === '/cookie-picker/browsers' && req.method === 'GET') {
|
||||
const browsers = findInstalledBrowsers();
|
||||
return jsonResponse({
|
||||
browsers: browsers.map(b => ({
|
||||
name: b.name,
|
||||
aliases: b.aliases,
|
||||
})),
|
||||
}, { port });
|
||||
}
|
||||
|
||||
// GET /cookie-picker/domains?browser=<name> — list domains + counts
|
||||
if (pathname === '/cookie-picker/domains' && req.method === 'GET') {
|
||||
const browserName = url.searchParams.get('browser');
|
||||
if (!browserName) {
|
||||
return errorResponse("Missing 'browser' parameter", 'missing_param', { port });
|
||||
}
|
||||
const result = listDomains(browserName);
|
||||
return jsonResponse({
|
||||
browser: result.browser,
|
||||
domains: result.domains,
|
||||
}, { port });
|
||||
}
|
||||
|
||||
// POST /cookie-picker/import — decrypt + import to Playwright session
|
||||
if (pathname === '/cookie-picker/import' && req.method === 'POST') {
|
||||
let body: any;
|
||||
try {
|
||||
body = await req.json();
|
||||
} catch {
|
||||
return errorResponse('Invalid JSON body', 'bad_request', { port });
|
||||
}
|
||||
|
||||
const { browser, domains } = body;
|
||||
if (!browser) return errorResponse("Missing 'browser' field", 'missing_param', { port });
|
||||
if (!domains || !Array.isArray(domains) || domains.length === 0) {
|
||||
return errorResponse("Missing or empty 'domains' array", 'missing_param', { port });
|
||||
}
|
||||
|
||||
// Decrypt cookies from the browser DB
|
||||
const result = await importCookies(browser, domains);
|
||||
|
||||
if (result.cookies.length === 0) {
|
||||
return jsonResponse({
|
||||
imported: 0,
|
||||
failed: result.failed,
|
||||
domainCounts: {},
|
||||
message: result.failed > 0
|
||||
? `All ${result.failed} cookies failed to decrypt`
|
||||
: 'No cookies found for the specified domains',
|
||||
}, { port });
|
||||
}
|
||||
|
||||
// Add to Playwright context
|
||||
const page = bm.getPage();
|
||||
await page.context().addCookies(result.cookies);
|
||||
|
||||
// Track what was imported
|
||||
for (const domain of Object.keys(result.domainCounts)) {
|
||||
importedDomains.add(domain);
|
||||
importedCounts.set(domain, (importedCounts.get(domain) || 0) + result.domainCounts[domain]);
|
||||
}
|
||||
|
||||
console.log(`[cookie-picker] Imported ${result.count} cookies for ${Object.keys(result.domainCounts).length} domains`);
|
||||
|
||||
return jsonResponse({
|
||||
imported: result.count,
|
||||
failed: result.failed,
|
||||
domainCounts: result.domainCounts,
|
||||
}, { port });
|
||||
}
|
||||
|
||||
// POST /cookie-picker/remove — clear cookies for domains
|
||||
if (pathname === '/cookie-picker/remove' && req.method === 'POST') {
|
||||
let body: any;
|
||||
try {
|
||||
body = await req.json();
|
||||
} catch {
|
||||
return errorResponse('Invalid JSON body', 'bad_request', { port });
|
||||
}
|
||||
|
||||
const { domains } = body;
|
||||
if (!domains || !Array.isArray(domains) || domains.length === 0) {
|
||||
return errorResponse("Missing or empty 'domains' array", 'missing_param', { port });
|
||||
}
|
||||
|
||||
const page = bm.getPage();
|
||||
const context = page.context();
|
||||
for (const domain of domains) {
|
||||
await context.clearCookies({ domain });
|
||||
importedDomains.delete(domain);
|
||||
importedCounts.delete(domain);
|
||||
}
|
||||
|
||||
console.log(`[cookie-picker] Removed cookies for ${domains.length} domains`);
|
||||
|
||||
return jsonResponse({
|
||||
removed: domains.length,
|
||||
domains,
|
||||
}, { port });
|
||||
}
|
||||
|
||||
// GET /cookie-picker/imported — currently imported domains + counts
|
||||
if (pathname === '/cookie-picker/imported' && req.method === 'GET') {
|
||||
const entries: Array<{ domain: string; count: number }> = [];
|
||||
for (const domain of importedDomains) {
|
||||
entries.push({ domain, count: importedCounts.get(domain) || 0 });
|
||||
}
|
||||
entries.sort((a, b) => b.count - a.count);
|
||||
|
||||
return jsonResponse({
|
||||
domains: entries,
|
||||
totalDomains: entries.length,
|
||||
totalCookies: entries.reduce((sum, e) => sum + e.count, 0),
|
||||
}, { port });
|
||||
}
|
||||
|
||||
return new Response('Not found', { status: 404 });
|
||||
} catch (err: any) {
|
||||
if (err instanceof CookieImportError) {
|
||||
return errorResponse(err.message, err.code, { port, status: 400, action: err.action });
|
||||
}
|
||||
console.error(`[cookie-picker] Error: ${err.message}`);
|
||||
return errorResponse(err.message || 'Internal error', 'internal_error', { port, status: 500 });
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,541 @@
|
|||
/**
|
||||
* Cookie picker UI — self-contained HTML page
|
||||
*
|
||||
* Dark theme, two-panel layout, vanilla HTML/CSS/JS.
|
||||
* Left: source browser domains with search + import buttons.
|
||||
* Right: imported domains with trash buttons.
|
||||
* No cookie values exposed anywhere.
|
||||
*/
|
||||
|
||||
export function getCookiePickerHTML(serverPort: number): string {
|
||||
const baseUrl = `http://127.0.0.1:${serverPort}`;
|
||||
|
||||
return `<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Cookie Import — gstack browse</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
|
||||
background: #0a0a0a;
|
||||
color: #e0e0e0;
|
||||
height: 100vh;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* ─── Header ──────────────────────────── */
|
||||
.header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 16px 24px;
|
||||
border-bottom: 1px solid #222;
|
||||
background: #0f0f0f;
|
||||
}
|
||||
.header h1 {
|
||||
font-size: 16px;
|
||||
font-weight: 600;
|
||||
color: #fff;
|
||||
}
|
||||
.header .port {
|
||||
font-size: 12px;
|
||||
color: #666;
|
||||
font-family: 'SF Mono', 'Fira Code', monospace;
|
||||
}
|
||||
|
||||
/* ─── Layout ──────────────────────────── */
|
||||
.container {
|
||||
display: flex;
|
||||
height: calc(100vh - 53px);
|
||||
}
|
||||
.panel {
|
||||
flex: 1;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
overflow: hidden;
|
||||
}
|
||||
.panel-left {
|
||||
border-right: 1px solid #222;
|
||||
}
|
||||
.panel-header {
|
||||
padding: 16px 20px 12px;
|
||||
font-size: 11px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
color: #888;
|
||||
}
|
||||
|
||||
/* ─── Browser Pills ───────────────────── */
|
||||
.browser-pills {
|
||||
display: flex;
|
||||
gap: 8px;
|
||||
padding: 0 20px 12px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
.pill {
|
||||
padding: 6px 14px;
|
||||
border-radius: 20px;
|
||||
border: 1px solid #333;
|
||||
background: #1a1a1a;
|
||||
color: #aaa;
|
||||
font-size: 13px;
|
||||
cursor: pointer;
|
||||
transition: all 0.15s;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
}
|
||||
.pill:hover { border-color: #555; color: #ddd; }
|
||||
.pill.active {
|
||||
border-color: #4ade80;
|
||||
background: #0a2a14;
|
||||
color: #4ade80;
|
||||
}
|
||||
.pill .dot {
|
||||
width: 6px; height: 6px;
|
||||
border-radius: 50%;
|
||||
background: #4ade80;
|
||||
}
|
||||
|
||||
/* ─── Search ──────────────────────────── */
|
||||
.search-wrap {
|
||||
padding: 0 20px 12px;
|
||||
}
|
||||
.search-input {
|
||||
width: 100%;
|
||||
padding: 8px 12px;
|
||||
border-radius: 8px;
|
||||
border: 1px solid #333;
|
||||
background: #141414;
|
||||
color: #e0e0e0;
|
||||
font-size: 13px;
|
||||
outline: none;
|
||||
transition: border-color 0.15s;
|
||||
}
|
||||
.search-input::placeholder { color: #555; }
|
||||
.search-input:focus { border-color: #555; }
|
||||
|
||||
/* ─── Domain List ─────────────────────── */
|
||||
.domain-list {
|
||||
flex: 1;
|
||||
overflow-y: auto;
|
||||
padding: 0 12px;
|
||||
}
|
||||
.domain-list::-webkit-scrollbar { width: 6px; }
|
||||
.domain-list::-webkit-scrollbar-track { background: transparent; }
|
||||
.domain-list::-webkit-scrollbar-thumb { background: #333; border-radius: 3px; }
|
||||
|
||||
.domain-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 8px 10px;
|
||||
border-radius: 6px;
|
||||
transition: background 0.1s;
|
||||
gap: 8px;
|
||||
}
|
||||
.domain-row:hover { background: #1a1a1a; }
|
||||
.domain-name {
|
||||
flex: 1;
|
||||
font-family: 'SF Mono', 'Fira Code', monospace;
|
||||
font-size: 13px;
|
||||
color: #ccc;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
}
|
||||
.domain-count {
|
||||
font-size: 12px;
|
||||
color: #666;
|
||||
font-family: 'SF Mono', 'Fira Code', monospace;
|
||||
min-width: 28px;
|
||||
text-align: right;
|
||||
}
|
||||
.btn-add, .btn-trash {
|
||||
width: 28px; height: 28px;
|
||||
border-radius: 6px;
|
||||
border: 1px solid #333;
|
||||
background: #1a1a1a;
|
||||
color: #888;
|
||||
font-size: 16px;
|
||||
cursor: pointer;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
transition: all 0.15s;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
.btn-add:hover { border-color: #4ade80; color: #4ade80; background: #0a2a14; }
|
||||
.btn-trash:hover { border-color: #f87171; color: #f87171; background: #2a0a0a; }
|
||||
.btn-add:disabled, .btn-trash:disabled {
|
||||
opacity: 0.3;
|
||||
cursor: not-allowed;
|
||||
pointer-events: none;
|
||||
}
|
||||
.btn-add.imported {
|
||||
border-color: #333;
|
||||
color: #4ade80;
|
||||
background: transparent;
|
||||
cursor: default;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
/* ─── Footer ──────────────────────────── */
|
||||
.panel-footer {
|
||||
padding: 12px 20px;
|
||||
border-top: 1px solid #222;
|
||||
font-size: 12px;
|
||||
color: #666;
|
||||
}
|
||||
|
||||
/* ─── Imported Panel ──────────────────── */
|
||||
.imported-empty {
|
||||
flex: 1;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
color: #444;
|
||||
font-size: 13px;
|
||||
padding: 20px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
/* ─── Banner ──────────────────────────── */
|
||||
.banner {
|
||||
padding: 10px 20px;
|
||||
font-size: 13px;
|
||||
display: none;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
}
|
||||
.banner.error {
|
||||
background: #1a0a0a;
|
||||
border-bottom: 1px solid #3a1111;
|
||||
color: #f87171;
|
||||
}
|
||||
.banner.info {
|
||||
background: #0a1a2a;
|
||||
border-bottom: 1px solid #112233;
|
||||
color: #60a5fa;
|
||||
}
|
||||
.banner .banner-text { flex: 1; }
|
||||
.banner .banner-close, .banner .banner-retry {
|
||||
background: none;
|
||||
border: 1px solid currentColor;
|
||||
color: inherit;
|
||||
padding: 3px 10px;
|
||||
border-radius: 4px;
|
||||
cursor: pointer;
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
/* ─── Spinner ─────────────────────────── */
|
||||
.spinner {
|
||||
display: inline-block;
|
||||
width: 14px; height: 14px;
|
||||
border: 2px solid #333;
|
||||
border-top-color: #4ade80;
|
||||
border-radius: 50%;
|
||||
animation: spin 0.6s linear infinite;
|
||||
}
|
||||
@keyframes spin { to { transform: rotate(360deg); } }
|
||||
|
||||
.loading-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 40px;
|
||||
gap: 10px;
|
||||
color: #666;
|
||||
font-size: 13px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
<h1>Cookie Import</h1>
|
||||
<span class="port">localhost:${serverPort}</span>
|
||||
</div>
|
||||
|
||||
<div id="banner" class="banner"></div>
|
||||
|
||||
<div class="container">
|
||||
<!-- Left Panel: Source Browser -->
|
||||
<div class="panel panel-left">
|
||||
<div class="panel-header">Source Browser</div>
|
||||
<div id="browser-pills" class="browser-pills"></div>
|
||||
<div class="search-wrap">
|
||||
<input type="text" class="search-input" id="search" placeholder="Search domains..." />
|
||||
</div>
|
||||
<div class="domain-list" id="source-domains">
|
||||
<div class="loading-row"><span class="spinner"></span> Detecting browsers...</div>
|
||||
</div>
|
||||
<div class="panel-footer" id="source-footer"></div>
|
||||
</div>
|
||||
|
||||
<!-- Right Panel: Imported -->
|
||||
<div class="panel panel-right">
|
||||
<div class="panel-header">Imported to Session</div>
|
||||
<div class="domain-list" id="imported-domains">
|
||||
<div class="imported-empty">No cookies imported yet</div>
|
||||
</div>
|
||||
<div class="panel-footer" id="imported-footer"></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
(function() {
|
||||
const BASE = '${baseUrl}';
|
||||
let activeBrowser = null;
|
||||
let allDomains = [];
|
||||
let importedSet = {}; // domain → count
|
||||
let inflight = {}; // domain → true (prevents double-click)
|
||||
|
||||
const $pills = document.getElementById('browser-pills');
|
||||
const $search = document.getElementById('search');
|
||||
const $sourceDomains = document.getElementById('source-domains');
|
||||
const $importedDomains = document.getElementById('imported-domains');
|
||||
const $sourceFooter = document.getElementById('source-footer');
|
||||
const $importedFooter = document.getElementById('imported-footer');
|
||||
const $banner = document.getElementById('banner');
|
||||
|
||||
// ─── Banner ────────────────────────────
|
||||
function showBanner(msg, type, retryFn) {
|
||||
$banner.className = 'banner ' + type;
|
||||
$banner.style.display = 'flex';
|
||||
let html = '<span class="banner-text">' + escHtml(msg) + '</span>';
|
||||
if (retryFn) {
|
||||
html += '<button class="banner-retry" id="banner-retry">Retry</button>';
|
||||
}
|
||||
html += '<button class="banner-close" id="banner-close">×</button>';
|
||||
$banner.innerHTML = html;
|
||||
document.getElementById('banner-close').onclick = () => { $banner.style.display = 'none'; };
|
||||
if (retryFn) {
|
||||
document.getElementById('banner-retry').onclick = () => {
|
||||
$banner.style.display = 'none';
|
||||
retryFn();
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
function escHtml(s) {
|
||||
return s.replace(/&/g,'&').replace(/</g,'<').replace(/>/g,'>');
|
||||
}
|
||||
|
||||
// ─── API ────────────────────────────────
|
||||
async function api(path, opts) {
|
||||
const res = await fetch(BASE + '/cookie-picker' + path, opts);
|
||||
const data = await res.json();
|
||||
if (!res.ok) {
|
||||
const err = new Error(data.error || 'Request failed');
|
||||
err.code = data.code;
|
||||
err.action = data.action;
|
||||
throw err;
|
||||
}
|
||||
return data;
|
||||
}
|
||||
|
||||
// ─── Init ───────────────────────────────
|
||||
async function init() {
|
||||
try {
|
||||
const [browserData, importedData] = await Promise.all([
|
||||
api('/browsers'),
|
||||
api('/imported'),
|
||||
]);
|
||||
|
||||
// Populate imported state
|
||||
for (const entry of importedData.domains) {
|
||||
importedSet[entry.domain] = entry.count;
|
||||
}
|
||||
renderImported();
|
||||
|
||||
// Render browser pills
|
||||
const browsers = browserData.browsers;
|
||||
if (browsers.length === 0) {
|
||||
$sourceDomains.innerHTML = '<div class="imported-empty">No Chromium browsers detected</div>';
|
||||
return;
|
||||
}
|
||||
|
||||
$pills.innerHTML = '';
|
||||
browsers.forEach(b => {
|
||||
const pill = document.createElement('button');
|
||||
pill.className = 'pill';
|
||||
pill.innerHTML = '<span class="dot"></span>' + escHtml(b.name);
|
||||
pill.onclick = () => selectBrowser(b.name);
|
||||
$pills.appendChild(pill);
|
||||
});
|
||||
|
||||
// Auto-select first browser
|
||||
selectBrowser(browsers[0].name);
|
||||
} catch (err) {
|
||||
showBanner(err.message, 'error', init);
|
||||
$sourceDomains.innerHTML = '<div class="imported-empty">Failed to load</div>';
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Select Browser ────────────────────
|
||||
async function selectBrowser(name) {
|
||||
activeBrowser = name;
|
||||
|
||||
// Update pills
|
||||
$pills.querySelectorAll('.pill').forEach(p => {
|
||||
p.classList.toggle('active', p.textContent === name);
|
||||
});
|
||||
|
||||
$sourceDomains.innerHTML = '<div class="loading-row"><span class="spinner"></span> Loading domains...</div>';
|
||||
$sourceFooter.textContent = '';
|
||||
$search.value = '';
|
||||
|
||||
try {
|
||||
const data = await api('/domains?browser=' + encodeURIComponent(name));
|
||||
allDomains = data.domains;
|
||||
renderSourceDomains();
|
||||
} catch (err) {
|
||||
showBanner(err.message, 'error', err.action === 'retry' ? () => selectBrowser(name) : null);
|
||||
$sourceDomains.innerHTML = '<div class="imported-empty">Failed to load domains</div>';
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Render Source Domains ─────────────
|
||||
function renderSourceDomains() {
|
||||
const query = $search.value.toLowerCase();
|
||||
const filtered = query
|
||||
? allDomains.filter(d => d.domain.toLowerCase().includes(query))
|
||||
: allDomains;
|
||||
|
||||
if (filtered.length === 0) {
|
||||
$sourceDomains.innerHTML = '<div class="imported-empty">' +
|
||||
(query ? 'No matching domains' : 'No cookie domains found') + '</div>';
|
||||
$sourceFooter.textContent = '';
|
||||
return;
|
||||
}
|
||||
|
||||
let html = '';
|
||||
for (const d of filtered) {
|
||||
const isImported = d.domain in importedSet;
|
||||
const isInflight = inflight[d.domain];
|
||||
html += '<div class="domain-row">';
|
||||
html += '<span class="domain-name">' + escHtml(d.domain) + '</span>';
|
||||
html += '<span class="domain-count">' + d.count + '</span>';
|
||||
if (isInflight) {
|
||||
html += '<span class="btn-add" disabled><span class="spinner" style="width:12px;height:12px;border-width:1.5px;"></span></span>';
|
||||
} else if (isImported) {
|
||||
html += '<span class="btn-add imported">✓</span>';
|
||||
} else {
|
||||
html += '<button class="btn-add" data-domain="' + escHtml(d.domain) + '" title="Import">+</button>';
|
||||
}
|
||||
html += '</div>';
|
||||
}
|
||||
$sourceDomains.innerHTML = html;
|
||||
|
||||
// Total counts
|
||||
const totalDomains = allDomains.length;
|
||||
const totalCookies = allDomains.reduce((s, d) => s + d.count, 0);
|
||||
$sourceFooter.textContent = totalDomains + ' domains · ' + totalCookies.toLocaleString() + ' cookies';
|
||||
|
||||
// Click handlers
|
||||
$sourceDomains.querySelectorAll('.btn-add[data-domain]').forEach(btn => {
|
||||
btn.addEventListener('click', () => importDomain(btn.dataset.domain));
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Import Domain ─────────────────────
|
||||
async function importDomain(domain) {
|
||||
if (inflight[domain] || domain in importedSet) return;
|
||||
inflight[domain] = true;
|
||||
renderSourceDomains();
|
||||
|
||||
try {
|
||||
const data = await api('/import', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ browser: activeBrowser, domains: [domain] }),
|
||||
});
|
||||
|
||||
if (data.domainCounts) {
|
||||
for (const [d, count] of Object.entries(data.domainCounts)) {
|
||||
importedSet[d] = (importedSet[d] || 0) + count;
|
||||
}
|
||||
}
|
||||
renderImported();
|
||||
} catch (err) {
|
||||
showBanner('Import failed for ' + domain + ': ' + err.message, 'error',
|
||||
err.action === 'retry' ? () => importDomain(domain) : null);
|
||||
} finally {
|
||||
delete inflight[domain];
|
||||
renderSourceDomains();
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Render Imported ───────────────────
|
||||
function renderImported() {
|
||||
const entries = Object.entries(importedSet).sort((a, b) => b[1] - a[1]);
|
||||
|
||||
if (entries.length === 0) {
|
||||
$importedDomains.innerHTML = '<div class="imported-empty">No cookies imported yet</div>';
|
||||
$importedFooter.textContent = '';
|
||||
return;
|
||||
}
|
||||
|
||||
let html = '';
|
||||
for (const [domain, count] of entries) {
|
||||
const isInflight = inflight['remove:' + domain];
|
||||
html += '<div class="domain-row">';
|
||||
html += '<span class="domain-name">' + escHtml(domain) + '</span>';
|
||||
html += '<span class="domain-count">' + count + '</span>';
|
||||
if (isInflight) {
|
||||
html += '<span class="btn-trash" disabled><span class="spinner" style="width:12px;height:12px;border-width:1.5px;border-top-color:#f87171;"></span></span>';
|
||||
} else {
|
||||
html += '<button class="btn-trash" data-domain="' + escHtml(domain) + '" title="Remove">🗑</button>';
|
||||
}
|
||||
html += '</div>';
|
||||
}
|
||||
$importedDomains.innerHTML = html;
|
||||
|
||||
const totalCookies = entries.reduce((s, e) => s + e[1], 0);
|
||||
$importedFooter.textContent = entries.length + ' domains · ' + totalCookies.toLocaleString() + ' cookies imported';
|
||||
|
||||
// Click handlers
|
||||
$importedDomains.querySelectorAll('.btn-trash[data-domain]').forEach(btn => {
|
||||
btn.addEventListener('click', () => removeDomain(btn.dataset.domain));
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Remove Domain ─────────────────────
|
||||
async function removeDomain(domain) {
|
||||
if (inflight['remove:' + domain]) return;
|
||||
inflight['remove:' + domain] = true;
|
||||
renderImported();
|
||||
|
||||
try {
|
||||
await api('/remove', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ domains: [domain] }),
|
||||
});
|
||||
delete importedSet[domain];
|
||||
renderImported();
|
||||
renderSourceDomains(); // update checkmarks
|
||||
} catch (err) {
|
||||
showBanner('Remove failed for ' + domain + ': ' + err.message, 'error',
|
||||
err.action === 'retry' ? () => removeDomain(domain) : null);
|
||||
} finally {
|
||||
delete inflight['remove:' + domain];
|
||||
renderImported();
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Search ────────────────────────────
|
||||
$search.addEventListener('input', renderSourceDomains);
|
||||
|
||||
// ─── Start ─────────────────────────────
|
||||
init();
|
||||
})();
|
||||
</script>
|
||||
</body>
|
||||
</html>`;
|
||||
}
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
/**
|
||||
* find-browse — locate the gstack browse binary.
|
||||
*
|
||||
* Compiled to browse/dist/find-browse (standalone binary, no bun runtime needed).
|
||||
* Outputs the absolute path to the browse binary on stdout, or exits 1 if not found.
|
||||
*/
|
||||
|
||||
import { existsSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { homedir } from 'os';
|
||||
|
||||
// ─── Binary Discovery ───────────────────────────────────────────
|
||||
|
||||
function getGitRoot(): string | null {
|
||||
try {
|
||||
const proc = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], {
|
||||
stdout: 'pipe',
|
||||
stderr: 'pipe',
|
||||
});
|
||||
if (proc.exitCode !== 0) return null;
|
||||
return proc.stdout.toString().trim();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function locateBinary(): string | null {
|
||||
const root = getGitRoot();
|
||||
const home = homedir();
|
||||
const markers = ['.codex', '.agents', '.claude'];
|
||||
|
||||
// Workspace-local takes priority (for development)
|
||||
if (root) {
|
||||
for (const m of markers) {
|
||||
const local = join(root, m, 'skills', 'gstack', 'browse', 'dist', 'browse');
|
||||
if (existsSync(local)) return local;
|
||||
}
|
||||
}
|
||||
|
||||
// Global fallback
|
||||
for (const m of markers) {
|
||||
const global = join(home, m, 'skills', 'gstack', 'browse', 'dist', 'browse');
|
||||
if (existsSync(global)) return global;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
// ─── Main ───────────────────────────────────────────────────────
|
||||
|
||||
function main() {
|
||||
const bin = locateBinary();
|
||||
if (!bin) {
|
||||
process.stderr.write('ERROR: browse binary not found. Run: cd <skill-dir> && ./setup\n');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(bin);
|
||||
}
|
||||
|
||||
main();
|
||||
|
|
@ -0,0 +1,269 @@
|
|||
/**
|
||||
* Meta commands — tabs, server control, screenshots, chain, diff, snapshot
|
||||
*/
|
||||
|
||||
import type { BrowserManager } from './browser-manager';
|
||||
import { handleSnapshot } from './snapshot';
|
||||
import { getCleanText } from './read-commands';
|
||||
import { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS } from './commands';
|
||||
import { validateNavigationUrl } from './url-validation';
|
||||
import * as Diff from 'diff';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { TEMP_DIR, isPathWithin } from './platform';
|
||||
|
||||
// Security: Path validation to prevent path traversal attacks
|
||||
const SAFE_DIRECTORIES = [TEMP_DIR, process.cwd()];
|
||||
|
||||
export function validateOutputPath(filePath: string): void {
|
||||
const resolved = path.resolve(filePath);
|
||||
const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir));
|
||||
if (!isSafe) {
|
||||
throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
|
||||
}
|
||||
}
|
||||
|
||||
export async function handleMetaCommand(
|
||||
command: string,
|
||||
args: string[],
|
||||
bm: BrowserManager,
|
||||
shutdown: () => Promise<void> | void
|
||||
): Promise<string> {
|
||||
switch (command) {
|
||||
// ─── Tabs ──────────────────────────────────────────
|
||||
case 'tabs': {
|
||||
const tabs = await bm.getTabListWithTitles();
|
||||
return tabs.map(t =>
|
||||
`${t.active ? '→ ' : ' '}[${t.id}] ${t.title || '(untitled)'} — ${t.url}`
|
||||
).join('\n');
|
||||
}
|
||||
|
||||
case 'tab': {
|
||||
const id = parseInt(args[0], 10);
|
||||
if (isNaN(id)) throw new Error('Usage: browse tab <id>');
|
||||
bm.switchTab(id);
|
||||
return `Switched to tab ${id}`;
|
||||
}
|
||||
|
||||
case 'newtab': {
|
||||
const url = args[0];
|
||||
const id = await bm.newTab(url);
|
||||
return `Opened tab ${id}${url ? ` → ${url}` : ''}`;
|
||||
}
|
||||
|
||||
case 'closetab': {
|
||||
const id = args[0] ? parseInt(args[0], 10) : undefined;
|
||||
await bm.closeTab(id);
|
||||
return `Closed tab${id ? ` ${id}` : ''}`;
|
||||
}
|
||||
|
||||
// ─── Server Control ────────────────────────────────
|
||||
case 'status': {
|
||||
const page = bm.getPage();
|
||||
const tabs = bm.getTabCount();
|
||||
return [
|
||||
`Status: healthy`,
|
||||
`URL: ${page.url()}`,
|
||||
`Tabs: ${tabs}`,
|
||||
`PID: ${process.pid}`,
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
case 'url': {
|
||||
return bm.getCurrentUrl();
|
||||
}
|
||||
|
||||
case 'stop': {
|
||||
await shutdown();
|
||||
return 'Server stopped';
|
||||
}
|
||||
|
||||
case 'restart': {
|
||||
// Signal that we want a restart — the CLI will detect exit and restart
|
||||
console.log('[browse] Restart requested. Exiting for CLI to restart.');
|
||||
await shutdown();
|
||||
return 'Restarting...';
|
||||
}
|
||||
|
||||
// ─── Visual ────────────────────────────────────────
|
||||
case 'screenshot': {
|
||||
// Parse priority: flags (--viewport, --clip) → selector (@ref, CSS) → output path
|
||||
const page = bm.getPage();
|
||||
let outputPath = `${TEMP_DIR}/browse-screenshot.png`;
|
||||
let clipRect: { x: number; y: number; width: number; height: number } | undefined;
|
||||
let targetSelector: string | undefined;
|
||||
let viewportOnly = false;
|
||||
|
||||
const remaining: string[] = [];
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--viewport') {
|
||||
viewportOnly = true;
|
||||
} else if (args[i] === '--clip') {
|
||||
const coords = args[++i];
|
||||
if (!coords) throw new Error('Usage: screenshot --clip x,y,w,h [path]');
|
||||
const parts = coords.split(',').map(Number);
|
||||
if (parts.length !== 4 || parts.some(isNaN))
|
||||
throw new Error('Usage: screenshot --clip x,y,width,height — all must be numbers');
|
||||
clipRect = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
|
||||
} else if (args[i].startsWith('--')) {
|
||||
throw new Error(`Unknown screenshot flag: ${args[i]}`);
|
||||
} else {
|
||||
remaining.push(args[i]);
|
||||
}
|
||||
}
|
||||
|
||||
// Separate target (selector/@ref) from output path
|
||||
for (const arg of remaining) {
|
||||
if (arg.startsWith('@e') || arg.startsWith('@c') || arg.startsWith('.') || arg.startsWith('#') || arg.includes('[')) {
|
||||
targetSelector = arg;
|
||||
} else {
|
||||
outputPath = arg;
|
||||
}
|
||||
}
|
||||
|
||||
validateOutputPath(outputPath);
|
||||
|
||||
if (clipRect && targetSelector) {
|
||||
throw new Error('Cannot use --clip with a selector/ref — choose one');
|
||||
}
|
||||
if (viewportOnly && clipRect) {
|
||||
throw new Error('Cannot use --viewport with --clip — choose one');
|
||||
}
|
||||
|
||||
if (targetSelector) {
|
||||
const resolved = await bm.resolveRef(targetSelector);
|
||||
const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
|
||||
await locator.screenshot({ path: outputPath, timeout: 5000 });
|
||||
return `Screenshot saved (element): ${outputPath}`;
|
||||
}
|
||||
|
||||
if (clipRect) {
|
||||
await page.screenshot({ path: outputPath, clip: clipRect });
|
||||
return `Screenshot saved (clip ${clipRect.x},${clipRect.y},${clipRect.width},${clipRect.height}): ${outputPath}`;
|
||||
}
|
||||
|
||||
await page.screenshot({ path: outputPath, fullPage: !viewportOnly });
|
||||
return `Screenshot saved${viewportOnly ? ' (viewport)' : ''}: ${outputPath}`;
|
||||
}
|
||||
|
||||
case 'pdf': {
|
||||
const page = bm.getPage();
|
||||
const pdfPath = args[0] || `${TEMP_DIR}/browse-page.pdf`;
|
||||
validateOutputPath(pdfPath);
|
||||
await page.pdf({ path: pdfPath, format: 'A4' });
|
||||
return `PDF saved: ${pdfPath}`;
|
||||
}
|
||||
|
||||
case 'responsive': {
|
||||
const page = bm.getPage();
|
||||
const prefix = args[0] || `${TEMP_DIR}/browse-responsive`;
|
||||
validateOutputPath(prefix);
|
||||
const viewports = [
|
||||
{ name: 'mobile', width: 375, height: 812 },
|
||||
{ name: 'tablet', width: 768, height: 1024 },
|
||||
{ name: 'desktop', width: 1280, height: 720 },
|
||||
];
|
||||
const originalViewport = page.viewportSize();
|
||||
const results: string[] = [];
|
||||
|
||||
for (const vp of viewports) {
|
||||
await page.setViewportSize({ width: vp.width, height: vp.height });
|
||||
const path = `${prefix}-${vp.name}.png`;
|
||||
await page.screenshot({ path, fullPage: true });
|
||||
results.push(`${vp.name} (${vp.width}x${vp.height}): ${path}`);
|
||||
}
|
||||
|
||||
// Restore original viewport
|
||||
if (originalViewport) {
|
||||
await page.setViewportSize(originalViewport);
|
||||
}
|
||||
|
||||
return results.join('\n');
|
||||
}
|
||||
|
||||
// ─── Chain ─────────────────────────────────────────
|
||||
case 'chain': {
|
||||
// Read JSON array from args[0] (if provided) or expect it was passed as body
|
||||
const jsonStr = args[0];
|
||||
if (!jsonStr) throw new Error('Usage: echo \'[["goto","url"],["text"]]\' | browse chain');
|
||||
|
||||
let commands: string[][];
|
||||
try {
|
||||
commands = JSON.parse(jsonStr);
|
||||
} catch {
|
||||
throw new Error('Invalid JSON. Expected: [["command", "arg1", "arg2"], ...]');
|
||||
}
|
||||
|
||||
if (!Array.isArray(commands)) throw new Error('Expected JSON array of commands');
|
||||
|
||||
const results: string[] = [];
|
||||
const { handleReadCommand } = await import('./read-commands');
|
||||
const { handleWriteCommand } = await import('./write-commands');
|
||||
|
||||
for (const cmd of commands) {
|
||||
const [name, ...cmdArgs] = cmd;
|
||||
try {
|
||||
let result: string;
|
||||
if (WRITE_COMMANDS.has(name)) result = await handleWriteCommand(name, cmdArgs, bm);
|
||||
else if (READ_COMMANDS.has(name)) result = await handleReadCommand(name, cmdArgs, bm);
|
||||
else if (META_COMMANDS.has(name)) result = await handleMetaCommand(name, cmdArgs, bm, shutdown);
|
||||
else throw new Error(`Unknown command: ${name}`);
|
||||
results.push(`[${name}] ${result}`);
|
||||
} catch (err: any) {
|
||||
results.push(`[${name}] ERROR: ${err.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
return results.join('\n\n');
|
||||
}
|
||||
|
||||
// ─── Diff ──────────────────────────────────────────
|
||||
case 'diff': {
|
||||
const [url1, url2] = args;
|
||||
if (!url1 || !url2) throw new Error('Usage: browse diff <url1> <url2>');
|
||||
|
||||
const page = bm.getPage();
|
||||
await validateNavigationUrl(url1);
|
||||
await page.goto(url1, { waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
const text1 = await getCleanText(page);
|
||||
|
||||
await validateNavigationUrl(url2);
|
||||
await page.goto(url2, { waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
const text2 = await getCleanText(page);
|
||||
|
||||
const changes = Diff.diffLines(text1, text2);
|
||||
const output: string[] = [`--- ${url1}`, `+++ ${url2}`, ''];
|
||||
|
||||
for (const part of changes) {
|
||||
const prefix = part.added ? '+' : part.removed ? '-' : ' ';
|
||||
const lines = part.value.split('\n').filter(l => l.length > 0);
|
||||
for (const line of lines) {
|
||||
output.push(`${prefix} ${line}`);
|
||||
}
|
||||
}
|
||||
|
||||
return output.join('\n');
|
||||
}
|
||||
|
||||
// ─── Snapshot ─────────────────────────────────────
|
||||
case 'snapshot': {
|
||||
return await handleSnapshot(args, bm);
|
||||
}
|
||||
|
||||
// ─── Handoff ────────────────────────────────────
|
||||
case 'handoff': {
|
||||
const message = args.join(' ') || 'User takeover requested';
|
||||
return await bm.handoff(message);
|
||||
}
|
||||
|
||||
case 'resume': {
|
||||
bm.resume();
|
||||
// Re-snapshot to capture current page state after human interaction
|
||||
const snapshot = await handleSnapshot(['-i'], bm);
|
||||
return `RESUMED\n${snapshot}`;
|
||||
}
|
||||
|
||||
default:
|
||||
throw new Error(`Unknown meta command: ${command}`);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
/**
|
||||
* Cross-platform constants for gstack browse.
|
||||
*
|
||||
* On macOS/Linux: TEMP_DIR = '/tmp', path.sep = '/' — identical to hardcoded values.
|
||||
* On Windows: TEMP_DIR = os.tmpdir(), path.sep = '\\' — correct Windows behavior.
|
||||
*/
|
||||
|
||||
import * as os from 'os';
|
||||
import * as path from 'path';
|
||||
|
||||
export const IS_WINDOWS = process.platform === 'win32';
|
||||
export const TEMP_DIR = IS_WINDOWS ? os.tmpdir() : '/tmp';
|
||||
|
||||
/** Check if resolvedPath is within dir, using platform-aware separators. */
|
||||
export function isPathWithin(resolvedPath: string, dir: string): boolean {
|
||||
return resolvedPath === dir || resolvedPath.startsWith(dir + path.sep);
|
||||
}
|
||||
|
|
@ -0,0 +1,335 @@
|
|||
/**
|
||||
* Read commands — extract data from pages without side effects
|
||||
*
|
||||
* text, html, links, forms, accessibility, js, eval, css, attrs,
|
||||
* console, network, cookies, storage, perf
|
||||
*/
|
||||
|
||||
import type { BrowserManager } from './browser-manager';
|
||||
import { consoleBuffer, networkBuffer, dialogBuffer } from './buffers';
|
||||
import type { Page } from 'playwright';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { TEMP_DIR, isPathWithin } from './platform';
|
||||
|
||||
/** Detect await keyword, ignoring comments. Accepted risk: await in string literals triggers wrapping (harmless). */
|
||||
function hasAwait(code: string): boolean {
|
||||
const stripped = code.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
|
||||
return /\bawait\b/.test(stripped);
|
||||
}
|
||||
|
||||
/** Detect whether code needs a block wrapper {…} vs expression wrapper (…) inside an async IIFE. */
|
||||
function needsBlockWrapper(code: string): boolean {
|
||||
const trimmed = code.trim();
|
||||
if (trimmed.split('\n').length > 1) return true;
|
||||
if (/\b(const|let|var|function|class|return|throw|if|for|while|switch|try)\b/.test(trimmed)) return true;
|
||||
if (trimmed.includes(';')) return true;
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Wrap code for page.evaluate(), using async IIFE with block or expression body as needed. */
|
||||
function wrapForEvaluate(code: string): string {
|
||||
if (!hasAwait(code)) return code;
|
||||
const trimmed = code.trim();
|
||||
return needsBlockWrapper(trimmed)
|
||||
? `(async()=>{\n${code}\n})()`
|
||||
: `(async()=>(${trimmed}))()`;
|
||||
}
|
||||
|
||||
// Security: Path validation to prevent path traversal attacks
|
||||
const SAFE_DIRECTORIES = [TEMP_DIR, process.cwd()];
|
||||
|
||||
export function validateReadPath(filePath: string): void {
|
||||
if (path.isAbsolute(filePath)) {
|
||||
const resolved = path.resolve(filePath);
|
||||
const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir));
|
||||
if (!isSafe) {
|
||||
throw new Error(`Absolute path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
|
||||
}
|
||||
}
|
||||
const normalized = path.normalize(filePath);
|
||||
if (normalized.includes('..')) {
|
||||
throw new Error('Path traversal sequences (..) are not allowed');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract clean text from a page (strips script/style/noscript/svg).
|
||||
* Exported for DRY reuse in meta-commands (diff).
|
||||
*/
|
||||
export async function getCleanText(page: Page): Promise<string> {
|
||||
return await page.evaluate(() => {
|
||||
const body = document.body;
|
||||
if (!body) return '';
|
||||
const clone = body.cloneNode(true) as HTMLElement;
|
||||
clone.querySelectorAll('script, style, noscript, svg').forEach(el => el.remove());
|
||||
return clone.innerText
|
||||
.split('\n')
|
||||
.map(line => line.trim())
|
||||
.filter(line => line.length > 0)
|
||||
.join('\n');
|
||||
});
|
||||
}
|
||||
|
||||
export async function handleReadCommand(
|
||||
command: string,
|
||||
args: string[],
|
||||
bm: BrowserManager
|
||||
): Promise<string> {
|
||||
const page = bm.getPage();
|
||||
|
||||
switch (command) {
|
||||
case 'text': {
|
||||
return await getCleanText(page);
|
||||
}
|
||||
|
||||
case 'html': {
|
||||
const selector = args[0];
|
||||
if (selector) {
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
return await resolved.locator.innerHTML({ timeout: 5000 });
|
||||
}
|
||||
return await page.innerHTML(resolved.selector);
|
||||
}
|
||||
return await page.content();
|
||||
}
|
||||
|
||||
case 'links': {
|
||||
const links = await page.evaluate(() =>
|
||||
[...document.querySelectorAll('a[href]')].map(a => ({
|
||||
text: a.textContent?.trim().slice(0, 120) || '',
|
||||
href: (a as HTMLAnchorElement).href,
|
||||
})).filter(l => l.text && l.href)
|
||||
);
|
||||
return links.map(l => `${l.text} → ${l.href}`).join('\n');
|
||||
}
|
||||
|
||||
case 'forms': {
|
||||
const forms = await page.evaluate(() => {
|
||||
return [...document.querySelectorAll('form')].map((form, i) => {
|
||||
const fields = [...form.querySelectorAll('input, select, textarea')].map(el => {
|
||||
const input = el as HTMLInputElement;
|
||||
return {
|
||||
tag: el.tagName.toLowerCase(),
|
||||
type: input.type || undefined,
|
||||
name: input.name || undefined,
|
||||
id: input.id || undefined,
|
||||
placeholder: input.placeholder || undefined,
|
||||
required: input.required || undefined,
|
||||
value: input.type === 'password' ? '[redacted]' : (input.value || undefined),
|
||||
options: el.tagName === 'SELECT'
|
||||
? [...(el as HTMLSelectElement).options].map(o => ({ value: o.value, text: o.text }))
|
||||
: undefined,
|
||||
};
|
||||
});
|
||||
return {
|
||||
index: i,
|
||||
action: form.action || undefined,
|
||||
method: form.method || 'get',
|
||||
id: form.id || undefined,
|
||||
fields,
|
||||
};
|
||||
});
|
||||
});
|
||||
return JSON.stringify(forms, null, 2);
|
||||
}
|
||||
|
||||
case 'accessibility': {
|
||||
const snapshot = await page.locator("body").ariaSnapshot();
|
||||
return snapshot;
|
||||
}
|
||||
|
||||
case 'js': {
|
||||
const expr = args[0];
|
||||
if (!expr) throw new Error('Usage: browse js <expression>');
|
||||
const wrapped = wrapForEvaluate(expr);
|
||||
const result = await page.evaluate(wrapped);
|
||||
return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
|
||||
}
|
||||
|
||||
case 'eval': {
|
||||
const filePath = args[0];
|
||||
if (!filePath) throw new Error('Usage: browse eval <js-file>');
|
||||
validateReadPath(filePath);
|
||||
if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
|
||||
const code = fs.readFileSync(filePath, 'utf-8');
|
||||
const wrapped = wrapForEvaluate(code);
|
||||
const result = await page.evaluate(wrapped);
|
||||
return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
|
||||
}
|
||||
|
||||
case 'css': {
|
||||
const [selector, property] = args;
|
||||
if (!selector || !property) throw new Error('Usage: browse css <selector> <property>');
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
const value = await resolved.locator.evaluate(
|
||||
(el, prop) => getComputedStyle(el).getPropertyValue(prop),
|
||||
property
|
||||
);
|
||||
return value;
|
||||
}
|
||||
const value = await page.evaluate(
|
||||
([sel, prop]) => {
|
||||
const el = document.querySelector(sel);
|
||||
if (!el) return `Element not found: ${sel}`;
|
||||
return getComputedStyle(el).getPropertyValue(prop);
|
||||
},
|
||||
[resolved.selector, property]
|
||||
);
|
||||
return value;
|
||||
}
|
||||
|
||||
case 'attrs': {
|
||||
const selector = args[0];
|
||||
if (!selector) throw new Error('Usage: browse attrs <selector>');
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
const attrs = await resolved.locator.evaluate((el) => {
|
||||
const result: Record<string, string> = {};
|
||||
for (const attr of el.attributes) {
|
||||
result[attr.name] = attr.value;
|
||||
}
|
||||
return result;
|
||||
});
|
||||
return JSON.stringify(attrs, null, 2);
|
||||
}
|
||||
const attrs = await page.evaluate((sel) => {
|
||||
const el = document.querySelector(sel);
|
||||
if (!el) return `Element not found: ${sel}`;
|
||||
const result: Record<string, string> = {};
|
||||
for (const attr of el.attributes) {
|
||||
result[attr.name] = attr.value;
|
||||
}
|
||||
return result;
|
||||
}, resolved.selector);
|
||||
return typeof attrs === 'string' ? attrs : JSON.stringify(attrs, null, 2);
|
||||
}
|
||||
|
||||
case 'console': {
|
||||
if (args[0] === '--clear') {
|
||||
consoleBuffer.clear();
|
||||
return 'Console buffer cleared.';
|
||||
}
|
||||
const entries = args[0] === '--errors'
|
||||
? consoleBuffer.toArray().filter(e => e.level === 'error' || e.level === 'warning')
|
||||
: consoleBuffer.toArray();
|
||||
if (entries.length === 0) return args[0] === '--errors' ? '(no console errors)' : '(no console messages)';
|
||||
return entries.map(e =>
|
||||
`[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
|
||||
).join('\n');
|
||||
}
|
||||
|
||||
case 'network': {
|
||||
if (args[0] === '--clear') {
|
||||
networkBuffer.clear();
|
||||
return 'Network buffer cleared.';
|
||||
}
|
||||
if (networkBuffer.length === 0) return '(no network requests)';
|
||||
return networkBuffer.toArray().map(e =>
|
||||
`${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
|
||||
).join('\n');
|
||||
}
|
||||
|
||||
case 'dialog': {
|
||||
if (args[0] === '--clear') {
|
||||
dialogBuffer.clear();
|
||||
return 'Dialog buffer cleared.';
|
||||
}
|
||||
if (dialogBuffer.length === 0) return '(no dialogs captured)';
|
||||
return dialogBuffer.toArray().map(e =>
|
||||
`[${new Date(e.timestamp).toISOString()}] [${e.type}] "${e.message}" → ${e.action}${e.response ? ` "${e.response}"` : ''}`
|
||||
).join('\n');
|
||||
}
|
||||
|
||||
case 'is': {
|
||||
const property = args[0];
|
||||
const selector = args[1];
|
||||
if (!property || !selector) throw new Error('Usage: browse is <property> <selector>\nProperties: visible, hidden, enabled, disabled, checked, editable, focused');
|
||||
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
let locator;
|
||||
if ('locator' in resolved) {
|
||||
locator = resolved.locator;
|
||||
} else {
|
||||
locator = page.locator(resolved.selector);
|
||||
}
|
||||
|
||||
switch (property) {
|
||||
case 'visible': return String(await locator.isVisible());
|
||||
case 'hidden': return String(await locator.isHidden());
|
||||
case 'enabled': return String(await locator.isEnabled());
|
||||
case 'disabled': return String(await locator.isDisabled());
|
||||
case 'checked': return String(await locator.isChecked());
|
||||
case 'editable': return String(await locator.isEditable());
|
||||
case 'focused': {
|
||||
const isFocused = await locator.evaluate(
|
||||
(el) => el === document.activeElement
|
||||
);
|
||||
return String(isFocused);
|
||||
}
|
||||
default:
|
||||
throw new Error(`Unknown property: ${property}. Use: visible, hidden, enabled, disabled, checked, editable, focused`);
|
||||
}
|
||||
}
|
||||
|
||||
case 'cookies': {
|
||||
const cookies = await page.context().cookies();
|
||||
return JSON.stringify(cookies, null, 2);
|
||||
}
|
||||
|
||||
case 'storage': {
|
||||
if (args[0] === 'set' && args[1]) {
|
||||
const key = args[1];
|
||||
const value = args[2] || '';
|
||||
await page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
|
||||
return `Set localStorage["${key}"]`;
|
||||
}
|
||||
const storage = await page.evaluate(() => ({
|
||||
localStorage: { ...localStorage },
|
||||
sessionStorage: { ...sessionStorage },
|
||||
}));
|
||||
// Redact values that look like secrets (tokens, keys, passwords, JWTs)
|
||||
const SENSITIVE_KEY = /(^|[_.-])(token|secret|key|password|credential|auth|jwt|session|csrf)($|[_.-])|api.?key/i;
|
||||
const SENSITIVE_VALUE = /^(eyJ|sk-|sk_live_|sk_test_|pk_live_|pk_test_|rk_live_|sk-ant-|ghp_|gho_|github_pat_|xox[bpsa]-|AKIA[A-Z0-9]{16}|AIza|SG\.|Bearer\s|sbp_)/;
|
||||
const redacted = JSON.parse(JSON.stringify(storage));
|
||||
for (const storeType of ['localStorage', 'sessionStorage'] as const) {
|
||||
const store = redacted[storeType];
|
||||
if (!store) continue;
|
||||
for (const [key, value] of Object.entries(store)) {
|
||||
if (typeof value !== 'string') continue;
|
||||
if (SENSITIVE_KEY.test(key) || SENSITIVE_VALUE.test(value)) {
|
||||
store[key] = `[REDACTED — ${value.length} chars]`;
|
||||
}
|
||||
}
|
||||
}
|
||||
return JSON.stringify(redacted, null, 2);
|
||||
}
|
||||
|
||||
case 'perf': {
|
||||
const timings = await page.evaluate(() => {
|
||||
const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
|
||||
if (!nav) return 'No navigation timing data available.';
|
||||
return {
|
||||
dns: Math.round(nav.domainLookupEnd - nav.domainLookupStart),
|
||||
tcp: Math.round(nav.connectEnd - nav.connectStart),
|
||||
ssl: Math.round(nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0),
|
||||
ttfb: Math.round(nav.responseStart - nav.requestStart),
|
||||
download: Math.round(nav.responseEnd - nav.responseStart),
|
||||
domParse: Math.round(nav.domInteractive - nav.responseEnd),
|
||||
domReady: Math.round(nav.domContentLoadedEventEnd - nav.startTime),
|
||||
load: Math.round(nav.loadEventEnd - nav.startTime),
|
||||
total: Math.round(nav.loadEventEnd - nav.startTime),
|
||||
};
|
||||
});
|
||||
if (typeof timings === 'string') return timings;
|
||||
return Object.entries(timings)
|
||||
.map(([k, v]) => `${k.padEnd(12)} ${v}ms`)
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
default:
|
||||
throw new Error(`Unknown read command: ${command}`);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,369 @@
|
|||
/**
|
||||
* gstack browse server — persistent Chromium daemon
|
||||
*
|
||||
* Architecture:
|
||||
* Bun.serve HTTP on localhost → routes commands to Playwright
|
||||
* Console/network/dialog buffers: CircularBuffer in-memory + async disk flush
|
||||
* Chromium crash → server EXITS with clear error (CLI auto-restarts)
|
||||
* Auto-shutdown after BROWSE_IDLE_TIMEOUT (default 30 min)
|
||||
*
|
||||
* State:
|
||||
* State file: <project-root>/.gstack/browse.json (set via BROWSE_STATE_FILE env)
|
||||
* Log files: <project-root>/.gstack/browse-{console,network,dialog}.log
|
||||
* Port: random 10000-60000 (or BROWSE_PORT env for debug override)
|
||||
*/
|
||||
|
||||
import { BrowserManager } from './browser-manager';
|
||||
import { handleReadCommand } from './read-commands';
|
||||
import { handleWriteCommand } from './write-commands';
|
||||
import { handleMetaCommand } from './meta-commands';
|
||||
import { handleCookiePickerRoute } from './cookie-picker-routes';
|
||||
import { COMMAND_DESCRIPTIONS } from './commands';
|
||||
import { SNAPSHOT_FLAGS } from './snapshot';
|
||||
import { resolveConfig, ensureStateDir, readVersionHash } from './config';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import * as crypto from 'crypto';
|
||||
|
||||
// ─── Config ─────────────────────────────────────────────────────
|
||||
const config = resolveConfig();
|
||||
ensureStateDir(config);
|
||||
|
||||
// ─── Auth ───────────────────────────────────────────────────────
|
||||
const AUTH_TOKEN = crypto.randomUUID();
|
||||
const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
|
||||
const IDLE_TIMEOUT_MS = parseInt(process.env.BROWSE_IDLE_TIMEOUT || '1800000', 10); // 30 min
|
||||
|
||||
function validateAuth(req: Request): boolean {
|
||||
const header = req.headers.get('authorization');
|
||||
return header === `Bearer ${AUTH_TOKEN}`;
|
||||
}
|
||||
|
||||
// ─── Help text (auto-generated from COMMAND_DESCRIPTIONS) ────────
|
||||
function generateHelpText(): string {
|
||||
// Group commands by category
|
||||
const groups = new Map<string, string[]>();
|
||||
for (const [cmd, meta] of Object.entries(COMMAND_DESCRIPTIONS)) {
|
||||
const display = meta.usage || cmd;
|
||||
const list = groups.get(meta.category) || [];
|
||||
list.push(display);
|
||||
groups.set(meta.category, list);
|
||||
}
|
||||
|
||||
const categoryOrder = [
|
||||
'Navigation', 'Reading', 'Interaction', 'Inspection',
|
||||
'Visual', 'Snapshot', 'Meta', 'Tabs', 'Server',
|
||||
];
|
||||
|
||||
const lines = ['gstack browse — headless browser for AI agents', '', 'Commands:'];
|
||||
for (const cat of categoryOrder) {
|
||||
const cmds = groups.get(cat);
|
||||
if (!cmds) continue;
|
||||
lines.push(` ${(cat + ':').padEnd(15)}${cmds.join(', ')}`);
|
||||
}
|
||||
|
||||
// Snapshot flags from source of truth
|
||||
lines.push('');
|
||||
lines.push('Snapshot flags:');
|
||||
const flagPairs: string[] = [];
|
||||
for (const flag of SNAPSHOT_FLAGS) {
|
||||
const label = flag.valueHint ? `${flag.short} ${flag.valueHint}` : flag.short;
|
||||
flagPairs.push(`${label} ${flag.long}`);
|
||||
}
|
||||
// Print two flags per line for compact display
|
||||
for (let i = 0; i < flagPairs.length; i += 2) {
|
||||
const left = flagPairs[i].padEnd(28);
|
||||
const right = flagPairs[i + 1] || '';
|
||||
lines.push(` ${left}${right}`);
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
// ─── Buffer (from buffers.ts) ────────────────────────────────────
|
||||
import { consoleBuffer, networkBuffer, dialogBuffer, addConsoleEntry, addNetworkEntry, addDialogEntry, type LogEntry, type NetworkEntry, type DialogEntry } from './buffers';
|
||||
export { consoleBuffer, networkBuffer, dialogBuffer, addConsoleEntry, addNetworkEntry, addDialogEntry, type LogEntry, type NetworkEntry, type DialogEntry };
|
||||
|
||||
const CONSOLE_LOG_PATH = config.consoleLog;
|
||||
const NETWORK_LOG_PATH = config.networkLog;
|
||||
const DIALOG_LOG_PATH = config.dialogLog;
|
||||
let lastConsoleFlushed = 0;
|
||||
let lastNetworkFlushed = 0;
|
||||
let lastDialogFlushed = 0;
|
||||
let flushInProgress = false;
|
||||
|
||||
async function flushBuffers() {
|
||||
if (flushInProgress) return; // Guard against concurrent flush
|
||||
flushInProgress = true;
|
||||
|
||||
try {
|
||||
// Console buffer
|
||||
const newConsoleCount = consoleBuffer.totalAdded - lastConsoleFlushed;
|
||||
if (newConsoleCount > 0) {
|
||||
const entries = consoleBuffer.last(Math.min(newConsoleCount, consoleBuffer.length));
|
||||
const lines = entries.map(e =>
|
||||
`[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
|
||||
).join('\n') + '\n';
|
||||
fs.appendFileSync(CONSOLE_LOG_PATH, lines);
|
||||
lastConsoleFlushed = consoleBuffer.totalAdded;
|
||||
}
|
||||
|
||||
// Network buffer
|
||||
const newNetworkCount = networkBuffer.totalAdded - lastNetworkFlushed;
|
||||
if (newNetworkCount > 0) {
|
||||
const entries = networkBuffer.last(Math.min(newNetworkCount, networkBuffer.length));
|
||||
const lines = entries.map(e =>
|
||||
`[${new Date(e.timestamp).toISOString()}] ${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
|
||||
).join('\n') + '\n';
|
||||
fs.appendFileSync(NETWORK_LOG_PATH, lines);
|
||||
lastNetworkFlushed = networkBuffer.totalAdded;
|
||||
}
|
||||
|
||||
// Dialog buffer
|
||||
const newDialogCount = dialogBuffer.totalAdded - lastDialogFlushed;
|
||||
if (newDialogCount > 0) {
|
||||
const entries = dialogBuffer.last(Math.min(newDialogCount, dialogBuffer.length));
|
||||
const lines = entries.map(e =>
|
||||
`[${new Date(e.timestamp).toISOString()}] [${e.type}] "${e.message}" → ${e.action}${e.response ? ` "${e.response}"` : ''}`
|
||||
).join('\n') + '\n';
|
||||
fs.appendFileSync(DIALOG_LOG_PATH, lines);
|
||||
lastDialogFlushed = dialogBuffer.totalAdded;
|
||||
}
|
||||
} catch {
|
||||
// Flush failures are non-fatal — buffers are in memory
|
||||
} finally {
|
||||
flushInProgress = false;
|
||||
}
|
||||
}
|
||||
|
||||
// Flush every 1 second
|
||||
const flushInterval = setInterval(flushBuffers, 1000);
|
||||
|
||||
// ─── Idle Timer ────────────────────────────────────────────────
|
||||
let lastActivity = Date.now();
|
||||
|
||||
function resetIdleTimer() {
|
||||
lastActivity = Date.now();
|
||||
}
|
||||
|
||||
const idleCheckInterval = setInterval(() => {
|
||||
if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) {
|
||||
console.log(`[browse] Idle for ${IDLE_TIMEOUT_MS / 1000}s, shutting down`);
|
||||
shutdown();
|
||||
}
|
||||
}, 60_000);
|
||||
|
||||
// ─── Command Sets (from commands.ts — single source of truth) ───
|
||||
import { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS } from './commands';
|
||||
export { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS };
|
||||
|
||||
// ─── Server ────────────────────────────────────────────────────
|
||||
const browserManager = new BrowserManager();
|
||||
let isShuttingDown = false;
|
||||
|
||||
// Find port: explicit BROWSE_PORT, or random in 10000-60000
|
||||
async function findPort(): Promise<number> {
|
||||
// Explicit port override (for debugging)
|
||||
if (BROWSE_PORT) {
|
||||
try {
|
||||
const testServer = Bun.serve({ port: BROWSE_PORT, fetch: () => new Response('ok') });
|
||||
testServer.stop();
|
||||
return BROWSE_PORT;
|
||||
} catch {
|
||||
throw new Error(`[browse] Port ${BROWSE_PORT} (from BROWSE_PORT env) is in use`);
|
||||
}
|
||||
}
|
||||
|
||||
// Random port with retry
|
||||
const MIN_PORT = 10000;
|
||||
const MAX_PORT = 60000;
|
||||
const MAX_RETRIES = 5;
|
||||
for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
|
||||
const port = MIN_PORT + Math.floor(Math.random() * (MAX_PORT - MIN_PORT));
|
||||
try {
|
||||
const testServer = Bun.serve({ port, fetch: () => new Response('ok') });
|
||||
testServer.stop();
|
||||
return port;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
throw new Error(`[browse] No available port after ${MAX_RETRIES} attempts in range ${MIN_PORT}-${MAX_PORT}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Translate Playwright errors into actionable messages for AI agents.
|
||||
*/
|
||||
function wrapError(err: any): string {
|
||||
const msg = err.message || String(err);
|
||||
// Timeout errors
|
||||
if (err.name === 'TimeoutError' || msg.includes('Timeout') || msg.includes('timeout')) {
|
||||
if (msg.includes('locator.click') || msg.includes('locator.fill') || msg.includes('locator.hover')) {
|
||||
return `Element not found or not interactable within timeout. Check your selector or run 'snapshot' for fresh refs.`;
|
||||
}
|
||||
if (msg.includes('page.goto') || msg.includes('Navigation')) {
|
||||
return `Page navigation timed out. The URL may be unreachable or the page may be loading slowly.`;
|
||||
}
|
||||
return `Operation timed out: ${msg.split('\n')[0]}`;
|
||||
}
|
||||
// Multiple elements matched
|
||||
if (msg.includes('resolved to') && msg.includes('elements')) {
|
||||
return `Selector matched multiple elements. Be more specific or use @refs from 'snapshot'.`;
|
||||
}
|
||||
// Pass through other errors
|
||||
return msg;
|
||||
}
|
||||
|
||||
async function handleCommand(body: any): Promise<Response> {
|
||||
const { command, args = [] } = body;
|
||||
|
||||
if (!command) {
|
||||
return new Response(JSON.stringify({ error: 'Missing "command" field' }), {
|
||||
status: 400,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
}
|
||||
|
||||
try {
|
||||
let result: string;
|
||||
|
||||
if (READ_COMMANDS.has(command)) {
|
||||
result = await handleReadCommand(command, args, browserManager);
|
||||
} else if (WRITE_COMMANDS.has(command)) {
|
||||
result = await handleWriteCommand(command, args, browserManager);
|
||||
} else if (META_COMMANDS.has(command)) {
|
||||
result = await handleMetaCommand(command, args, browserManager, shutdown);
|
||||
} else if (command === 'help') {
|
||||
const helpText = generateHelpText();
|
||||
return new Response(helpText, {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'text/plain' },
|
||||
});
|
||||
} else {
|
||||
return new Response(JSON.stringify({
|
||||
error: `Unknown command: ${command}`,
|
||||
hint: `Available commands: ${[...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS].sort().join(', ')}`,
|
||||
}), {
|
||||
status: 400,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
}
|
||||
|
||||
browserManager.resetFailures();
|
||||
return new Response(result, {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'text/plain' },
|
||||
});
|
||||
} catch (err: any) {
|
||||
browserManager.incrementFailures();
|
||||
let errorMsg = wrapError(err);
|
||||
const hint = browserManager.getFailureHint();
|
||||
if (hint) errorMsg += '\n' + hint;
|
||||
return new Response(JSON.stringify({ error: errorMsg }), {
|
||||
status: 500,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function shutdown() {
|
||||
if (isShuttingDown) return;
|
||||
isShuttingDown = true;
|
||||
|
||||
console.log('[browse] Shutting down...');
|
||||
clearInterval(flushInterval);
|
||||
clearInterval(idleCheckInterval);
|
||||
await flushBuffers(); // Final flush (async now)
|
||||
|
||||
await browserManager.close();
|
||||
|
||||
// Clean up state file
|
||||
try { fs.unlinkSync(config.stateFile); } catch {}
|
||||
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Handle signals
|
||||
process.on('SIGTERM', shutdown);
|
||||
process.on('SIGINT', shutdown);
|
||||
|
||||
// ─── Start ─────────────────────────────────────────────────────
|
||||
async function start() {
|
||||
// Clear old log files
|
||||
try { fs.unlinkSync(CONSOLE_LOG_PATH); } catch {}
|
||||
try { fs.unlinkSync(NETWORK_LOG_PATH); } catch {}
|
||||
try { fs.unlinkSync(DIALOG_LOG_PATH); } catch {}
|
||||
|
||||
const port = await findPort();
|
||||
|
||||
// Launch browser
|
||||
await browserManager.launch();
|
||||
|
||||
const startTime = Date.now();
|
||||
const server = Bun.serve({
|
||||
port,
|
||||
hostname: '127.0.0.1',
|
||||
fetch: async (req) => {
|
||||
resetIdleTimer();
|
||||
|
||||
const url = new URL(req.url);
|
||||
|
||||
// Cookie picker routes — no auth required (localhost-only)
|
||||
if (url.pathname.startsWith('/cookie-picker')) {
|
||||
return handleCookiePickerRoute(url, req, browserManager);
|
||||
}
|
||||
|
||||
// Health check — no auth required (now async)
|
||||
if (url.pathname === '/health') {
|
||||
const healthy = await browserManager.isHealthy();
|
||||
return new Response(JSON.stringify({
|
||||
status: healthy ? 'healthy' : 'unhealthy',
|
||||
uptime: Math.floor((Date.now() - startTime) / 1000),
|
||||
tabs: browserManager.getTabCount(),
|
||||
currentUrl: browserManager.getCurrentUrl(),
|
||||
}), {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
}
|
||||
|
||||
// All other endpoints require auth
|
||||
if (!validateAuth(req)) {
|
||||
return new Response(JSON.stringify({ error: 'Unauthorized' }), {
|
||||
status: 401,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
});
|
||||
}
|
||||
|
||||
if (url.pathname === '/command' && req.method === 'POST') {
|
||||
const body = await req.json();
|
||||
return handleCommand(body);
|
||||
}
|
||||
|
||||
return new Response('Not found', { status: 404 });
|
||||
},
|
||||
});
|
||||
|
||||
// Write state file (atomic: write .tmp then rename)
|
||||
const state = {
|
||||
pid: process.pid,
|
||||
port,
|
||||
token: AUTH_TOKEN,
|
||||
startedAt: new Date().toISOString(),
|
||||
serverPath: path.resolve(import.meta.dir, 'server.ts'),
|
||||
binaryVersion: readVersionHash() || undefined,
|
||||
};
|
||||
const tmpFile = config.stateFile + '.tmp';
|
||||
fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), { mode: 0o600 });
|
||||
fs.renameSync(tmpFile, config.stateFile);
|
||||
|
||||
browserManager.serverPort = port;
|
||||
console.log(`[browse] Server running on http://127.0.0.1:${port} (PID: ${process.pid})`);
|
||||
console.log(`[browse] State file: ${config.stateFile}`);
|
||||
console.log(`[browse] Idle timeout: ${IDLE_TIMEOUT_MS / 1000}s`);
|
||||
}
|
||||
|
||||
start().catch((err) => {
|
||||
console.error(`[browse] Failed to start: ${err.message}`);
|
||||
process.exit(1);
|
||||
});
|
||||
|
|
@ -0,0 +1,398 @@
|
|||
/**
|
||||
* Snapshot command — accessibility tree with ref-based element selection
|
||||
*
|
||||
* Architecture (Locator map — no DOM mutation):
|
||||
* 1. page.locator(scope).ariaSnapshot() → YAML-like accessibility tree
|
||||
* 2. Parse tree, assign refs @e1, @e2, ...
|
||||
* 3. Build Playwright Locator for each ref (getByRole + nth)
|
||||
* 4. Store Map<string, Locator> on BrowserManager
|
||||
* 5. Return compact text output with refs prepended
|
||||
*
|
||||
* Extended features:
|
||||
* --diff / -D: Compare against last snapshot, return unified diff
|
||||
* --annotate / -a: Screenshot with overlay boxes at each @ref
|
||||
* --output / -o: Output path for annotated screenshot
|
||||
* -C / --cursor-interactive: Scan for cursor:pointer/onclick/tabindex elements
|
||||
*
|
||||
* Later: "click @e3" → look up Locator → locator.click()
|
||||
*/
|
||||
|
||||
import type { Page, Locator } from 'playwright';
|
||||
import type { BrowserManager, RefEntry } from './browser-manager';
|
||||
import * as Diff from 'diff';
|
||||
import { TEMP_DIR, isPathWithin } from './platform';
|
||||
|
||||
// Roles considered "interactive" for the -i flag
|
||||
const INTERACTIVE_ROLES = new Set([
|
||||
'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
|
||||
'listbox', 'menuitem', 'menuitemcheckbox', 'menuitemradio',
|
||||
'option', 'searchbox', 'slider', 'spinbutton', 'switch', 'tab',
|
||||
'treeitem',
|
||||
]);
|
||||
|
||||
interface SnapshotOptions {
|
||||
interactive?: boolean; // -i: only interactive elements
|
||||
compact?: boolean; // -c: remove empty structural elements
|
||||
depth?: number; // -d N: limit tree depth
|
||||
selector?: string; // -s SEL: scope to CSS selector
|
||||
diff?: boolean; // -D / --diff: diff against last snapshot
|
||||
annotate?: boolean; // -a / --annotate: annotated screenshot
|
||||
outputPath?: string; // -o / --output: path for annotated screenshot
|
||||
cursorInteractive?: boolean; // -C / --cursor-interactive: scan cursor:pointer etc.
|
||||
}
|
||||
|
||||
/**
|
||||
* Snapshot flag metadata — single source of truth for CLI parsing and doc generation.
|
||||
*
|
||||
* Imported by:
|
||||
* - gen-skill-docs.ts (generates {{SNAPSHOT_FLAGS}} tables)
|
||||
* - skill-parser.ts (validates flags in SKILL.md examples)
|
||||
*/
|
||||
export const SNAPSHOT_FLAGS: Array<{
|
||||
short: string;
|
||||
long: string;
|
||||
description: string;
|
||||
takesValue?: boolean;
|
||||
valueHint?: string;
|
||||
optionKey: keyof SnapshotOptions;
|
||||
}> = [
|
||||
{ short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs', optionKey: 'interactive' },
|
||||
{ short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' },
|
||||
{ short: '-d', long: '--depth', description: 'Limit tree depth (0 = root only, default: unlimited)', takesValue: true, valueHint: '<N>', optionKey: 'depth' },
|
||||
{ short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '<sel>', optionKey: 'selector' },
|
||||
{ short: '-D', long: '--diff', description: 'Unified diff against previous snapshot (first call stores baseline)', optionKey: 'diff' },
|
||||
{ short: '-a', long: '--annotate', description: 'Annotated screenshot with red overlay boxes and ref labels', optionKey: 'annotate' },
|
||||
{ short: '-o', long: '--output', description: 'Output path for annotated screenshot (default: <temp>/browse-annotated.png)', takesValue: true, valueHint: '<path>', optionKey: 'outputPath' },
|
||||
{ short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick)', optionKey: 'cursorInteractive' },
|
||||
];
|
||||
|
||||
interface ParsedNode {
|
||||
indent: number;
|
||||
role: string;
|
||||
name: string | null;
|
||||
props: string; // e.g., "[level=1]"
|
||||
children: string; // inline text content after ":"
|
||||
rawLine: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse CLI args into SnapshotOptions — driven by SNAPSHOT_FLAGS metadata.
|
||||
*/
|
||||
export function parseSnapshotArgs(args: string[]): SnapshotOptions {
|
||||
const opts: SnapshotOptions = {};
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
const flag = SNAPSHOT_FLAGS.find(f => f.short === args[i] || f.long === args[i]);
|
||||
if (!flag) throw new Error(`Unknown snapshot flag: ${args[i]}`);
|
||||
if (flag.takesValue) {
|
||||
const value = args[++i];
|
||||
if (!value) throw new Error(`Usage: snapshot ${flag.short} <value>`);
|
||||
if (flag.optionKey === 'depth') {
|
||||
(opts as any)[flag.optionKey] = parseInt(value, 10);
|
||||
if (isNaN(opts.depth!)) throw new Error('Usage: snapshot -d <number>');
|
||||
} else {
|
||||
(opts as any)[flag.optionKey] = value;
|
||||
}
|
||||
} else {
|
||||
(opts as any)[flag.optionKey] = true;
|
||||
}
|
||||
}
|
||||
return opts;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse one line of ariaSnapshot output.
|
||||
*
|
||||
* Format examples:
|
||||
* - heading "Test" [level=1]
|
||||
* - link "Link A":
|
||||
* - /url: /a
|
||||
* - textbox "Name"
|
||||
* - paragraph: Some text
|
||||
* - combobox "Role":
|
||||
*/
|
||||
function parseLine(line: string): ParsedNode | null {
|
||||
// Match: (indent)(- )(role)( "name")?( [props])?(: inline)?
|
||||
const match = line.match(/^(\s*)-\s+(\w+)(?:\s+"([^"]*)")?(?:\s+(\[.*?\]))?\s*(?::\s*(.*))?$/);
|
||||
if (!match) {
|
||||
// Skip metadata lines like "- /url: /a"
|
||||
return null;
|
||||
}
|
||||
return {
|
||||
indent: match[1].length,
|
||||
role: match[2],
|
||||
name: match[3] ?? null,
|
||||
props: match[4] || '',
|
||||
children: match[5]?.trim() || '',
|
||||
rawLine: line,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Take an accessibility snapshot and build the ref map.
|
||||
*/
|
||||
export async function handleSnapshot(
|
||||
args: string[],
|
||||
bm: BrowserManager
|
||||
): Promise<string> {
|
||||
const opts = parseSnapshotArgs(args);
|
||||
const page = bm.getPage();
|
||||
|
||||
// Get accessibility tree via ariaSnapshot
|
||||
let rootLocator: Locator;
|
||||
if (opts.selector) {
|
||||
rootLocator = page.locator(opts.selector);
|
||||
const count = await rootLocator.count();
|
||||
if (count === 0) throw new Error(`Selector not found: ${opts.selector}`);
|
||||
} else {
|
||||
rootLocator = page.locator('body');
|
||||
}
|
||||
|
||||
const ariaText = await rootLocator.ariaSnapshot();
|
||||
if (!ariaText || ariaText.trim().length === 0) {
|
||||
bm.setRefMap(new Map());
|
||||
return '(no accessible elements found)';
|
||||
}
|
||||
|
||||
// Parse the ariaSnapshot output
|
||||
const lines = ariaText.split('\n');
|
||||
const refMap = new Map<string, RefEntry>();
|
||||
const output: string[] = [];
|
||||
let refCounter = 1;
|
||||
|
||||
// Track role+name occurrences for nth() disambiguation
|
||||
const roleNameCounts = new Map<string, number>();
|
||||
const roleNameSeen = new Map<string, number>();
|
||||
|
||||
// First pass: count role+name pairs for disambiguation
|
||||
for (const line of lines) {
|
||||
const node = parseLine(line);
|
||||
if (!node) continue;
|
||||
const key = `${node.role}:${node.name || ''}`;
|
||||
roleNameCounts.set(key, (roleNameCounts.get(key) || 0) + 1);
|
||||
}
|
||||
|
||||
// Second pass: assign refs and build locators
|
||||
for (const line of lines) {
|
||||
const node = parseLine(line);
|
||||
if (!node) continue;
|
||||
|
||||
const depth = Math.floor(node.indent / 2);
|
||||
const isInteractive = INTERACTIVE_ROLES.has(node.role);
|
||||
|
||||
// Depth filter
|
||||
if (opts.depth !== undefined && depth > opts.depth) continue;
|
||||
|
||||
// Interactive filter: skip non-interactive but still count for locator indices
|
||||
if (opts.interactive && !isInteractive) {
|
||||
// Still track for nth() counts
|
||||
const key = `${node.role}:${node.name || ''}`;
|
||||
roleNameSeen.set(key, (roleNameSeen.get(key) || 0) + 1);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Compact filter: skip elements with no name and no inline content that aren't interactive
|
||||
if (opts.compact && !isInteractive && !node.name && !node.children) continue;
|
||||
|
||||
// Assign ref
|
||||
const ref = `e${refCounter++}`;
|
||||
const indent = ' '.repeat(depth);
|
||||
|
||||
// Build Playwright locator
|
||||
const key = `${node.role}:${node.name || ''}`;
|
||||
const seenIndex = roleNameSeen.get(key) || 0;
|
||||
roleNameSeen.set(key, seenIndex + 1);
|
||||
const totalCount = roleNameCounts.get(key) || 1;
|
||||
|
||||
let locator: Locator;
|
||||
if (opts.selector) {
|
||||
locator = page.locator(opts.selector).getByRole(node.role as any, {
|
||||
name: node.name || undefined,
|
||||
});
|
||||
} else {
|
||||
locator = page.getByRole(node.role as any, {
|
||||
name: node.name || undefined,
|
||||
});
|
||||
}
|
||||
|
||||
// Disambiguate with nth() if multiple elements share role+name
|
||||
if (totalCount > 1) {
|
||||
locator = locator.nth(seenIndex);
|
||||
}
|
||||
|
||||
refMap.set(ref, { locator, role: node.role, name: node.name || '' });
|
||||
|
||||
// Format output line
|
||||
let outputLine = `${indent}@${ref} [${node.role}]`;
|
||||
if (node.name) outputLine += ` "${node.name}"`;
|
||||
if (node.props) outputLine += ` ${node.props}`;
|
||||
if (node.children) outputLine += `: ${node.children}`;
|
||||
|
||||
output.push(outputLine);
|
||||
}
|
||||
|
||||
// ─── Cursor-interactive scan (-C) ─────────────────────────
|
||||
if (opts.cursorInteractive) {
|
||||
try {
|
||||
const cursorElements = await page.evaluate(() => {
|
||||
const STANDARD_INTERACTIVE = new Set([
|
||||
'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY', 'DETAILS',
|
||||
]);
|
||||
|
||||
const results: Array<{ selector: string; text: string; reason: string }> = [];
|
||||
const allElements = document.querySelectorAll('*');
|
||||
|
||||
for (const el of allElements) {
|
||||
// Skip standard interactive elements (already in ARIA tree)
|
||||
if (STANDARD_INTERACTIVE.has(el.tagName)) continue;
|
||||
// Skip hidden elements
|
||||
if (!(el as HTMLElement).offsetParent && el.tagName !== 'BODY') continue;
|
||||
|
||||
const style = getComputedStyle(el);
|
||||
const hasCursorPointer = style.cursor === 'pointer';
|
||||
const hasOnclick = el.hasAttribute('onclick');
|
||||
const hasTabindex = el.hasAttribute('tabindex') && parseInt(el.getAttribute('tabindex')!, 10) >= 0;
|
||||
const hasRole = el.hasAttribute('role');
|
||||
|
||||
if (!hasCursorPointer && !hasOnclick && !hasTabindex) continue;
|
||||
// Skip if it has an ARIA role (likely already captured)
|
||||
if (hasRole) continue;
|
||||
|
||||
// Build deterministic nth-child CSS path
|
||||
const parts: string[] = [];
|
||||
let current: Element | null = el;
|
||||
while (current && current !== document.documentElement) {
|
||||
const parent = current.parentElement;
|
||||
if (!parent) break;
|
||||
const siblings = [...parent.children];
|
||||
const index = siblings.indexOf(current) + 1;
|
||||
parts.unshift(`${current.tagName.toLowerCase()}:nth-child(${index})`);
|
||||
current = parent;
|
||||
}
|
||||
const selector = parts.join(' > ');
|
||||
|
||||
const text = (el as HTMLElement).innerText?.trim().slice(0, 80) || el.tagName.toLowerCase();
|
||||
const reasons: string[] = [];
|
||||
if (hasCursorPointer) reasons.push('cursor:pointer');
|
||||
if (hasOnclick) reasons.push('onclick');
|
||||
if (hasTabindex) reasons.push(`tabindex=${el.getAttribute('tabindex')}`);
|
||||
|
||||
results.push({ selector, text, reason: reasons.join(', ') });
|
||||
}
|
||||
return results;
|
||||
});
|
||||
|
||||
if (cursorElements.length > 0) {
|
||||
output.push('');
|
||||
output.push('── cursor-interactive (not in ARIA tree) ──');
|
||||
let cRefCounter = 1;
|
||||
for (const elem of cursorElements) {
|
||||
const ref = `c${cRefCounter++}`;
|
||||
const locator = page.locator(elem.selector);
|
||||
refMap.set(ref, { locator, role: 'cursor-interactive', name: elem.text });
|
||||
output.push(`@${ref} [${elem.reason}] "${elem.text}"`);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
output.push('');
|
||||
output.push('(cursor scan failed — CSP restriction)');
|
||||
}
|
||||
}
|
||||
|
||||
// Store ref map on BrowserManager
|
||||
bm.setRefMap(refMap);
|
||||
|
||||
if (output.length === 0) {
|
||||
return '(no interactive elements found)';
|
||||
}
|
||||
|
||||
const snapshotText = output.join('\n');
|
||||
|
||||
// ─── Annotated screenshot (-a) ────────────────────────────
|
||||
if (opts.annotate) {
|
||||
const screenshotPath = opts.outputPath || `${TEMP_DIR}/browse-annotated.png`;
|
||||
// Validate output path (consistent with screenshot/pdf/responsive)
|
||||
const resolvedPath = require('path').resolve(screenshotPath);
|
||||
const safeDirs = [TEMP_DIR, process.cwd()];
|
||||
if (!safeDirs.some((dir: string) => isPathWithin(resolvedPath, dir))) {
|
||||
throw new Error(`Path must be within: ${safeDirs.join(', ')}`);
|
||||
}
|
||||
try {
|
||||
// Inject overlay divs at each ref's bounding box
|
||||
const boxes: Array<{ ref: string; box: { x: number; y: number; width: number; height: number } }> = [];
|
||||
for (const [ref, entry] of refMap) {
|
||||
try {
|
||||
const box = await entry.locator.boundingBox({ timeout: 1000 });
|
||||
if (box) {
|
||||
boxes.push({ ref: `@${ref}`, box });
|
||||
}
|
||||
} catch {
|
||||
// Element may be offscreen or hidden — skip
|
||||
}
|
||||
}
|
||||
|
||||
await page.evaluate((boxes) => {
|
||||
for (const { ref, box } of boxes) {
|
||||
const overlay = document.createElement('div');
|
||||
overlay.className = '__browse_annotation__';
|
||||
overlay.style.cssText = `
|
||||
position: absolute; top: ${box.y}px; left: ${box.x}px;
|
||||
width: ${box.width}px; height: ${box.height}px;
|
||||
border: 2px solid red; background: rgba(255,0,0,0.1);
|
||||
pointer-events: none; z-index: 99999;
|
||||
font-size: 10px; color: red; font-weight: bold;
|
||||
`;
|
||||
const label = document.createElement('span');
|
||||
label.textContent = ref;
|
||||
label.style.cssText = 'position: absolute; top: -14px; left: 0; background: red; color: white; padding: 0 3px; font-size: 10px;';
|
||||
overlay.appendChild(label);
|
||||
document.body.appendChild(overlay);
|
||||
}
|
||||
}, boxes);
|
||||
|
||||
await page.screenshot({ path: screenshotPath, fullPage: true });
|
||||
|
||||
// Always remove overlays
|
||||
await page.evaluate(() => {
|
||||
document.querySelectorAll('.__browse_annotation__').forEach(el => el.remove());
|
||||
});
|
||||
|
||||
output.push('');
|
||||
output.push(`[annotated screenshot: ${screenshotPath}]`);
|
||||
} catch {
|
||||
// Remove overlays even on screenshot failure
|
||||
try {
|
||||
await page.evaluate(() => {
|
||||
document.querySelectorAll('.__browse_annotation__').forEach(el => el.remove());
|
||||
});
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Diff mode (-D) ───────────────────────────────────────
|
||||
if (opts.diff) {
|
||||
const lastSnapshot = bm.getLastSnapshot();
|
||||
if (!lastSnapshot) {
|
||||
bm.setLastSnapshot(snapshotText);
|
||||
return snapshotText + '\n\n(no previous snapshot to diff against — this snapshot stored as baseline)';
|
||||
}
|
||||
|
||||
const changes = Diff.diffLines(lastSnapshot, snapshotText);
|
||||
const diffOutput: string[] = ['--- previous snapshot', '+++ current snapshot', ''];
|
||||
|
||||
for (const part of changes) {
|
||||
const prefix = part.added ? '+' : part.removed ? '-' : ' ';
|
||||
const diffLines = part.value.split('\n').filter(l => l.length > 0);
|
||||
for (const line of diffLines) {
|
||||
diffOutput.push(`${prefix} ${line}`);
|
||||
}
|
||||
}
|
||||
|
||||
bm.setLastSnapshot(snapshotText);
|
||||
return diffOutput.join('\n');
|
||||
}
|
||||
|
||||
// Store for future diffs
|
||||
bm.setLastSnapshot(snapshotText);
|
||||
|
||||
return output.join('\n');
|
||||
}
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
/**
|
||||
* URL validation for navigation commands — blocks dangerous schemes and cloud metadata endpoints.
|
||||
* Localhost and private IPs are allowed (primary use case: QA testing local dev servers).
|
||||
*/
|
||||
|
||||
const BLOCKED_METADATA_HOSTS = new Set([
|
||||
'169.254.169.254', // AWS/GCP/Azure instance metadata
|
||||
'fd00::', // IPv6 unique local (metadata in some cloud setups)
|
||||
'metadata.google.internal', // GCP metadata
|
||||
'metadata.azure.internal', // Azure IMDS
|
||||
]);
|
||||
|
||||
/**
|
||||
* Normalize hostname for blocklist comparison:
|
||||
* - Strip trailing dot (DNS fully-qualified notation)
|
||||
* - Strip IPv6 brackets (URL.hostname includes [] for IPv6)
|
||||
* - Resolve hex (0xA9FEA9FE) and decimal (2852039166) IP representations
|
||||
*/
|
||||
function normalizeHostname(hostname: string): string {
|
||||
// Strip IPv6 brackets
|
||||
let h = hostname.startsWith('[') && hostname.endsWith(']')
|
||||
? hostname.slice(1, -1)
|
||||
: hostname;
|
||||
// Strip trailing dot
|
||||
if (h.endsWith('.')) h = h.slice(0, -1);
|
||||
return h;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a hostname resolves to the link-local metadata IP 169.254.169.254.
|
||||
* Catches hex (0xA9FEA9FE), decimal (2852039166), and octal (0251.0376.0251.0376) forms.
|
||||
*/
|
||||
function isMetadataIp(hostname: string): boolean {
|
||||
// Try to parse as a numeric IP via URL constructor — it normalizes all forms
|
||||
try {
|
||||
const probe = new URL(`http://${hostname}`);
|
||||
const normalized = probe.hostname;
|
||||
if (BLOCKED_METADATA_HOSTS.has(normalized)) return true;
|
||||
// Also check after stripping trailing dot
|
||||
if (normalized.endsWith('.') && BLOCKED_METADATA_HOSTS.has(normalized.slice(0, -1))) return true;
|
||||
} catch {
|
||||
// Not a valid hostname — can't be a metadata IP
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a hostname to its IP addresses and check if any resolve to blocked metadata IPs.
|
||||
* Mitigates DNS rebinding: even if the hostname looks safe, the resolved IP might not be.
|
||||
*/
|
||||
async function resolvesToBlockedIp(hostname: string): Promise<boolean> {
|
||||
try {
|
||||
const dns = await import('node:dns');
|
||||
const { resolve4 } = dns.promises;
|
||||
const addresses = await resolve4(hostname);
|
||||
return addresses.some(addr => BLOCKED_METADATA_HOSTS.has(addr));
|
||||
} catch {
|
||||
// DNS resolution failed — not a rebinding risk
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export async function validateNavigationUrl(url: string): Promise<void> {
|
||||
let parsed: URL;
|
||||
try {
|
||||
parsed = new URL(url);
|
||||
} catch {
|
||||
throw new Error(`Invalid URL: ${url}`);
|
||||
}
|
||||
|
||||
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
|
||||
throw new Error(
|
||||
`Blocked: scheme "${parsed.protocol}" is not allowed. Only http: and https: URLs are permitted.`
|
||||
);
|
||||
}
|
||||
|
||||
const hostname = normalizeHostname(parsed.hostname.toLowerCase());
|
||||
|
||||
if (BLOCKED_METADATA_HOSTS.has(hostname) || isMetadataIp(hostname)) {
|
||||
throw new Error(
|
||||
`Blocked: ${parsed.hostname} is a cloud metadata endpoint. Access is denied for security.`
|
||||
);
|
||||
}
|
||||
|
||||
// DNS rebinding protection: resolve hostname and check if it points to metadata IPs
|
||||
if (await resolvesToBlockedIp(hostname)) {
|
||||
throw new Error(
|
||||
`Blocked: ${parsed.hostname} resolves to a cloud metadata IP. Possible DNS rebinding attack.`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,352 @@
|
|||
/**
|
||||
* Write commands — navigate and interact with pages (side effects)
|
||||
*
|
||||
* goto, back, forward, reload, click, fill, select, hover, type,
|
||||
* press, scroll, wait, viewport, cookie, header, useragent
|
||||
*/
|
||||
|
||||
import type { BrowserManager } from './browser-manager';
|
||||
import { findInstalledBrowsers, importCookies } from './cookie-import-browser';
|
||||
import { validateNavigationUrl } from './url-validation';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { TEMP_DIR, isPathWithin } from './platform';
|
||||
|
||||
export async function handleWriteCommand(
|
||||
command: string,
|
||||
args: string[],
|
||||
bm: BrowserManager
|
||||
): Promise<string> {
|
||||
const page = bm.getPage();
|
||||
|
||||
switch (command) {
|
||||
case 'goto': {
|
||||
const url = args[0];
|
||||
if (!url) throw new Error('Usage: browse goto <url>');
|
||||
await validateNavigationUrl(url);
|
||||
const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
const status = response?.status() || 'unknown';
|
||||
return `Navigated to ${url} (${status})`;
|
||||
}
|
||||
|
||||
case 'back': {
|
||||
await page.goBack({ waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
return `Back → ${page.url()}`;
|
||||
}
|
||||
|
||||
case 'forward': {
|
||||
await page.goForward({ waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
return `Forward → ${page.url()}`;
|
||||
}
|
||||
|
||||
case 'reload': {
|
||||
await page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 });
|
||||
return `Reloaded ${page.url()}`;
|
||||
}
|
||||
|
||||
case 'click': {
|
||||
const selector = args[0];
|
||||
if (!selector) throw new Error('Usage: browse click <selector>');
|
||||
|
||||
// Auto-route: if ref points to a real <option> inside a <select>, use selectOption
|
||||
const role = bm.getRefRole(selector);
|
||||
if (role === 'option') {
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
const optionInfo = await resolved.locator.evaluate(el => {
|
||||
if (el.tagName !== 'OPTION') return null; // custom [role=option], not real <option>
|
||||
const option = el as HTMLOptionElement;
|
||||
const select = option.closest('select');
|
||||
if (!select) return null;
|
||||
return { value: option.value, text: option.text };
|
||||
});
|
||||
if (optionInfo) {
|
||||
await resolved.locator.locator('xpath=ancestor::select').selectOption(optionInfo.value, { timeout: 5000 });
|
||||
return `Selected "${optionInfo.text}" (auto-routed from click on <option>) → now at ${page.url()}`;
|
||||
}
|
||||
// Real <option> with no parent <select> or custom [role=option] — fall through to normal click
|
||||
}
|
||||
}
|
||||
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
try {
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.click({ timeout: 5000 });
|
||||
} else {
|
||||
await page.click(resolved.selector, { timeout: 5000 });
|
||||
}
|
||||
} catch (err: any) {
|
||||
// Enhanced error guidance: clicking <option> elements always fails (not visible / timeout)
|
||||
const isOption = 'locator' in resolved
|
||||
? await resolved.locator.evaluate(el => el.tagName === 'OPTION').catch(() => false)
|
||||
: await page.evaluate(
|
||||
(sel: string) => document.querySelector(sel)?.tagName === 'OPTION',
|
||||
(resolved as { selector: string }).selector
|
||||
).catch(() => false);
|
||||
if (isOption) {
|
||||
throw new Error(
|
||||
`Cannot click <option> elements. Use 'browse select <parent-select> <value>' instead of 'click' for dropdown options.`
|
||||
);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
// Wait briefly for any navigation/DOM update
|
||||
await page.waitForLoadState('domcontentloaded').catch(() => {});
|
||||
return `Clicked ${selector} → now at ${page.url()}`;
|
||||
}
|
||||
|
||||
case 'fill': {
|
||||
const [selector, ...valueParts] = args;
|
||||
const value = valueParts.join(' ');
|
||||
if (!selector || !value) throw new Error('Usage: browse fill <selector> <value>');
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.fill(value, { timeout: 5000 });
|
||||
} else {
|
||||
await page.fill(resolved.selector, value, { timeout: 5000 });
|
||||
}
|
||||
return `Filled ${selector}`;
|
||||
}
|
||||
|
||||
case 'select': {
|
||||
const [selector, ...valueParts] = args;
|
||||
const value = valueParts.join(' ');
|
||||
if (!selector || !value) throw new Error('Usage: browse select <selector> <value>');
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.selectOption(value, { timeout: 5000 });
|
||||
} else {
|
||||
await page.selectOption(resolved.selector, value, { timeout: 5000 });
|
||||
}
|
||||
return `Selected "${value}" in ${selector}`;
|
||||
}
|
||||
|
||||
case 'hover': {
|
||||
const selector = args[0];
|
||||
if (!selector) throw new Error('Usage: browse hover <selector>');
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.hover({ timeout: 5000 });
|
||||
} else {
|
||||
await page.hover(resolved.selector, { timeout: 5000 });
|
||||
}
|
||||
return `Hovered ${selector}`;
|
||||
}
|
||||
|
||||
case 'type': {
|
||||
const text = args.join(' ');
|
||||
if (!text) throw new Error('Usage: browse type <text>');
|
||||
await page.keyboard.type(text);
|
||||
return `Typed ${text.length} characters`;
|
||||
}
|
||||
|
||||
case 'press': {
|
||||
const key = args[0];
|
||||
if (!key) throw new Error('Usage: browse press <key> (e.g., Enter, Tab, Escape)');
|
||||
await page.keyboard.press(key);
|
||||
return `Pressed ${key}`;
|
||||
}
|
||||
|
||||
case 'scroll': {
|
||||
const selector = args[0];
|
||||
if (selector) {
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.scrollIntoViewIfNeeded({ timeout: 5000 });
|
||||
} else {
|
||||
await page.locator(resolved.selector).scrollIntoViewIfNeeded({ timeout: 5000 });
|
||||
}
|
||||
return `Scrolled ${selector} into view`;
|
||||
}
|
||||
await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
|
||||
return 'Scrolled to bottom';
|
||||
}
|
||||
|
||||
case 'wait': {
|
||||
const selector = args[0];
|
||||
if (!selector) throw new Error('Usage: browse wait <selector|--networkidle|--load|--domcontentloaded>');
|
||||
if (selector === '--networkidle') {
|
||||
const timeout = args[1] ? parseInt(args[1], 10) : 15000;
|
||||
await page.waitForLoadState('networkidle', { timeout });
|
||||
return 'Network idle';
|
||||
}
|
||||
if (selector === '--load') {
|
||||
await page.waitForLoadState('load');
|
||||
return 'Page loaded';
|
||||
}
|
||||
if (selector === '--domcontentloaded') {
|
||||
await page.waitForLoadState('domcontentloaded');
|
||||
return 'DOM content loaded';
|
||||
}
|
||||
const timeout = args[1] ? parseInt(args[1], 10) : 15000;
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.waitFor({ state: 'visible', timeout });
|
||||
} else {
|
||||
await page.waitForSelector(resolved.selector, { timeout });
|
||||
}
|
||||
return `Element ${selector} appeared`;
|
||||
}
|
||||
|
||||
case 'viewport': {
|
||||
const size = args[0];
|
||||
if (!size || !size.includes('x')) throw new Error('Usage: browse viewport <WxH> (e.g., 375x812)');
|
||||
const [w, h] = size.split('x').map(Number);
|
||||
await bm.setViewport(w, h);
|
||||
return `Viewport set to ${w}x${h}`;
|
||||
}
|
||||
|
||||
case 'cookie': {
|
||||
const cookieStr = args[0];
|
||||
if (!cookieStr || !cookieStr.includes('=')) throw new Error('Usage: browse cookie <name>=<value>');
|
||||
const eq = cookieStr.indexOf('=');
|
||||
const name = cookieStr.slice(0, eq);
|
||||
const value = cookieStr.slice(eq + 1);
|
||||
const url = new URL(page.url());
|
||||
await page.context().addCookies([{
|
||||
name,
|
||||
value,
|
||||
domain: url.hostname,
|
||||
path: '/',
|
||||
}]);
|
||||
return `Cookie set: ${name}=****`;
|
||||
}
|
||||
|
||||
case 'header': {
|
||||
const headerStr = args[0];
|
||||
if (!headerStr || !headerStr.includes(':')) throw new Error('Usage: browse header <name>:<value>');
|
||||
const sep = headerStr.indexOf(':');
|
||||
const name = headerStr.slice(0, sep).trim();
|
||||
const value = headerStr.slice(sep + 1).trim();
|
||||
await bm.setExtraHeader(name, value);
|
||||
const sensitiveHeaders = ['authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token'];
|
||||
const redactedValue = sensitiveHeaders.includes(name.toLowerCase()) ? '****' : value;
|
||||
return `Header set: ${name}: ${redactedValue}`;
|
||||
}
|
||||
|
||||
case 'useragent': {
|
||||
const ua = args.join(' ');
|
||||
if (!ua) throw new Error('Usage: browse useragent <string>');
|
||||
bm.setUserAgent(ua);
|
||||
const error = await bm.recreateContext();
|
||||
if (error) {
|
||||
return `User agent set to "${ua}" but: ${error}`;
|
||||
}
|
||||
return `User agent set: ${ua}`;
|
||||
}
|
||||
|
||||
case 'upload': {
|
||||
const [selector, ...filePaths] = args;
|
||||
if (!selector || filePaths.length === 0) throw new Error('Usage: browse upload <selector> <file1> [file2...]');
|
||||
|
||||
// Validate all files exist before upload
|
||||
for (const fp of filePaths) {
|
||||
if (!fs.existsSync(fp)) throw new Error(`File not found: ${fp}`);
|
||||
}
|
||||
|
||||
const resolved = await bm.resolveRef(selector);
|
||||
if ('locator' in resolved) {
|
||||
await resolved.locator.setInputFiles(filePaths);
|
||||
} else {
|
||||
await page.locator(resolved.selector).setInputFiles(filePaths);
|
||||
}
|
||||
|
||||
const fileInfo = filePaths.map(fp => {
|
||||
const stat = fs.statSync(fp);
|
||||
return `${path.basename(fp)} (${stat.size}B)`;
|
||||
}).join(', ');
|
||||
return `Uploaded: ${fileInfo}`;
|
||||
}
|
||||
|
||||
case 'dialog-accept': {
|
||||
const text = args.length > 0 ? args.join(' ') : null;
|
||||
bm.setDialogAutoAccept(true);
|
||||
bm.setDialogPromptText(text);
|
||||
return text
|
||||
? `Dialogs will be accepted with text: "${text}"`
|
||||
: 'Dialogs will be accepted';
|
||||
}
|
||||
|
||||
case 'dialog-dismiss': {
|
||||
bm.setDialogAutoAccept(false);
|
||||
bm.setDialogPromptText(null);
|
||||
return 'Dialogs will be dismissed';
|
||||
}
|
||||
|
||||
case 'cookie-import': {
|
||||
const filePath = args[0];
|
||||
if (!filePath) throw new Error('Usage: browse cookie-import <json-file>');
|
||||
// Path validation — prevent reading arbitrary files
|
||||
if (path.isAbsolute(filePath)) {
|
||||
const safeDirs = [TEMP_DIR, process.cwd()];
|
||||
const resolved = path.resolve(filePath);
|
||||
if (!safeDirs.some(dir => isPathWithin(resolved, dir))) {
|
||||
throw new Error(`Path must be within: ${safeDirs.join(', ')}`);
|
||||
}
|
||||
}
|
||||
if (path.normalize(filePath).includes('..')) {
|
||||
throw new Error('Path traversal sequences (..) are not allowed');
|
||||
}
|
||||
if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
|
||||
const raw = fs.readFileSync(filePath, 'utf-8');
|
||||
let cookies: any[];
|
||||
try { cookies = JSON.parse(raw); } catch { throw new Error(`Invalid JSON in ${filePath}`); }
|
||||
if (!Array.isArray(cookies)) throw new Error('Cookie file must contain a JSON array');
|
||||
|
||||
// Auto-fill domain from current page URL when missing (consistent with cookie command)
|
||||
const pageUrl = new URL(page.url());
|
||||
const defaultDomain = pageUrl.hostname;
|
||||
|
||||
for (const c of cookies) {
|
||||
if (!c.name || c.value === undefined) throw new Error('Each cookie must have "name" and "value" fields');
|
||||
if (!c.domain) c.domain = defaultDomain;
|
||||
if (!c.path) c.path = '/';
|
||||
}
|
||||
|
||||
await page.context().addCookies(cookies);
|
||||
return `Loaded ${cookies.length} cookies from ${filePath}`;
|
||||
}
|
||||
|
||||
case 'cookie-import-browser': {
|
||||
// Two modes:
|
||||
// 1. Direct CLI import: cookie-import-browser <browser> --domain <domain>
|
||||
// 2. Open picker UI: cookie-import-browser [browser]
|
||||
const browserArg = args[0];
|
||||
const domainIdx = args.indexOf('--domain');
|
||||
|
||||
if (domainIdx !== -1 && domainIdx + 1 < args.length) {
|
||||
// Direct import mode — no UI
|
||||
const domain = args[domainIdx + 1];
|
||||
const browser = browserArg || 'comet';
|
||||
const result = await importCookies(browser, [domain]);
|
||||
if (result.cookies.length > 0) {
|
||||
await page.context().addCookies(result.cookies);
|
||||
}
|
||||
const msg = [`Imported ${result.count} cookies for ${domain} from ${browser}`];
|
||||
if (result.failed > 0) msg.push(`(${result.failed} failed to decrypt)`);
|
||||
return msg.join(' ');
|
||||
}
|
||||
|
||||
// Picker UI mode — open in user's browser
|
||||
const port = bm.serverPort;
|
||||
if (!port) throw new Error('Server port not available');
|
||||
|
||||
const browsers = findInstalledBrowsers();
|
||||
if (browsers.length === 0) {
|
||||
throw new Error('No Chromium browsers found. Supported: Comet, Chrome, Arc, Brave, Edge');
|
||||
}
|
||||
|
||||
const pickerUrl = `http://127.0.0.1:${port}/cookie-picker`;
|
||||
try {
|
||||
Bun.spawn(['open', pickerUrl], { stdout: 'ignore', stderr: 'ignore' });
|
||||
} catch {
|
||||
// open may fail silently — URL is in the message below
|
||||
}
|
||||
|
||||
return `Cookie picker opened at ${pickerUrl}\nDetected browsers: ${browsers.map(b => b.name).join(', ')}\nSelect domains to import, then close the picker when done.`;
|
||||
}
|
||||
|
||||
default:
|
||||
throw new Error(`Unknown write command: ${command}`);
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,146 @@
|
|||
// gstack-guardian.js — OpenCode plugin for gstack safety skills
|
||||
// Integrates: /careful, /freeze, /guard
|
||||
//
|
||||
// Usage: Place this file in your OpenCode plugin directory
|
||||
// or reference it in your OpenCode configuration.
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
// State file for freeze boundary
|
||||
const FREEZE_STATE = path.join(process.env.HOME, '.gstack', 'freeze-dir.txt');
|
||||
|
||||
// Destructive command patterns
|
||||
const DANGEROUS_PATTERNS = [
|
||||
{ pattern: /rm\s+(-[a-zA-Z]*r|--recursive)/, message: 'Destructive: recursive delete (rm -r). This permanently removes files.', name: 'rm_recursive' },
|
||||
{ pattern: /DROP\s+(TABLE|DATABASE)/i, message: 'Destructive: SQL DROP detected. This permanently deletes database objects.', name: 'drop_table' },
|
||||
{ pattern: /\bTRUNCATE\b/i, message: 'Destructive: SQL TRUNCATE detected. This deletes all rows from a table.', name: 'truncate' },
|
||||
{ pattern: /git\s+push\s+.*(-f\b|--force)/, message: 'Destructive: git force-push rewrites remote history. Other contributors may lose work.', name: 'git_force_push' },
|
||||
{ pattern: /git\s+reset\s+--hard/, message: 'Destructive: git reset --hard discards all uncommitted changes.', name: 'git_reset_hard' },
|
||||
{ pattern: /git\s+(checkout|restore)\s+\./, message: 'Destructive: discards all uncommitted changes in the working tree.', name: 'git_discard' },
|
||||
{ pattern: /kubectl\s+delete/, message: 'Destructive: kubectl delete removes Kubernetes resources. May impact production.', name: 'kubectl_delete' },
|
||||
{ pattern: /docker\s+(rm\s+-f|system\s+prune)/, message: 'Destructive: Docker force-remove or prune. May delete running containers or cached images.', name: 'docker_destructive' },
|
||||
];
|
||||
|
||||
// Safe rm targets (build artifacts)
|
||||
const SAFE_RM_TARGETS = [
|
||||
'node_modules', '.next', 'dist', '__pycache__', '.cache', 'build', '.turbo', 'coverage',
|
||||
];
|
||||
|
||||
function isSafeRm(cmd) {
|
||||
// Check if this is rm -r targeting only safe directories
|
||||
const rmMatch = cmd.match(/rm\s+(-[a-zA-Z]+\s+)*/);
|
||||
if (!rmMatch) return false;
|
||||
|
||||
const args = cmd.replace(/rm\s+(-[a-zA-Z]+\s+)*/, '').trim();
|
||||
const targets = args.split(/\s+/);
|
||||
|
||||
return targets.every(target => {
|
||||
if (target.startsWith('-')) return true;
|
||||
const basename = path.basename(target);
|
||||
return SAFE_RM_TARGETS.includes(basename);
|
||||
});
|
||||
}
|
||||
|
||||
function checkCareful(cmd) {
|
||||
// Skip if it's a safe rm
|
||||
if (/rm\s+(-[a-zA-Z]*r|--recursive)/.test(cmd) && isSafeRm(cmd)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Check dangerous patterns
|
||||
for (const { pattern, message, name } of DANGEROUS_PATTERNS) {
|
||||
if (pattern.test(cmd)) {
|
||||
return { message: `[careful] ${message}`, pattern: name };
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
function checkFreeze(filePath) {
|
||||
try {
|
||||
const freezeDir = fs.readFileSync(FREEZE_STATE, 'utf-8').trim();
|
||||
if (!freezeDir) return null;
|
||||
|
||||
const resolvedPath = path.resolve(filePath);
|
||||
const resolvedBoundary = path.resolve(freezeDir);
|
||||
|
||||
if (!resolvedPath.startsWith(resolvedBoundary)) {
|
||||
return {
|
||||
message: `[freeze] Blocked: ${filePath} is outside the freeze boundary (${freezeDir}). Only edits within the frozen directory are allowed.`,
|
||||
};
|
||||
}
|
||||
} catch (e) {
|
||||
if (e.code !== 'ENOENT') throw e;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
module.exports = async ({ project, client, $, directory, worktree }) => {
|
||||
// Read guard state
|
||||
const guardStateFile = path.join(process.env.HOME, '.gstack', 'guard-active.txt');
|
||||
|
||||
function isGuardActive() {
|
||||
try {
|
||||
return fs.existsSync(guardStateFile);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function isCarefulActive() {
|
||||
try {
|
||||
return fs.existsSync(path.join(process.env.HOME, '.gstack', 'careful-active.txt'));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function isFreezeActive() {
|
||||
try {
|
||||
return fs.existsSync(FREEZE_STATE);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
'tool.execute.before': async (input, output) => {
|
||||
const guardActive = isGuardActive();
|
||||
const carefulActive = isCarefulActive() || guardActive;
|
||||
const freezeActive = isFreezeActive() || guardActive;
|
||||
|
||||
// === Careful: Destructive command interception ===
|
||||
if (carefulActive && input.tool === 'bash') {
|
||||
const cmd = output.args?.command || '';
|
||||
const result = checkCareful(cmd);
|
||||
if (result) {
|
||||
throw new Error(
|
||||
`⚠️ GStack Guard: Destructive command intercepted\n` +
|
||||
`Command: ${cmd}\n` +
|
||||
`Pattern: ${result.pattern}\n` +
|
||||
`Message: ${result.message}\n` +
|
||||
`To override, disable /careful or /guard first.`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// === Freeze: Edit directory restriction ===
|
||||
if (freezeActive && (input.tool === 'edit' || input.tool === 'write')) {
|
||||
const filePath = output.args?.filePath || output.args?.path || '';
|
||||
if (filePath) {
|
||||
const result = checkFreeze(filePath);
|
||||
if (result) {
|
||||
throw new Error(
|
||||
`⚠️ GStack Freeze: Edit intercepted\n` +
|
||||
result.message +
|
||||
`\nTo remove restriction, run /unfreeze.`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
};
|
||||
};
|
||||
|
|
@ -0,0 +1,907 @@
|
|||
---
|
||||
name: review
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust
|
||||
boundary violations, conditional side effects, and other structural issues. Use when
|
||||
asked to "review this PR", "code review", "pre-landing review", or "check my diff".
|
||||
Proactively suggest when the user is about to merge or land code changes.
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Edit
|
||||
- Write
|
||||
- Grep
|
||||
- Glob
|
||||
- Agent
|
||||
- AskUserQuestion
|
||||
- WebSearch
|
||||
---
|
||||
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
|
||||
## Preamble (run first)
|
||||
|
||||
```bash
|
||||
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
|
||||
[ -n "$_UPD" ] && echo "$_UPD" || true
|
||||
mkdir -p ~/.gstack/sessions
|
||||
touch ~/.gstack/sessions/"$PPID"
|
||||
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
|
||||
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
|
||||
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
|
||||
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
|
||||
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
|
||||
echo "BRANCH: $_BRANCH"
|
||||
echo "PROACTIVE: $_PROACTIVE"
|
||||
source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true
|
||||
REPO_MODE=${REPO_MODE:-unknown}
|
||||
echo "REPO_MODE: $REPO_MODE"
|
||||
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
|
||||
echo "LAKE_INTRO: $_LAKE_SEEN"
|
||||
_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true)
|
||||
_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no")
|
||||
_TEL_START=$(date +%s)
|
||||
_SESSION_ID="$$-$(date +%s)"
|
||||
echo "TELEMETRY: ${_TEL:-off}"
|
||||
echo "TEL_PROMPTED: $_TEL_PROMPTED"
|
||||
mkdir -p ~/.gstack/analytics
|
||||
echo '{"skill":"review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done
|
||||
```
|
||||
|
||||
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills — only invoke
|
||||
them when the user explicitly asks. The user opted out of proactive suggestions.
|
||||
|
||||
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
|
||||
|
||||
If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle.
|
||||
Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete
|
||||
thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean"
|
||||
Then offer to open the essay in their default browser:
|
||||
|
||||
```bash
|
||||
open https://garryslist.org/posts/boil-the-ocean
|
||||
touch ~/.gstack/.completeness-intro-seen
|
||||
```
|
||||
|
||||
Only run `open` if the user says yes. Always run `touch` to mark as seen. This only happens once.
|
||||
|
||||
If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: After the lake intro is handled,
|
||||
ask the user about telemetry. Use AskUserQuestion:
|
||||
|
||||
> Help gstack get better! Community mode shares usage data (which skills you use, how long
|
||||
> they take, crash info) with a stable device ID so we can track trends and fix bugs faster.
|
||||
> No code, file paths, or repo names are ever sent.
|
||||
> Change anytime with `gstack-config set telemetry off`.
|
||||
|
||||
Options:
|
||||
- A) Help gstack get better! (recommended)
|
||||
- B) No thanks
|
||||
|
||||
If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community`
|
||||
|
||||
If B: ask a follow-up AskUserQuestion:
|
||||
|
||||
> How about anonymous mode? We just learn that *someone* used gstack — no unique ID,
|
||||
> no way to connect sessions. Just a counter that helps us know if anyone's out there.
|
||||
|
||||
Options:
|
||||
- A) Sure, anonymous is fine
|
||||
- B) No thanks, fully off
|
||||
|
||||
If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous`
|
||||
If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off`
|
||||
|
||||
Always run:
|
||||
```bash
|
||||
touch ~/.gstack/.telemetry-prompted
|
||||
```
|
||||
|
||||
This only happens once. If `TEL_PROMPTED` is `yes`, skip this entirely.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call:**
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
|
||||
3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` — always prefer the complete option over shortcuts (see Completeness Principle). Include `Completeness: X/10` for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
|
||||
4. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Completeness Principle — Boil the Lake
|
||||
|
||||
AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
|
||||
|
||||
- If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — **always recommend A**. The delta between 80 lines and 150 lines is meaningless with CC+gstack. "Good enough" is the wrong instinct when "complete" costs minutes more.
|
||||
- **Lake vs. ocean:** A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
|
||||
- **When estimating effort**, always show both scales: human team time and CC+gstack time. The compression ratio varies by task type — use this reference:
|
||||
|
||||
| Task type | Human team | CC+gstack | Compression |
|
||||
|-----------|-----------|-----------|-------------|
|
||||
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
|
||||
| Test writing | 1 day | 15 min | ~50x |
|
||||
| Feature implementation | 1 week | 30 min | ~30x |
|
||||
| Bug fix + regression test | 4 hours | 15 min | ~20x |
|
||||
| Architecture / design | 2 days | 4 hours | ~5x |
|
||||
| Research / exploration | 1 day | 3 hours | ~3x |
|
||||
|
||||
- This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds.
|
||||
|
||||
**Anti-patterns — DON'T do this:**
|
||||
- BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.)
|
||||
- BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with CC.)
|
||||
- BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
|
||||
- BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")
|
||||
|
||||
## Repo Ownership Mode — See Something, Say Something
|
||||
|
||||
`REPO_MODE` from the preamble tells you who owns issues in this repo:
|
||||
|
||||
- **`solo`** — One person does 80%+ of the work. They own everything. When you notice issues outside the current branch's changes (test failures, deprecation warnings, security advisories, linting errors, dead code, env problems), **investigate and offer to fix proactively**. The solo dev is the only person who will fix it. Default to action.
|
||||
- **`collaborative`** — Multiple active contributors. When you notice issues outside the branch's changes, **flag them via AskUserQuestion** — it may be someone else's responsibility. Default to asking, not fixing.
|
||||
- **`unknown`** — Treat as collaborative (safer default — ask before fixing).
|
||||
|
||||
**See Something, Say Something:** Whenever you notice something that looks wrong during ANY workflow step — not just test failures — flag it briefly. One sentence: what you noticed and its impact. In solo mode, follow up with "Want me to fix it?" In collaborative mode, just flag it and move on.
|
||||
|
||||
Never let a noticed issue silently pass. The whole point is proactive communication.
|
||||
|
||||
## Search Before Building
|
||||
|
||||
Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — **search first.** Read `~/.claude/skills/gstack/ETHOS.md` for the full philosophy.
|
||||
|
||||
**Three layers of knowledge:**
|
||||
- **Layer 1** (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
|
||||
- **Layer 2** (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
|
||||
- **Layer 3** (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.
|
||||
|
||||
**Eureka moment:** When first-principles reasoning reveals conventional wisdom is wrong, name it:
|
||||
"EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
|
||||
|
||||
Log eureka moments:
|
||||
```bash
|
||||
jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
|
||||
```
|
||||
Replace SKILL_NAME and ONE_LINE_SUMMARY. Runs inline — don't stop the workflow.
|
||||
|
||||
**WebSearch fallback:** If WebSearch is unavailable, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
## Contributor Mode
|
||||
|
||||
If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
|
||||
|
||||
**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better!
|
||||
|
||||
**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore.
|
||||
|
||||
**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs.
|
||||
|
||||
**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer):
|
||||
|
||||
```
|
||||
# {Title}
|
||||
|
||||
Hey gstack team — ran into this while using /{skill-name}:
|
||||
|
||||
**What I was trying to do:** {what the user/agent was attempting}
|
||||
**What happened instead:** {what actually happened}
|
||||
**My rating:** {0-10} — {one sentence on why it wasn't a 10}
|
||||
|
||||
## Steps to reproduce
|
||||
1. {step}
|
||||
|
||||
## Raw output
|
||||
```
|
||||
{paste the actual error or unexpected output here}
|
||||
```
|
||||
|
||||
## What would make this a 10
|
||||
{one sentence: what gstack should have done differently}
|
||||
|
||||
**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill}
|
||||
```
|
||||
|
||||
Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
|
||||
|
||||
## Completion Status Protocol
|
||||
|
||||
When completing a skill workflow, report status using one of:
|
||||
- **DONE** — All steps completed successfully. Evidence provided for each claim.
|
||||
- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern.
|
||||
- **BLOCKED** — Cannot proceed. State what is blocking and what was tried.
|
||||
- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need.
|
||||
|
||||
### Escalation
|
||||
|
||||
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
|
||||
|
||||
Bad work is worse than no work. You will not be penalized for escalating.
|
||||
- If you have attempted a task 3 times without success, STOP and escalate.
|
||||
- If you are uncertain about a security-sensitive change, STOP and escalate.
|
||||
- If the scope of work exceeds what you can verify, STOP and escalate.
|
||||
|
||||
Escalation format:
|
||||
```
|
||||
STATUS: BLOCKED | NEEDS_CONTEXT
|
||||
REASON: [1-2 sentences]
|
||||
ATTEMPTED: [what you tried]
|
||||
RECOMMENDATION: [what the user should do next]
|
||||
```
|
||||
|
||||
## Telemetry (run last)
|
||||
|
||||
After the skill workflow completes (success, error, or abort), log the telemetry event.
|
||||
Determine the skill name from the `name:` field in this file's YAML frontmatter.
|
||||
Determine the outcome from the workflow result (success if completed normally, error
|
||||
if it failed, abort if the user interrupted).
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes telemetry to
|
||||
`~/.gstack/analytics/` (user config directory, not project files). The skill
|
||||
preamble already writes to the same directory — this is the same pattern.
|
||||
Skipping this command loses session duration and outcome data.
|
||||
|
||||
Run this bash:
|
||||
|
||||
```bash
|
||||
_TEL_END=$(date +%s)
|
||||
_TEL_DUR=$(( _TEL_END - _TEL_START ))
|
||||
rm -f ~/.gstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
|
||||
~/.claude/skills/gstack/bin/gstack-telemetry-log \
|
||||
--skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
|
||||
--used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &
|
||||
```
|
||||
|
||||
Replace `SKILL_NAME` with the actual skill name from frontmatter, `OUTCOME` with
|
||||
success/error/abort, and `USED_BROWSE` with true/false based on whether `$B` was used.
|
||||
If you cannot determine the outcome, use "unknown". This runs in the background and
|
||||
never blocks the user.
|
||||
|
||||
## Plan Status Footer
|
||||
|
||||
When you are in plan mode and about to call ExitPlanMode:
|
||||
|
||||
1. Check if the plan file already has a `## GSTACK REVIEW REPORT` section.
|
||||
2. If it DOES — skip (a review skill already wrote a richer report).
|
||||
3. If it does NOT — run this command:
|
||||
|
||||
\`\`\`bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-read
|
||||
\`\`\`
|
||||
|
||||
Then write a `## GSTACK REVIEW REPORT` section to the end of the plan file:
|
||||
|
||||
- If the output contains review entries (JSONL lines before `---CONFIG---`): format the
|
||||
standard report table with runs/status/findings per skill, same format as the review
|
||||
skills use.
|
||||
- If the output is `NO_REVIEWS` or empty: write this placeholder table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | 0 | — | — |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | 0 | — | — |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | 0 | — | — |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | 0 | — | — |
|
||||
|
||||
**VERDICT:** NO REVIEWS YET — run \`/autoplan\` for full review pipeline, or individual reviews above.
|
||||
\`\`\`
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
## Step 0: Detect base branch
|
||||
|
||||
Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
|
||||
|
||||
1. Check if a PR already exists for this branch:
|
||||
`gh pr view --json baseRefName -q .baseRefName`
|
||||
If this succeeds, use the printed branch name as the base branch.
|
||||
|
||||
2. If no PR exists (command fails), detect the repo's default branch:
|
||||
`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
|
||||
|
||||
3. If both commands fail, fall back to `main`.
|
||||
|
||||
Print the detected base branch name. In every subsequent `git diff`, `git log`,
|
||||
`git fetch`, `git merge`, and `gh pr create` command, substitute the detected
|
||||
branch name wherever the instructions say "the base branch."
|
||||
|
||||
---
|
||||
|
||||
# Pre-Landing PR Review
|
||||
|
||||
You are running the `/review` workflow. Analyze the current branch's diff against the base branch for structural issues that tests don't catch.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check branch
|
||||
|
||||
1. Run `git branch --show-current` to get the current branch.
|
||||
2. If on the base branch, output: **"Nothing to review — you're on the base branch or have no changes against it."** and stop.
|
||||
3. Run `git fetch origin <base> --quiet && git diff origin/<base> --stat` to check if there's a diff. If no diff, output the same message and stop.
|
||||
|
||||
---
|
||||
|
||||
## Step 1.5: Scope Drift Detection
|
||||
|
||||
Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?**
|
||||
|
||||
1. Read `TODOS.md` (if it exists). Read PR description (`gh pr view --json body --jq .body 2>/dev/null || true`).
|
||||
Read commit messages (`git log origin/<base>..HEAD --oneline`).
|
||||
**If no PR exists:** rely on commit messages and TODOS.md for stated intent — this is the common case since /review runs before /ship creates the PR.
|
||||
2. Identify the **stated intent** — what was this branch supposed to accomplish?
|
||||
3. Run `git diff origin/<base> --stat` and compare the files changed against the stated intent.
|
||||
4. Evaluate with skepticism:
|
||||
|
||||
**SCOPE CREEP detection:**
|
||||
- Files changed that are unrelated to the stated intent
|
||||
- New features or refactors not mentioned in the plan
|
||||
- "While I was in there..." changes that expand blast radius
|
||||
|
||||
**MISSING REQUIREMENTS detection:**
|
||||
- Requirements from TODOS.md/PR description not addressed in the diff
|
||||
- Test coverage gaps for stated requirements
|
||||
- Partial implementations (started but not finished)
|
||||
|
||||
5. Output (before the main review begins):
|
||||
```
|
||||
Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING]
|
||||
Intent: <1-line summary of what was requested>
|
||||
Delivered: <1-line summary of what the diff actually does>
|
||||
[If drift: list each out-of-scope change]
|
||||
[If missing: list each unaddressed requirement]
|
||||
```
|
||||
|
||||
6. This is **INFORMATIONAL** — does not block the review. Proceed to Step 2.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read the checklist
|
||||
|
||||
Read `.claude/skills/review/checklist.md`.
|
||||
|
||||
**If the file cannot be read, STOP and report the error.** Do not proceed without the checklist.
|
||||
|
||||
---
|
||||
|
||||
## Step 2.5: Check for Greptile review comments
|
||||
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
|
||||
|
||||
**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
|
||||
|
||||
**If Greptile comments are found:** Store the classifications (VALID & ACTIONABLE, VALID BUT ALREADY FIXED, FALSE POSITIVE, SUPPRESSED) — you will need them in Step 5.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Get the diff
|
||||
|
||||
Fetch the latest base branch to avoid false positives from stale local state:
|
||||
|
||||
```bash
|
||||
git fetch origin <base> --quiet
|
||||
```
|
||||
|
||||
Run `git diff origin/<base>` to get the full diff. This includes both committed and uncommitted changes against the latest base branch.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Two-pass review
|
||||
|
||||
Apply the checklist against the diff in two passes:
|
||||
|
||||
1. **Pass 1 (CRITICAL):** SQL & Data Safety, Race Conditions & Concurrency, LLM Output Trust Boundary, Enum & Value Completeness
|
||||
2. **Pass 2 (INFORMATIONAL):** Conditional Side Effects, Magic Numbers & String Coupling, Dead Code & Consistency, LLM Prompt Issues, Test Gaps, View/Frontend, Performance & Bundle Impact
|
||||
|
||||
**Enum & Value Completeness requires reading code OUTSIDE the diff.** When the diff introduces a new enum value, status, tier, or type constant, use Grep to find all files that reference sibling values, then Read those files to check if the new value is handled. This is the one category where within-diff review is insufficient.
|
||||
|
||||
**Search-before-recommending:** When recommending a fix pattern (especially for concurrency, caching, auth, or framework-specific behavior):
|
||||
- Verify the pattern is current best practice for the framework version in use
|
||||
- Check if a built-in solution exists in newer versions before recommending a workaround
|
||||
- Verify API signatures against current docs (APIs change between versions)
|
||||
|
||||
Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge.
|
||||
|
||||
Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.
|
||||
|
||||
---
|
||||
|
||||
## Step 4.5: Design Review (conditional)
|
||||
|
||||
## Design Review (conditional, diff-scoped)
|
||||
|
||||
Check if the diff touches frontend files using `gstack-diff-scope`:
|
||||
|
||||
```bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-diff-scope <base> 2>/dev/null)
|
||||
```
|
||||
|
||||
**If `SCOPE_FRONTEND=false`:** Skip design review silently. No output.
|
||||
|
||||
**If `SCOPE_FRONTEND=true`:**
|
||||
|
||||
1. **Check for DESIGN.md.** If `DESIGN.md` or `design-system.md` exists in the repo root, read it. All design findings are calibrated against it — patterns blessed in DESIGN.md are not flagged. If not found, use universal design principles.
|
||||
|
||||
2. **Read `.claude/skills/review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
|
||||
|
||||
3. **Read each changed frontend file** (full file, not just diff hunks). Frontend files are identified by the patterns listed in the checklist.
|
||||
|
||||
4. **Apply the design checklist** against the changed files. For each item:
|
||||
- **[HIGH] mechanical CSS fix** (`outline: none`, `!important`, `font-size < 16px`): classify as AUTO-FIX
|
||||
- **[HIGH/MEDIUM] design judgment needed**: classify as ASK
|
||||
- **[LOW] intent-based detection**: present as "Possible — verify visually or run /design-review"
|
||||
|
||||
5. **Include findings** in the review output under a "Design Review" header, following the output format in the checklist. Design findings merge with code review findings into the same Fix-First flow.
|
||||
|
||||
6. **Log the result** for the Review Readiness Dashboard:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-review-lite","timestamp":"TIMESTAMP","status":"STATUS","findings":N,"auto_fixed":M,"commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Substitute: TIMESTAMP = ISO 8601 datetime, STATUS = "clean" if 0 findings or "issues_found", N = total findings, M = auto-fixed count, COMMIT = output of `git rev-parse --short HEAD`.
|
||||
|
||||
7. **Codex design voice** (optional, automatic if available):
|
||||
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
If Codex is available, run a lightweight design check on the diff:
|
||||
|
||||
```bash
|
||||
TMPERR_DRL=$(mktemp /tmp/codex-drl-XXXXXXXX)
|
||||
codex exec "Review the git diff on this branch. Run 7 litmus checks (YES/NO each): 1. Brand/product unmistakable in first screen? 2. One strong visual anchor present? 3. Page understandable by scanning headlines only? 4. Each section has one job? 5. Are cards actually necessary? 6. Does motion improve hierarchy or atmosphere? 7. Would design feel premium with all decorative shadows removed? Flag any hard rejections: 1. Generic SaaS card grid as first impression 2. Beautiful image with weak brand 3. Strong headline with no clear action 4. Busy imagery behind text 5. Sections repeating same mood statement 6. Carousel with no narrative purpose 7. App UI made of stacked cards instead of layout 5 most important design findings only. Reference file:line." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DRL"
|
||||
```
|
||||
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_DRL" && rm -f "$TMPERR_DRL"
|
||||
```
|
||||
|
||||
**Error handling:** All errors are non-blocking. On auth failure, timeout, or empty response — skip with a brief note and continue.
|
||||
|
||||
Present Codex output under a `CODEX (design):` header, merged with the checklist findings above.
|
||||
|
||||
Include any design findings alongside the findings from Step 4. They follow the same Fix-First flow in Step 5 — AUTO-FIX for mechanical CSS fixes, ASK for everything else.
|
||||
|
||||
---
|
||||
|
||||
## Step 4.75: Test Coverage Diagram
|
||||
|
||||
100% coverage is the goal. Evaluate every codepath changed in the diff and identify test gaps. Gaps become INFORMATIONAL findings that follow the Fix-First flow.
|
||||
|
||||
### Test Framework Detection
|
||||
|
||||
Before analyzing coverage, detect the project's test framework:
|
||||
|
||||
1. **Read CLAUDE.md** — look for a `## Testing` section with test command and framework name. If found, use that as the authoritative source.
|
||||
2. **If CLAUDE.md has no testing section, auto-detect:**
|
||||
|
||||
```bash
|
||||
# Detect project runtime
|
||||
[ -f Gemfile ] && echo "RUNTIME:ruby"
|
||||
[ -f package.json ] && echo "RUNTIME:node"
|
||||
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
|
||||
[ -f go.mod ] && echo "RUNTIME:go"
|
||||
[ -f Cargo.toml ] && echo "RUNTIME:rust"
|
||||
# Check for existing test infrastructure
|
||||
ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
|
||||
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
|
||||
```
|
||||
|
||||
3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
|
||||
|
||||
**Step 1. Trace every codepath changed** using `git diff origin/<base>...HEAD`:
|
||||
|
||||
Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:
|
||||
|
||||
1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.
|
||||
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
|
||||
- Where does input come from? (request params, props, database, API call)
|
||||
- What transforms it? (validation, mapping, computation)
|
||||
- Where does it go? (database write, API response, rendered output, side effect)
|
||||
- What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
|
||||
3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
|
||||
- Every function/method that was added or modified
|
||||
- Every conditional branch (if/else, switch, ternary, guard clause, early return)
|
||||
- Every error path (try/catch, rescue, error boundary, fallback)
|
||||
- Every call to another function (trace into it — does IT have untested branches?)
|
||||
- Every edge: what happens with null input? Empty array? Invalid type?
|
||||
|
||||
This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.
|
||||
|
||||
**Step 2. Map user flows, interactions, and error states:**
|
||||
|
||||
Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
|
||||
|
||||
- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
|
||||
- **Interaction edge cases:** What happens when the user does something unexpected?
|
||||
- Double-click/rapid resubmit
|
||||
- Navigate away mid-operation (back button, close tab, click another link)
|
||||
- Submit with stale data (page sat open for 30 minutes, session expired)
|
||||
- Slow connection (API takes 10 seconds — what does the user see?)
|
||||
- Concurrent actions (two tabs, same form)
|
||||
- **Error states the user can see:** For every error the code handles, what does the user actually experience?
|
||||
- Is there a clear error message or a silent failure?
|
||||
- Can the user recover (retry, go back, fix input) or are they stuck?
|
||||
- What happens with no network? With a 500 from the API? With invalid data from the server?
|
||||
- **Empty/zero/boundary states:** What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?
|
||||
|
||||
Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.
|
||||
|
||||
**Step 3. Check each branch against existing tests:**
|
||||
|
||||
Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:
|
||||
- Function `processPayment()` → look for `billing.test.ts`, `billing.spec.ts`, `test/billing_test.rb`
|
||||
- An if/else → look for tests covering BOTH the true AND false path
|
||||
- An error handler → look for a test that triggers that specific error condition
|
||||
- A call to `helperFn()` that has its own branches → those branches need tests too
|
||||
- A user flow → look for an integration or E2E test that walks through the journey
|
||||
- An interaction edge case → look for a test that simulates the unexpected action
|
||||
|
||||
Quality scoring rubric:
|
||||
- ★★★ Tests behavior with edge cases AND error paths
|
||||
- ★★ Tests correct behavior, happy path only
|
||||
- ★ Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")
|
||||
|
||||
### E2E Test Decision Matrix
|
||||
|
||||
When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:
|
||||
|
||||
**RECOMMEND E2E (mark as [→E2E] in the diagram):**
|
||||
- Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
|
||||
- Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
|
||||
- Auth/payment/data-destruction flows — too important to trust unit tests alone
|
||||
|
||||
**RECOMMEND EVAL (mark as [→EVAL] in the diagram):**
|
||||
- Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
|
||||
- Changes to prompt templates, system instructions, or tool definitions
|
||||
|
||||
**STICK WITH UNIT TESTS:**
|
||||
- Pure function with clear inputs/outputs
|
||||
- Internal helper with no side effects
|
||||
- Edge case of a single function (null input, empty array)
|
||||
- Obscure/rare flow that isn't customer-facing
|
||||
|
||||
### REGRESSION RULE (mandatory)
|
||||
|
||||
**IRON RULE:** When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is written immediately. No AskUserQuestion. No skipping. Regressions are the highest-priority test because they prove something broke.
|
||||
|
||||
A regression is when:
|
||||
- The diff modifies existing behavior (not new code)
|
||||
- The existing test suite (if any) doesn't cover the changed path
|
||||
- The change introduces a new failure mode for existing callers
|
||||
|
||||
When uncertain whether a change is a regression, err on the side of writing the test.
|
||||
|
||||
Format: commit as `test: regression test for {what broke}`
|
||||
|
||||
**Step 4. Output ASCII coverage diagram:**
|
||||
|
||||
Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:
|
||||
|
||||
```
|
||||
CODE PATH COVERAGE
|
||||
===========================
|
||||
[+] src/services/billing.ts
|
||||
│
|
||||
├── processPayment()
|
||||
│ ├── [★★★ TESTED] Happy path + card declined + timeout — billing.test.ts:42
|
||||
│ ├── [GAP] Network timeout — NO TEST
|
||||
│ └── [GAP] Invalid currency — NO TEST
|
||||
│
|
||||
└── refundPayment()
|
||||
├── [★★ TESTED] Full refund — billing.test.ts:89
|
||||
└── [★ TESTED] Partial refund (checks non-throw only) — billing.test.ts:101
|
||||
|
||||
USER FLOW COVERAGE
|
||||
===========================
|
||||
[+] Payment checkout flow
|
||||
│
|
||||
├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
|
||||
├── [GAP] [→E2E] Double-click submit — needs E2E, not just unit
|
||||
├── [GAP] Navigate away during payment — unit test sufficient
|
||||
└── [★ TESTED] Form validation errors (checks render only) — checkout.test.ts:40
|
||||
|
||||
[+] Error states
|
||||
│
|
||||
├── [★★ TESTED] Card declined message — billing.test.ts:58
|
||||
├── [GAP] Network timeout UX (what does user see?) — NO TEST
|
||||
└── [GAP] Empty cart submission — NO TEST
|
||||
|
||||
[+] LLM integration
|
||||
│
|
||||
└── [GAP] [→EVAL] Prompt template change — needs eval test
|
||||
|
||||
─────────────────────────────────
|
||||
COVERAGE: 5/13 paths tested (38%)
|
||||
Code paths: 3/5 (60%)
|
||||
User flows: 2/8 (25%)
|
||||
QUALITY: ★★★: 2 ★★: 2 ★: 1
|
||||
GAPS: 8 paths need tests (2 need E2E, 1 needs eval)
|
||||
─────────────────────────────────
|
||||
```
|
||||
|
||||
**Fast path:** All paths covered → "Step 4.75: All new code paths have test coverage ✓" Continue.
|
||||
|
||||
**Step 5. Generate tests for gaps (Fix-First):**
|
||||
|
||||
If test framework is detected and gaps were identified:
|
||||
- Classify each gap as AUTO-FIX or ASK per the Fix-First Heuristic:
|
||||
- **AUTO-FIX:** Simple unit tests for pure functions, edge cases of existing tested functions
|
||||
- **ASK:** E2E tests, tests requiring new test infrastructure, tests for ambiguous behavior
|
||||
- For AUTO-FIX gaps: generate the test, run it, commit as `test: coverage for {feature}`
|
||||
- For ASK gaps: include in the Fix-First batch question with the other review findings
|
||||
- For paths marked [→E2E]: always ASK (E2E tests are higher-effort and need user confirmation)
|
||||
- For paths marked [→EVAL]: always ASK (eval tests need user confirmation on quality criteria)
|
||||
|
||||
If no test framework detected → include gaps as INFORMATIONAL findings only, no generation.
|
||||
|
||||
**Diff is test-only changes:** Skip Step 4.75 entirely: "No new application code paths to audit."
|
||||
|
||||
This step subsumes the "Test Gaps" category from Pass 2 — do not duplicate findings between the checklist Test Gaps item and this coverage diagram. Include any coverage gaps alongside the findings from Step 4 and Step 4.5. They follow the same Fix-First flow — gaps are INFORMATIONAL findings.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Fix-First Review
|
||||
|
||||
**Every finding gets action — not just critical ones.**
|
||||
|
||||
Output a summary header: `Pre-Landing Review: N issues (X critical, Y informational)`
|
||||
|
||||
### Step 5a: Classify each finding
|
||||
|
||||
For each finding, classify as AUTO-FIX or ASK per the Fix-First Heuristic in
|
||||
checklist.md. Critical findings lean toward ASK; informational findings lean
|
||||
toward AUTO-FIX.
|
||||
|
||||
### Step 5b: Auto-fix all AUTO-FIX items
|
||||
|
||||
Apply each fix directly. For each one, output a one-line summary:
|
||||
`[AUTO-FIXED] [file:line] Problem → what you did`
|
||||
|
||||
### Step 5c: Batch-ask about ASK items
|
||||
|
||||
If there are ASK items remaining, present them in ONE AskUserQuestion:
|
||||
|
||||
- List each item with a number, the severity label, the problem, and a recommended fix
|
||||
- For each item, provide options: A) Fix as recommended, B) Skip
|
||||
- Include an overall RECOMMENDATION
|
||||
|
||||
Example format:
|
||||
```
|
||||
I auto-fixed 5 issues. 2 need your input:
|
||||
|
||||
1. [CRITICAL] app/models/post.rb:42 — Race condition in status transition
|
||||
Fix: Add `WHERE status = 'draft'` to the UPDATE
|
||||
→ A) Fix B) Skip
|
||||
|
||||
2. [INFORMATIONAL] app/services/generator.rb:88 — LLM output not type-checked before DB write
|
||||
Fix: Add JSON schema validation
|
||||
→ A) Fix B) Skip
|
||||
|
||||
RECOMMENDATION: Fix both — #1 is a real race condition, #2 prevents silent data corruption.
|
||||
```
|
||||
|
||||
If 3 or fewer ASK items, you may use individual AskUserQuestion calls instead of batching.
|
||||
|
||||
### Step 5d: Apply user-approved fixes
|
||||
|
||||
Apply fixes for items where the user chose "Fix." Output what was fixed.
|
||||
|
||||
If no ASK items exist (everything was AUTO-FIX), skip the question entirely.
|
||||
|
||||
### Verification of claims
|
||||
|
||||
Before producing the final review output:
|
||||
- If you claim "this pattern is safe" → cite the specific line proving safety
|
||||
- If you claim "this is handled elsewhere" → read and cite the handling code
|
||||
- If you claim "tests cover this" → name the test file and method
|
||||
- Never say "likely handled" or "probably tested" — verify or flag as unknown
|
||||
|
||||
**Rationalization prevention:** "This looks fine" is not a finding. Either cite evidence it IS fine, or flag it as unverified.
|
||||
|
||||
### Greptile comment resolution
|
||||
|
||||
After outputting your own findings, if Greptile comments were classified in Step 2.5:
|
||||
|
||||
**Include a Greptile summary in your output header:** `+ N Greptile comments (X valid, Y fixed, Z FP)`
|
||||
|
||||
Before replying to any comment, run the **Escalation Detection** algorithm from greptile-triage.md to determine whether to use Tier 1 (friendly) or Tier 2 (firm) reply templates.
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are included in your findings — they follow the Fix-First flow (auto-fixed if mechanical, batched into ASK if not) (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses A (fix), reply using the **Fix reply template** from greptile-triage.md (include inline diff + explanation). If the user chooses C (false positive), reply using the **False Positive reply template** (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
2. **FALSE POSITIVE comments:** Present each one via AskUserQuestion:
|
||||
- Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
|
||||
- Explain concisely why it's a false positive
|
||||
- Options:
|
||||
- A) Reply to Greptile explaining why this is incorrect (recommended if clearly wrong)
|
||||
- B) Fix it anyway (if low-effort and harmless)
|
||||
- C) Ignore — don't reply, don't fix
|
||||
|
||||
If the user chooses A, reply using the **False Positive reply template** from greptile-triage.md (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply using the **Already Fixed reply template** from greptile-triage.md — no AskUserQuestion needed:
|
||||
- Include what was done and the fixing commit SHA
|
||||
- Save to both per-project and global greptile-history
|
||||
|
||||
4. **SUPPRESSED comments:** Skip silently — these are known false positives from previous triage.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.5: TODOS cross-reference
|
||||
|
||||
Read `TODOS.md` in the repository root (if it exists). Cross-reference the PR against open TODOs:
|
||||
|
||||
- **Does this PR close any open TODOs?** If yes, note which items in your output: "This PR addresses TODO: <title>"
|
||||
- **Does this PR create work that should become a TODO?** If yes, flag it as an informational finding.
|
||||
- **Are there related TODOs that provide context for this review?** If yes, reference them when discussing related findings.
|
||||
|
||||
If TODOS.md doesn't exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.6: Documentation staleness check
|
||||
|
||||
Cross-reference the diff against documentation files. For each `.md` file in the repo root (README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, etc.):
|
||||
|
||||
1. Check if code changes in the diff affect features, components, or workflows described in that doc file.
|
||||
2. If the doc file was NOT updated in this branch but the code it describes WAS changed, flag it as an INFORMATIONAL finding:
|
||||
"Documentation may be stale: [file] describes [feature/component] but code changed in this branch. Consider running `/document-release`."
|
||||
|
||||
This is informational only — never critical. The fix action is `/document-release`.
|
||||
|
||||
If no documentation files exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.7: Adversarial review (auto-scaled)
|
||||
|
||||
Adversarial review thoroughness scales automatically based on diff size. No configuration needed.
|
||||
|
||||
**Detect diff size and tool availability:**
|
||||
|
||||
```bash
|
||||
DIFF_INS=$(git diff origin/<base> --stat | tail -1 | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo "0")
|
||||
DIFF_DEL=$(git diff origin/<base> --stat | tail -1 | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo "0")
|
||||
DIFF_TOTAL=$((DIFF_INS + DIFF_DEL))
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
# Respect old opt-out
|
||||
OLD_CFG=$(~/.claude/skills/gstack/bin/gstack-config get codex_reviews 2>/dev/null || true)
|
||||
echo "DIFF_SIZE: $DIFF_TOTAL"
|
||||
echo "OLD_CFG: ${OLD_CFG:-not_set}"
|
||||
```
|
||||
|
||||
If `OLD_CFG` is `disabled`: skip this step silently. Continue to the next step.
|
||||
|
||||
**User override:** If the user explicitly requested a specific tier (e.g., "run all passes", "paranoid review", "full adversarial", "do all 4 passes", "thorough review"), honor that request regardless of diff size. Jump to the matching tier section.
|
||||
|
||||
**Auto-select tier based on diff size:**
|
||||
- **Small (< 50 lines changed):** Skip adversarial review entirely. Print: "Small diff ($DIFF_TOTAL lines) — adversarial review skipped." Continue to the next step.
|
||||
- **Medium (50–199 lines changed):** Run Codex adversarial challenge (or Claude adversarial subagent if Codex unavailable). Jump to the "Medium tier" section.
|
||||
- **Large (200+ lines changed):** Run all remaining passes — Codex structured review + Claude adversarial subagent + Codex adversarial. Jump to the "Large tier" section.
|
||||
|
||||
---
|
||||
|
||||
### Medium tier (50–199 lines)
|
||||
|
||||
Claude's structured review already ran. Now add a **cross-model adversarial challenge**.
|
||||
|
||||
**If Codex is available:** run the Codex adversarial challenge. **If Codex is NOT available:** fall back to the Claude adversarial subagent instead.
|
||||
|
||||
**Codex adversarial:**
|
||||
|
||||
```bash
|
||||
TMPERR_ADV=$(mktemp /tmp/codex-adv-XXXXXXXX)
|
||||
codex exec "Review the changes on this branch against the base branch. Run git diff origin/<base> to see the diff. Your job is to find ways this code will fail in production. Think like an attacker and a chaos engineer. Find edge cases, race conditions, security holes, resource leaks, failure modes, and silent data corruption paths. Be adversarial. Be thorough. No compliments — just the problems." -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR_ADV"
|
||||
```
|
||||
|
||||
Set the Bash tool's `timeout` parameter to `300000` (5 minutes). Do NOT use the `timeout` shell command — it doesn't exist on macOS. After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_ADV"
|
||||
```
|
||||
|
||||
Present the full output verbatim. This is informational — it never blocks shipping.
|
||||
|
||||
**Error handling:** All errors are non-blocking — adversarial review 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."
|
||||
- **Timeout:** "Codex timed out after 5 minutes."
|
||||
- **Empty response:** "Codex returned no response. Stderr: <paste relevant error>."
|
||||
|
||||
On any Codex error, fall back to the Claude adversarial subagent automatically.
|
||||
|
||||
**Claude adversarial subagent** (fallback when Codex unavailable or errored):
|
||||
|
||||
Dispatch via the Agent tool. The subagent has fresh context — no checklist bias from the structured review. This genuine independence catches things the primary reviewer is blind to.
|
||||
|
||||
Subagent prompt:
|
||||
"Read the diff for this branch with `git diff origin/<base>`. Think like an attacker and a chaos engineer. Your job is to find ways this code will fail in production. Look for: edge cases, race conditions, security holes, resource leaks, failure modes, silent data corruption, logic errors that produce wrong results silently, error handling that swallows failures, and trust boundary violations. Be adversarial. Be thorough. No compliments — just the problems. For each finding, classify as FIXABLE (you know how to fix it) or INVESTIGATE (needs human judgment)."
|
||||
|
||||
Present findings under an `ADVERSARIAL REVIEW (Claude subagent):` header. **FIXABLE findings** flow into the same Fix-First pipeline as the structured review. **INVESTIGATE findings** are presented as informational.
|
||||
|
||||
If the subagent fails or times out: "Claude adversarial subagent unavailable. Continuing without adversarial review."
|
||||
|
||||
**Persist the review result:**
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"adversarial-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","tier":"medium","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Substitute STATUS: "clean" if no findings, "issues_found" if findings exist. SOURCE: "codex" if Codex ran, "claude" if subagent ran. If both failed, do NOT persist.
|
||||
|
||||
**Cleanup:** Run `rm -f "$TMPERR_ADV"` after processing (if Codex was used).
|
||||
|
||||
---
|
||||
|
||||
### Large tier (200+ lines)
|
||||
|
||||
Claude's structured review already ran. Now run **all three remaining passes** for maximum coverage:
|
||||
|
||||
**1. Codex structured review (if available):**
|
||||
```bash
|
||||
TMPERR=$(mktemp /tmp/codex-review-XXXXXXXX)
|
||||
codex review --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"
|
||||
```
|
||||
|
||||
Set the Bash tool's `timeout` parameter to `300000` (5 minutes). Do NOT use the `timeout` shell command — it doesn't exist on macOS. Present output under `CODEX SAYS (code review):` header.
|
||||
Check for `[P1]` markers: found → `GATE: FAIL`, not found → `GATE: PASS`.
|
||||
|
||||
If GATE is FAIL, use AskUserQuestion:
|
||||
```
|
||||
Codex found N critical issues in the diff.
|
||||
|
||||
A) Investigate and fix now (recommended)
|
||||
B) Continue — review will still complete
|
||||
```
|
||||
|
||||
If A: address the findings. Re-run `codex review` to verify.
|
||||
|
||||
Read stderr for errors (same error handling as medium tier).
|
||||
|
||||
After stderr: `rm -f "$TMPERR"`
|
||||
|
||||
**2. Claude adversarial subagent:** Dispatch a subagent with the adversarial prompt (same prompt as medium tier). This always runs regardless of Codex availability.
|
||||
|
||||
**3. Codex adversarial challenge (if available):** Run `codex exec` with the adversarial prompt (same as medium tier).
|
||||
|
||||
If Codex is not available for steps 1 and 3, note to the user: "Codex CLI not found — large-diff review ran Claude structured + Claude adversarial (2 of 4 passes). Install Codex for full 4-pass coverage: `npm install -g @openai/codex`"
|
||||
|
||||
**Persist the review result AFTER all passes complete** (not after each sub-step):
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"adversarial-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","tier":"large","gate":"GATE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Substitute: STATUS = "clean" if no findings across ALL passes, "issues_found" if any pass found issues. SOURCE = "both" if Codex ran, "claude" if only Claude subagent ran. GATE = the Codex structured review gate result ("pass"/"fail"), or "informational" if Codex was unavailable. If all passes failed, do NOT persist.
|
||||
|
||||
---
|
||||
|
||||
### Cross-model synthesis (medium and large tiers)
|
||||
|
||||
After all passes complete, synthesize findings across all sources:
|
||||
|
||||
```
|
||||
ADVERSARIAL REVIEW SYNTHESIS (auto: TIER, N lines):
|
||||
════════════════════════════════════════════════════════════
|
||||
High confidence (found by multiple sources): [findings agreed on by >1 pass]
|
||||
Unique to Claude structured review: [from earlier step]
|
||||
Unique to Claude adversarial: [from subagent, if ran]
|
||||
Unique to Codex: [from codex adversarial or code review, if ran]
|
||||
Models used: Claude structured ✓ Claude adversarial ✓/✗ Codex ✓/✗
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
High-confidence findings (agreed on by multiple sources) should be prioritized for fixes.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
|
||||
- **Fix-first, not read-only.** AUTO-FIX items are applied directly. ASK items are only applied after user approval. Never commit, push, or create PRs — that's /ship's job.
|
||||
- **Be terse.** One line problem, one line fix. No preamble.
|
||||
- **Only flag real problems.** Skip anything that's fine.
|
||||
- **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence. Never post vague replies.
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
# TODOS.md Format Reference
|
||||
|
||||
Shared reference for the canonical TODOS.md format. Referenced by `/ship` (Step 5.5) and `/plan-ceo-review` (TODOS.md updates section) to ensure consistent TODO item structure.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```markdown
|
||||
# TODOS
|
||||
|
||||
## <Skill/Component> ← e.g., ## Browse, ## Ship, ## Review, ## Infrastructure
|
||||
<items sorted P0 first, then P1, P2, P3, P4>
|
||||
|
||||
## Completed
|
||||
<finished items with completion annotation>
|
||||
```
|
||||
|
||||
**Sections:** Organize by skill or component (`## Browse`, `## Ship`, `## Review`, `## QA`, `## Retro`, `## Infrastructure`). Within each section, sort items by priority (P0 at top).
|
||||
|
||||
---
|
||||
|
||||
## TODO Item Format
|
||||
|
||||
Each item is an H3 under its section:
|
||||
|
||||
```markdown
|
||||
### <Title>
|
||||
|
||||
**What:** One-line description of the work.
|
||||
|
||||
**Why:** The concrete problem it solves or value it unlocks.
|
||||
|
||||
**Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
|
||||
|
||||
**Effort:** S / M / L / XL
|
||||
**Priority:** P0 / P1 / P2 / P3 / P4
|
||||
**Depends on:** <prerequisites, or "None">
|
||||
```
|
||||
|
||||
**Required fields:** What, Why, Context, Effort, Priority
|
||||
**Optional fields:** Depends on, Blocked by
|
||||
|
||||
---
|
||||
|
||||
## Priority Definitions
|
||||
|
||||
- **P0** — Blocking: must be done before next release
|
||||
- **P1** — Critical: should be done this cycle
|
||||
- **P2** — Important: do when P0/P1 are clear
|
||||
- **P3** — Nice-to-have: revisit after adoption/usage data
|
||||
- **P4** — Someday: good idea, no urgency
|
||||
|
||||
---
|
||||
|
||||
## Completed Item Format
|
||||
|
||||
When an item is completed, move it to the `## Completed` section preserving its original content and appending:
|
||||
|
||||
```markdown
|
||||
**Completed:** vX.Y.Z (YYYY-MM-DD)
|
||||
```
|
||||
|
|
@ -0,0 +1,190 @@
|
|||
# Pre-Landing Review Checklist
|
||||
|
||||
## Instructions
|
||||
|
||||
Review the `git diff origin/main` output for the issues listed below. Be specific — cite `file:line` and suggest fixes. Skip anything that's fine. Only flag real problems.
|
||||
|
||||
**Two-pass review:**
|
||||
- **Pass 1 (CRITICAL):** Run SQL & Data Safety and LLM Output Trust Boundary first. Highest severity.
|
||||
- **Pass 2 (INFORMATIONAL):** Run all remaining categories. Lower severity but still actioned.
|
||||
|
||||
All findings get action via Fix-First Review: obvious mechanical fixes are applied automatically,
|
||||
genuinely ambiguous issues are batched into a single user question.
|
||||
|
||||
**Output format:**
|
||||
|
||||
```
|
||||
Pre-Landing Review: N issues (X critical, Y informational)
|
||||
|
||||
**AUTO-FIXED:**
|
||||
- [file:line] Problem → fix applied
|
||||
|
||||
**NEEDS INPUT:**
|
||||
- [file:line] Problem description
|
||||
Recommended fix: suggested fix
|
||||
```
|
||||
|
||||
If no issues found: `Pre-Landing Review: No issues found.`
|
||||
|
||||
Be terse. For each issue: one line describing the problem, one line with the fix. No preamble, no summaries, no "looks good overall."
|
||||
|
||||
---
|
||||
|
||||
## Review Categories
|
||||
|
||||
### Pass 1 — CRITICAL
|
||||
|
||||
#### SQL & Data Safety
|
||||
- String interpolation in SQL (even if values are `.to_i`/`.to_f` — use parameterized queries (Rails: sanitize_sql_array/Arel; Node: prepared statements; Python: parameterized queries))
|
||||
- TOCTOU races: check-then-set patterns that should be atomic `WHERE` + `update_all`
|
||||
- Bypassing model validations for direct DB writes (Rails: update_column; Django: QuerySet.update(); Prisma: raw queries)
|
||||
- N+1 queries: Missing eager loading (Rails: .includes(); SQLAlchemy: joinedload(); Prisma: include) for associations used in loops/views
|
||||
|
||||
#### Race Conditions & Concurrency
|
||||
- Read-check-write without uniqueness constraint or catch duplicate key error and retry (e.g., `where(hash:).first` then `save!` without handling concurrent insert)
|
||||
- find-or-create without unique DB index — concurrent calls can create duplicates
|
||||
- Status transitions that don't use atomic `WHERE old_status = ? UPDATE SET new_status` — concurrent updates can skip or double-apply transitions
|
||||
- Unsafe HTML rendering (Rails: .html_safe/raw(); React: dangerouslySetInnerHTML; Vue: v-html; Django: |safe/mark_safe) on user-controlled data (XSS)
|
||||
|
||||
#### LLM Output Trust Boundary
|
||||
- LLM-generated values (emails, URLs, names) written to DB or passed to mailers without format validation. Add lightweight guards (`EMAIL_REGEXP`, `URI.parse`, `.strip`) before persisting.
|
||||
- Structured tool output (arrays, hashes) accepted without type/shape checks before database writes.
|
||||
|
||||
#### Enum & Value Completeness
|
||||
When the diff introduces a new enum value, status string, tier name, or type constant:
|
||||
- **Trace it through every consumer.** Read (don't just grep — READ) each file that switches on, filters by, or displays that value. If any consumer doesn't handle the new value, flag it. Common miss: adding a value to the frontend dropdown but the backend model/compute method doesn't persist it.
|
||||
- **Check allowlists/filter arrays.** Search for arrays or `%w[]` lists containing sibling values (e.g., if adding "revise" to tiers, find every `%w[quick lfg mega]` and verify "revise" is included where needed).
|
||||
- **Check `case`/`if-elsif` chains.** If existing code branches on the enum, does the new value fall through to a wrong default?
|
||||
To do this: use Grep to find all references to the sibling values (e.g., grep for "lfg" or "mega" to find all tier consumers). Read each match. This step requires reading code OUTSIDE the diff.
|
||||
|
||||
### Pass 2 — INFORMATIONAL
|
||||
|
||||
#### Conditional Side Effects
|
||||
- Code paths that branch on a condition but forget to apply a side effect on one branch. Example: item promoted to verified but URL only attached when a secondary condition is true — the other branch promotes without the URL, creating an inconsistent record.
|
||||
- Log messages that claim an action happened but the action was conditionally skipped. The log should reflect what actually occurred.
|
||||
|
||||
#### Magic Numbers & String Coupling
|
||||
- Bare numeric literals used in multiple files — should be named constants documented together
|
||||
- Error message strings used as query filters elsewhere (grep for the string — is anything matching on it?)
|
||||
|
||||
#### Dead Code & Consistency
|
||||
- Variables assigned but never read
|
||||
- Version mismatch between PR title and VERSION/CHANGELOG files
|
||||
- CHANGELOG entries that describe changes inaccurately (e.g., "changed from X to Y" when X never existed)
|
||||
- Comments/docstrings that describe old behavior after the code changed
|
||||
|
||||
#### LLM Prompt Issues
|
||||
- 0-indexed lists in prompts (LLMs reliably return 1-indexed)
|
||||
- Prompt text listing available tools/capabilities that don't match what's actually wired up in the `tool_classes`/`tools` array
|
||||
- Word/token limits stated in multiple places that could drift
|
||||
|
||||
#### Test Gaps
|
||||
- Negative-path tests that assert type/status but not the side effects (URL attached? field populated? callback fired?)
|
||||
- Assertions on string content without checking format (e.g., asserting title present but not URL format)
|
||||
- `.expects(:something).never` missing when a code path should explicitly NOT call an external service
|
||||
- Security enforcement features (blocking, rate limiting, auth) without integration tests verifying the enforcement path works end-to-end
|
||||
|
||||
#### Completeness Gaps
|
||||
- Shortcut implementations where the complete version would cost <30 minutes CC time (e.g., partial enum handling, incomplete error paths, missing edge cases that are straightforward to add)
|
||||
- Options presented with only human-team effort estimates — should show both human and CC+gstack time
|
||||
- Test coverage gaps where adding the missing tests is a "lake" not an "ocean" (e.g., missing negative-path tests, missing edge case tests that mirror happy-path structure)
|
||||
- Features implemented at 80-90% when 100% is achievable with modest additional code
|
||||
|
||||
#### Crypto & Entropy
|
||||
- Truncation of data instead of hashing (last N chars instead of SHA-256) — less entropy, easier collisions
|
||||
- `rand()` / `Random.rand` for security-sensitive values — use `SecureRandom` instead
|
||||
- Non-constant-time comparisons (`==`) on secrets or tokens — vulnerable to timing attacks
|
||||
|
||||
#### Time Window Safety
|
||||
- Date-key lookups that assume "today" covers 24h — report at 8am PT only sees midnight→8am under today's key
|
||||
- Mismatched time windows between related features — one uses hourly buckets, another uses daily keys for the same data
|
||||
|
||||
#### Type Coercion at Boundaries
|
||||
- Values crossing Ruby→JSON→JS boundaries where type could change (numeric vs string) — hash/digest inputs must normalize types
|
||||
- Hash/digest inputs that don't call `.to_s` or equivalent before serialization — `{ cores: 8 }` vs `{ cores: "8" }` produce different hashes
|
||||
|
||||
#### View/Frontend
|
||||
- Inline `<style>` blocks in partials (re-parsed every render)
|
||||
- O(n*m) lookups in views (`Array#find` in a loop instead of `index_by` hash)
|
||||
- Ruby-side `.select{}` filtering on DB results that could be a `WHERE` clause (unless intentionally avoiding leading-wildcard `LIKE`)
|
||||
|
||||
#### Performance & Bundle Impact
|
||||
- New `dependencies` entries in package.json that are known-heavy: moment.js (→ date-fns, 330KB→22KB), lodash full (→ lodash-es or per-function imports), jquery, core-js full polyfill
|
||||
- Significant lockfile growth (many new transitive dependencies from a single addition)
|
||||
- Images added without `loading="lazy"` or explicit width/height attributes (causes layout shift / CLS)
|
||||
- Large static assets committed to repo (>500KB per file)
|
||||
- Synchronous `<script>` tags without async/defer
|
||||
- CSS `@import` in stylesheets (blocks parallel loading — use bundler imports instead)
|
||||
- `useEffect` with fetch that depends on another fetch result (request waterfall — combine or parallelize)
|
||||
- Named → default import switches on tree-shakeable libraries (breaks tree-shaking)
|
||||
- New `require()` calls in ESM codebases
|
||||
|
||||
**DO NOT flag:**
|
||||
- devDependencies additions (don't affect production bundle)
|
||||
- Dynamic `import()` calls (code splitting — these are good)
|
||||
- Small utility additions (<5KB gzipped)
|
||||
- Server-side-only dependencies
|
||||
|
||||
---
|
||||
|
||||
## Severity Classification
|
||||
|
||||
```
|
||||
CRITICAL (highest severity): INFORMATIONAL (lower severity):
|
||||
├─ SQL & Data Safety ├─ Conditional Side Effects
|
||||
├─ Race Conditions & Concurrency ├─ Magic Numbers & String Coupling
|
||||
├─ LLM Output Trust Boundary ├─ Dead Code & Consistency
|
||||
└─ Enum & Value Completeness ├─ LLM Prompt Issues
|
||||
├─ Test Gaps
|
||||
├─ Completeness Gaps
|
||||
├─ Crypto & Entropy
|
||||
├─ Time Window Safety
|
||||
├─ Type Coercion at Boundaries
|
||||
├─ View/Frontend
|
||||
└─ Performance & Bundle Impact
|
||||
|
||||
All findings are actioned via Fix-First Review. Severity determines
|
||||
presentation order and classification of AUTO-FIX vs ASK — critical
|
||||
findings lean toward ASK (they're riskier), informational findings
|
||||
lean toward AUTO-FIX (they're more mechanical).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fix-First Heuristic
|
||||
|
||||
This heuristic is referenced by both `/review` and `/ship`. It determines whether
|
||||
the agent auto-fixes a finding or asks the user.
|
||||
|
||||
```
|
||||
AUTO-FIX (agent fixes without asking): ASK (needs human judgment):
|
||||
├─ Dead code / unused variables ├─ Security (auth, XSS, injection)
|
||||
├─ N+1 queries (missing eager loading) ├─ Race conditions
|
||||
├─ Stale comments contradicting code ├─ Design decisions
|
||||
├─ Magic numbers → named constants ├─ Large fixes (>20 lines)
|
||||
├─ Missing LLM output validation ├─ Enum completeness
|
||||
├─ Version/path mismatches ├─ Removing functionality
|
||||
├─ Variables assigned but never read └─ Anything changing user-visible
|
||||
└─ Inline styles, O(n*m) view lookups behavior
|
||||
```
|
||||
|
||||
**Rule of thumb:** If the fix is mechanical and a senior engineer would apply it
|
||||
without discussion, it's AUTO-FIX. If reasonable engineers could disagree about
|
||||
the fix, it's ASK.
|
||||
|
||||
**Critical findings default toward ASK** (they're inherently riskier).
|
||||
**Informational findings default toward AUTO-FIX** (they're more mechanical).
|
||||
|
||||
---
|
||||
|
||||
## Suppressions — DO NOT flag these
|
||||
|
||||
- "X is redundant with Y" when the redundancy is harmless and aids readability (e.g., `present?` redundant with `length > 20`)
|
||||
- "Add a comment explaining why this threshold/constant was chosen" — thresholds change during tuning, comments rot
|
||||
- "This assertion could be tighter" when the assertion already covers the behavior
|
||||
- Suggesting consistency-only changes (wrapping a value in a conditional to match how another constant is guarded)
|
||||
- "Regex doesn't handle edge case X" when the input is constrained and X never occurs in practice
|
||||
- "Test exercises multiple guards simultaneously" — that's fine, tests don't need to isolate every guard
|
||||
- Eval threshold changes (max_actionable, min scores) — these are tuned empirically and change constantly
|
||||
- Harmless no-ops (e.g., `.reject` on an element that's never in the array)
|
||||
- ANYTHING already addressed in the diff you're reviewing — read the FULL diff before commenting
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
# Design Review Checklist (Lite)
|
||||
|
||||
> **Subset of DESIGN_METHODOLOGY** — when adding items here, also update `generateDesignMethodology()` in `scripts/gen-skill-docs.ts`, and vice versa.
|
||||
|
||||
## Instructions
|
||||
|
||||
This checklist applies to **source code in the diff** — not rendered output. Read each changed frontend file (full file, not just diff hunks) and flag anti-patterns.
|
||||
|
||||
**Trigger:** Only run this checklist if the diff touches frontend files. Use `gstack-diff-scope` to detect:
|
||||
|
||||
```bash
|
||||
source <(~/.claude/skills/gstack/bin/gstack-diff-scope <base> 2>/dev/null)
|
||||
```
|
||||
|
||||
If `SCOPE_FRONTEND=false`, skip the entire design review silently.
|
||||
|
||||
**DESIGN.md calibration:** If `DESIGN.md` or `design-system.md` exists in the repo root, read it first. All findings are calibrated against the project's stated design system. Patterns explicitly blessed in DESIGN.md are NOT flagged. If no DESIGN.md exists, use universal design principles.
|
||||
|
||||
---
|
||||
|
||||
## Confidence Tiers
|
||||
|
||||
Each item is tagged with a detection confidence level:
|
||||
|
||||
- **[HIGH]** — Reliably detectable via grep/pattern match. Definitive findings.
|
||||
- **[MEDIUM]** — Detectable via pattern aggregation or heuristic. Flag as findings but expect some noise.
|
||||
- **[LOW]** — Requires understanding visual intent. Present as: "Possible issue — verify visually or run /design-review."
|
||||
|
||||
---
|
||||
|
||||
## Classification
|
||||
|
||||
**AUTO-FIX** (mechanical CSS fixes only — HIGH confidence, no design judgment needed):
|
||||
- `outline: none` without replacement → add `outline: revert` or `&:focus-visible { outline: 2px solid currentColor; }`
|
||||
- `!important` in new CSS → remove and fix specificity
|
||||
- `font-size` < 16px on body text → bump to 16px
|
||||
|
||||
**ASK** (everything else — requires design judgment):
|
||||
- All AI slop findings, typography structure, spacing choices, interaction state gaps, DESIGN.md violations
|
||||
|
||||
**LOW confidence items** → present as "Possible: [description]. Verify visually or run /design-review." Never AUTO-FIX.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
Design Review: N issues (X auto-fixable, Y need input, Z possible)
|
||||
|
||||
**AUTO-FIXED:**
|
||||
- [file:line] Problem → fix applied
|
||||
|
||||
**NEEDS INPUT:**
|
||||
- [file:line] Problem description
|
||||
Recommended fix: suggested fix
|
||||
|
||||
**POSSIBLE (verify visually):**
|
||||
- [file:line] Possible issue — verify with /design-review
|
||||
```
|
||||
|
||||
If no issues found: `Design Review: No issues found.`
|
||||
|
||||
If no frontend files changed: skip silently, no output.
|
||||
|
||||
---
|
||||
|
||||
## Categories
|
||||
|
||||
### 1. AI Slop Detection (6 items) — highest priority
|
||||
|
||||
These are the telltale signs of AI-generated UI that no designer at a respected studio would ship.
|
||||
|
||||
- **[MEDIUM]** Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes. Look for `linear-gradient` with values in the `#6366f1`–`#8b5cf6` range, or CSS custom properties resolving to purple/violet.
|
||||
|
||||
- **[LOW]** The 3-column feature grid: icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. Look for a grid/flex container with exactly 3 children that each contain a circular element + heading + paragraph.
|
||||
|
||||
- **[LOW]** Icons in colored circles as section decoration. Look for elements with `border-radius: 50%` + a background color used as decorative containers for icons.
|
||||
|
||||
- **[HIGH]** Centered everything: `text-align: center` on all headings, descriptions, and cards. Grep for `text-align: center` density — if >60% of text containers use center alignment, flag it.
|
||||
|
||||
- **[MEDIUM]** Uniform bubbly border-radius on every element: same large radius (16px+) applied to cards, buttons, inputs, containers uniformly. Aggregate `border-radius` values — if >80% use the same value ≥16px, flag it.
|
||||
|
||||
- **[MEDIUM]** Generic hero copy: "Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...", "Revolutionize your...", "Streamline your workflow". Grep HTML/JSX content for these patterns.
|
||||
|
||||
### 2. Typography (4 items)
|
||||
|
||||
- **[HIGH]** Body text `font-size` < 16px. Grep for `font-size` declarations on `body`, `p`, `.text`, or base styles. Values below 16px (or 1rem when base is 16px) are flagged.
|
||||
|
||||
- **[HIGH]** More than 3 font families introduced in the diff. Count distinct `font-family` declarations. Flag if >3 unique families appear across changed files.
|
||||
|
||||
- **[HIGH]** Heading hierarchy skipping levels: `h1` followed by `h3` without an `h2` in the same file/component. Check HTML/JSX for heading tags.
|
||||
|
||||
- **[HIGH]** Blacklisted fonts: Papyrus, Comic Sans, Lobster, Impact, Jokerman. Grep `font-family` for these names.
|
||||
|
||||
### 3. Spacing & Layout (4 items)
|
||||
|
||||
- **[MEDIUM]** Arbitrary spacing values not on a 4px or 8px scale, when DESIGN.md specifies a spacing scale. Check `margin`, `padding`, `gap` values against the stated scale. Only flag when DESIGN.md defines a scale.
|
||||
|
||||
- **[MEDIUM]** Fixed widths without responsive handling: `width: NNNpx` on containers without `max-width` or `@media` breakpoints. Risk of horizontal scroll on mobile.
|
||||
|
||||
- **[MEDIUM]** Missing `max-width` on text containers: body text or paragraph containers with no `max-width` set, allowing lines >75 characters. Check for `max-width` on text wrappers.
|
||||
|
||||
- **[HIGH]** `!important` in new CSS rules. Grep for `!important` in added lines. Almost always a specificity escape hatch that should be fixed properly.
|
||||
|
||||
### 4. Interaction States (3 items)
|
||||
|
||||
- **[MEDIUM]** Interactive elements (buttons, links, inputs) missing hover/focus states. Check if `:hover` and `:focus` or `:focus-visible` pseudo-classes exist for new interactive element styles.
|
||||
|
||||
- **[HIGH]** `outline: none` or `outline: 0` without a replacement focus indicator. Grep for `outline:\s*none` or `outline:\s*0`. This removes keyboard accessibility.
|
||||
|
||||
- **[LOW]** Touch targets < 44px on interactive elements. Check `min-height`/`min-width`/`padding` on buttons and links. Requires computing effective size from multiple properties — low confidence from code alone.
|
||||
|
||||
### 5. DESIGN.md Violations (3 items, conditional)
|
||||
|
||||
Only apply if `DESIGN.md` or `design-system.md` exists:
|
||||
|
||||
- **[MEDIUM]** Colors not in the stated palette. Compare color values in changed CSS against the palette defined in DESIGN.md.
|
||||
|
||||
- **[MEDIUM]** Fonts not in the stated typography section. Compare `font-family` values against DESIGN.md's font list.
|
||||
|
||||
- **[MEDIUM]** Spacing values outside the stated scale. Compare `margin`/`padding`/`gap` values against DESIGN.md's spacing scale.
|
||||
|
||||
---
|
||||
|
||||
## Suppressions
|
||||
|
||||
Do NOT flag:
|
||||
- Patterns explicitly documented in DESIGN.md as intentional choices
|
||||
- Third-party/vendor CSS files (node_modules, vendor directories)
|
||||
- CSS resets or normalize stylesheets
|
||||
- Test fixture files
|
||||
- Generated/minified CSS
|
||||
|
|
@ -0,0 +1,220 @@
|
|||
# Greptile Comment Triage
|
||||
|
||||
Shared reference for fetching, filtering, and classifying Greptile review comments on GitHub PRs. Both `/review` (Step 2.5) and `/ship` (Step 3.75) reference this document.
|
||||
|
||||
---
|
||||
|
||||
## Fetch
|
||||
|
||||
Run these commands to detect the PR and fetch comments. Both API calls run in parallel.
|
||||
|
||||
```bash
|
||||
REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
|
||||
PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null)
|
||||
```
|
||||
|
||||
**If either fails or is empty:** Skip Greptile triage silently. This integration is additive — the workflow works without it.
|
||||
|
||||
```bash
|
||||
# Fetch line-level review comments AND top-level PR comments in parallel
|
||||
gh api repos/$REPO/pulls/$PR_NUMBER/comments \
|
||||
--jq '.[] | select(.user.login == "greptile-apps[bot]") | select(.position != null) | {id: .id, path: .path, line: .line, body: .body, html_url: .html_url, source: "line-level"}' > /tmp/greptile_line.json &
|
||||
gh api repos/$REPO/issues/$PR_NUMBER/comments \
|
||||
--jq '.[] | select(.user.login == "greptile-apps[bot]") | {id: .id, body: .body, html_url: .html_url, source: "top-level"}' > /tmp/greptile_top.json &
|
||||
wait
|
||||
```
|
||||
|
||||
**If API errors or zero Greptile comments across both endpoints:** Skip silently.
|
||||
|
||||
The `position != null` filter on line-level comments automatically skips outdated comments from force-pushed code.
|
||||
|
||||
---
|
||||
|
||||
## Suppressions Check
|
||||
|
||||
Derive the project-specific history path:
|
||||
```bash
|
||||
REMOTE_SLUG=$(browse/bin/remote-slug 2>/dev/null || ~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
PROJECT_HISTORY="$HOME/.gstack/projects/$REMOTE_SLUG/greptile-history.md"
|
||||
```
|
||||
|
||||
Read `$PROJECT_HISTORY` if it exists (per-project suppressions). Each line records a previous triage outcome:
|
||||
|
||||
```
|
||||
<date> | <repo> | <type:fp|fix|already-fixed> | <file-pattern> | <category>
|
||||
```
|
||||
|
||||
**Categories** (fixed set): `race-condition`, `null-check`, `error-handling`, `style`, `type-safety`, `security`, `performance`, `correctness`, `other`
|
||||
|
||||
Match each fetched comment against entries where:
|
||||
- `type == fp` (only suppress known false positives, not previously fixed real issues)
|
||||
- `repo` matches the current repo
|
||||
- `file-pattern` matches the comment's file path
|
||||
- `category` matches the issue type in the comment
|
||||
|
||||
Skip matched comments as **SUPPRESSED**.
|
||||
|
||||
If the history file doesn't exist or has unparseable lines, skip those lines and continue — never fail on a malformed history file.
|
||||
|
||||
---
|
||||
|
||||
## Classify
|
||||
|
||||
For each non-suppressed comment:
|
||||
|
||||
1. **Line-level comments:** Read the file at the indicated `path:line` and surrounding context (±10 lines)
|
||||
2. **Top-level comments:** Read the full comment body
|
||||
3. Cross-reference the comment against the full diff (`git diff origin/main`) and the review checklist
|
||||
4. Classify:
|
||||
- **VALID & ACTIONABLE** — a real bug, race condition, security issue, or correctness problem that exists in the current code
|
||||
- **VALID BUT ALREADY FIXED** — a real issue that was addressed in a subsequent commit on the branch. Identify the fixing commit SHA.
|
||||
- **FALSE POSITIVE** — the comment misunderstands the code, flags something handled elsewhere, or is stylistic noise
|
||||
- **SUPPRESSED** — already filtered in the suppressions check above
|
||||
|
||||
---
|
||||
|
||||
## Reply APIs
|
||||
|
||||
When replying to Greptile comments, use the correct endpoint based on comment source:
|
||||
|
||||
**Line-level comments** (from `pulls/$PR/comments`):
|
||||
```bash
|
||||
gh api repos/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies \
|
||||
-f body="<reply text>"
|
||||
```
|
||||
|
||||
**Top-level comments** (from `issues/$PR/comments`):
|
||||
```bash
|
||||
gh api repos/$REPO/issues/$PR_NUMBER/comments \
|
||||
-f body="<reply text>"
|
||||
```
|
||||
|
||||
**If a reply POST fails** (e.g., PR was closed, no write permission): warn and continue. Do not stop the workflow for a failed reply.
|
||||
|
||||
---
|
||||
|
||||
## Reply Templates
|
||||
|
||||
Use these templates for every Greptile reply. Always include concrete evidence — never post vague replies.
|
||||
|
||||
### Tier 1 (First response) — Friendly, evidence-included
|
||||
|
||||
**For FIXES (user chose to fix the issue):**
|
||||
|
||||
```
|
||||
**Fixed** in `<commit-sha>`.
|
||||
|
||||
\`\`\`diff
|
||||
- <old problematic line(s)>
|
||||
+ <new fixed line(s)>
|
||||
\`\`\`
|
||||
|
||||
**Why:** <1-sentence explanation of what was wrong and how the fix addresses it>
|
||||
```
|
||||
|
||||
**For ALREADY FIXED (issue addressed in a prior commit on the branch):**
|
||||
|
||||
```
|
||||
**Already fixed** in `<commit-sha>`.
|
||||
|
||||
**What was done:** <1-2 sentences describing how the existing commit addresses this issue>
|
||||
```
|
||||
|
||||
**For FALSE POSITIVES (the comment is incorrect):**
|
||||
|
||||
```
|
||||
**Not a bug.** <1 sentence directly stating why this is incorrect>
|
||||
|
||||
**Evidence:**
|
||||
- <specific code reference showing the pattern is safe/correct>
|
||||
- <e.g., "The nil check is handled by `ActiveRecord::FinderMethods#find` which raises RecordNotFound, not nil">
|
||||
|
||||
**Suggested re-rank:** This appears to be a `<style|noise|misread>` issue, not a `<what Greptile called it>`. Consider lowering severity.
|
||||
```
|
||||
|
||||
### Tier 2 (Greptile re-flags after prior reply) — Firm, overwhelming evidence
|
||||
|
||||
Use Tier 2 when escalation detection (below) identifies a prior GStack reply on the same thread. Include maximum evidence to close the discussion.
|
||||
|
||||
```
|
||||
**This has been reviewed and confirmed as [intentional/already-fixed/not-a-bug].**
|
||||
|
||||
\`\`\`diff
|
||||
<full relevant diff showing the change or safe pattern>
|
||||
\`\`\`
|
||||
|
||||
**Evidence chain:**
|
||||
1. <file:line permalink showing the safe pattern or fix>
|
||||
2. <commit SHA where it was addressed, if applicable>
|
||||
3. <architecture rationale or design decision, if applicable>
|
||||
|
||||
**Suggested re-rank:** Please recalibrate — this is a `<actual category>` issue, not `<claimed category>`. [Link to specific file change permalink if helpful]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Escalation Detection
|
||||
|
||||
Before composing a reply, check if a prior GStack reply already exists on this comment thread:
|
||||
|
||||
1. **For line-level comments:** Fetch replies via `gh api repos/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies`. Check if any reply body contains GStack markers: `**Fixed**`, `**Not a bug.**`, `**Already fixed**`.
|
||||
|
||||
2. **For top-level comments:** Scan the fetched issue comments for replies posted after the Greptile comment that contain GStack markers.
|
||||
|
||||
3. **If a prior GStack reply exists AND Greptile posted again on the same file+category:** Use Tier 2 (firm) templates.
|
||||
|
||||
4. **If no prior GStack reply exists:** Use Tier 1 (friendly) templates.
|
||||
|
||||
If escalation detection fails (API error, ambiguous thread): default to Tier 1. Never escalate on ambiguity.
|
||||
|
||||
---
|
||||
|
||||
## Severity Assessment & Re-ranking
|
||||
|
||||
When classifying comments, also assess whether Greptile's implied severity matches reality:
|
||||
|
||||
- If Greptile flags something as a **security/correctness/race-condition** issue but it's actually a **style/performance** nit: include `**Suggested re-rank:**` in the reply requesting the category be corrected.
|
||||
- If Greptile flags a low-severity style issue as if it were critical: push back in the reply.
|
||||
- Always be specific about why the re-ranking is warranted — cite code and line numbers, not opinions.
|
||||
|
||||
---
|
||||
|
||||
## History File Writes
|
||||
|
||||
Before writing, ensure both directories exist:
|
||||
```bash
|
||||
REMOTE_SLUG=$(browse/bin/remote-slug 2>/dev/null || ~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
mkdir -p "$HOME/.gstack/projects/$REMOTE_SLUG"
|
||||
mkdir -p ~/.gstack
|
||||
```
|
||||
|
||||
Append one line per triage outcome to **both** files (per-project for suppressions, global for retro):
|
||||
- `~/.gstack/projects/$REMOTE_SLUG/greptile-history.md` (per-project)
|
||||
- `~/.gstack/greptile-history.md` (global aggregate)
|
||||
|
||||
Format:
|
||||
```
|
||||
<YYYY-MM-DD> | <owner/repo> | <type> | <file-pattern> | <category>
|
||||
```
|
||||
|
||||
Example entries:
|
||||
```
|
||||
2026-03-13 | garrytan/myapp | fp | app/services/auth_service.rb | race-condition
|
||||
2026-03-13 | garrytan/myapp | fix | app/models/user.rb | null-check
|
||||
2026-03-13 | garrytan/myapp | already-fixed | lib/payments.rb | error-handling
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Include a Greptile summary in the output header:
|
||||
```
|
||||
+ N Greptile comments (X valid, Y fixed, Z FP)
|
||||
```
|
||||
|
||||
For each classified comment, show:
|
||||
- Classification tag: `[VALID]`, `[FIXED]`, `[FALSE POSITIVE]`, `[SUPPRESSED]`
|
||||
- File:line reference (for line-level) or `[top-level]` (for top-level)
|
||||
- One-line body summary
|
||||
- Permalink URL (the `html_url` field)
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
#!/bin/bash
|
||||
# setup — Install gstack-opencode for OpenCode
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
SKILLS_DIR="$HOME/.config/opencode/skills"
|
||||
GSTACK_SKILLS_DIR="$SKILLS_DIR/gstack"
|
||||
|
||||
echo "🔧 Installing gstack-opencode..."
|
||||
|
||||
# 1. Check prerequisites
|
||||
echo "Checking prerequisites..."
|
||||
if ! command -v bun &> /dev/null; then
|
||||
echo "❌ bun is not installed. Install it first: https://bun.sh"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 2. Build browse binary if not exists
|
||||
if [ ! -f "$SCRIPT_DIR/browse/dist/browse" ]; then
|
||||
echo "Building browse binary..."
|
||||
if [ -d "$SCRIPT_DIR/source" ]; then
|
||||
(cd "$SCRIPT_DIR/source" && bun install && bun build --compile browse/src/cli.ts --outfile "$SCRIPT_DIR/browse/dist/browse")
|
||||
else
|
||||
echo "❌ Source directory not found. Clone gstack first."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# 3. Create OpenCode skills directory
|
||||
echo "Creating OpenCode skills directory..."
|
||||
mkdir -p "$GSTACK_SKILLS_DIR"
|
||||
|
||||
# 4. Symlink skills
|
||||
echo "Linking skills..."
|
||||
for skill_dir in "$SCRIPT_DIR/skills"/*/; do
|
||||
skill_name=$(basename "$skill_dir")
|
||||
target="$GSTACK_SKILLS_DIR/$skill_name"
|
||||
|
||||
if [ -L "$target" ]; then
|
||||
rm "$target"
|
||||
elif [ -d "$target" ]; then
|
||||
echo "Warning: $target exists and is not a symlink. Skipping."
|
||||
continue
|
||||
fi
|
||||
|
||||
ln -sf "$skill_dir" "$target"
|
||||
echo " ✓ Linked: $skill_name"
|
||||
done
|
||||
|
||||
# 5. Create ~/.gstack directories
|
||||
echo "Creating state directories..."
|
||||
mkdir -p ~/.gstack/{sessions,projects,analytics}
|
||||
|
||||
# 6. Create environment file
|
||||
cat > "$GSTACK_SKILLS_DIR/.env" << EOF
|
||||
export GSTACK_OPENCODE_DIR="$SCRIPT_DIR"
|
||||
export GSTACK_BROWSE="$SCRIPT_DIR/browse/dist/browse"
|
||||
EOF
|
||||
|
||||
echo ""
|
||||
echo "✅ gstack-opencode installed successfully!"
|
||||
echo ""
|
||||
echo "Skills location: $GSTACK_SKILLS_DIR"
|
||||
echo "Browse binary: $SCRIPT_DIR/browse/dist/browse"
|
||||
echo ""
|
||||
echo "Available skills:"
|
||||
ls -1 "$GSTACK_SKILLS_DIR" | sed 's/^/ \//' | head -28
|
||||
echo ""
|
||||
echo "To use in your shell, add to your .bashrc/.zshrc:"
|
||||
echo " source $SCRIPT_DIR/bin/gstack-env.sh"
|
||||
|
|
@ -0,0 +1,444 @@
|
|||
---
|
||||
name: autoplan
|
||||
description: "Auto-review pipeline — reads the full CEO, design, and eng review skills from disk and runs them sequentially with auto-decisions using 6 decision principles. Surfaces taste decisions (close approac"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Prerequisite Skill Offer
|
||||
|
||||
When the design doc check above prints "No design doc found," offer the prerequisite
|
||||
skill before proceeding.
|
||||
|
||||
Say to the user via question:
|
||||
|
||||
> "No design doc found for this branch. `/office-hours` produces a structured problem
|
||||
> statement, premise challenge, and explored alternatives — it gives this review much
|
||||
> sharper input to work with. Takes about 10 minutes. The design doc is per-feature,
|
||||
> not per-product — it captures the thinking behind this specific change."
|
||||
|
||||
Options:
|
||||
- A) Run /office-hours now (we'll pick up the review right after)
|
||||
- B) Skip — proceed with standard review
|
||||
|
||||
If they skip: "No worries — standard review. If you ever want sharper input, try
|
||||
/office-hours first next time." Then proceed normally. Do not re-offer later in the session.
|
||||
|
||||
If they choose A:
|
||||
|
||||
Say: "Running /office-hours inline. Once the design doc is ready, I'll pick up
|
||||
the review right where we left off."
|
||||
|
||||
Read the office-hours skill file from disk using the Read tool:
|
||||
`${GSTACK_OPENCODE_DIR}/office-hours/SKILL.md`
|
||||
|
||||
Follow it inline, **skipping these sections** (already handled by the parent skill):
|
||||
- Preamble (run first)
|
||||
- question Format
|
||||
- Completeness Principle — Boil the Lake
|
||||
- Search Before Building
|
||||
- Contributor Mode
|
||||
- Completion Status Protocol
|
||||
- Telemetry (run last)
|
||||
|
||||
If the Read fails (file not found), say:
|
||||
"Could not load /office-hours — proceeding with standard review."
|
||||
|
||||
After /office-hours completes, re-run the design doc check:
|
||||
```bash
|
||||
SLUG=$(${GSTACK_OPENCODE_DIR}/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
|
||||
DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
|
||||
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
|
||||
```
|
||||
|
||||
If a design doc is now found, read it and continue the review.
|
||||
If none was produced (user may have cancelled), proceed with standard review.
|
||||
|
||||
# /autoplan — Auto-Review Pipeline
|
||||
|
||||
One command. Rough plan in, fully reviewed plan out.
|
||||
|
||||
/autoplan reads the full CEO, design, and eng review skill files from disk and follows
|
||||
them at full depth — same rigor, same sections, same methodology as running each skill
|
||||
manually. The only difference: intermediate question calls are auto-decided using
|
||||
the 6 principles below. Taste decisions (where reasonable people could disagree) are
|
||||
surfaced at a final approval gate.
|
||||
|
||||
---
|
||||
|
||||
## The 6 Decision Principles
|
||||
|
||||
These rules auto-answer every intermediate question:
|
||||
|
||||
1. **Choose completeness** — Ship the whole thing. Pick the approach that covers more edge cases.
|
||||
2. **Boil lakes** — Fix everything in the blast radius (files modified by this plan + direct importers). Auto-approve expansions that are in blast radius AND < 1 day CC effort (< 5 files, no new infra).
|
||||
3. **Pragmatic** — If two options fix the same thing, pick the cleaner one. 5 seconds choosing, not 5 minutes.
|
||||
4. **DRY** — Duplicates existing functionality? Reject. Reuse what exists.
|
||||
5. **Explicit over clever** — 10-line obvious fix > 200-line abstraction. Pick what a new contributor reads in 30 seconds.
|
||||
6. **Bias toward action** — Merge > review cycles > stale deliberation. Flag concerns but don't block.
|
||||
|
||||
**Conflict resolution (context-dependent tiebreakers):**
|
||||
- **CEO phase:** P1 (completeness) + P2 (boil lakes) dominate.
|
||||
- **Eng phase:** P5 (explicit) + P3 (pragmatic) dominate.
|
||||
- **Design phase:** P5 (explicit) + P1 (completeness) dominate.
|
||||
|
||||
---
|
||||
|
||||
## Decision Classification
|
||||
|
||||
Every auto-decision is classified:
|
||||
|
||||
**Mechanical** — one clearly right answer. Auto-decide silently.
|
||||
Examples: run codex (always yes), run evals (always yes), reduce scope on a complete plan (always no).
|
||||
|
||||
**Taste** — reasonable people could disagree. Auto-decide with recommendation, but surface at the final gate. Three natural sources:
|
||||
1. **Close approaches** — top two are both viable with different tradeoffs.
|
||||
2. **Borderline scope** — in blast radius but 3-5 files, or ambiguous radius.
|
||||
3. **Codex disagreements** — codex recommends differently and has a valid point.
|
||||
|
||||
---
|
||||
|
||||
## What "Auto-Decide" Means
|
||||
|
||||
Auto-decide replaces the USER'S judgment with the 6 principles. It does NOT replace
|
||||
the ANALYSIS. Every section in the loaded skill files must still be executed at the
|
||||
same depth as the interactive version. The only thing that changes is who answers the
|
||||
question: you do, using the 6 principles, instead of the user.
|
||||
|
||||
**You MUST still:**
|
||||
- READ the actual code, diffs, and files each section references
|
||||
- PRODUCE every output the section requires (diagrams, tables, registries, artifacts)
|
||||
- IDENTIFY every issue the section is designed to catch
|
||||
- DECIDE each issue using the 6 principles (instead of asking the user)
|
||||
- LOG each decision in the audit trail
|
||||
- WRITE all required artifacts to disk
|
||||
|
||||
**You MUST NOT:**
|
||||
- Compress a review section into a one-liner table row
|
||||
- Write "no issues found" without showing what you examined
|
||||
- Skip a section because "it doesn't apply" without stating what you checked and why
|
||||
- Produce a summary instead of the required output (e.g., "architecture looks good"
|
||||
instead of the ASCII dependency graph the section requires)
|
||||
|
||||
"No issues found" is a valid output for a section — but only after doing the analysis.
|
||||
State what you examined and why nothing was flagged (1-2 sentences minimum).
|
||||
"Skipped" is never valid for a non-skip-listed section.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Intake + Restore Point
|
||||
|
||||
### Step 1: Capture restore point
|
||||
|
||||
Before doing anything, save the plan file's current state to an external file:
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-')
|
||||
DATETIME=$(date +%Y%m%d-%H%M%S)
|
||||
echo "RESTORE_PATH=$HOME/.gstack/projects/$SLUG/${BRANCH}-autoplan-restore-${DATETIME}.md"
|
||||
```
|
||||
|
||||
Write the plan file's full contents to the restore path with this header:
|
||||
```
|
||||
# /autoplan Restore Point
|
||||
Captured: [timestamp] | Branch: [branch] | Commit: [short hash]
|
||||
|
||||
## Re-run Instructions
|
||||
1. Copy "Original Plan State" below back to your plan file
|
||||
2. Invoke /autoplan
|
||||
|
||||
## Original Plan State
|
||||
[verbatim plan file contents]
|
||||
```
|
||||
|
||||
Then prepend a one-line HTML comment to the plan file:
|
||||
`<!-- /autoplan restore point: [RESTORE_PATH] -->`
|
||||
|
||||
### Step 2: Read context
|
||||
|
||||
- Read CLAUDE.md, TODOS.md, git log -30, git diff against the base branch --stat
|
||||
- Discover design docs: `ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1`
|
||||
- Detect UI scope: grep the plan for view/rendering terms (component, screen, form,
|
||||
button, modal, layout, dashboard, sidebar, nav, dialog). Require 2+ matches. Exclude
|
||||
false positives ("page" alone, "UI" in acronyms).
|
||||
|
||||
### Step 3: Load skill files from disk
|
||||
|
||||
Read each file using the Read tool:
|
||||
- `${GSTACK_OPENCODE_DIR}/plan-ceo-review/SKILL.md`
|
||||
- `${GSTACK_OPENCODE_DIR}/plan-design-review/SKILL.md` (only if UI scope detected)
|
||||
- `${GSTACK_OPENCODE_DIR}/plan-eng-review/SKILL.md`
|
||||
|
||||
**Section skip list — when following a loaded skill file, SKIP these sections
|
||||
(they are already handled by /autoplan):**
|
||||
- Preamble (run first)
|
||||
- question Format
|
||||
- Completeness Principle — Boil the Lake
|
||||
- Search Before Building
|
||||
- Contributor Mode
|
||||
- Completion Status Protocol
|
||||
- Telemetry (run last)
|
||||
- Step 0: Detect base branch
|
||||
- Review Readiness Dashboard
|
||||
- Plan File Review Report
|
||||
- Prerequisite Skill Offer (BENEFITS_FROM)
|
||||
|
||||
Follow ONLY the review-specific methodology, sections, and required outputs.
|
||||
|
||||
Output: "Here's what I'm working with: [plan summary]. UI scope: [yes/no].
|
||||
Loaded review skills from disk. Starting full review pipeline with auto-decisions."
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: CEO Review (Strategy & Scope)
|
||||
|
||||
Follow plan-ceo-review/SKILL.md — all sections, full depth.
|
||||
Override: every question → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Mode selection: SELECTIVE EXPANSION
|
||||
- Premises: accept reasonable ones (P6), challenge only clearly wrong ones
|
||||
- **GATE: Present premises to user for confirmation** — this is the ONE question
|
||||
that is NOT auto-decided. Premises require human judgment.
|
||||
- Alternatives: pick highest completeness (P1). If tied, pick simplest (P5).
|
||||
If top 2 are close → mark TASTE DECISION.
|
||||
- Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3).
|
||||
Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION.
|
||||
- All 10 review sections: run fully, auto-decide each issue, log every decision.
|
||||
|
||||
**Required execution checklist (CEO):**
|
||||
|
||||
Step 0 (0A-0F) — run each sub-step and produce:
|
||||
- 0A: Premise challenge with specific premises named and evaluated
|
||||
- 0B: Existing code leverage map (sub-problems → existing code)
|
||||
- 0C: Dream state diagram (CURRENT → THIS PLAN → 12-MONTH IDEAL)
|
||||
- 0C-bis: Implementation alternatives table (2-3 approaches with effort/risk/pros/cons)
|
||||
- 0D: Mode-specific analysis with scope decisions logged
|
||||
- 0E: Temporal interrogation (HOUR 1 → HOUR 6+)
|
||||
- 0F: Mode selection confirmation
|
||||
|
||||
Sections 1-10 — for EACH section, run the evaluation criteria from the loaded skill file:
|
||||
- Sections WITH findings: full analysis, auto-decide each issue, log to audit trail
|
||||
- Sections with NO findings: 1-2 sentences stating what was examined and why nothing
|
||||
was flagged. NEVER compress a section to just its name in a table row.
|
||||
- Section 11 (Design): run only if UI scope was detected in Phase 0
|
||||
|
||||
**Mandatory outputs from Phase 1:**
|
||||
- "NOT in scope" section with deferred items and rationale
|
||||
- "What already exists" section mapping sub-problems to existing code
|
||||
- Error & Rescue Registry table (from Section 2)
|
||||
- Failure Modes Registry table (from review sections)
|
||||
- Dream state delta (where this plan leaves us vs 12-month ideal)
|
||||
- Completion Summary (the full summary table from the CEO skill)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Design Review (conditional — skip if no UI scope)
|
||||
|
||||
Follow plan-design-review/SKILL.md — all 7 dimensions, full depth.
|
||||
Override: every question → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Focus areas: all relevant dimensions (P1)
|
||||
- Structural issues (missing states, broken hierarchy): auto-fix (P5)
|
||||
- Aesthetic/taste issues: mark TASTE DECISION
|
||||
- Design system alignment: auto-fix if DESIGN.md exists and fix is obvious
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Eng Review + Codex
|
||||
|
||||
Follow plan-eng-review/SKILL.md — all sections, full depth.
|
||||
Override: every question → auto-decide using the 6 principles.
|
||||
|
||||
**Override rules:**
|
||||
- Scope challenge: never reduce (P2)
|
||||
- Codex review: always run if available (P6)
|
||||
Command: `codex exec "Review this plan for architectural issues, missing edge cases, and hidden complexity. Be adversarial. File: <plan_path>" -s read-only --enable web_search_cached`
|
||||
Timeout: 10 minutes, then proceed with "Codex timed out — single-reviewer mode"
|
||||
- Architecture choices: explicit over clever (P5). If codex disagrees with valid reason → TASTE DECISION.
|
||||
- Evals: always include all relevant suites (P1)
|
||||
- Test plan: generate artifact at `~/.gstack/projects/$SLUG/{user}-{branch}-test-plan-{datetime}.md`
|
||||
- TODOS.md: collect all deferred scope expansions from Phase 1, auto-write
|
||||
|
||||
**Required execution checklist (Eng):**
|
||||
|
||||
1. Step 0 (Scope Challenge): Read actual code referenced by the plan. Map each
|
||||
sub-problem to existing code. Run the complexity check. Produce concrete findings.
|
||||
|
||||
2. Step 0.5 (Codex): Run if available. Present full output under CODEX SAYS header.
|
||||
|
||||
3. Section 1 (Architecture): Produce ASCII dependency graph showing new components
|
||||
and their relationships to existing ones. Evaluate coupling, scaling, security.
|
||||
|
||||
4. Section 2 (Code Quality): Identify DRY violations, naming issues, complexity.
|
||||
Reference specific files and patterns. Auto-decide each finding.
|
||||
|
||||
5. **Section 3 (Test Review) — NEVER SKIP OR COMPRESS.**
|
||||
This section requires reading actual code, not summarizing from memory.
|
||||
- Read the diff or the plan's affected files
|
||||
- Build the test diagram: list every NEW UX flow, data flow, codepath, and branch
|
||||
- For EACH item in the diagram: what type of test covers it? Does one exist? Gaps?
|
||||
- For LLM/prompt changes: which eval suites must run?
|
||||
- Auto-deciding test gaps means: identify the gap → decide whether to add a test
|
||||
or defer (with rationale and principle) → log the decision. It does NOT mean
|
||||
skipping the analysis.
|
||||
- Write the test plan artifact to disk
|
||||
|
||||
6. Section 4 (Performance): Evaluate N+1 queries, memory, caching, slow paths.
|
||||
|
||||
**Mandatory outputs from Phase 3:**
|
||||
- "NOT in scope" section
|
||||
- "What already exists" section
|
||||
- Architecture ASCII diagram (Section 1)
|
||||
- Test diagram mapping codepaths to coverage (Section 3)
|
||||
- Test plan artifact written to disk (Section 3)
|
||||
- Failure modes registry with critical gap flags
|
||||
- Completion Summary (the full summary from the Eng skill)
|
||||
- TODOS.md updates (collected from all phases)
|
||||
|
||||
---
|
||||
|
||||
## Decision Audit Trail
|
||||
|
||||
After each auto-decision, append a row to the plan file using Edit:
|
||||
|
||||
```markdown
|
||||
<!-- AUTONOMOUS DECISION LOG -->
|
||||
## Decision Audit Trail
|
||||
|
||||
| # | Phase | Decision | Principle | Rationale | Rejected |
|
||||
|---|-------|----------|-----------|-----------|----------|
|
||||
```
|
||||
|
||||
Write one row per decision incrementally (via Edit). This keeps the audit on disk,
|
||||
not accumulated in conversation context.
|
||||
|
||||
---
|
||||
|
||||
## Pre-Gate Verification
|
||||
|
||||
Before presenting the Final Approval Gate, verify that required outputs were actually
|
||||
produced. Check the plan file and conversation for each item.
|
||||
|
||||
**Phase 1 (CEO) outputs:**
|
||||
- [ ] Premise challenge with specific premises named (not just "premises accepted")
|
||||
- [ ] All applicable review sections have findings OR explicit "examined X, nothing flagged"
|
||||
- [ ] Error & Rescue Registry table produced (or noted N/A with reason)
|
||||
- [ ] Failure Modes Registry table produced (or noted N/A with reason)
|
||||
- [ ] "NOT in scope" section written
|
||||
- [ ] "What already exists" section written
|
||||
- [ ] Dream state delta written
|
||||
- [ ] Completion Summary produced
|
||||
|
||||
**Phase 2 (Design) outputs — only if UI scope detected:**
|
||||
- [ ] All 7 dimensions evaluated with scores
|
||||
- [ ] Issues identified and auto-decided
|
||||
|
||||
**Phase 3 (Eng) outputs:**
|
||||
- [ ] Scope challenge with actual code analysis (not just "scope is fine")
|
||||
- [ ] Architecture ASCII diagram produced
|
||||
- [ ] Test diagram mapping codepaths to test coverage
|
||||
- [ ] Test plan artifact written to disk at ~/.gstack/projects/$SLUG/
|
||||
- [ ] "NOT in scope" section written
|
||||
- [ ] "What already exists" section written
|
||||
- [ ] Failure modes registry with critical gap assessment
|
||||
- [ ] Completion Summary produced
|
||||
|
||||
**Audit trail:**
|
||||
- [ ] Decision Audit Trail has at least one row per auto-decision (not empty)
|
||||
|
||||
If ANY checkbox above is missing, go back and produce the missing output. Max 2
|
||||
attempts — if still missing after retrying twice, proceed to the gate with a warning
|
||||
noting which items are incomplete. Do not loop indefinitely.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Final Approval Gate
|
||||
|
||||
**STOP here and present the final state to the user.**
|
||||
|
||||
Present as a message, then use question:
|
||||
|
||||
```
|
||||
## /autoplan Review Complete
|
||||
|
||||
### Plan Summary
|
||||
[1-3 sentence summary]
|
||||
|
||||
### Decisions Made: [N] total ([M] auto-decided, [K] choices for you)
|
||||
|
||||
### Your Choices (taste decisions)
|
||||
[For each taste decision:]
|
||||
**Choice [N]: [title]** (from [phase])
|
||||
I recommend [X] — [principle]. But [Y] is also viable:
|
||||
[1-sentence downstream impact if you pick Y]
|
||||
|
||||
### Auto-Decided: [M] decisions [see Decision Audit Trail in plan file]
|
||||
|
||||
### Review Scores
|
||||
- CEO: [summary]
|
||||
- Design: [summary or "skipped, no UI scope"]
|
||||
- Eng: [summary]
|
||||
- Codex: [summary or "unavailable"]
|
||||
|
||||
### Deferred to TODOS.md
|
||||
[Items auto-deferred with reasons]
|
||||
```
|
||||
|
||||
**Cognitive load management:**
|
||||
- 0 taste decisions: skip "Your Choices" section
|
||||
- 1-7 taste decisions: flat list
|
||||
- 8+: group by phase. Add warning: "This plan had unusually high ambiguity ([N] taste decisions). Review carefully."
|
||||
|
||||
question options:
|
||||
- A) Approve as-is (accept all recommendations)
|
||||
- B) Approve with overrides (specify which taste decisions to change)
|
||||
- C) Interrogate (ask about any specific decision)
|
||||
- D) Revise (the plan itself needs changes)
|
||||
- E) Reject (start over)
|
||||
|
||||
**Option handling:**
|
||||
- A: mark APPROVED, write review logs, suggest /ship
|
||||
- B: ask which overrides, apply, re-present gate
|
||||
- C: answer freeform, re-present gate
|
||||
- D: make changes, re-run affected phases (scope→1B, design→2, test plan→3, arch→3). Max 3 cycles.
|
||||
- E: start over
|
||||
|
||||
---
|
||||
|
||||
## Completion: Write Review Logs
|
||||
|
||||
On approval, write 3 separate review log entries so /ship's dashboard recognizes them:
|
||||
|
||||
```bash
|
||||
COMMIT=$(git rev-parse --short HEAD 2>/dev/null)
|
||||
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"mode":"SELECTIVE_EXPANSION","via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-eng-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"issues_found":0,"mode":"FULL_REVIEW","via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
```
|
||||
|
||||
If Phase 2 ran (UI scope):
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"via":"autoplan","commit":"'"$COMMIT"'"}'
|
||||
```
|
||||
|
||||
Replace field values with actual counts from the review.
|
||||
|
||||
Suggest next step: `/ship` when ready to create the PR.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Never abort.** The user chose /autoplan. Respect that choice. Surface all taste decisions, never redirect to interactive review.
|
||||
- **Premises are the one gate.** The only non-auto-decided question is the premise confirmation in Phase 1.
|
||||
- **Log every decision.** No silent auto-decisions. Every choice gets a row in the audit trail.
|
||||
- **Full depth means full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0). "Full depth" means: read the code the section asks you to read, produce the outputs the section requires, identify every issue, and decide each one. A one-sentence summary of a section is not "full depth" — it is a skip. If you catch yourself writing fewer than 3 sentences for any review section, you are likely compressing.
|
||||
- **Artifacts are deliverables.** Test plan artifact, failure modes registry, error/rescue table, ASCII diagrams — these must exist on disk or in the plan file when the review completes. If they don't exist, the review is incomplete.
|
||||
- **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: benchmark
|
||||
description: "Performance regression detection using the browse daemon. Establishes baselines for page load times, Core Web Vitals, and resource sizes. Compares before/after on every PR. Tracks performance trends o"
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: browse
|
||||
description: "Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with elements, verify page state, diff before/after actions, take annotated screenshots, check responsive layouts, "
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,204 @@
|
|||
---
|
||||
name: canary
|
||||
description: "Post-deploy canary monitoring. Watches the live app for console errors, performance regressions, and page failures using the browse daemon. Takes periodic screenshots, compares against pre-deploy base"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /canary — Post-Deploy Visual Monitor
|
||||
|
||||
You are a **Release Reliability Engineer** watching production after a deploy. You've seen deploys that pass CI but break in production — a missing environment variable, a CDN cache serving stale assets, a database migration that's slower than expected on real data. Your job is to catch these in the first 10 minutes, not 10 hours.
|
||||
|
||||
You use the browse daemon to watch the live app, take screenshots, check console errors, and compare against baselines. You are the safety net between "shipped" and "verified."
|
||||
|
||||
## User-invocable
|
||||
When the user types `/canary`, run this skill.
|
||||
|
||||
## Arguments
|
||||
- `/canary <url>` — monitor a URL for 10 minutes after deploy
|
||||
- `/canary <url> --duration 5m` — custom monitoring duration (1m to 30m)
|
||||
- `/canary <url> --baseline` — capture baseline screenshots (run BEFORE deploying)
|
||||
- `/canary <url> --pages /,/dashboard,/settings` — specify pages to monitor
|
||||
- `/canary <url> --quick` — single-pass health check (no continuous monitoring)
|
||||
|
||||
## Instructions
|
||||
|
||||
### Phase 1: Setup
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null || echo "SLUG=unknown")"
|
||||
mkdir -p .gstack/canary-reports
|
||||
mkdir -p .gstack/canary-reports/baselines
|
||||
mkdir -p .gstack/canary-reports/screenshots
|
||||
```
|
||||
|
||||
Parse the user's arguments. Default duration is 10 minutes. Default pages: auto-discover from the app's navigation.
|
||||
|
||||
### Phase 2: Baseline Capture (--baseline mode)
|
||||
|
||||
If the user passed `--baseline`, capture the current state BEFORE deploying.
|
||||
|
||||
For each page (either from `--pages` or the homepage):
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <page-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o ".gstack/canary-reports/baselines/<page-name>.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} perf
|
||||
${GSTACK_BROWSE} text
|
||||
```
|
||||
|
||||
Collect for each page: screenshot path, console error count, page load time from `perf`, and a text content snapshot.
|
||||
|
||||
Save the baseline manifest to `.gstack/canary-reports/baseline.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "<url>",
|
||||
"timestamp": "<ISO>",
|
||||
"branch": "<current branch>",
|
||||
"pages": {
|
||||
"/": {
|
||||
"screenshot": "baselines/home.png",
|
||||
"console_errors": 0,
|
||||
"load_time_ms": 450
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then STOP and tell the user: "Baseline captured. Deploy your changes, then run `/canary <url>` to monitor."
|
||||
|
||||
### Phase 3: Page Discovery
|
||||
|
||||
If no `--pages` were specified, auto-discover pages to monitor:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <url>
|
||||
${GSTACK_BROWSE} links
|
||||
${GSTACK_BROWSE} snapshot -i
|
||||
```
|
||||
|
||||
Extract the top 5 internal navigation links from the `links` output. Always include the homepage. Present the page list via question:
|
||||
|
||||
- **Context:** Monitoring the production site at the given URL after a deploy.
|
||||
- **Question:** Which pages should the canary monitor?
|
||||
- **RECOMMENDATION:** Choose A — these are the main navigation targets.
|
||||
- A) Monitor these pages: [list the discovered pages]
|
||||
- B) Add more pages (user specifies)
|
||||
- C) Monitor homepage only (quick check)
|
||||
|
||||
### Phase 4: Pre-Deploy Snapshot (if no baseline exists)
|
||||
|
||||
If no `baseline.json` exists, take a quick snapshot now as a reference point.
|
||||
|
||||
For each page to monitor:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <page-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o ".gstack/canary-reports/screenshots/pre-<page-name>.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} perf
|
||||
```
|
||||
|
||||
Record the console error count and load time for each page. These become the reference for detecting regressions during monitoring.
|
||||
|
||||
### Phase 5: Continuous Monitoring Loop
|
||||
|
||||
Monitor for the specified duration. Every 60 seconds, check each page:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <page-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o ".gstack/canary-reports/screenshots/<page-name>-<check-number>.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} perf
|
||||
```
|
||||
|
||||
After each check, compare results against the baseline (or pre-deploy snapshot):
|
||||
|
||||
1. **Page load failure** — `goto` returns error or timeout → CRITICAL ALERT
|
||||
2. **New console errors** — errors not present in baseline → HIGH ALERT
|
||||
3. **Performance regression** — load time exceeds 2x baseline → MEDIUM ALERT
|
||||
4. **Broken links** — new 404s not in baseline → LOW ALERT
|
||||
|
||||
**Alert on changes, not absolutes.** A page with 3 console errors in the baseline is fine if it still has 3. One NEW error is an alert.
|
||||
|
||||
**Don't cry wolf.** Only alert on patterns that persist across 2 or more consecutive checks. A single transient network blip is not an alert.
|
||||
|
||||
**If a CRITICAL or HIGH alert is detected**, immediately notify the user via question:
|
||||
|
||||
```
|
||||
CANARY ALERT
|
||||
════════════
|
||||
Time: [timestamp, e.g., check #3 at 180s]
|
||||
Page: [page URL]
|
||||
Type: [CRITICAL / HIGH / MEDIUM]
|
||||
Finding: [what changed — be specific]
|
||||
Evidence: [screenshot path]
|
||||
Baseline: [baseline value]
|
||||
Current: [current value]
|
||||
```
|
||||
|
||||
- **Context:** Canary monitoring detected an issue on [page] after [duration].
|
||||
- **RECOMMENDATION:** Choose based on severity — A for critical, B for transient.
|
||||
- A) Investigate now — stop monitoring, focus on this issue
|
||||
- B) Continue monitoring — this might be transient (wait for next check)
|
||||
- C) Rollback — revert the deploy immediately
|
||||
- D) Dismiss — false positive, continue monitoring
|
||||
|
||||
### Phase 6: Health Report
|
||||
|
||||
After monitoring completes (or if the user stops early), produce a summary:
|
||||
|
||||
```
|
||||
CANARY REPORT — [url]
|
||||
═════════════════════
|
||||
Duration: [X minutes]
|
||||
Pages: [N pages monitored]
|
||||
Checks: [N total checks performed]
|
||||
Status: [HEALTHY / DEGRADED / BROKEN]
|
||||
|
||||
Per-Page Results:
|
||||
─────────────────────────────────────────────────────
|
||||
Page Status Errors Avg Load
|
||||
/ HEALTHY 0 450ms
|
||||
/dashboard DEGRADED 2 new 1200ms (was 400ms)
|
||||
/settings HEALTHY 0 380ms
|
||||
|
||||
Alerts Fired: [N] (X critical, Y high, Z medium)
|
||||
Screenshots: .gstack/canary-reports/screenshots/
|
||||
|
||||
VERDICT: [DEPLOY IS HEALTHY / DEPLOY HAS ISSUES — details above]
|
||||
```
|
||||
|
||||
Save report to `.gstack/canary-reports/{date}-canary.md` and `.gstack/canary-reports/{date}-canary.json`.
|
||||
|
||||
Log the result for the review dashboard:
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
|
||||
Write a JSONL entry: `{"skill":"canary","timestamp":"<ISO>","status":"<HEALTHY/DEGRADED/BROKEN>","url":"<url>","duration_min":<N>,"alerts":<N>}`
|
||||
|
||||
### Phase 7: Baseline Update
|
||||
|
||||
If the deploy is healthy, offer to update the baseline:
|
||||
|
||||
- **Context:** Canary monitoring completed. The deploy is healthy.
|
||||
- **RECOMMENDATION:** Choose A — deploy is healthy, new baseline reflects current production.
|
||||
- A) Update baseline with current screenshots
|
||||
- B) Keep old baseline
|
||||
|
||||
If the user chooses A, copy the latest screenshots to the baselines directory and update `baseline.json`.
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Speed matters.** Start monitoring within 30 seconds of invocation. Don't over-analyze before monitoring.
|
||||
- **Alert on changes, not absolutes.** Compare against baseline, not industry standards.
|
||||
- **Screenshots are evidence.** Every alert includes a screenshot path. No exceptions.
|
||||
- **Transient tolerance.** Only alert on patterns that persist across 2+ consecutive checks.
|
||||
- **Baseline is king.** Without a baseline, canary is a health check. Encourage `--baseline` before deploying.
|
||||
- **Performance thresholds are relative.** 2x baseline is a regression. 1.5x might be normal variance.
|
||||
- **Read-only.** Observe and report. Don't modify code unless the user explicitly asks to investigate and fix.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: careful
|
||||
description: "Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE, force-push, git reset --hard, kubectl delete, and similar destructive operations. User can override each warning. Use when "
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,406 @@
|
|||
---
|
||||
name: codex
|
||||
description: "OpenAI Codex CLI wrapper — three modes. Code review: independent diff review via codex review with pass/fail gate. Challenge: adversarial mode that tries to break your code. Consult: ask codex anyth"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /codex — Multi-AI Second Opinion
|
||||
|
||||
You are running the `/codex` skill. This wraps the OpenAI Codex CLI to get an independent,
|
||||
brutally honest second opinion from a different AI system.
|
||||
|
||||
Codex is the "200 IQ autistic developer" — direct, terse, technically precise, challenges
|
||||
assumptions, catches things you might miss. Present its output faithfully, not summarized.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Check codex binary
|
||||
|
||||
```bash
|
||||
CODEX_BIN=$(which codex 2>/dev/null || echo "")
|
||||
[ -z "$CODEX_BIN" ] && echo "NOT_FOUND" || echo "FOUND: $CODEX_BIN"
|
||||
```
|
||||
|
||||
If `NOT_FOUND`: stop and tell the user:
|
||||
"Codex CLI not found. Install it: `npm install -g @openai/codex` or see https://github.com/openai/codex"
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Detect mode
|
||||
|
||||
Parse the user's input to determine which mode to run:
|
||||
|
||||
1. `/codex review` or `/codex review <instructions>` — **Review mode** (Step 2A)
|
||||
2. `/codex challenge` or `/codex challenge <focus>` — **Challenge mode** (Step 2B)
|
||||
3. `/codex` with no arguments — **Auto-detect:**
|
||||
- Check for a diff (with fallback if origin isn't available):
|
||||
`git diff origin/<base> --stat 2>/dev/null | tail -1 || git diff <base> --stat 2>/dev/null | tail -1`
|
||||
- If a diff exists, use question:
|
||||
```
|
||||
Codex detected changes against the base branch. What should it do?
|
||||
A) Review the diff (code review with pass/fail gate)
|
||||
B) Challenge the diff (adversarial — try to break it)
|
||||
C) Something else — I'll provide a prompt
|
||||
```
|
||||
- If no diff, check for plan files scoped to the current project:
|
||||
`ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1`
|
||||
If no project-scoped match, fall back to: `ls -t ~/.claude/plans/*.md 2>/dev/null | head -1`
|
||||
but warn the user: "Note: this plan may be from a different project."
|
||||
- If a plan file exists, offer to review it
|
||||
- Otherwise, ask: "What would you like to ask Codex?"
|
||||
4. `/codex <anything else>` — **Consult mode** (Step 2C), where the remaining text is the prompt
|
||||
|
||||
---
|
||||
|
||||
## Step 2A: Review Mode
|
||||
|
||||
Run Codex code review against the current branch diff.
|
||||
|
||||
1. Create temp files for output capture:
|
||||
```bash
|
||||
TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)
|
||||
```
|
||||
|
||||
2. Run the review (5-minute timeout):
|
||||
```bash
|
||||
codex review --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"
|
||||
```
|
||||
|
||||
Use `timeout: 300000` on the Bash call. If the user provided custom instructions
|
||||
(e.g., `/codex review focus on security`), pass them as the prompt argument:
|
||||
```bash
|
||||
codex review "focus on security" --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"
|
||||
```
|
||||
|
||||
3. Capture the output. Then parse cost from stderr:
|
||||
```bash
|
||||
grep "tokens used" "$TMPERR" 2>/dev/null || echo "tokens: unknown"
|
||||
```
|
||||
|
||||
4. Determine gate verdict by checking the review output for critical findings.
|
||||
If the output contains `[P1]` — the gate is **FAIL**.
|
||||
If no `[P1]` markers are found (only `[P2]` or no findings) — the gate is **PASS**.
|
||||
|
||||
5. Present the output:
|
||||
|
||||
```
|
||||
CODEX SAYS (code review):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full codex output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
GATE: PASS Tokens: 14,331 | Est. cost: ~$0.12
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
GATE: FAIL (N critical findings)
|
||||
```
|
||||
|
||||
6. **Cross-model comparison:** If `/review` (Claude's own review) was already run
|
||||
earlier in this conversation, compare the two sets of findings:
|
||||
|
||||
```
|
||||
CROSS-MODEL ANALYSIS:
|
||||
Both found: [findings that overlap between Claude and Codex]
|
||||
Only Codex found: [findings unique to Codex]
|
||||
Only Claude found: [findings unique to Claude's /review]
|
||||
Agreement rate: X% (N/M total unique findings overlap)
|
||||
```
|
||||
|
||||
7. Persist the review result:
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"codex-review","timestamp":"TIMESTAMP","status":"STATUS","gate":"GATE","findings":N,"findings_fixed":N}'
|
||||
```
|
||||
|
||||
Substitute: TIMESTAMP (ISO 8601), STATUS ("clean" if PASS, "issues_found" if FAIL),
|
||||
GATE ("pass" or "fail"), findings (count of [P1] + [P2] markers),
|
||||
findings_fixed (count of findings that were addressed/fixed before shipping).
|
||||
|
||||
8. Clean up temp files:
|
||||
```bash
|
||||
rm -f "$TMPERR"
|
||||
```
|
||||
|
||||
## Plan File Review Report
|
||||
|
||||
After displaying the Review Readiness Dashboard in conversation output, also update the
|
||||
**plan file** itself so review status is visible to anyone reading the plan.
|
||||
|
||||
### Detect the plan file
|
||||
|
||||
1. Check if there is an active plan file in this conversation (the host provides plan file
|
||||
paths in system messages — look for plan file references in the conversation context).
|
||||
2. If not found, skip this section silently — not every review runs in plan mode.
|
||||
|
||||
### Generate the report
|
||||
|
||||
Read the review log output you already have from the Review Readiness Dashboard step above.
|
||||
Parse each JSONL entry. Each skill logs different fields:
|
||||
|
||||
- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
|
||||
→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
|
||||
→ If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
|
||||
- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
|
||||
→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"
|
||||
- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
|
||||
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
|
||||
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
|
||||
|
||||
All fields needed for the Findings column are now present in the JSONL entries.
|
||||
For the review you just completed, you may use richer details from your own Completion
|
||||
Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
|
||||
|
||||
Produce this markdown table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines (omit any that are empty/not applicable):
|
||||
|
||||
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
|
||||
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
|
||||
- **UNRESOLVED:** total unresolved decisions across all reviews
|
||||
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
|
||||
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
|
||||
|
||||
### Write to the plan file
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file
|
||||
(not just at the end — content may have been added after it).
|
||||
- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\`
|
||||
through either the next \`## \` heading or end of file, whichever comes first. This ensures
|
||||
content added after the report section is preserved, not eaten. If the Edit fails
|
||||
(e.g., concurrent edit changed the content), re-read the plan file and retry once.
|
||||
- If no such section exists, **append it** to the end of the plan file.
|
||||
- Always place it as the very last section in the plan file. If it was found mid-file,
|
||||
move it: delete the old location and append at the end.
|
||||
|
||||
---
|
||||
|
||||
## Step 2B: Challenge (Adversarial) Mode
|
||||
|
||||
Codex tries to break your code — finding edge cases, race conditions, security holes,
|
||||
and failure modes that a normal review would miss.
|
||||
|
||||
1. Construct the adversarial prompt. If the user provided a focus area
|
||||
(e.g., `/codex challenge security`), include it:
|
||||
|
||||
Default prompt (no focus):
|
||||
"Review the changes on this branch against the base branch. Run `git diff origin/<base>` to see the diff. Your job is to find ways this code will fail in production. Think like an attacker and a chaos engineer. Find edge cases, race conditions, security holes, resource leaks, failure modes, and silent data corruption paths. Be adversarial. Be thorough. No compliments — just the problems."
|
||||
|
||||
With focus (e.g., "security"):
|
||||
"Review the changes on this branch against the base branch. Run `git diff origin/<base>` to see the diff. Focus specifically on SECURITY. Your job is to find every way an attacker could exploit this code. Think about injection vectors, auth bypasses, privilege escalation, data exposure, and timing attacks. Be adversarial."
|
||||
|
||||
2. Run codex exec with **JSONL output** to capture reasoning traces and tool calls (5-minute timeout):
|
||||
```bash
|
||||
codex exec "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
for line in sys.stdin:
|
||||
line = line.strip()
|
||||
if not line: continue
|
||||
try:
|
||||
obj = json.loads(line)
|
||||
t = obj.get('type','')
|
||||
if t == 'item.completed' and 'item' in obj:
|
||||
item = obj['item']
|
||||
itype = item.get('type','')
|
||||
text = item.get('text','')
|
||||
if itype == 'reasoning' and text:
|
||||
print(f'[codex thinking] {text}')
|
||||
print()
|
||||
elif itype == 'agent_message' and text:
|
||||
print(text)
|
||||
elif itype == 'command_execution':
|
||||
cmd = item.get('command','')
|
||||
if cmd: print(f'[codex ran] {cmd}')
|
||||
elif t == 'turn.completed':
|
||||
usage = obj.get('usage',{})
|
||||
tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
|
||||
if tokens: print(f'\ntokens used: {tokens}')
|
||||
except: pass
|
||||
"
|
||||
```
|
||||
|
||||
This parses codex's JSONL events to extract reasoning traces, tool calls, and the final
|
||||
response. The `[codex thinking]` lines show what codex reasoned through before its answer.
|
||||
|
||||
3. Present the full streamed output:
|
||||
|
||||
```
|
||||
CODEX SAYS (adversarial challenge):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full output from above, verbatim>
|
||||
════════════════════════════════════════════════════════════
|
||||
Tokens: N | Est. cost: ~$X.XX
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2C: Consult Mode
|
||||
|
||||
Ask Codex anything about the codebase. Supports session continuity for follow-ups.
|
||||
|
||||
1. **Check for existing session:**
|
||||
```bash
|
||||
cat .context/codex-session-id 2>/dev/null || echo "NO_SESSION"
|
||||
```
|
||||
|
||||
If a session file exists (not `NO_SESSION`), use question:
|
||||
```
|
||||
You have an active Codex conversation from earlier. Continue it or start fresh?
|
||||
A) Continue the conversation (Codex remembers the prior context)
|
||||
B) Start a new conversation
|
||||
```
|
||||
|
||||
2. Create temp files:
|
||||
```bash
|
||||
TMPRESP=$(mktemp /tmp/codex-resp-XXXXXX.txt)
|
||||
TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)
|
||||
```
|
||||
|
||||
3. **Plan review auto-detection:** If the user's prompt is about reviewing a plan,
|
||||
or if plan files exist and the user said `/codex` with no arguments:
|
||||
```bash
|
||||
ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1
|
||||
```
|
||||
If no project-scoped match, fall back to `ls -t ~/.claude/plans/*.md 2>/dev/null | head -1`
|
||||
but warn: "Note: this plan may be from a different project — verify before sending to Codex."
|
||||
Read the plan file and prepend the persona to the user's prompt:
|
||||
"You are a brutally honest technical reviewer. Review this plan for: logical gaps and
|
||||
unstated assumptions, missing error handling or edge cases, overcomplexity (is there a
|
||||
simpler approach?), feasibility risks (what could go wrong?), and missing dependencies
|
||||
or sequencing issues. Be direct. Be terse. No compliments. Just the problems.
|
||||
|
||||
THE PLAN:
|
||||
<plan content>"
|
||||
|
||||
4. Run codex exec with **JSONL output** to capture reasoning traces (5-minute timeout):
|
||||
|
||||
For a **new session:**
|
||||
```bash
|
||||
codex exec "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>"$TMPERR" | python3 -c "
|
||||
import sys, json
|
||||
for line in sys.stdin:
|
||||
line = line.strip()
|
||||
if not line: continue
|
||||
try:
|
||||
obj = json.loads(line)
|
||||
t = obj.get('type','')
|
||||
if t == 'thread.started':
|
||||
tid = obj.get('thread_id','')
|
||||
if tid: print(f'SESSION_ID:{tid}')
|
||||
elif t == 'item.completed' and 'item' in obj:
|
||||
item = obj['item']
|
||||
itype = item.get('type','')
|
||||
text = item.get('text','')
|
||||
if itype == 'reasoning' and text:
|
||||
print(f'[codex thinking] {text}')
|
||||
print()
|
||||
elif itype == 'agent_message' and text:
|
||||
print(text)
|
||||
elif itype == 'command_execution':
|
||||
cmd = item.get('command','')
|
||||
if cmd: print(f'[codex ran] {cmd}')
|
||||
elif t == 'turn.completed':
|
||||
usage = obj.get('usage',{})
|
||||
tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
|
||||
if tokens: print(f'\ntokens used: {tokens}')
|
||||
except: pass
|
||||
"
|
||||
```
|
||||
|
||||
For a **resumed session** (user chose "Continue"):
|
||||
```bash
|
||||
codex exec resume <session-id> "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>"$TMPERR" | python3 -c "
|
||||
<same python streaming parser as above>
|
||||
"
|
||||
```
|
||||
|
||||
5. Capture session ID from the streamed output. The parser prints `SESSION_ID:<id>`
|
||||
from the `thread.started` event. Save it for follow-ups:
|
||||
```bash
|
||||
mkdir -p .context
|
||||
```
|
||||
Save the session ID printed by the parser (the line starting with `SESSION_ID:`)
|
||||
to `.context/codex-session-id`.
|
||||
|
||||
6. Present the full streamed output:
|
||||
|
||||
```
|
||||
CODEX SAYS (consult):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full output, verbatim — includes [codex thinking] traces>
|
||||
════════════════════════════════════════════════════════════
|
||||
Tokens: N | Est. cost: ~$X.XX
|
||||
Session saved — run /codex again to continue this conversation.
|
||||
```
|
||||
|
||||
7. After presenting, note any points where Codex's analysis differs from your own
|
||||
understanding. If there is a disagreement, flag it:
|
||||
"Note: Claude Code disagrees on X because Y."
|
||||
|
||||
---
|
||||
|
||||
## Model & Reasoning
|
||||
|
||||
**Model:** No model is hardcoded — codex uses whatever its current default is (the frontier
|
||||
agentic coding model). This means as OpenAI ships newer models, /codex automatically
|
||||
uses them. If the user wants a specific model, pass `-m` through to codex.
|
||||
|
||||
**Reasoning effort:** All modes use `xhigh` — maximum reasoning power. When reviewing code, breaking code, or consulting on architecture, you want the model thinking as hard as possible.
|
||||
|
||||
**Web search:** All codex commands use `--enable web_search_cached` so Codex can look up
|
||||
docs and APIs during review. This is OpenAI's cached index — fast, no extra cost.
|
||||
|
||||
If the user specifies a model (e.g., `/codex review -m gpt-5.1-codex-max`
|
||||
or `/codex challenge -m gpt-5.2`), pass the `-m` flag through to codex.
|
||||
|
||||
---
|
||||
|
||||
## Cost Estimation
|
||||
|
||||
Parse token count from stderr. Codex prints `tokens used\nN` to stderr.
|
||||
|
||||
Display as: `Tokens: N`
|
||||
|
||||
If token count is not available, display: `Tokens: unknown`
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Binary not found:** Detected in Step 0. Stop with install instructions.
|
||||
- **Auth error:** Codex prints an auth error to stderr. Surface the error:
|
||||
"Codex authentication failed. Run `codex login` in your terminal to authenticate via ChatGPT."
|
||||
- **Timeout:** If the Bash call times out (5 min), tell the user:
|
||||
"Codex timed out after 5 minutes. The diff may be too large or the API may be slow. Try again or use a smaller scope."
|
||||
- **Empty response:** If `$TMPRESP` is empty or doesn't exist, tell the user:
|
||||
"Codex returned no response. Check stderr for errors."
|
||||
- **Session resume failure:** If resume fails, delete the session file and start fresh.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode.
|
||||
- **Present output verbatim.** Do not truncate, summarize, or editorialize Codex's output
|
||||
before showing it. Show it in full inside the CODEX SAYS block.
|
||||
- **Add synthesis after, not instead of.** Any Claude commentary comes after the full output.
|
||||
- **5-minute timeout** on all Bash calls to codex (`timeout: 300000`).
|
||||
- **No double-reviewing.** If the user already ran `/review`, Codex provides a second
|
||||
independent opinion. Do not re-run Claude Code's own review.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: cso
|
||||
description: "Chief Security Officer mode. Performs OWASP Top 10 audit, STRIDE threat modeling, attack surface analysis, auth flow verification, secret detection, dependency CVE scanning, supply chain risk assessme"
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,426 @@
|
|||
---
|
||||
name: design-consultation
|
||||
description: "Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview pag"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Pre-checks
|
||||
|
||||
**Check for existing DESIGN.md:**
|
||||
|
||||
```bash
|
||||
ls DESIGN.md design-system.md 2>/dev/null || echo "NO_DESIGN_FILE"
|
||||
```
|
||||
|
||||
- If a DESIGN.md exists: Read it. Ask the user: "You already have a design system. Want to **update** it, **start fresh**, or **cancel**?"
|
||||
- If no DESIGN.md: continue.
|
||||
|
||||
**Gather product context from the codebase:**
|
||||
|
||||
```bash
|
||||
cat README.md 2>/dev/null | head -50
|
||||
cat package.json 2>/dev/null | head -20
|
||||
ls src/ app/ pages/ components/ 2>/dev/null | head -30
|
||||
```
|
||||
|
||||
Look for office-hours output:
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
ls ~/.gstack/projects/$SLUG/*office-hours* 2>/dev/null | head -5
|
||||
ls .context/*office-hours* .context/attachments/*office-hours* 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
If office-hours output exists, read it — the product context is pre-filled.
|
||||
|
||||
If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to explore first with `/office-hours`? Once we know the product direction, we can set up the design system."*
|
||||
|
||||
**Find the browse binary (optional — enables visual competitive research):**
|
||||
|
||||
## SETUP (run this check BEFORE any browse command)
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
B=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/${GSTACK_OPENCODE_DIR}/browse/dist/browse" ] && B="$_ROOT/${GSTACK_OPENCODE_DIR}/browse/dist/browse"
|
||||
[ -z "$B" ] && B=${GSTACK_OPENCODE_DIR}/browse/dist/browse
|
||||
if [ -x "$B" ]; then
|
||||
echo "READY: $B"
|
||||
else
|
||||
echo "NEEDS_SETUP"
|
||||
fi
|
||||
```
|
||||
|
||||
If `NEEDS_SETUP`:
|
||||
1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
|
||||
2. Run: `cd <SKILL_DIR> && ./setup`
|
||||
3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
|
||||
|
||||
If browse is not available, that's fine — visual research is optional. The skill works without it using WebSearch and your built-in design knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Product Context
|
||||
|
||||
Ask the user a single question that covers everything you need to know. Pre-fill what you can infer from the codebase.
|
||||
|
||||
**question Q1 — include ALL of these:**
|
||||
1. Confirm what the product is, who it's for, what space/industry
|
||||
2. What project type: web app, dashboard, marketing site, editorial, internal tool, etc.
|
||||
3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
|
||||
4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation."
|
||||
|
||||
If the README or office-hours output gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research what's out there in this space, or should I work from what I know?"*
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Research (only if user said yes)
|
||||
|
||||
If the user wants competitive research:
|
||||
|
||||
**Step 1: Identify what's out there via WebSearch**
|
||||
|
||||
Use WebSearch to find 5-10 products in their space. Search for:
|
||||
- "[product category] website design"
|
||||
- "[product category] best websites 2025"
|
||||
- "best [industry] web apps"
|
||||
|
||||
**Step 2: Visual research via browse (if available)**
|
||||
|
||||
If the browse binary is available (`$B` is set), visit the top 3-5 sites in the space and capture visual evidence:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto "https://example-site.com"
|
||||
${GSTACK_BROWSE} screenshot "/tmp/design-research-site-name.png"
|
||||
${GSTACK_BROWSE} snapshot
|
||||
```
|
||||
|
||||
For each site, analyze: fonts actually used, color palette, layout approach, spacing density, aesthetic direction. The screenshot gives you the feel; the snapshot gives you structural data.
|
||||
|
||||
If a site blocks the headless browser or requires login, skip it and note why.
|
||||
|
||||
If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
|
||||
|
||||
**Step 3: Synthesize findings**
|
||||
|
||||
**Three-layer synthesis:**
|
||||
- **Layer 1 (tried and true):** What design patterns does every product in this category share? These are table stakes — users expect them.
|
||||
- **Layer 2 (new and popular):** What are the search results and current design discourse saying? What's trending? What new patterns are emerging?
|
||||
- **Layer 3 (first principles):** Given what we know about THIS product's users and positioning — is there a reason the conventional design approach is wrong? Where should we deliberately break from the category norms?
|
||||
|
||||
**Eureka check:** If Layer 3 reasoning reveals a genuine design insight — a reason the category's visual language fails THIS product — name it: "EUREKA: Every [category] product does X because they assume [assumption]. But this product's users [evidence] — so we should do Y instead." Log the eureka moment (see preamble).
|
||||
|
||||
Summarize conversationally:
|
||||
> "I looked at what's out there. Here's the landscape: they converge on [patterns]. Most of them feel [observation — e.g., interchangeable, polished but generic, etc.]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."
|
||||
|
||||
**Graceful degradation:**
|
||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||
- Browse unavailable → WebSearch only (still good)
|
||||
- WebSearch also unavailable → agent's built-in design knowledge (always works)
|
||||
|
||||
If the user said no research, skip entirely and proceed to Phase 3 using your built-in design knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Design Outside Voices (parallel)
|
||||
|
||||
Use question:
|
||||
> "Want outside design voices? Codex evaluates against OpenAI's design hard rules + litmus checks; Claude subagent does an independent design direction proposal."
|
||||
>
|
||||
> A) Yes — run outside design voices
|
||||
> B) No — proceed without
|
||||
|
||||
If user chooses B, skip this step and continue.
|
||||
|
||||
**Check Codex availability:**
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
**If Codex is available**, launch both voices simultaneously:
|
||||
|
||||
1. **Codex design voice** (via Bash):
|
||||
```bash
|
||||
TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX)
|
||||
codex exec "Given this product context, propose a complete design direction:
|
||||
- Visual thesis: one sentence describing mood, material, and energy
|
||||
- Typography: specific font names (not defaults — no Inter/Roboto/Arial/system) + hex colors
|
||||
- Color system: CSS variables for background, surface, primary text, muted text, accent
|
||||
- Layout: composition-first, not component-first. First viewport as poster, not document
|
||||
- Differentiation: 2 deliberate departures from category norms
|
||||
- Anti-slop: no purple gradients, no 3-column icon grids, no centered everything, no decorative blobs
|
||||
|
||||
Be opinionated. Be specific. Do not hedge. This is YOUR design direction — own it." -s read-only -c 'model_reasoning_effort="medium"' --enable web_search_cached 2>"$TMPERR_DESIGN"
|
||||
```
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN"
|
||||
```
|
||||
|
||||
2. **Claude design subagent** (via Agent tool):
|
||||
Dispatch a subagent with this prompt:
|
||||
"Given this product context, propose a design direction that would SURPRISE. What would the cool indie studio do that the enterprise UI team wouldn't?
|
||||
- Propose an aesthetic direction, typography stack (specific font names), color palette (hex values)
|
||||
- 2 deliberate departures from category norms
|
||||
- What emotional reaction should the user have in the first 3 seconds?
|
||||
|
||||
Be bold. Be specific. No hedging."
|
||||
|
||||
**Error handling (all non-blocking):**
|
||||
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate."
|
||||
- **Timeout:** "Codex timed out after 5 minutes."
|
||||
- **Empty response:** "Codex returned no response."
|
||||
- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`.
|
||||
- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review."
|
||||
|
||||
Present Codex output under a `CODEX SAYS (design direction):` header.
|
||||
Present subagent output under a `CLAUDE SUBAGENT (design direction):` header.
|
||||
|
||||
**Synthesis:** Claude main references both Codex and subagent proposals in the Phase 3 proposal. Present:
|
||||
- Areas of agreement between all three voices (Claude main + Codex + subagent)
|
||||
- Genuine divergences as creative alternatives for the user to choose from
|
||||
- "Codex and I agree on X. Codex suggested Y where I'm proposing Z — here's why..."
|
||||
|
||||
**Log the result:**
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable".
|
||||
|
||||
## Phase 3: The Complete Proposal
|
||||
|
||||
This is the soul of the skill. Propose EVERYTHING as one coherent package.
|
||||
|
||||
**question Q2 — present the full proposal with SAFE/RISK breakdown:**
|
||||
|
||||
```
|
||||
Based on [product context] and [research findings / my design knowledge]:
|
||||
|
||||
AESTHETIC: [direction] — [one-line rationale]
|
||||
DECORATION: [level] — [why this pairs with the aesthetic]
|
||||
LAYOUT: [approach] — [why this fits the product type]
|
||||
COLOR: [approach] + proposed palette (hex values) — [rationale]
|
||||
TYPOGRAPHY: [3 font recommendations with roles] — [why these fonts]
|
||||
SPACING: [base unit + density] — [rationale]
|
||||
MOTION: [approach] — [rationale]
|
||||
|
||||
This system is coherent because [explain how choices reinforce each other].
|
||||
|
||||
SAFE CHOICES (category baseline — your users expect these):
|
||||
- [2-3 decisions that match category conventions, with rationale for playing safe]
|
||||
|
||||
RISKS (where your product gets its own face):
|
||||
- [2-3 deliberate departures from convention]
|
||||
- For each risk: what it is, why it works, what you gain, what it costs
|
||||
|
||||
The safe choices keep you literate in your category. The risks are where
|
||||
your product becomes memorable. Which risks appeal to you? Want to see
|
||||
different ones? Or adjust anything else?
|
||||
```
|
||||
|
||||
The SAFE/RISK breakdown is critical. Design coherence is table stakes — every product in a category can be coherent and still look identical. The real question is: where do you take creative risks? The agent should always propose at least 2 risks, each with a clear rationale for why the risk is worth taking and what the user gives up. Risks might include: an unexpected typeface for the category, a bold accent color nobody else uses, tighter or looser spacing than the norm, a layout approach that breaks from convention, motion choices that add personality.
|
||||
|
||||
**Options:** A) Looks great — generate the preview page. B) I want to adjust [section]. C) I want different risks — show me wilder options. D) Start over with a different direction. E) Skip the preview, just write DESIGN.md.
|
||||
|
||||
### Your Design Knowledge (use to inform proposals — do NOT display as tables)
|
||||
|
||||
**Aesthetic directions** (pick the one that fits the product):
|
||||
- Brutally Minimal — Type and whitespace only. No decoration. Modernist.
|
||||
- Maximalist Chaos — Dense, layered, pattern-heavy. Y2K meets contemporary.
|
||||
- Retro-Futuristic — Vintage tech nostalgia. CRT glow, pixel grids, warm monospace.
|
||||
- Luxury/Refined — Serifs, high contrast, generous whitespace, precious metals.
|
||||
- Playful/Toy-like — Rounded, bouncy, bold primaries. Approachable and fun.
|
||||
- Editorial/Magazine — Strong typographic hierarchy, asymmetric grids, pull quotes.
|
||||
- Brutalist/Raw — Exposed structure, system fonts, visible grid, no polish.
|
||||
- Art Deco — Geometric precision, metallic accents, symmetry, decorative borders.
|
||||
- Organic/Natural — Earth tones, rounded forms, hand-drawn texture, grain.
|
||||
- Industrial/Utilitarian — Function-first, data-dense, monospace accents, muted palette.
|
||||
|
||||
**Decoration levels:** minimal (typography does all the work) / intentional (subtle texture, grain, or background treatment) / expressive (full creative direction, layered depth, patterns)
|
||||
|
||||
**Layout approaches:** grid-disciplined (strict columns, predictable alignment) / creative-editorial (asymmetry, overlap, grid-breaking) / hybrid (grid for app, creative for marketing)
|
||||
|
||||
**Color approaches:** restrained (1 accent + neutrals, color is rare and meaningful) / balanced (primary + secondary, semantic colors for hierarchy) / expressive (color as a primary design tool, bold palettes)
|
||||
|
||||
**Motion approaches:** minimal-functional (only transitions that aid comprehension) / intentional (subtle entrance animations, meaningful state transitions) / expressive (full choreography, scroll-driven, playful)
|
||||
|
||||
**Font recommendations by purpose:**
|
||||
- Display/Hero: Satoshi, General Sans, Instrument Serif, Fraunces, Clash Grotesk, Cabinet Grotesk
|
||||
- Body: Instrument Sans, DM Sans, Source Sans 3, Geist, Plus Jakarta Sans, Outfit
|
||||
- Data/Tables: Geist (tabular-nums), DM Sans (tabular-nums), JetBrains Mono, IBM Plex Mono
|
||||
- Code: JetBrains Mono, Fira Code, Berkeley Mono, Geist Mono
|
||||
|
||||
**Font blacklist** (never recommend):
|
||||
Papyrus, Comic Sans, Lobster, Impact, Jokerman, Bleeding Cowboys, Permanent Marker, Bradley Hand, Brush Script, Hobo, Trajan, Raleway, Clash Display, Courier New (for body)
|
||||
|
||||
**Overused fonts** (never recommend as primary — use only if user specifically requests):
|
||||
Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Montserrat, Poppins
|
||||
|
||||
**AI slop anti-patterns** (never include in your recommendations):
|
||||
- Purple/violet gradients as default accent
|
||||
- 3-column feature grid with icons in colored circles
|
||||
- Centered everything with uniform spacing
|
||||
- Uniform bubbly border-radius on all elements
|
||||
- Gradient buttons as the primary CTA pattern
|
||||
- Generic stock-photo-style hero sections
|
||||
- "Built for X" / "Designed for Y" marketing copy patterns
|
||||
|
||||
### Coherence Validation
|
||||
|
||||
When the user overrides one section, check if the rest still coheres. Flag mismatches with a gentle nudge — never block:
|
||||
|
||||
- Brutalist/Minimal aesthetic + expressive motion → "Heads up: brutalist aesthetics usually pair with minimal motion. Your combo is unusual — which is fine if intentional. Want me to suggest motion that fits, or keep it?"
|
||||
- Expressive color + restrained decoration → "Bold palette with minimal decoration can work, but the colors will carry a lot of weight. Want me to suggest decoration that supports the palette?"
|
||||
- Creative-editorial layout + data-heavy product → "Editorial layouts are gorgeous but can fight data density. Want me to show how a hybrid approach keeps both?"
|
||||
- Always accept the user's final choice. Never refuse to proceed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Drill-downs (only if user requests adjustments)
|
||||
|
||||
When the user wants to change a specific section, go deep on that section:
|
||||
|
||||
- **Fonts:** Present 3-5 specific candidates with rationale, explain what each evokes, offer the preview page
|
||||
- **Colors:** Present 2-3 palette options with hex values, explain the color theory reasoning
|
||||
- **Aesthetic:** Walk through which directions fit their product and why
|
||||
- **Layout/Spacing/Motion:** Present the approaches with concrete tradeoffs for their product type
|
||||
|
||||
Each drill-down is one focused question. After the user decides, re-check coherence with the rest of the system.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Font & Color Preview Page (default ON)
|
||||
|
||||
Generate a polished HTML preview page and open it in the user's browser. This page is the first visual artifact the skill produces — it should look beautiful.
|
||||
|
||||
```bash
|
||||
PREVIEW_FILE="/tmp/design-consultation-preview-$(date +%s).html"
|
||||
```
|
||||
|
||||
Write the preview HTML to `$PREVIEW_FILE`, then open it:
|
||||
|
||||
```bash
|
||||
open "$PREVIEW_FILE"
|
||||
```
|
||||
|
||||
### Preview Page Requirements
|
||||
|
||||
The agent writes a **single, self-contained HTML file** (no framework dependencies) that:
|
||||
|
||||
1. **Loads proposed fonts** from Google Fonts (or Bunny Fonts) via `<link>` tags
|
||||
2. **Uses the proposed color palette** throughout — dogfood the design system
|
||||
3. **Shows the product name** (not "Lorem Ipsum") as the hero heading
|
||||
4. **Font specimen section:**
|
||||
- Each font candidate shown in its proposed role (hero heading, body paragraph, button label, data table row)
|
||||
- Side-by-side comparison if multiple candidates for one role
|
||||
- Real content that matches the product (e.g., civic tech → government data examples)
|
||||
5. **Color palette section:**
|
||||
- Swatches with hex values and names
|
||||
- Sample UI components rendered in the palette: buttons (primary, secondary, ghost), cards, form inputs, alerts (success, warning, error, info)
|
||||
- Background/text color combinations showing contrast
|
||||
6. **Realistic product mockups** — this is what makes the preview page powerful. Based on the project type from Phase 1, render 2-3 realistic page layouts using the full design system:
|
||||
- **Dashboard / web app:** sample data table with metrics, sidebar nav, header with user avatar, stat cards
|
||||
- **Marketing site:** hero section with real copy, feature highlights, testimonial block, CTA
|
||||
- **Settings / admin:** form with labeled inputs, toggle switches, dropdowns, save button
|
||||
- **Auth / onboarding:** login form with social buttons, branding, input validation states
|
||||
- Use the product name, realistic content for the domain, and the proposed spacing/layout/border-radius. The user should see their product (roughly) before writing any code.
|
||||
7. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
|
||||
8. **Clean, professional layout** — the preview page IS a taste signal for the skill
|
||||
9. **Responsive** — looks good on any screen width
|
||||
|
||||
The page should make the user think "oh nice, they thought of this." It's selling the design system by showing what the product could feel like, not just listing hex codes and font names.
|
||||
|
||||
If `open` fails (headless environment), tell the user: *"I wrote the preview to [path] — open it in your browser to see the fonts and colors rendered."*
|
||||
|
||||
If the user says skip the preview, go directly to Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Write DESIGN.md & Confirm
|
||||
|
||||
Write `DESIGN.md` to the repo root with this structure:
|
||||
|
||||
```markdown
|
||||
# Design System — [Project Name]
|
||||
|
||||
## Product Context
|
||||
- **What this is:** [1-2 sentence description]
|
||||
- **Who it's for:** [target users]
|
||||
- **Space/industry:** [category, peers]
|
||||
- **Project type:** [web app / dashboard / marketing site / editorial / internal tool]
|
||||
|
||||
## Aesthetic Direction
|
||||
- **Direction:** [name]
|
||||
- **Decoration level:** [minimal / intentional / expressive]
|
||||
- **Mood:** [1-2 sentence description of how the product should feel]
|
||||
- **Reference sites:** [URLs, if research was done]
|
||||
|
||||
## Typography
|
||||
- **Display/Hero:** [font name] — [rationale]
|
||||
- **Body:** [font name] — [rationale]
|
||||
- **UI/Labels:** [font name or "same as body"]
|
||||
- **Data/Tables:** [font name] — [rationale, must support tabular-nums]
|
||||
- **Code:** [font name]
|
||||
- **Loading:** [CDN URL or self-hosted strategy]
|
||||
- **Scale:** [modular scale with specific px/rem values for each level]
|
||||
|
||||
## Color
|
||||
- **Approach:** [restrained / balanced / expressive]
|
||||
- **Primary:** [hex] — [what it represents, usage]
|
||||
- **Secondary:** [hex] — [usage]
|
||||
- **Neutrals:** [warm/cool grays, hex range from lightest to darkest]
|
||||
- **Semantic:** success [hex], warning [hex], error [hex], info [hex]
|
||||
- **Dark mode:** [strategy — redesign surfaces, reduce saturation 10-20%]
|
||||
|
||||
## Spacing
|
||||
- **Base unit:** [4px or 8px]
|
||||
- **Density:** [compact / comfortable / spacious]
|
||||
- **Scale:** 2xs(2) xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48) 3xl(64)
|
||||
|
||||
## Layout
|
||||
- **Approach:** [grid-disciplined / creative-editorial / hybrid]
|
||||
- **Grid:** [columns per breakpoint]
|
||||
- **Max content width:** [value]
|
||||
- **Border radius:** [hierarchical scale — e.g., sm:4px, md:8px, lg:12px, full:9999px]
|
||||
|
||||
## Motion
|
||||
- **Approach:** [minimal-functional / intentional / expressive]
|
||||
- **Easing:** enter(ease-out) exit(ease-in) move(ease-in-out)
|
||||
- **Duration:** micro(50-100ms) short(150-250ms) medium(250-400ms) long(400-700ms)
|
||||
|
||||
## Decisions Log
|
||||
| Date | Decision | Rationale |
|
||||
|------|----------|-----------|
|
||||
| [today] | Initial design system created | Created by /design-consultation based on [product context / research] |
|
||||
```
|
||||
|
||||
**Update CLAUDE.md** (or create it if it doesn't exist) — append this section:
|
||||
|
||||
```markdown
|
||||
## Design System
|
||||
Always read DESIGN.md before making any visual or UI decisions.
|
||||
All font choices, colors, spacing, and aesthetic direction are defined there.
|
||||
Do not deviate without explicit user approval.
|
||||
In QA mode, flag any code that doesn't match DESIGN.md.
|
||||
```
|
||||
|
||||
**question Q-final — show summary and confirm:**
|
||||
|
||||
List all decisions. Flag any that used agent defaults without explicit user confirmation (the user should know what they're shipping). Options:
|
||||
- A) Ship it — write DESIGN.md and CLAUDE.md
|
||||
- B) I want to change something (specify what)
|
||||
- C) Start over
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
1. **Propose, don't present menus.** You are a consultant, not a form. Make opinionated recommendations based on the product context, then let the user adjust.
|
||||
2. **Every recommendation needs a rationale.** Never say "I recommend X" without "because Y."
|
||||
3. **Coherence over individual choices.** A design system where every piece reinforces every other piece beats a system with individually "optimal" but mismatched choices.
|
||||
4. **Never recommend blacklisted or overused fonts as primary.** If the user specifically requests one, comply but explain the tradeoff.
|
||||
5. **The preview page must be beautiful.** It's the first visual output and sets the tone for the whole skill.
|
||||
6. **Conversational tone.** This isn't a rigid workflow. If the user wants to talk through a decision, engage as a thoughtful design partner.
|
||||
7. **Accept the user's final choice.** Nudge on coherence issues, but never block or refuse to write a DESIGN.md because you disagree with a choice.
|
||||
8. **No AI slop in your own output.** Your recommendations, your preview page, your DESIGN.md — all should demonstrate the taste you're asking the user to adopt.
|
||||
|
|
@ -0,0 +1,675 @@
|
|||
---
|
||||
name: design-review
|
||||
description: "Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues in source code, committing each"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
**Create output directories:**
|
||||
|
||||
```bash
|
||||
REPORT_DIR=".gstack/design-reports"
|
||||
mkdir -p "$REPORT_DIR/screenshots"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phases 1-6: Design Audit Baseline
|
||||
|
||||
## Modes
|
||||
|
||||
### Full (default)
|
||||
Systematic review of all pages reachable from homepage. Visit 5-8 pages. Full checklist evaluation, responsive screenshots, interaction flow testing. Produces complete design audit report with letter grades.
|
||||
|
||||
### Quick (`--quick`)
|
||||
Homepage + 2 key pages only. First Impression + Design System Extraction + abbreviated checklist. Fastest path to a design score.
|
||||
|
||||
### Deep (`--deep`)
|
||||
Comprehensive review: 10-15 pages, every interaction flow, exhaustive checklist. For pre-launch audits or major redesigns.
|
||||
|
||||
### Diff-aware (automatic when on a feature branch with no URL)
|
||||
When on a feature branch, scope to pages affected by the branch changes:
|
||||
1. Analyze the branch diff: `git diff main...HEAD --name-only`
|
||||
2. Map changed files to affected pages/routes
|
||||
3. Detect running app on common local ports (3000, 4000, 8080)
|
||||
4. Audit only affected pages, compare design quality before/after
|
||||
|
||||
### Regression (`--regression` or previous `design-baseline.json` found)
|
||||
Run full audit, then load previous `design-baseline.json`. Compare: per-category grade deltas, new findings, resolved findings. Output regression table in report.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: First Impression
|
||||
|
||||
The most uniquely designer-like output. Form a gut reaction before analyzing anything.
|
||||
|
||||
1. Navigate to the target URL
|
||||
2. Take a full-page desktop screenshot: `${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/first-impression.png"`
|
||||
3. Write the **First Impression** using this structured critique format:
|
||||
- "The site communicates **[what]**." (what it says at a glance — competence? playfulness? confusion?)
|
||||
- "I notice **[observation]**." (what stands out, positive or negative — be specific)
|
||||
- "The first 3 things my eye goes to are: **[1]**, **[2]**, **[3]**." (hierarchy check — are these intentional?)
|
||||
- "If I had to describe this in one word: **[word]**." (gut verdict)
|
||||
|
||||
This is the section users read first. Be opinionated. A designer doesn't hedge — they react.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Design System Extraction
|
||||
|
||||
Extract the actual design system the site uses (not what a DESIGN.md says, but what's rendered):
|
||||
|
||||
```bash
|
||||
# Fonts in use (capped at 500 elements to avoid timeout)
|
||||
${GSTACK_BROWSE} js "JSON.stringify([...new Set([...document.querySelectorAll('*')].slice(0,500).map(e => getComputedStyle(e).fontFamily))])"
|
||||
|
||||
# Color palette in use
|
||||
${GSTACK_BROWSE} js "JSON.stringify([...new Set([...document.querySelectorAll('*')].slice(0,500).flatMap(e => [getComputedStyle(e).color, getComputedStyle(e).backgroundColor]).filter(c => c !== 'rgba(0, 0, 0, 0)'))])"
|
||||
|
||||
# Heading hierarchy
|
||||
${GSTACK_BROWSE} js "JSON.stringify([...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].map(h => ({tag:h.tagName, text:h.textContent.trim().slice(0,50), size:getComputedStyle(h).fontSize, weight:getComputedStyle(h).fontWeight})))"
|
||||
|
||||
# Touch target audit (find undersized interactive elements)
|
||||
${GSTACK_BROWSE} js "JSON.stringify([...document.querySelectorAll('a,button,input,[role=button]')].filter(e => {const r=e.getBoundingClientRect(); return r.width>0 && (r.width<44||r.height<44)}).map(e => ({tag:e.tagName, text:(e.textContent||'').trim().slice(0,30), w:Math.round(e.getBoundingClientRect().width), h:Math.round(e.getBoundingClientRect().height)})).slice(0,20))"
|
||||
|
||||
# Performance baseline
|
||||
${GSTACK_BROWSE} perf
|
||||
```
|
||||
|
||||
Structure findings as an **Inferred Design System**:
|
||||
- **Fonts:** list with usage counts. Flag if >3 distinct font families.
|
||||
- **Colors:** palette extracted. Flag if >12 unique non-gray colors. Note warm/cool/mixed.
|
||||
- **Heading Scale:** h1-h6 sizes. Flag skipped levels, non-systematic size jumps.
|
||||
- **Spacing Patterns:** sample padding/margin values. Flag non-scale values.
|
||||
|
||||
After extraction, offer: *"Want me to save this as your DESIGN.md? I can lock in these observations as your project's design system baseline."*
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Page-by-Page Visual Audit
|
||||
|
||||
For each page in scope:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/{page}-annotated.png"
|
||||
${GSTACK_BROWSE} responsive "$REPORT_DIR/screenshots/{page}"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} perf
|
||||
```
|
||||
|
||||
### Auth Detection
|
||||
|
||||
After the first navigation, check if the URL changed to a login-like path:
|
||||
```bash
|
||||
${GSTACK_BROWSE} url
|
||||
```
|
||||
If URL contains `/login`, `/signin`, `/auth`, or `/sso`: the site requires authentication. question: "This site requires authentication. Want to import cookies from your browser? Run `/setup-browser-cookies` first if needed."
|
||||
|
||||
### Design Audit Checklist (10 categories, ~80 items)
|
||||
|
||||
Apply these at each page. Each finding gets an impact rating (high/medium/polish) and category.
|
||||
|
||||
**1. Visual Hierarchy & Composition** (8 items)
|
||||
- Clear focal point? One primary CTA per view?
|
||||
- Eye flows naturally top-left to bottom-right?
|
||||
- Visual noise — competing elements fighting for attention?
|
||||
- Information density appropriate for content type?
|
||||
- Z-index clarity — nothing unexpectedly overlapping?
|
||||
- Above-the-fold content communicates purpose in 3 seconds?
|
||||
- Squint test: hierarchy still visible when blurred?
|
||||
- White space is intentional, not leftover?
|
||||
|
||||
**2. Typography** (15 items)
|
||||
- Font count <=3 (flag if more)
|
||||
- Scale follows ratio (1.25 major third or 1.333 perfect fourth)
|
||||
- Line-height: 1.5x body, 1.15-1.25x headings
|
||||
- Measure: 45-75 chars per line (66 ideal)
|
||||
- Heading hierarchy: no skipped levels (h1→h3 without h2)
|
||||
- Weight contrast: >=2 weights used for hierarchy
|
||||
- No blacklisted fonts (Papyrus, Comic Sans, Lobster, Impact, Jokerman)
|
||||
- If primary font is Inter/Roboto/Open Sans/Poppins → flag as potentially generic
|
||||
- `text-wrap: balance` or `text-pretty` on headings (check via `${GSTACK_BROWSE} css <heading> text-wrap`)
|
||||
- Curly quotes used, not straight quotes
|
||||
- Ellipsis character (`…`) not three dots (`...`)
|
||||
- `font-variant-numeric: tabular-nums` on number columns
|
||||
- Body text >= 16px
|
||||
- Caption/label >= 12px
|
||||
- No letterspacing on lowercase text
|
||||
|
||||
**3. Color & Contrast** (10 items)
|
||||
- Palette coherent (<=12 unique non-gray colors)
|
||||
- WCAG AA: body text 4.5:1, large text (18px+) 3:1, UI components 3:1
|
||||
- Semantic colors consistent (success=green, error=red, warning=yellow/amber)
|
||||
- No color-only encoding (always add labels, icons, or patterns)
|
||||
- Dark mode: surfaces use elevation, not just lightness inversion
|
||||
- Dark mode: text off-white (~#E0E0E0), not pure white
|
||||
- Primary accent desaturated 10-20% in dark mode
|
||||
- `color-scheme: dark` on html element (if dark mode present)
|
||||
- No red/green only combinations (8% of men have red-green deficiency)
|
||||
- Neutral palette is warm or cool consistently — not mixed
|
||||
|
||||
**4. Spacing & Layout** (12 items)
|
||||
- Grid consistent at all breakpoints
|
||||
- Spacing uses a scale (4px or 8px base), not arbitrary values
|
||||
- Alignment is consistent — nothing floats outside the grid
|
||||
- Rhythm: related items closer together, distinct sections further apart
|
||||
- Border-radius hierarchy (not uniform bubbly radius on everything)
|
||||
- Inner radius = outer radius - gap (nested elements)
|
||||
- No horizontal scroll on mobile
|
||||
- Max content width set (no full-bleed body text)
|
||||
- `env(safe-area-inset-*)` for notch devices
|
||||
- URL reflects state (filters, tabs, pagination in query params)
|
||||
- Flex/grid used for layout (not JS measurement)
|
||||
- Breakpoints: mobile (375), tablet (768), desktop (1024), wide (1440)
|
||||
|
||||
**5. Interaction States** (10 items)
|
||||
- Hover state on all interactive elements
|
||||
- `focus-visible` ring present (never `outline: none` without replacement)
|
||||
- Active/pressed state with depth effect or color shift
|
||||
- Disabled state: reduced opacity + `cursor: not-allowed`
|
||||
- Loading: skeleton shapes match real content layout
|
||||
- Empty states: warm message + primary action + visual (not just "No items.")
|
||||
- Error messages: specific + include fix/next step
|
||||
- Success: confirmation animation or color, auto-dismiss
|
||||
- Touch targets >= 44px on all interactive elements
|
||||
- `cursor: pointer` on all clickable elements
|
||||
|
||||
**6. Responsive Design** (8 items)
|
||||
- Mobile layout makes *design* sense (not just stacked desktop columns)
|
||||
- Touch targets sufficient on mobile (>= 44px)
|
||||
- No horizontal scroll on any viewport
|
||||
- Images handle responsive (srcset, sizes, or CSS containment)
|
||||
- Text readable without zooming on mobile (>= 16px body)
|
||||
- Navigation collapses appropriately (hamburger, bottom nav, etc.)
|
||||
- Forms usable on mobile (correct input types, no autoFocus on mobile)
|
||||
- No `user-scalable=no` or `maximum-scale=1` in viewport meta
|
||||
|
||||
**7. Motion & Animation** (6 items)
|
||||
- Easing: ease-out for entering, ease-in for exiting, ease-in-out for moving
|
||||
- Duration: 50-700ms range (nothing slower unless page transition)
|
||||
- Purpose: every animation communicates something (state change, attention, spatial relationship)
|
||||
- `prefers-reduced-motion` respected (check: `${GSTACK_BROWSE} js "matchMedia('(prefers-reduced-motion: reduce)').matches"`)
|
||||
- No `transition: all` — properties listed explicitly
|
||||
- Only `transform` and `opacity` animated (not layout properties like width, height, top, left)
|
||||
|
||||
**8. Content & Microcopy** (8 items)
|
||||
- Empty states designed with warmth (message + action + illustration/icon)
|
||||
- Error messages specific: what happened + why + what to do next
|
||||
- Button labels specific ("Save API Key" not "Continue" or "Submit")
|
||||
- No placeholder/lorem ipsum text visible in production
|
||||
- Truncation handled (`text-overflow: ellipsis`, `line-clamp`, or `break-words`)
|
||||
- Active voice ("Install the CLI" not "The CLI will be installed")
|
||||
- Loading states end with `…` ("Saving…" not "Saving...")
|
||||
- Destructive actions have confirmation modal or undo window
|
||||
|
||||
**9. AI Slop Detection** (10 anti-patterns — the blacklist)
|
||||
|
||||
The test: would a human designer at a respected studio ever ship this?
|
||||
|
||||
- Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
|
||||
- **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
|
||||
- Icons in colored circles as section decoration (SaaS starter template look)
|
||||
- Centered everything (`text-align: center` on all headings, descriptions, cards)
|
||||
- Uniform bubbly border-radius on every element (same large radius on everything)
|
||||
- Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
|
||||
- Emoji as design elements (rockets in headings, emoji as bullet points)
|
||||
- Colored left-border on cards (`border-left: 3px solid <accent>`)
|
||||
- Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
|
||||
- Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
|
||||
|
||||
**10. Performance as Design** (6 items)
|
||||
- LCP < 2.0s (web apps), < 1.5s (informational sites)
|
||||
- CLS < 0.1 (no visible layout shifts during load)
|
||||
- Skeleton quality: shapes match real content, shimmer animation
|
||||
- Images: `loading="lazy"`, width/height dimensions set, WebP/AVIF format
|
||||
- Fonts: `font-display: swap`, preconnect to CDN origins
|
||||
- No visible font swap flash (FOUT) — critical fonts preloaded
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Interaction Flow Review
|
||||
|
||||
Walk 2-3 key user flows and evaluate the *feel*, not just the function:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} snapshot -i
|
||||
${GSTACK_BROWSE} click @e3 # perform action
|
||||
${GSTACK_BROWSE} snapshot -D # diff to see what changed
|
||||
```
|
||||
|
||||
Evaluate:
|
||||
- **Response feel:** Does clicking feel responsive? Any delays or missing loading states?
|
||||
- **Transition quality:** Are transitions intentional or generic/absent?
|
||||
- **Feedback clarity:** Did the action clearly succeed or fail? Is the feedback immediate?
|
||||
- **Form polish:** Focus states visible? Validation timing correct? Errors near the source?
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Cross-Page Consistency
|
||||
|
||||
Compare screenshots and observations across pages for:
|
||||
- Navigation bar consistent across all pages?
|
||||
- Footer consistent?
|
||||
- Component reuse vs one-off designs (same button styled differently on different pages?)
|
||||
- Tone consistency (one page playful while another is corporate?)
|
||||
- Spacing rhythm carries across pages?
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Compile Report
|
||||
|
||||
### Output Locations
|
||||
|
||||
**Local:** `.gstack/design-reports/design-audit-{domain}-{YYYY-MM-DD}.md`
|
||||
|
||||
**Project-scoped:**
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
Write to: `~/.gstack/projects/{slug}/{user}-{branch}-design-audit-{datetime}.md`
|
||||
|
||||
**Baseline:** Write `design-baseline.json` for regression mode:
|
||||
```json
|
||||
{
|
||||
"date": "YYYY-MM-DD",
|
||||
"url": "<target>",
|
||||
"designScore": "B",
|
||||
"aiSlopScore": "C",
|
||||
"categoryGrades": { "hierarchy": "A", "typography": "B", ... },
|
||||
"findings": [{ "id": "FINDING-001", "title": "...", "impact": "high", "category": "typography" }]
|
||||
}
|
||||
```
|
||||
|
||||
### Scoring System
|
||||
|
||||
**Dual headline scores:**
|
||||
- **Design Score: {A-F}** — weighted average of all 10 categories
|
||||
- **AI Slop Score: {A-F}** — standalone grade with pithy verdict
|
||||
|
||||
**Per-category grades:**
|
||||
- **A:** Intentional, polished, delightful. Shows design thinking.
|
||||
- **B:** Solid fundamentals, minor inconsistencies. Looks professional.
|
||||
- **C:** Functional but generic. No major problems, no design point of view.
|
||||
- **D:** Noticeable problems. Feels unfinished or careless.
|
||||
- **F:** Actively hurting user experience. Needs significant rework.
|
||||
|
||||
**Grade computation:** Each category starts at A. Each High-impact finding drops one letter grade. Each Medium-impact finding drops half a letter grade. Polish findings are noted but do not affect grade. Minimum is F.
|
||||
|
||||
**Category weights for Design Score:**
|
||||
| Category | Weight |
|
||||
|----------|--------|
|
||||
| Visual Hierarchy | 15% |
|
||||
| Typography | 15% |
|
||||
| Spacing & Layout | 15% |
|
||||
| Color & Contrast | 10% |
|
||||
| Interaction States | 10% |
|
||||
| Responsive | 10% |
|
||||
| Content Quality | 10% |
|
||||
| AI Slop | 5% |
|
||||
| Motion | 5% |
|
||||
| Performance Feel | 5% |
|
||||
|
||||
AI Slop is 5% of Design Score but also graded independently as a headline metric.
|
||||
|
||||
### Regression Output
|
||||
|
||||
When previous `design-baseline.json` exists or `--regression` flag is used:
|
||||
- Load baseline grades
|
||||
- Compare: per-category deltas, new findings, resolved findings
|
||||
- Append regression table to report
|
||||
|
||||
---
|
||||
|
||||
## Design Critique Format
|
||||
|
||||
Use structured feedback, not opinions:
|
||||
- "I notice..." — observation (e.g., "I notice the primary CTA competes with the secondary action")
|
||||
- "I wonder..." — question (e.g., "I wonder if users will understand what 'Process' means here")
|
||||
- "What if..." — suggestion (e.g., "What if we moved search to a more prominent position?")
|
||||
- "I think... because..." — reasoned opinion (e.g., "I think the spacing between sections is too uniform because it doesn't create hierarchy")
|
||||
|
||||
Tie everything to user goals and product objectives. Always suggest specific improvements alongside problems.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
1. **Think like a designer, not a QA engineer.** You care whether things feel right, look intentional, and respect the user. You do NOT just care whether things "work."
|
||||
2. **Screenshots are evidence.** Every finding needs at least one screenshot. Use annotated screenshots (`snapshot -a`) to highlight elements.
|
||||
3. **Be specific and actionable.** "Change X to Y because Z" — not "the spacing feels off."
|
||||
4. **Never read source code.** Evaluate the rendered site, not the implementation. (Exception: offer to write DESIGN.md from extracted observations.)
|
||||
5. **AI Slop detection is your superpower.** Most developers can't evaluate whether their site looks AI-generated. You can. Be direct about it.
|
||||
6. **Quick wins matter.** Always include a "Quick Wins" section — the 3-5 highest-impact fixes that take <30 minutes each.
|
||||
7. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses.
|
||||
8. **Responsive is design, not just "not broken."** A stacked desktop layout on mobile is not responsive design — it's lazy. Evaluate whether the mobile layout makes *design* sense.
|
||||
9. **Document incrementally.** Write each finding to the report as you find it. Don't batch.
|
||||
10. **Depth over breadth.** 5-10 well-documented findings with screenshots and specific suggestions > 20 vague observations.
|
||||
11. **Show screenshots to the user.** After every `${GSTACK_BROWSE} screenshot`, `${GSTACK_BROWSE} snapshot -a -o`, or `${GSTACK_BROWSE} responsive` command, use the Read tool on the output file(s) so the user can see them inline. For `responsive` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user.
|
||||
|
||||
### Design Hard Rules
|
||||
|
||||
**Classifier — determine rule set before evaluating:**
|
||||
- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules
|
||||
- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules
|
||||
- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections
|
||||
|
||||
**Hard rejection criteria** (instant-fail patterns — flag if ANY apply):
|
||||
1. Generic SaaS card grid as first impression
|
||||
2. Beautiful image with weak brand
|
||||
3. Strong headline with no clear action
|
||||
4. Busy imagery behind text
|
||||
5. Sections repeating same mood statement
|
||||
6. Carousel with no narrative purpose
|
||||
7. App UI made of stacked cards instead of layout
|
||||
|
||||
**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring):
|
||||
1. Brand/product unmistakable in first screen?
|
||||
2. One strong visual anchor present?
|
||||
3. Page understandable by scanning headlines only?
|
||||
4. Each section has one job?
|
||||
5. Are cards actually necessary?
|
||||
6. Does motion improve hierarchy or atmosphere?
|
||||
7. Would design feel premium with all decorative shadows removed?
|
||||
|
||||
**Landing page rules** (apply when classifier = MARKETING/LANDING):
|
||||
- First viewport reads as one composition, not a dashboard
|
||||
- Brand-first hierarchy: brand > headline > body > CTA
|
||||
- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
|
||||
- No flat single-color backgrounds — use gradients, images, subtle patterns
|
||||
- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
|
||||
- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
|
||||
- No cards in hero. Cards only when card IS the interaction
|
||||
- One job per section: one purpose, one headline, one short supporting sentence
|
||||
- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal)
|
||||
- Color: define CSS variables, avoid purple-on-white defaults, one accent color default
|
||||
- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting"
|
||||
- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document
|
||||
|
||||
**App UI rules** (apply when classifier = APP UI):
|
||||
- Calm surface hierarchy, strong typography, few colors
|
||||
- Dense but readable, minimal chrome
|
||||
- Organize: primary workspace, navigation, secondary context, one accent
|
||||
- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
|
||||
- Copy: utility language — orientation, status, action. Not mood/brand/aspiration
|
||||
- Cards only when card IS the interaction
|
||||
- Section headings state what area is or what user can do ("Selected KPIs", "Plan status")
|
||||
|
||||
**Universal rules** (apply to ALL types):
|
||||
- Define CSS variables for color system
|
||||
- No default font stacks (Inter, Roboto, Arial, system)
|
||||
- One job per section
|
||||
- "If deleting 30% of the copy improves it, keep deleting"
|
||||
- Cards earn their existence — no decorative card grids
|
||||
|
||||
**AI Slop blacklist** (the 10 patterns that scream "AI-generated"):
|
||||
1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
|
||||
2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
|
||||
3. Icons in colored circles as section decoration (SaaS starter template look)
|
||||
4. Centered everything (`text-align: center` on all headings, descriptions, cards)
|
||||
5. Uniform bubbly border-radius on every element (same large radius on everything)
|
||||
6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
|
||||
7. Emoji as design elements (rockets in headings, emoji as bullet points)
|
||||
8. Colored left-border on cards (`border-left: 3px solid <accent>`)
|
||||
9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
|
||||
10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
|
||||
|
||||
Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology.
|
||||
|
||||
Record baseline design score and AI slop score at end of Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
.gstack/design-reports/
|
||||
├── design-audit-{domain}-{YYYY-MM-DD}.md # Structured report
|
||||
├── screenshots/
|
||||
│ ├── first-impression.png # Phase 1
|
||||
│ ├── {page}-annotated.png # Per-page annotated
|
||||
│ ├── {page}-mobile.png # Responsive
|
||||
│ ├── {page}-tablet.png
|
||||
│ ├── {page}-desktop.png
|
||||
│ ├── finding-001-before.png # Before fix
|
||||
│ ├── finding-001-after.png # After fix
|
||||
│ └── ...
|
||||
└── design-baseline.json # For regression mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Outside Voices (parallel)
|
||||
|
||||
**Automatic:** Outside voices run automatically when Codex is available. No opt-in needed.
|
||||
|
||||
**Check Codex availability:**
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
**If Codex is available**, launch both voices simultaneously:
|
||||
|
||||
1. **Codex design voice** (via Bash):
|
||||
```bash
|
||||
TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX)
|
||||
codex exec "Review the frontend source code in this repo. Evaluate against these design hard rules:
|
||||
- Spacing: systematic (design tokens / CSS variables) or magic numbers?
|
||||
- Typography: expressive purposeful fonts or default stacks?
|
||||
- Color: CSS variables with defined system, or hardcoded hex scattered?
|
||||
- Responsive: breakpoints defined? calc(100svh - header) for heroes? Mobile tested?
|
||||
- A11y: ARIA landmarks, alt text, contrast ratios, 44px touch targets?
|
||||
- Motion: 2-3 intentional animations, or zero / ornamental only?
|
||||
- Cards: used only when card IS the interaction? No decorative card grids?
|
||||
|
||||
First classify as MARKETING/LANDING PAGE vs APP UI vs HYBRID, then apply matching rules.
|
||||
|
||||
LITMUS CHECKS — answer YES/NO:
|
||||
1. Brand/product unmistakable in first screen?
|
||||
2. One strong visual anchor present?
|
||||
3. Page understandable by scanning headlines only?
|
||||
4. Each section has one job?
|
||||
5. Are cards actually necessary?
|
||||
6. Does motion improve hierarchy or atmosphere?
|
||||
7. Would design feel premium with all decorative shadows removed?
|
||||
|
||||
HARD REJECTION — flag if ANY apply:
|
||||
1. Generic SaaS card grid as first impression
|
||||
2. Beautiful image with weak brand
|
||||
3. Strong headline with no clear action
|
||||
4. Busy imagery behind text
|
||||
5. Sections repeating same mood statement
|
||||
6. Carousel with no narrative purpose
|
||||
7. App UI made of stacked cards instead of layout
|
||||
|
||||
Be specific. Reference file:line for every finding." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DESIGN"
|
||||
```
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN"
|
||||
```
|
||||
|
||||
2. **Claude design subagent** (via Agent tool):
|
||||
Dispatch a subagent with this prompt:
|
||||
"Review the frontend source code in this repo. You are an independent senior product designer doing a source-code design audit. Focus on CONSISTENCY PATTERNS across files rather than individual violations:
|
||||
- Are spacing values systematic across the codebase?
|
||||
- Is there ONE color system or scattered approaches?
|
||||
- Do responsive breakpoints follow a consistent set?
|
||||
- Is the accessibility approach consistent or spotty?
|
||||
|
||||
For each finding: what's wrong, severity (critical/high/medium), and the file:line."
|
||||
|
||||
**Error handling (all non-blocking):**
|
||||
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate."
|
||||
- **Timeout:** "Codex timed out after 5 minutes."
|
||||
- **Empty response:** "Codex returned no response."
|
||||
- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`.
|
||||
- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review."
|
||||
|
||||
Present Codex output under a `CODEX SAYS (design source audit):` header.
|
||||
Present subagent output under a `CLAUDE SUBAGENT (design consistency):` header.
|
||||
|
||||
**Synthesis — Litmus scorecard:**
|
||||
|
||||
Use the same scorecard format as /plan-design-review (shown above). Fill in from both outputs.
|
||||
Merge findings into the triage with `[codex]` / `[subagent]` / `[cross-model]` tags.
|
||||
|
||||
**Log the result:**
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable".
|
||||
|
||||
## Phase 7: Triage
|
||||
|
||||
Sort all discovered findings by impact, then decide which to fix:
|
||||
|
||||
- **High Impact:** Fix first. These affect the first impression and hurt user trust.
|
||||
- **Medium Impact:** Fix next. These reduce polish and are felt subconsciously.
|
||||
- **Polish:** Fix if time allows. These separate good from great.
|
||||
|
||||
Mark findings that cannot be fixed from source code (e.g., third-party widget issues, content problems requiring copy from the team) as "deferred" regardless of impact.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Fix Loop
|
||||
|
||||
For each fixable finding, in impact order:
|
||||
|
||||
### 8a. Locate source
|
||||
|
||||
```bash
|
||||
# Search for CSS classes, component names, style files
|
||||
# Glob for file patterns matching the affected page
|
||||
```
|
||||
|
||||
- Find the source file(s) responsible for the design issue
|
||||
- ONLY modify files directly related to the finding
|
||||
- Prefer CSS/styling changes over structural component changes
|
||||
|
||||
### 8b. Fix
|
||||
|
||||
- Read the source code, understand the context
|
||||
- Make the **minimal fix** — smallest change that resolves the design issue
|
||||
- CSS-only changes are preferred (safer, more reversible)
|
||||
- Do NOT refactor surrounding code, add features, or "improve" unrelated things
|
||||
|
||||
### 8c. Commit
|
||||
|
||||
```bash
|
||||
git add <only-changed-files>
|
||||
git commit -m "style(design): FINDING-NNN — short description"
|
||||
```
|
||||
|
||||
- One commit per fix. Never bundle multiple fixes.
|
||||
- Message format: `style(design): FINDING-NNN — short description`
|
||||
|
||||
### 8d. Re-test
|
||||
|
||||
Navigate back to the affected page and verify the fix:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <affected-url>
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/finding-NNN-after.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} snapshot -D
|
||||
```
|
||||
|
||||
Take **before/after screenshot pair** for every fix.
|
||||
|
||||
### 8e. Classify
|
||||
|
||||
- **verified**: re-test confirms the fix works, no new errors introduced
|
||||
- **best-effort**: fix applied but couldn't fully verify (e.g., needs specific browser state)
|
||||
- **reverted**: regression detected → `git revert HEAD` → mark finding as "deferred"
|
||||
|
||||
### 8e.5. Regression Test (design-review variant)
|
||||
|
||||
Design fixes are typically CSS-only. Only generate regression tests for fixes involving
|
||||
JavaScript behavior changes — broken dropdowns, animation failures, conditional rendering,
|
||||
interactive state issues.
|
||||
|
||||
For CSS-only fixes: skip entirely. CSS regressions are caught by re-running /design-review.
|
||||
|
||||
If the fix involved JS behavior: follow the same procedure as /qa Phase 8e.5 (study existing
|
||||
test patterns, write a regression test encoding the exact bug condition, run it, commit if
|
||||
passes or defer if fails). Commit format: `test(design): regression test for FINDING-NNN`.
|
||||
|
||||
### 8f. Self-Regulation (STOP AND EVALUATE)
|
||||
|
||||
Every 5 fixes (or after any revert), compute the design-fix risk level:
|
||||
|
||||
```
|
||||
DESIGN-FIX RISK:
|
||||
Start at 0%
|
||||
Each revert: +15%
|
||||
Each CSS-only file change: +0% (safe — styling only)
|
||||
Each JSX/TSX/component file change: +5% per file
|
||||
After fix 10: +1% per additional fix
|
||||
Touching unrelated files: +20%
|
||||
```
|
||||
|
||||
**If risk > 20%:** STOP immediately. Show the user what you've done so far. Ask whether to continue.
|
||||
|
||||
**Hard cap: 30 fixes.** After 30 fixes, stop regardless of remaining findings.
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Final Design Audit
|
||||
|
||||
After all fixes are applied:
|
||||
|
||||
1. Re-run the design audit on all affected pages
|
||||
2. Compute final design score and AI slop score
|
||||
3. **If final scores are WORSE than baseline:** WARN prominently — something regressed
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: Report
|
||||
|
||||
Write the report to both local and project-scoped locations:
|
||||
|
||||
**Local:** `.gstack/design-reports/design-audit-{domain}-{YYYY-MM-DD}.md`
|
||||
|
||||
**Project-scoped:**
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-audit-{datetime}.md`
|
||||
|
||||
**Per-finding additions** (beyond standard design audit report):
|
||||
- Fix Status: verified / best-effort / reverted / deferred
|
||||
- Commit SHA (if fixed)
|
||||
- Files Changed (if fixed)
|
||||
- Before/After screenshots (if fixed)
|
||||
|
||||
**Summary section:**
|
||||
- Total findings
|
||||
- Fixes applied (verified: X, best-effort: Y, reverted: Z)
|
||||
- Deferred findings
|
||||
- Design score delta: baseline → final
|
||||
- AI slop score delta: baseline → final
|
||||
|
||||
**PR Summary:** Include a one-line summary suitable for PR descriptions:
|
||||
> "Design review found N issues, fixed M. Design score X → Y, AI slop score X → Y."
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: TODOS.md Update
|
||||
|
||||
If the repo has a `TODOS.md`:
|
||||
|
||||
1. **New deferred design findings** → add as TODOs with impact level, category, and description
|
||||
2. **Fixed findings that were in TODOS.md** → annotate with "Fixed by /design-review on {branch}, {date}"
|
||||
|
||||
---
|
||||
|
||||
## Additional Rules (design-review specific)
|
||||
|
||||
11. **Clean working tree required.** If dirty, use question to offer commit/stash/abort before proceeding.
|
||||
12. **One commit per fix.** Never bundle multiple design fixes into one commit.
|
||||
13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files.
|
||||
14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately.
|
||||
15. **Self-regulate.** Follow the design-fix risk heuristic. When in doubt, stop and ask.
|
||||
16. **CSS-first.** Prefer CSS/styling changes over structural component changes. CSS-only changes are safer and more reversible.
|
||||
17. **DESIGN.md export.** You MAY write a DESIGN.md file if the user accepts the offer from Phase 2.
|
||||
|
|
@ -0,0 +1,341 @@
|
|||
---
|
||||
name: document-release
|
||||
description: "Post-ship documentation update. Reads all project docs, cross-references the diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, polishes CHANGELOG voice, cleans up TODOS, "
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# Document Release: Post-Ship Documentation Update
|
||||
|
||||
You are running the `/document-release` workflow. This runs **after `/ship`** (code committed, PR
|
||||
exists or about to exist) but **before the PR merges**. Your job: ensure every documentation file
|
||||
in the project is accurate, up to date, and written in a friendly, user-forward voice.
|
||||
|
||||
You are mostly automated. Make obvious factual updates directly. Stop and ask only for risky or
|
||||
subjective decisions.
|
||||
|
||||
**Only stop for:**
|
||||
- Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites)
|
||||
- VERSION bump decision (if not already bumped)
|
||||
- New TODOS items to add
|
||||
- Cross-doc contradictions that are narrative (not factual)
|
||||
|
||||
**Never stop for:**
|
||||
- Factual corrections clearly from the diff
|
||||
- Adding items to tables/lists
|
||||
- Updating paths, counts, version numbers
|
||||
- Fixing stale cross-references
|
||||
- CHANGELOG voice polish (minor wording adjustments)
|
||||
- Marking TODOS complete
|
||||
- Cross-doc factual inconsistencies (e.g., version number mismatch)
|
||||
|
||||
**NEVER do:**
|
||||
- Overwrite, replace, or regenerate CHANGELOG entries — polish wording only, preserve all content
|
||||
- Bump VERSION without asking — always use question for version changes
|
||||
- Use `Write` tool on CHANGELOG.md — always use `Edit` with exact `old_string` matches
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Pre-flight & Diff Analysis
|
||||
|
||||
1. Check the current branch. If on the base branch, **abort**: "You're on the base branch. Run from a feature branch."
|
||||
|
||||
2. Gather context about what changed:
|
||||
|
||||
```bash
|
||||
git diff <base>...HEAD --stat
|
||||
```
|
||||
|
||||
```bash
|
||||
git log <base>..HEAD --oneline
|
||||
```
|
||||
|
||||
```bash
|
||||
git diff <base>...HEAD --name-only
|
||||
```
|
||||
|
||||
3. Discover all documentation files in the repo:
|
||||
|
||||
```bash
|
||||
find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort
|
||||
```
|
||||
|
||||
4. Classify the changes into categories relevant to documentation:
|
||||
- **New features** — new files, new commands, new skills, new capabilities
|
||||
- **Changed behavior** — modified services, updated APIs, config changes
|
||||
- **Removed functionality** — deleted files, removed commands
|
||||
- **Infrastructure** — build system, test infrastructure, CI
|
||||
|
||||
5. Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Per-File Documentation Audit
|
||||
|
||||
Read each documentation file and cross-reference it against the diff. Use these generic heuristics
|
||||
(adapt to whatever project you're in — these are not gstack-specific):
|
||||
|
||||
**README.md:**
|
||||
- Does it describe all features and capabilities visible in the diff?
|
||||
- Are install/setup instructions consistent with the changes?
|
||||
- Are examples, demos, and usage descriptions still valid?
|
||||
- Are troubleshooting steps still accurate?
|
||||
|
||||
**ARCHITECTURE.md:**
|
||||
- Do ASCII diagrams and component descriptions match the current code?
|
||||
- Are design decisions and "why" explanations still accurate?
|
||||
- Be conservative — only update things clearly contradicted by the diff. Architecture docs
|
||||
describe things unlikely to change frequently.
|
||||
|
||||
**CONTRIBUTING.md — New contributor smoke test:**
|
||||
- Walk through the setup instructions as if you are a brand new contributor.
|
||||
- Are the listed commands accurate? Would each step succeed?
|
||||
- Do test tier descriptions match the current test infrastructure?
|
||||
- Are workflow descriptions (dev setup, contributor mode, etc.) current?
|
||||
- Flag anything that would fail or confuse a first-time contributor.
|
||||
|
||||
**CLAUDE.md / project instructions:**
|
||||
- Does the project structure section match the actual file tree?
|
||||
- Are listed commands and scripts accurate?
|
||||
- Do build/test instructions match what's in package.json (or equivalent)?
|
||||
|
||||
**Any other .md files:**
|
||||
- Read the file, determine its purpose and audience.
|
||||
- Cross-reference against the diff to check if it contradicts anything the file says.
|
||||
|
||||
For each file, classify needed updates as:
|
||||
|
||||
- **Auto-update** — Factual corrections clearly warranted by the diff: adding an item to a
|
||||
table, updating a file path, fixing a count, updating a project structure tree.
|
||||
- **Ask user** — Narrative changes, section removal, security model changes, large rewrites
|
||||
(more than ~10 lines in one section), ambiguous relevance, adding entirely new sections.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Apply Auto-Updates
|
||||
|
||||
Make all clear, factual updates directly using the Edit tool.
|
||||
|
||||
For each file modified, output a one-line summary describing **what specifically changed** — not
|
||||
just "Updated README.md" but "README.md: added /new-skill to skills table, updated skill count
|
||||
from 9 to 10."
|
||||
|
||||
**Never auto-update:**
|
||||
- README introduction or project positioning
|
||||
- ARCHITECTURE philosophy or design rationale
|
||||
- Security model descriptions
|
||||
- Do not remove entire sections from any document
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Ask About Risky/Questionable Changes
|
||||
|
||||
For each risky or questionable update identified in Step 2, use question with:
|
||||
- Context: project name, branch, which doc file, what we're reviewing
|
||||
- The specific documentation decision
|
||||
- `RECOMMENDATION: Choose [X] because [one-line reason]`
|
||||
- Options including C) Skip — leave as-is
|
||||
|
||||
Apply approved changes immediately after each answer.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: CHANGELOG Voice Polish
|
||||
|
||||
**CRITICAL — NEVER CLOBBER CHANGELOG ENTRIES.**
|
||||
|
||||
This step polishes voice. It does NOT rewrite, replace, or regenerate CHANGELOG content.
|
||||
|
||||
A real incident occurred where an agent replaced existing CHANGELOG entries when it should have
|
||||
preserved them. This skill must NEVER do that.
|
||||
|
||||
**Rules:**
|
||||
1. Read the entire CHANGELOG.md first. Understand what is already there.
|
||||
2. Only modify wording within existing entries. Never delete, reorder, or replace entries.
|
||||
3. Never regenerate a CHANGELOG entry from scratch. The entry was written by `/ship` from the
|
||||
actual diff and commit history. It is the source of truth. You are polishing prose, not
|
||||
rewriting history.
|
||||
4. If an entry looks wrong or incomplete, use question — do NOT silently fix it.
|
||||
5. Use Edit tool with exact `old_string` matches — never use Write to overwrite CHANGELOG.md.
|
||||
|
||||
**If CHANGELOG was not modified in this branch:** skip this step.
|
||||
|
||||
**If CHANGELOG was modified in this branch**, review the entry for voice:
|
||||
|
||||
- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not,
|
||||
rewrite the wording (not the content).
|
||||
- Lead with what the user can now **do** — not implementation details.
|
||||
- "You can now..." not "Refactored the..."
|
||||
- Flag and rewrite any entry that reads like a commit message.
|
||||
- Internal/contributor changes belong in a separate "### For contributors" subsection.
|
||||
- Auto-fix minor voice adjustments. Use question if a rewrite would alter meaning.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Cross-Doc Consistency & Discoverability Check
|
||||
|
||||
After auditing each file individually, do a cross-doc consistency pass:
|
||||
|
||||
1. Does the README's feature/capability list match what CLAUDE.md (or project instructions) describes?
|
||||
2. Does ARCHITECTURE's component list match CONTRIBUTING's project structure description?
|
||||
3. Does CHANGELOG's latest version match the VERSION file?
|
||||
4. **Discoverability:** Is every documentation file reachable from README.md or CLAUDE.md? If
|
||||
ARCHITECTURE.md exists but neither README nor CLAUDE.md links to it, flag it. Every doc
|
||||
should be discoverable from one of the two entry-point files.
|
||||
5. Flag any contradictions between documents. Auto-fix clear factual inconsistencies (e.g., a
|
||||
version mismatch). Use question for narrative contradictions.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: TODOS.md Cleanup
|
||||
|
||||
This is a second pass that complements `/ship`'s Step 5.5. Read `review/TODOS-format.md` (if
|
||||
available) for the canonical TODO item format.
|
||||
|
||||
If TODOS.md does not exist, skip this step.
|
||||
|
||||
1. **Completed items not yet marked:** Cross-reference the diff against open TODO items. If a
|
||||
TODO is clearly completed by the changes in this branch, move it to the Completed section
|
||||
with `**Completed:** vX.Y.Z.W (YYYY-MM-DD)`. Be conservative — only mark items with clear
|
||||
evidence in the diff.
|
||||
|
||||
2. **Items needing description updates:** If a TODO references files or components that were
|
||||
significantly changed, its description may be stale. Use question to confirm whether
|
||||
the TODO should be updated, completed, or left as-is.
|
||||
|
||||
3. **New deferred work:** Check the diff for `TODO`, `FIXME`, `HACK`, and `XXX` comments. For
|
||||
each one that represents meaningful deferred work (not a trivial inline note), use
|
||||
question to ask whether it should be captured in TODOS.md.
|
||||
|
||||
---
|
||||
|
||||
## Step 8: VERSION Bump Question
|
||||
|
||||
**CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.**
|
||||
|
||||
1. **If VERSION does not exist:** Skip silently.
|
||||
|
||||
2. Check if VERSION was already modified on this branch:
|
||||
|
||||
```bash
|
||||
git diff <base>...HEAD -- VERSION
|
||||
```
|
||||
|
||||
3. **If VERSION was NOT bumped:** Use question:
|
||||
- RECOMMENDATION: Choose C (Skip) because docs-only changes rarely warrant a version bump
|
||||
- A) Bump PATCH (X.Y.Z+1) — if doc changes ship alongside code changes
|
||||
- B) Bump MINOR (X.Y+1.0) — if this is a significant standalone release
|
||||
- C) Skip — no version bump needed
|
||||
|
||||
4. **If VERSION was already bumped:** Do NOT skip silently. Instead, check whether the bump
|
||||
still covers the full scope of changes on this branch:
|
||||
|
||||
a. Read the CHANGELOG entry for the current VERSION. What features does it describe?
|
||||
b. Read the full diff (`git diff <base>...HEAD --stat` and `git diff <base>...HEAD --name-only`).
|
||||
Are there significant changes (new features, new skills, new commands, major refactors)
|
||||
that are NOT mentioned in the CHANGELOG entry for the current version?
|
||||
c. **If the CHANGELOG entry covers everything:** Skip — output "VERSION: Already bumped to
|
||||
vX.Y.Z, covers all changes."
|
||||
d. **If there are significant uncovered changes:** Use question explaining what the
|
||||
current version covers vs what's new, and ask:
|
||||
- RECOMMENDATION: Choose A because the new changes warrant their own version
|
||||
- A) Bump to next patch (X.Y.Z+1) — give the new changes their own version
|
||||
- B) Keep current version — add new changes to the existing CHANGELOG entry
|
||||
- C) Skip — leave version as-is, handle later
|
||||
|
||||
The key insight: a VERSION bump set for "feature A" should not silently absorb "feature B"
|
||||
if feature B is substantial enough to deserve its own version entry.
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Commit & Output
|
||||
|
||||
**Empty check first:** Run `git status` (never use `-uall`). If no documentation files were
|
||||
modified by any previous step, output "All documentation is up to date." and exit without
|
||||
committing.
|
||||
|
||||
**Commit:**
|
||||
|
||||
1. Stage modified documentation files by name (never `git add -A` or `git add .`).
|
||||
2. Create a single commit:
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: update project documentation for vX.Y.Z.W
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. Push to the current branch:
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**PR body update (idempotent, race-safe):**
|
||||
|
||||
1. Read the existing PR body into a PID-unique tempfile:
|
||||
|
||||
```bash
|
||||
gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md
|
||||
```
|
||||
|
||||
2. If the tempfile already contains a `## Documentation` section, replace that section with the
|
||||
updated content. If it does not contain one, append a `## Documentation` section at the end.
|
||||
|
||||
3. The Documentation section should include a **doc diff preview** — for each file modified,
|
||||
describe what specifically changed (e.g., "README.md: added /document-release to skills
|
||||
table, updated skill count from 9 to 10").
|
||||
|
||||
4. Write the updated body back:
|
||||
|
||||
```bash
|
||||
gh pr edit --body-file /tmp/gstack-pr-body-$$.md
|
||||
```
|
||||
|
||||
5. Clean up the tempfile:
|
||||
|
||||
```bash
|
||||
rm -f /tmp/gstack-pr-body-$$.md
|
||||
```
|
||||
|
||||
6. If `gh pr view` fails (no PR exists): skip with message "No PR found — skipping body update."
|
||||
7. If `gh pr edit` fails: warn "Could not update PR body — documentation changes are in the
|
||||
commit." and continue.
|
||||
|
||||
**Structured doc health summary (final output):**
|
||||
|
||||
Output a scannable summary showing every documentation file's status:
|
||||
|
||||
```
|
||||
Documentation health:
|
||||
README.md [status] ([details])
|
||||
ARCHITECTURE.md [status] ([details])
|
||||
CONTRIBUTING.md [status] ([details])
|
||||
CHANGELOG.md [status] ([details])
|
||||
TODOS.md [status] ([details])
|
||||
VERSION [status] ([details])
|
||||
```
|
||||
|
||||
Where status is one of:
|
||||
- Updated — with description of what changed
|
||||
- Current — no changes needed
|
||||
- Voice polished — wording adjusted
|
||||
- Not bumped — user chose to skip
|
||||
- Already bumped — version was set by /ship
|
||||
- Skipped — file does not exist
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Read before editing.** Always read the full content of a file before modifying it.
|
||||
- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries.
|
||||
- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes.
|
||||
- **Be explicit about what changed.** Every edit gets a one-line summary.
|
||||
- **Generic heuristics, not project-specific.** The audit checks work on any repo.
|
||||
- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
|
||||
- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
|
||||
who hasn't seen the code.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: freeze
|
||||
description: "Restrict file edits to a specific directory for the session. Blocks Edit and Write outside the allowed path. Use when debugging to prevent accidentally "fixing" unrelated code, or when you want to sco"
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
name: gstack-upgrade
|
||||
description: "Upgrade gstack to the latest version. Detects global vs vendored install, runs the upgrade, and shows what's new. Use when asked to "upgrade gstack", "update gstack", or "get latest version"."
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Standalone usage
|
||||
|
||||
When invoked directly as `/gstack-upgrade` (not from a preamble):
|
||||
|
||||
1. Force a fresh update check (bypass cache):
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-update-check --force 2>/dev/null || \
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-update-check --force 2>/dev/null || true
|
||||
```
|
||||
Use the output to determine if an upgrade is available.
|
||||
|
||||
2. If `UPGRADE_AVAILABLE <old> <new>`: follow Steps 2-6 above.
|
||||
|
||||
3. If no output (primary is up to date): check for a stale local vendored copy.
|
||||
|
||||
Run the Step 2 bash block above to detect the primary install type and directory (`INSTALL_TYPE` and `INSTALL_DIR`). Then run the Step 4.5 detection bash block above to check for a local vendored copy (`LOCAL_GSTACK`).
|
||||
|
||||
**If `LOCAL_GSTACK` is empty** (no local vendored copy): tell the user "You're already on the latest version (v{version})."
|
||||
|
||||
**If `LOCAL_GSTACK` is non-empty**, compare versions:
|
||||
```bash
|
||||
PRIMARY_VER=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown")
|
||||
LOCAL_VER=$(cat "$LOCAL_GSTACK/VERSION" 2>/dev/null || echo "unknown")
|
||||
echo "PRIMARY=$PRIMARY_VER LOCAL=$LOCAL_VER"
|
||||
```
|
||||
|
||||
**If versions differ:** follow the Step 4.5 sync bash block above to update the local copy from the primary. Tell user: "Global v{PRIMARY_VER} is up to date. Updated local vendored copy from v{LOCAL_VER} → v{PRIMARY_VER}. Commit `${GSTACK_OPENCODE_DIR}/` when you're ready."
|
||||
|
||||
**If versions match:** tell the user "You're on the latest version (v{PRIMARY_VER}). Global and local vendored copy are both up to date."
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: guard
|
||||
description: "Full safety mode: destructive command warnings + directory-scoped edits. Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with /freeze (blocks edits outside a specified directory)"
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
name: investigate
|
||||
description: "Systematic debugging with root cause investigation. Four phases: investigate, analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "w"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Root Cause Investigation
|
||||
|
||||
Gather context before forming any hypothesis.
|
||||
|
||||
1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time via question.
|
||||
|
||||
2. **Read the code:** Trace the code path from the symptom back to potential causes. Use Grep to find all references, Read to understand the logic.
|
||||
|
||||
3. **Check recent changes:**
|
||||
```bash
|
||||
git log --oneline -20 -- <affected-files>
|
||||
```
|
||||
Was this working before? What changed? A regression means the root cause is in the diff.
|
||||
|
||||
4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.
|
||||
|
||||
Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why.
|
||||
|
||||
---
|
||||
|
||||
## Scope Lock
|
||||
|
||||
After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep.
|
||||
|
||||
```bash
|
||||
[ -x "${GSTACK_OPENCODE_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE"
|
||||
```
|
||||
|
||||
**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file:
|
||||
|
||||
```bash
|
||||
STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
|
||||
mkdir -p "$STATE_DIR"
|
||||
echo "<detected-directory>/" > "$STATE_DIR/freeze-dir.txt"
|
||||
echo "Debug scope locked to: <detected-directory>/"
|
||||
```
|
||||
|
||||
Substitute `<detected-directory>` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `<dir>/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction."
|
||||
|
||||
If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why.
|
||||
|
||||
**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Pattern Analysis
|
||||
|
||||
Check if this bug matches a known pattern:
|
||||
|
||||
| Pattern | Signature | Where to look |
|
||||
|---------|-----------|---------------|
|
||||
| Race condition | Intermittent, timing-dependent | Concurrent access to shared state |
|
||||
| Nil/null propagation | NoMethodError, TypeError | Missing guards on optional values |
|
||||
| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks |
|
||||
| Integration failure | Timeout, unexpected response | External API calls, service boundaries |
|
||||
| Configuration drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state |
|
||||
| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache, Turbo |
|
||||
|
||||
Also check:
|
||||
- `TODOS.md` for related known issues
|
||||
- `git log` for prior fixes in the same area — **recurring bugs in the same files are an architectural smell**, not a coincidence
|
||||
|
||||
**External pattern search:** If the bug doesn't match a known pattern above, WebSearch for:
|
||||
- "{framework} {generic error type}" — **sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.
|
||||
- "{library} {component} known issues"
|
||||
|
||||
If WebSearch is unavailable, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Hypothesis Testing
|
||||
|
||||
Before writing ANY fix, verify your hypothesis.
|
||||
|
||||
1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?
|
||||
|
||||
2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If WebSearch is unavailable, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess.
|
||||
|
||||
3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use question:
|
||||
```
|
||||
3 hypotheses tested, none match. This may be an architectural issue
|
||||
rather than a simple bug.
|
||||
|
||||
A) Continue investigating — I have a new hypothesis: [describe]
|
||||
B) Escalate for human review — this needs someone who knows the system
|
||||
C) Add logging and wait — instrument the area and catch it next time
|
||||
```
|
||||
|
||||
**Red flags** — if you see any of these, slow down:
|
||||
- "Quick fix for now" — there is no "for now." Fix it right or escalate.
|
||||
- Proposing a fix before tracing data flow — you're guessing.
|
||||
- Each fix reveals a new problem elsewhere — wrong layer, not wrong code.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Implementation
|
||||
|
||||
Once root cause is confirmed:
|
||||
|
||||
1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem.
|
||||
|
||||
2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code.
|
||||
|
||||
3. **Write a regression test** that:
|
||||
- **Fails** without the fix (proves the test is meaningful)
|
||||
- **Passes** with the fix (proves the fix works)
|
||||
|
||||
4. **Run the full test suite.** Paste the output. No regressions allowed.
|
||||
|
||||
5. **If the fix touches >5 files:** Use question to flag the blast radius:
|
||||
```
|
||||
This fix touches N files. That's a large blast radius for a bug fix.
|
||||
A) Proceed — the root cause genuinely spans these files
|
||||
B) Split — fix the critical path now, defer the rest
|
||||
C) Rethink — maybe there's a more targeted approach
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Verification & Report
|
||||
|
||||
**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional.
|
||||
|
||||
Run the test suite and paste the output.
|
||||
|
||||
Output a structured debug report:
|
||||
```
|
||||
DEBUG REPORT
|
||||
════════════════════════════════════════
|
||||
Symptom: [what the user observed]
|
||||
Root cause: [what was actually wrong]
|
||||
Fix: [what was changed, with file:line references]
|
||||
Evidence: [test output, reproduction attempt showing fix works]
|
||||
Regression test: [file:line of the new test]
|
||||
Related: [TODOS.md items, prior bugs in same area, architectural notes]
|
||||
Status: DONE | DONE_WITH_CONCERNS | BLOCKED
|
||||
════════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **3+ failed fix attempts → STOP and question the architecture.** Wrong architecture, not failed hypothesis.
|
||||
- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it.
|
||||
- **Never say "this should fix it."** Verify and prove it. Run the tests.
|
||||
- **If fix touches >5 files → question** about blast radius before proceeding.
|
||||
- **Completion status:**
|
||||
- DONE — root cause found, fix applied, regression test written, all tests pass
|
||||
- DONE_WITH_CONCERNS — fixed but cannot fully verify (e.g., intermittent bug, requires staging)
|
||||
- BLOCKED — root cause unclear after investigation, escalated
|
||||
|
|
@ -0,0 +1,592 @@
|
|||
---
|
||||
name: land-and-deploy
|
||||
description: "Land and deploy workflow. Merges the PR, waits for CI and deploy, verifies production health via canary checks. Takes over after /ship creates the PR. Use when: "merge", "land", "deploy", "merge and v"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /land-and-deploy — Merge, Deploy, Verify
|
||||
|
||||
You are a **Release Engineer** who has deployed to production thousands of times. You know the two worst feelings in software: the merge that breaks prod, and the merge that sits in queue for 45 minutes while you stare at the screen. Your job is to handle both gracefully — merge efficiently, wait intelligently, verify thoroughly, and give the user a clear verdict.
|
||||
|
||||
This skill picks up where `/ship` left off. `/ship` creates the PR. You merge it, wait for deploy, and verify production.
|
||||
|
||||
## User-invocable
|
||||
When the user types `/land-and-deploy`, run this skill.
|
||||
|
||||
## Arguments
|
||||
- `/land-and-deploy` — auto-detect PR from current branch, no post-deploy URL
|
||||
- `/land-and-deploy <url>` — auto-detect PR, verify deploy at this URL
|
||||
- `/land-and-deploy #123` — specific PR number
|
||||
- `/land-and-deploy #123 <url>` — specific PR + verification URL
|
||||
|
||||
## Non-interactive philosophy (like /ship) — with one critical gate
|
||||
|
||||
This is a **mostly automated** workflow. Do NOT ask for confirmation at any step except
|
||||
the ones listed below. The user said `/land-and-deploy` which means DO IT — but verify
|
||||
readiness first.
|
||||
|
||||
**Always stop for:**
|
||||
- **Pre-merge readiness gate (Step 3.5)** — this is the ONE confirmation before merge
|
||||
- GitHub CLI not authenticated
|
||||
- No PR found for this branch
|
||||
- CI failures or merge conflicts
|
||||
- Permission denied on merge
|
||||
- Deploy workflow failure (offer revert)
|
||||
- Production health issues detected by canary (offer revert)
|
||||
|
||||
**Never stop for:**
|
||||
- Choosing merge method (auto-detect from repo settings)
|
||||
- Timeout warnings (warn and continue gracefully)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check GitHub CLI authentication:
|
||||
```bash
|
||||
gh auth status
|
||||
```
|
||||
If not authenticated, **STOP**: "GitHub CLI is not authenticated. Run `gh auth login` first."
|
||||
|
||||
2. Parse arguments. If the user specified `#NNN`, use that PR number. If a URL was provided, save it for canary verification in Step 7.
|
||||
|
||||
3. If no PR number specified, detect from current branch:
|
||||
```bash
|
||||
gh pr view --json number,state,title,url,mergeStateStatus,mergeable,baseRefName,headRefName
|
||||
```
|
||||
|
||||
4. Validate the PR state:
|
||||
- If no PR exists: **STOP.** "No PR found for this branch. Run `/ship` first to create one."
|
||||
- If `state` is `MERGED`: "PR is already merged. Nothing to do."
|
||||
- If `state` is `CLOSED`: "PR is closed (not merged). Reopen it first."
|
||||
- If `state` is `OPEN`: continue.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Pre-merge checks
|
||||
|
||||
Check CI status and merge readiness:
|
||||
|
||||
```bash
|
||||
gh pr checks --json name,state,status,conclusion
|
||||
```
|
||||
|
||||
Parse the output:
|
||||
1. If any required checks are **FAILING**: **STOP.** Show the failing checks.
|
||||
2. If required checks are **PENDING**: proceed to Step 3.
|
||||
3. If all checks pass (or no required checks): skip Step 3, go to Step 4.
|
||||
|
||||
Also check for merge conflicts:
|
||||
```bash
|
||||
gh pr view --json mergeable -q .mergeable
|
||||
```
|
||||
If `CONFLICTING`: **STOP.** "PR has merge conflicts. Resolve them and push before landing."
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Wait for CI (if pending)
|
||||
|
||||
If required checks are still pending, wait for them to complete. Use a timeout of 15 minutes:
|
||||
|
||||
```bash
|
||||
gh pr checks --watch --fail-fast
|
||||
```
|
||||
|
||||
Record the CI wait time for the deploy report.
|
||||
|
||||
If CI passes within the timeout: continue to Step 4.
|
||||
If CI fails: **STOP.** Show failures.
|
||||
If timeout (15 min): **STOP.** "CI has been running for 15 minutes. Investigate manually."
|
||||
|
||||
---
|
||||
|
||||
## Step 3.5: Pre-merge readiness gate
|
||||
|
||||
**This is the critical safety check before an irreversible merge.** The merge cannot
|
||||
be undone without a revert commit. Gather ALL evidence, build a readiness report,
|
||||
and get explicit user confirmation before proceeding.
|
||||
|
||||
Collect evidence for each check below. Track warnings (yellow) and blockers (red).
|
||||
|
||||
### 3.5a: Review staleness check
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-read 2>/dev/null
|
||||
```
|
||||
|
||||
Parse the output. For each review skill (plan-eng-review, plan-ceo-review,
|
||||
plan-design-review, design-review-lite, codex-review):
|
||||
|
||||
1. Find the most recent entry within the last 7 days.
|
||||
2. Extract its `commit` field.
|
||||
3. Compare against current HEAD: `git rev-list --count STORED_COMMIT..HEAD`
|
||||
|
||||
**Staleness rules:**
|
||||
- 0 commits since review → CURRENT
|
||||
- 1-3 commits since review → RECENT (yellow if those commits touch code, not just docs)
|
||||
- 4+ commits since review → STALE (red — review may not reflect current code)
|
||||
- No review found → NOT RUN
|
||||
|
||||
**Critical check:** Look at what changed AFTER the last review. Run:
|
||||
```bash
|
||||
git log --oneline STORED_COMMIT..HEAD
|
||||
```
|
||||
If any commits after the review contain words like "fix", "refactor", "rewrite",
|
||||
"overhaul", or touch more than 5 files — flag as **STALE (significant changes
|
||||
since review)**. The review was done on different code than what's about to merge.
|
||||
|
||||
### 3.5b: Test results
|
||||
|
||||
**Free tests — run them now:**
|
||||
|
||||
Read CLAUDE.md to find the project's test command. If not specified, use `bun test`.
|
||||
Run the test command and capture the exit code and output.
|
||||
|
||||
```bash
|
||||
bun test 2>&1 | tail -10
|
||||
```
|
||||
|
||||
If tests fail: **BLOCKER.** Cannot merge with failing tests.
|
||||
|
||||
**E2E tests — check recent results:**
|
||||
|
||||
```bash
|
||||
ls -t ~/.gstack-dev/evals/*-e2e-*-$(date +%Y-%m-%d)*.json 2>/dev/null | head -20
|
||||
```
|
||||
|
||||
For each eval file from today, parse pass/fail counts. Show:
|
||||
- Total tests, pass count, fail count
|
||||
- How long ago the run finished (from file timestamp)
|
||||
- Total cost
|
||||
- Names of any failing tests
|
||||
|
||||
If no E2E results from today: **WARNING — no E2E tests run today.**
|
||||
If E2E results exist but have failures: **WARNING — N tests failed.** List them.
|
||||
|
||||
**LLM judge evals — check recent results:**
|
||||
|
||||
```bash
|
||||
ls -t ~/.gstack-dev/evals/*-llm-judge-*-$(date +%Y-%m-%d)*.json 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
If found, parse and show pass/fail. If not found, note "No LLM evals run today."
|
||||
|
||||
### 3.5c: PR body accuracy check
|
||||
|
||||
Read the current PR body:
|
||||
```bash
|
||||
gh pr view --json body -q .body
|
||||
```
|
||||
|
||||
Read the current diff summary:
|
||||
```bash
|
||||
git log --oneline $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main)..HEAD | head -20
|
||||
```
|
||||
|
||||
Compare the PR body against the actual commits. Check for:
|
||||
1. **Missing features** — commits that add significant functionality not mentioned in the PR
|
||||
2. **Stale descriptions** — PR body mentions things that were later changed or reverted
|
||||
3. **Wrong version** — PR title or body references a version that doesn't match VERSION file
|
||||
|
||||
If the PR body looks stale or incomplete: **WARNING — PR body may not reflect current
|
||||
changes.** List what's missing or stale.
|
||||
|
||||
### 3.5d: Document-release check
|
||||
|
||||
Check if documentation was updated on this branch:
|
||||
|
||||
```bash
|
||||
git log --oneline --all-match --grep="docs:" $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main)..HEAD | head -5
|
||||
```
|
||||
|
||||
Also check if key doc files were modified:
|
||||
```bash
|
||||
git diff --name-only $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main)...HEAD -- README.md CHANGELOG.md ARCHITECTURE.md CONTRIBUTING.md CLAUDE.md VERSION
|
||||
```
|
||||
|
||||
If CHANGELOG.md and VERSION were NOT modified on this branch and the diff includes
|
||||
new features (new files, new commands, new skills): **WARNING — /document-release
|
||||
likely not run. CHANGELOG and VERSION not updated despite new features.**
|
||||
|
||||
If only docs changed (no code): skip this check.
|
||||
|
||||
### 3.5e: Readiness report and confirmation
|
||||
|
||||
Build the full readiness report:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════╗
|
||||
║ PRE-MERGE READINESS REPORT ║
|
||||
╠══════════════════════════════════════════════════════════╣
|
||||
║ ║
|
||||
║ PR: #NNN — title ║
|
||||
║ Branch: feature → main ║
|
||||
║ ║
|
||||
║ REVIEWS ║
|
||||
║ ├─ Eng Review: CURRENT / STALE (N commits) / — ║
|
||||
║ ├─ CEO Review: CURRENT / — (optional) ║
|
||||
║ ├─ Design Review: CURRENT / — (optional) ║
|
||||
║ └─ Codex Review: CURRENT / — (optional) ║
|
||||
║ ║
|
||||
║ TESTS ║
|
||||
║ ├─ Free tests: PASS / FAIL (blocker) ║
|
||||
║ ├─ E2E tests: 52/52 pass (25 min ago) / NOT RUN ║
|
||||
║ └─ LLM evals: PASS / NOT RUN ║
|
||||
║ ║
|
||||
║ DOCUMENTATION ║
|
||||
║ ├─ CHANGELOG: Updated / NOT UPDATED (warning) ║
|
||||
║ ├─ VERSION: 0.9.8.0 / NOT BUMPED (warning) ║
|
||||
║ └─ Doc release: Run / NOT RUN (warning) ║
|
||||
║ ║
|
||||
║ PR BODY ║
|
||||
║ └─ Accuracy: Current / STALE (warning) ║
|
||||
║ ║
|
||||
║ WARNINGS: N | BLOCKERS: N ║
|
||||
╚══════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
If there are BLOCKERS (failing free tests): list them and recommend B.
|
||||
If there are WARNINGS but no blockers: list each warning and recommend A if
|
||||
warnings are minor, or B if warnings are significant.
|
||||
If everything is green: recommend A.
|
||||
|
||||
Use question:
|
||||
|
||||
- **Re-ground:** "About to merge PR #NNN (title) from branch X to Y. Here's the
|
||||
readiness report." Show the report above.
|
||||
- List each warning and blocker explicitly.
|
||||
- **RECOMMENDATION:** Choose A if green. Choose B if there are significant warnings.
|
||||
Choose C only if the user understands the risks.
|
||||
- A) Merge — readiness checks passed (Completeness: 10/10)
|
||||
- B) Don't merge yet — address the warnings first (Completeness: 10/10)
|
||||
- C) Merge anyway — I understand the risks (Completeness: 3/10)
|
||||
|
||||
If the user chooses B: **STOP.** List exactly what needs to be done:
|
||||
- If reviews are stale: "Re-run /plan-eng-review (or /review) to review current code."
|
||||
- If E2E not run: "Run `bun run test:e2e` to verify."
|
||||
- If docs not updated: "Run /document-release to update documentation."
|
||||
- If PR body stale: "Update the PR body to reflect current changes."
|
||||
|
||||
If the user chooses A or C: continue to Step 4.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Merge the PR
|
||||
|
||||
Record the start timestamp for timing data.
|
||||
|
||||
Try auto-merge first (respects repo merge settings and merge queues):
|
||||
|
||||
```bash
|
||||
gh pr merge --auto --delete-branch
|
||||
```
|
||||
|
||||
If `--auto` is not available (repo doesn't have auto-merge enabled), merge directly:
|
||||
|
||||
```bash
|
||||
gh pr merge --squash --delete-branch
|
||||
```
|
||||
|
||||
If the merge fails with a permission error: **STOP.** "You don't have merge permissions on this repo. Ask a maintainer to merge."
|
||||
|
||||
If merge queue is active, `gh pr merge --auto` will enqueue. Poll for the PR to actually merge:
|
||||
|
||||
```bash
|
||||
gh pr view --json state -q .state
|
||||
```
|
||||
|
||||
Poll every 30 seconds, up to 30 minutes. Show a progress message every 2 minutes: "Waiting for merge queue... (Xm elapsed)"
|
||||
|
||||
If the PR state changes to `MERGED`: capture the merge commit SHA and continue.
|
||||
If the PR is removed from the queue (state goes back to `OPEN`): **STOP.** "PR was removed from the merge queue."
|
||||
If timeout (30 min): **STOP.** "Merge queue has been processing for 30 minutes. Check the queue manually."
|
||||
|
||||
Record merge timestamp and duration.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Deploy strategy detection
|
||||
|
||||
Determine what kind of project this is and how to verify the deploy.
|
||||
|
||||
First, run the deploy configuration bootstrap to detect or read persisted deploy settings:
|
||||
|
||||
```bash
|
||||
# Check for persisted deploy config in CLAUDE.md
|
||||
DEPLOY_CONFIG=$(grep -A 20 "## Deploy Configuration" CLAUDE.md 2>/dev/null || echo "NO_CONFIG")
|
||||
echo "$DEPLOY_CONFIG"
|
||||
|
||||
# If config exists, parse it
|
||||
if [ "$DEPLOY_CONFIG" != "NO_CONFIG" ]; then
|
||||
PROD_URL=$(echo "$DEPLOY_CONFIG" | grep -i "production.*url" | head -1 | sed 's/.*: *//')
|
||||
PLATFORM=$(echo "$DEPLOY_CONFIG" | grep -i "platform" | head -1 | sed 's/.*: *//')
|
||||
echo "PERSISTED_PLATFORM:$PLATFORM"
|
||||
echo "PERSISTED_URL:$PROD_URL"
|
||||
fi
|
||||
|
||||
# Auto-detect platform from config files
|
||||
[ -f fly.toml ] && echo "PLATFORM:fly"
|
||||
[ -f render.yaml ] && echo "PLATFORM:render"
|
||||
([ -f vercel.json ] || [ -d .vercel ]) && echo "PLATFORM:vercel"
|
||||
[ -f netlify.toml ] && echo "PLATFORM:netlify"
|
||||
[ -f Procfile ] && echo "PLATFORM:heroku"
|
||||
([ -f railway.json ] || [ -f railway.toml ]) && echo "PLATFORM:railway"
|
||||
|
||||
# Detect deploy workflows
|
||||
for f in .github/workflows/*.yml .github/workflows/*.yaml; do
|
||||
[ -f "$f" ] && grep -qiE "deploy|release|production|staging|cd" "$f" 2>/dev/null && echo "DEPLOY_WORKFLOW:$f"
|
||||
done
|
||||
```
|
||||
|
||||
If `PERSISTED_PLATFORM` and `PERSISTED_URL` were found in CLAUDE.md, use them directly
|
||||
and skip manual detection. If no persisted config exists, use the auto-detected platform
|
||||
to guide deploy verification. If nothing is detected, ask the user via question
|
||||
in the decision tree below.
|
||||
|
||||
If you want to persist deploy settings for future runs, suggest the user run `/setup-deploy`.
|
||||
|
||||
Then run `gstack-diff-scope` to classify the changes:
|
||||
|
||||
```bash
|
||||
eval $(${GSTACK_OPENCODE_DIR}/bin/gstack-diff-scope $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main) 2>/dev/null)
|
||||
echo "FRONTEND=$SCOPE_FRONTEND BACKEND=$SCOPE_BACKEND DOCS=$SCOPE_DOCS CONFIG=$SCOPE_CONFIG"
|
||||
```
|
||||
|
||||
**Decision tree (evaluate in order):**
|
||||
|
||||
1. If the user provided a production URL as an argument: use it for canary verification. Also check for deploy workflows.
|
||||
|
||||
2. Check for GitHub Actions deploy workflows:
|
||||
```bash
|
||||
gh run list --branch <base> --limit 5 --json name,status,conclusion,headSha,workflowName
|
||||
```
|
||||
Look for workflow names containing "deploy", "release", "production", "staging", or "cd". If found: poll the deploy workflow in Step 6, then run canary.
|
||||
|
||||
3. If SCOPE_DOCS is the only scope that's true (no frontend, no backend, no config): skip verification entirely. Output: "PR merged. Documentation-only change — no deploy verification needed." Go to Step 9.
|
||||
|
||||
4. If no deploy workflows detected and no URL provided: use question once:
|
||||
- **Context:** PR merged successfully. No deploy workflow or production URL detected.
|
||||
- **RECOMMENDATION:** Choose B if this is a library/CLI tool. Choose A if this is a web app.
|
||||
- A) Provide a production URL to verify
|
||||
- B) Skip verification — this project doesn't have a web deploy
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Wait for deploy (if applicable)
|
||||
|
||||
The deploy verification strategy depends on the platform detected in Step 5.
|
||||
|
||||
### Strategy A: GitHub Actions workflow
|
||||
|
||||
If a deploy workflow was detected, find the run triggered by the merge commit:
|
||||
|
||||
```bash
|
||||
gh run list --branch <base> --limit 10 --json databaseId,headSha,status,conclusion,name,workflowName
|
||||
```
|
||||
|
||||
Match by the merge commit SHA (captured in Step 4). If multiple matching workflows, prefer the one whose name matches the deploy workflow detected in Step 5.
|
||||
|
||||
Poll every 30 seconds:
|
||||
```bash
|
||||
gh run view <run-id> --json status,conclusion
|
||||
```
|
||||
|
||||
### Strategy B: Platform CLI (Fly.io, Render, Heroku)
|
||||
|
||||
If a deploy status command was configured in CLAUDE.md (e.g., `fly status --app myapp`), use it instead of or in addition to GitHub Actions polling.
|
||||
|
||||
**Fly.io:** After merge, Fly deploys via GitHub Actions or `fly deploy`. Check with:
|
||||
```bash
|
||||
fly status --app {app} 2>/dev/null
|
||||
```
|
||||
Look for `Machines` status showing `started` and recent deployment timestamp.
|
||||
|
||||
**Render:** Render auto-deploys on push to the connected branch. Check by polling the production URL until it responds:
|
||||
```bash
|
||||
curl -sf {production-url} -o /dev/null -w "%{http_code}" 2>/dev/null
|
||||
```
|
||||
Render deploys typically take 2-5 minutes. Poll every 30 seconds.
|
||||
|
||||
**Heroku:** Check latest release:
|
||||
```bash
|
||||
heroku releases --app {app} -n 1 2>/dev/null
|
||||
```
|
||||
|
||||
### Strategy C: Auto-deploy platforms (Vercel, Netlify)
|
||||
|
||||
Vercel and Netlify deploy automatically on merge. No explicit deploy trigger needed. Wait 60 seconds for the deploy to propagate, then proceed directly to canary verification in Step 7.
|
||||
|
||||
### Strategy D: Custom deploy hooks
|
||||
|
||||
If CLAUDE.md has a custom deploy status command in the "Custom deploy hooks" section, run that command and check its exit code.
|
||||
|
||||
### Common: Timing and failure handling
|
||||
|
||||
Record deploy start time. Show progress every 2 minutes: "Deploy in progress... (Xm elapsed)"
|
||||
|
||||
If deploy succeeds (`conclusion` is `success` or health check passes): record deploy duration, continue to Step 7.
|
||||
|
||||
If deploy fails (`conclusion` is `failure`): use question:
|
||||
- **Context:** Deploy workflow failed after merging PR.
|
||||
- **RECOMMENDATION:** Choose A to investigate before reverting.
|
||||
- A) Investigate the deploy logs
|
||||
- B) Create a revert commit on the base branch
|
||||
- C) Continue anyway — the deploy failure might be unrelated
|
||||
|
||||
If timeout (20 min): warn "Deploy has been running for 20 minutes" and ask whether to continue waiting or skip verification.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Canary verification (conditional depth)
|
||||
|
||||
Use the diff-scope classification from Step 5 to determine canary depth:
|
||||
|
||||
| Diff Scope | Canary Depth |
|
||||
|------------|-------------|
|
||||
| SCOPE_DOCS only | Already skipped in Step 5 |
|
||||
| SCOPE_CONFIG only | Smoke: `${GSTACK_BROWSE} goto` + verify 200 status |
|
||||
| SCOPE_BACKEND only | Console errors + perf check |
|
||||
| SCOPE_FRONTEND (any) | Full: console + perf + screenshot |
|
||||
| Mixed scopes | Full canary |
|
||||
|
||||
**Full canary sequence:**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <url>
|
||||
```
|
||||
|
||||
Check that the page loaded successfully (200, not an error page).
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} console --errors
|
||||
```
|
||||
|
||||
Check for critical console errors: lines containing `Error`, `Uncaught`, `Failed to load`, `TypeError`, `ReferenceError`. Ignore warnings.
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} perf
|
||||
```
|
||||
|
||||
Check that page load time is under 10 seconds.
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} text
|
||||
```
|
||||
|
||||
Verify the page has content (not blank, not a generic error page).
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} snapshot -i -a -o ".gstack/deploy-reports/post-deploy.png"
|
||||
```
|
||||
|
||||
Take an annotated screenshot as evidence.
|
||||
|
||||
**Health assessment:**
|
||||
- Page loads successfully with 200 status → PASS
|
||||
- No critical console errors → PASS
|
||||
- Page has real content (not blank or error screen) → PASS
|
||||
- Loads in under 10 seconds → PASS
|
||||
|
||||
If all pass: mark as HEALTHY, continue to Step 9.
|
||||
|
||||
If any fail: show the evidence (screenshot path, console errors, perf numbers). Use question:
|
||||
- **Context:** Post-deploy canary detected issues on the production site.
|
||||
- **RECOMMENDATION:** Choose based on severity — B for critical (site down), A for minor (console errors).
|
||||
- A) Expected (deploy in progress, cache clearing) — mark as healthy
|
||||
- B) Broken — create a revert commit
|
||||
- C) Investigate further (open the site, look at logs)
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Revert (if needed)
|
||||
|
||||
If the user chose to revert at any point:
|
||||
|
||||
```bash
|
||||
git fetch origin <base>
|
||||
git checkout <base>
|
||||
git revert <merge-commit-sha> --no-edit
|
||||
git push origin <base>
|
||||
```
|
||||
|
||||
If the revert has conflicts: warn "Revert has conflicts — manual resolution needed. The merge commit SHA is `<sha>`. You can run `git revert <sha>` manually."
|
||||
|
||||
If the base branch has push protections: warn "Branch protections may prevent direct push — create a revert PR instead: `gh pr create --title 'revert: <original PR title>'`"
|
||||
|
||||
After a successful revert, note the revert commit SHA and continue to Step 9 with status REVERTED.
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Deploy report
|
||||
|
||||
Create the deploy report directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .gstack/deploy-reports
|
||||
```
|
||||
|
||||
Produce and display the ASCII summary:
|
||||
|
||||
```
|
||||
LAND & DEPLOY REPORT
|
||||
═════════════════════
|
||||
PR: #<number> — <title>
|
||||
Branch: <head-branch> → <base-branch>
|
||||
Merged: <timestamp> (<merge method>)
|
||||
Merge SHA: <sha>
|
||||
|
||||
Timing:
|
||||
CI wait: <duration>
|
||||
Queue: <duration or "direct merge">
|
||||
Deploy: <duration or "no workflow detected">
|
||||
Canary: <duration or "skipped">
|
||||
Total: <end-to-end duration>
|
||||
|
||||
CI: <PASSED / SKIPPED>
|
||||
Deploy: <PASSED / FAILED / NO WORKFLOW>
|
||||
Verification: <HEALTHY / DEGRADED / SKIPPED / REVERTED>
|
||||
Scope: <FRONTEND / BACKEND / CONFIG / DOCS / MIXED>
|
||||
Console: <N errors or "clean">
|
||||
Load time: <Xs>
|
||||
Screenshot: <path or "none">
|
||||
|
||||
VERDICT: <DEPLOYED AND VERIFIED / DEPLOYED (UNVERIFIED) / REVERTED>
|
||||
```
|
||||
|
||||
Save report to `.gstack/deploy-reports/{date}-pr{number}-deploy.md`.
|
||||
|
||||
Log to the review dashboard:
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
|
||||
Write a JSONL entry with timing data:
|
||||
```json
|
||||
{"skill":"land-and-deploy","timestamp":"<ISO>","status":"<SUCCESS/REVERTED>","pr":<number>,"merge_sha":"<sha>","deploy_status":"<HEALTHY/DEGRADED/SKIPPED>","ci_wait_s":<N>,"queue_s":<N>,"deploy_s":<N>,"canary_s":<N>,"total_s":<N>}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Suggest follow-ups
|
||||
|
||||
After the deploy report, suggest relevant follow-ups:
|
||||
|
||||
- If a production URL was verified: "Run `/canary <url> --duration 10m` for extended monitoring."
|
||||
- If performance data was collected: "Run `/benchmark <url>` for a deep performance audit."
|
||||
- "Run `/document-release` to update project documentation."
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Never force push.** Use `gh pr merge` which is safe.
|
||||
- **Never skip CI.** If checks are failing, stop.
|
||||
- **Auto-detect everything.** PR number, merge method, deploy strategy, project type. Only ask when information genuinely can't be inferred.
|
||||
- **Poll with backoff.** Don't hammer GitHub API. 30-second intervals for CI/deploy, with reasonable timeouts.
|
||||
- **Revert is always an option.** At every failure point, offer revert as an escape hatch.
|
||||
- **Single-pass verification, not continuous monitoring.** `/land-and-deploy` checks once. `/canary` does the extended monitoring loop.
|
||||
- **Clean up.** Delete the feature branch after merge (via `--delete-branch`).
|
||||
- **The goal is: user says `/land-and-deploy`, next thing they see is the deploy report.**
|
||||
|
|
@ -0,0 +1,839 @@
|
|||
---
|
||||
name: office-hours
|
||||
description: "YC Office Hours — two modes. Startup mode: six forcing questions that expose demand reality, status quo, desperate specificity, narrowest wedge, observation, and future-fit. Builder mode: design thi"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Context Gathering
|
||||
|
||||
Understand the project and the area the user wants to change.
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
```
|
||||
|
||||
1. Read `CLAUDE.md`, `TODOS.md` (if they exist).
|
||||
2. Run `git log --oneline -30` and `git diff origin/main --stat 2>/dev/null` to understand recent context.
|
||||
3. Use Grep/Glob to map the codebase areas most relevant to the user's request.
|
||||
4. **List existing design docs for this project:**
|
||||
```bash
|
||||
ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null
|
||||
```
|
||||
If design docs exist, list them: "Prior designs for this project: [titles + dates]"
|
||||
|
||||
5. **Ask: what's your goal with this?** This is a real question, not a formality. The answer determines everything about how the session runs.
|
||||
|
||||
Via question, ask:
|
||||
|
||||
> Before we dig in — what's your goal with this?
|
||||
>
|
||||
> - **Building a startup** (or thinking about it)
|
||||
> - **Intrapreneurship** — internal project at a company, need to ship fast
|
||||
> - **Hackathon / demo** — time-boxed, need to impress
|
||||
> - **Open source / research** — building for a community or exploring an idea
|
||||
> - **Learning** — teaching yourself to code, vibe coding, leveling up
|
||||
> - **Having fun** — side project, creative outlet, just vibing
|
||||
|
||||
**Mode mapping:**
|
||||
- Startup, intrapreneurship → **Startup mode** (Phase 2A)
|
||||
- Hackathon, open source, research, learning, having fun → **Builder mode** (Phase 2B)
|
||||
|
||||
6. **Assess product stage** (only for startup/intrapreneurship modes):
|
||||
- Pre-product (idea stage, no users yet)
|
||||
- Has users (people using it, not yet paying)
|
||||
- Has paying customers
|
||||
|
||||
Output: "Here's what I understand about this project and the area you want to change: ..."
|
||||
|
||||
---
|
||||
|
||||
## Phase 2A: Startup Mode — YC Product Diagnostic
|
||||
|
||||
Use this mode when the user is building a startup or doing intrapreneurship.
|
||||
|
||||
### Operating Principles
|
||||
|
||||
These are non-negotiable. They shape every response in this mode.
|
||||
|
||||
**Specificity is the only currency.** Vague answers get pushed. "Enterprises in healthcare" is not a customer. "Everyone needs this" means you can't find anyone. You need a name, a role, a company, a reason.
|
||||
|
||||
**Interest is not demand.** Waitlists, signups, "that's interesting" — none of it counts. Behavior counts. Money counts. Panic when it breaks counts. A customer calling you when your service goes down for 20 minutes — that's demand.
|
||||
|
||||
**The user's words beat the founder's pitch.** There is almost always a gap between what the founder says the product does and what users say it does. The user's version is the truth. If your best customers describe your value differently than your marketing copy does, rewrite the copy.
|
||||
|
||||
**Watch, don't demo.** Guided walkthroughs teach you nothing about real usage. Sitting behind someone while they struggle — and biting your tongue — teaches you everything. If you haven't done this, that's assignment #1.
|
||||
|
||||
**The status quo is your real competitor.** Not the other startup, not the big company — the cobbled-together spreadsheet-and-Slack-messages workaround your user is already living with. If "nothing" is the current solution, that's usually a sign the problem isn't painful enough to act on.
|
||||
|
||||
**Narrow beats wide, early.** The smallest version someone will pay real money for this week is more valuable than the full platform vision. Wedge first. Expand from strength.
|
||||
|
||||
### Response Posture
|
||||
|
||||
- **Be direct to the point of discomfort.** Comfort means you haven't pushed hard enough. Your job is diagnosis, not encouragement. Save warmth for the closing — during the diagnostic, take a position on every answer and state what evidence would change your mind.
|
||||
- **Push once, then push again.** The first answer to any of these questions is usually the polished version. The real answer comes after the second or third push. "You said 'enterprises in healthcare.' Can you name one specific person at one specific company?"
|
||||
- **Calibrated acknowledgment, not praise.** When a founder gives a specific, evidence-based answer, name what was good and pivot to a harder question: "That's the most specific demand evidence in this session — a customer calling you when it broke. Let's see if your wedge is equally sharp." Don't linger. The best reward for a good answer is a harder follow-up.
|
||||
- **Name common failure patterns.** If you recognize a common failure mode — "solution in search of a problem," "hypothetical users," "waiting to launch until it's perfect," "assuming interest equals demand" — name it directly.
|
||||
- **End with the assignment.** Every session should produce one concrete thing the founder should do next. Not a strategy — an action.
|
||||
|
||||
### Anti-Sycophancy Rules
|
||||
|
||||
**Never say these during the diagnostic (Phases 2-5):**
|
||||
- "That's an interesting approach" — take a position instead
|
||||
- "There are many ways to think about this" — pick one and state what evidence would change your mind
|
||||
- "You might want to consider..." — say "This is wrong because..." or "This works because..."
|
||||
- "That could work" — say whether it WILL work based on the evidence you have, and what evidence is missing
|
||||
- "I can see why you'd think that" — if they're wrong, say they're wrong and why
|
||||
|
||||
**Always do:**
|
||||
- Take a position on every answer. State your position AND what evidence would change it. This is rigor — not hedging, not fake certainty.
|
||||
- Challenge the strongest version of the founder's claim, not a strawman.
|
||||
|
||||
### Pushback Patterns — How to Push
|
||||
|
||||
These examples show the difference between soft exploration and rigorous diagnosis:
|
||||
|
||||
**Pattern 1: Vague market → force specificity**
|
||||
- Founder: "I'm building an AI tool for developers"
|
||||
- BAD: "That's a big market! Let's explore what kind of tool."
|
||||
- GOOD: "There are 10,000 AI developer tools right now. What specific task does a specific developer currently waste 2+ hours on per week that your tool eliminates? Name the person."
|
||||
|
||||
**Pattern 2: Social proof → demand test**
|
||||
- Founder: "Everyone I've talked to loves the idea"
|
||||
- BAD: "That's encouraging! Who specifically have you talked to?"
|
||||
- GOOD: "Loving an idea is free. Has anyone offered to pay? Has anyone asked when it ships? Has anyone gotten angry when your prototype broke? Love is not demand."
|
||||
|
||||
**Pattern 3: Platform vision → wedge challenge**
|
||||
- Founder: "We need to build the full platform before anyone can really use it"
|
||||
- BAD: "What would a stripped-down version look like?"
|
||||
- GOOD: "That's a red flag. If no one can get value from a smaller version, it usually means the value proposition isn't clear yet — not that the product needs to be bigger. What's the one thing a user would pay for this week?"
|
||||
|
||||
**Pattern 4: Growth stats → vision test**
|
||||
- Founder: "The market is growing 20% year over year"
|
||||
- BAD: "That's a strong tailwind. How do you plan to capture that growth?"
|
||||
- GOOD: "Growth rate is not a vision. Every competitor in your space can cite the same stat. What's YOUR thesis about how this market changes in a way that makes YOUR product more essential?"
|
||||
|
||||
**Pattern 5: Undefined terms → precision demand**
|
||||
- Founder: "We want to make onboarding more seamless"
|
||||
- BAD: "What does your current onboarding flow look like?"
|
||||
- GOOD: "'Seamless' is not a product feature — it's a feeling. What specific step in onboarding causes users to drop off? What's the drop-off rate? Have you watched someone go through it?"
|
||||
|
||||
### The Six Forcing Questions
|
||||
|
||||
Ask these questions **ONE AT A TIME** via question. Push on each one until the answer is specific, evidence-based, and uncomfortable. Comfort means the founder hasn't gone deep enough.
|
||||
|
||||
**Smart routing based on product stage — you don't always need all six:**
|
||||
- Pre-product → Q1, Q2, Q3
|
||||
- Has users → Q2, Q4, Q5
|
||||
- Has paying customers → Q4, Q5, Q6
|
||||
- Pure engineering/infra → Q2, Q4 only
|
||||
|
||||
**Intrapreneurship adaptation:** For internal projects, reframe Q4 as "what's the smallest demo that gets your VP/sponsor to greenlight the project?" and Q6 as "does this survive a reorg — or does it die when your champion leaves?"
|
||||
|
||||
#### Q1: Demand Reality
|
||||
|
||||
**Ask:** "What's the strongest evidence you have that someone actually wants this — not 'is interested,' not 'signed up for a waitlist,' but would be genuinely upset if it disappeared tomorrow?"
|
||||
|
||||
**Push until you hear:** Specific behavior. Someone paying. Someone expanding usage. Someone building their workflow around it. Someone who would have to scramble if you vanished.
|
||||
|
||||
**Red flags:** "People say it's interesting." "We got 500 waitlist signups." "VCs are excited about the space." None of these are demand.
|
||||
|
||||
**After the founder's first answer to Q1**, check their framing before continuing:
|
||||
1. **Language precision:** Are the key terms in their answer defined? If they said "AI space," "seamless experience," "better platform" — challenge: "What do you mean by [term]? Can you define it so I could measure it?"
|
||||
2. **Hidden assumptions:** What does their framing take for granted? "I need to raise money" assumes capital is required. "The market needs this" assumes verified pull. Name one assumption and ask if it's verified.
|
||||
3. **Real vs. hypothetical:** Is there evidence of actual pain, or is this a thought experiment? "I think developers would want..." is hypothetical. "Three developers at my last company spent 10 hours a week on this" is real.
|
||||
|
||||
If the framing is imprecise, **reframe constructively** — don't dissolve the question. Say: "Let me try restating what I think you're actually building: [reframe]. Does that capture it better?" Then proceed with the corrected framing. This takes 60 seconds, not 10 minutes.
|
||||
|
||||
#### Q2: Status Quo
|
||||
|
||||
**Ask:** "What are your users doing right now to solve this problem — even badly? What does that workaround cost them?"
|
||||
|
||||
**Push until you hear:** A specific workflow. Hours spent. Dollars wasted. Tools duct-taped together. People hired to do it manually. Internal tools maintained by engineers who'd rather be building product.
|
||||
|
||||
**Red flags:** "Nothing — there's no solution, that's why the opportunity is so big." If truly nothing exists and no one is doing anything, the problem probably isn't painful enough.
|
||||
|
||||
#### Q3: Desperate Specificity
|
||||
|
||||
**Ask:** "Name the actual human who needs this most. What's their title? What gets them promoted? What gets them fired? What keeps them up at night?"
|
||||
|
||||
**Push until you hear:** A name. A role. A specific consequence they face if the problem isn't solved. Ideally something the founder heard directly from that person's mouth.
|
||||
|
||||
**Red flags:** Category-level answers. "Healthcare enterprises." "SMBs." "Marketing teams." These are filters, not people. You can't email a category.
|
||||
|
||||
#### Q4: Narrowest Wedge
|
||||
|
||||
**Ask:** "What's the smallest possible version of this that someone would pay real money for — this week, not after you build the platform?"
|
||||
|
||||
**Push until you hear:** One feature. One workflow. Maybe something as simple as a weekly email or a single automation. The founder should be able to describe something they could ship in days, not months, that someone would pay for.
|
||||
|
||||
**Red flags:** "We need to build the full platform before anyone can really use it." "We could strip it down but then it wouldn't be differentiated." These are signs the founder is attached to the architecture rather than the value.
|
||||
|
||||
**Bonus push:** "What if the user didn't have to do anything at all to get value? No login, no integration, no setup. What would that look like?"
|
||||
|
||||
#### Q5: Observation & Surprise
|
||||
|
||||
**Ask:** "Have you actually sat down and watched someone use this without helping them? What did they do that surprised you?"
|
||||
|
||||
**Push until you hear:** A specific surprise. Something the user did that contradicted the founder's assumptions. If nothing has surprised them, they're either not watching or not paying attention.
|
||||
|
||||
**Red flags:** "We sent out a survey." "We did some demo calls." "Nothing surprising, it's going as expected." Surveys lie. Demos are theater. And "as expected" means filtered through existing assumptions.
|
||||
|
||||
**The gold:** Users doing something the product wasn't designed for. That's often the real product trying to emerge.
|
||||
|
||||
#### Q6: Future-Fit
|
||||
|
||||
**Ask:** "If the world looks meaningfully different in 3 years — and it will — does your product become more essential or less?"
|
||||
|
||||
**Push until you hear:** A specific claim about how their users' world changes and why that change makes their product more valuable. Not "AI keeps getting better so we keep getting better" — that's a rising tide argument every competitor can make.
|
||||
|
||||
**Red flags:** "The market is growing 20% per year." Growth rate is not a vision. "AI will make everything better." That's not a product thesis.
|
||||
|
||||
---
|
||||
|
||||
**Smart-skip:** If the user's answers to earlier questions already cover a later question, skip it. Only ask questions whose answers aren't yet clear.
|
||||
|
||||
**STOP** after each question. Wait for the response before asking the next.
|
||||
|
||||
**Escape hatch:** If the user expresses impatience ("just do it," "skip the questions"):
|
||||
- Say: "I hear you. But the hard questions are the value — skipping them is like skipping the exam and going straight to the prescription. Let me ask two more, then we'll move."
|
||||
- Consult the smart routing table for the founder's product stage. Ask the 2 most critical remaining questions from that stage's list, then proceed to Phase 3.
|
||||
- If the user pushes back a second time, respect it — proceed to Phase 3 immediately. Don't ask a third time.
|
||||
- If only 1 question remains, ask it. If 0 remain, proceed directly.
|
||||
- Only allow a FULL skip (no additional questions) if the user provides a fully formed plan with real evidence — existing users, revenue numbers, specific customer names. Even then, still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives).
|
||||
|
||||
---
|
||||
|
||||
## Phase 2B: Builder Mode — Design Partner
|
||||
|
||||
Use this mode when the user is building for fun, learning, hacking on open source, at a hackathon, or doing research.
|
||||
|
||||
### Operating Principles
|
||||
|
||||
1. **Delight is the currency** — what makes someone say "whoa"?
|
||||
2. **Ship something you can show people.** The best version of anything is the one that exists.
|
||||
3. **The best side projects solve your own problem.** If you're building it for yourself, trust that instinct.
|
||||
4. **Explore before you optimize.** Try the weird idea first. Polish later.
|
||||
|
||||
### Response Posture
|
||||
|
||||
- **Enthusiastic, opinionated collaborator.** You're here to help them build the coolest thing possible. Riff on their ideas. Get excited about what's exciting.
|
||||
- **Help them find the most exciting version of their idea.** Don't settle for the obvious version.
|
||||
- **Suggest cool things they might not have thought of.** Bring adjacent ideas, unexpected combinations, "what if you also..." suggestions.
|
||||
- **End with concrete build steps, not business validation tasks.** The deliverable is "what to build next," not "who to interview."
|
||||
|
||||
### Questions (generative, not interrogative)
|
||||
|
||||
Ask these **ONE AT A TIME** via question. The goal is to brainstorm and sharpen the idea, not interrogate.
|
||||
|
||||
- **What's the coolest version of this?** What would make it genuinely delightful?
|
||||
- **Who would you show this to?** What would make them say "whoa"?
|
||||
- **What's the fastest path to something you can actually use or share?**
|
||||
- **What existing thing is closest to this, and how is yours different?**
|
||||
- **What would you add if you had unlimited time?** What's the 10x version?
|
||||
|
||||
**Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear.
|
||||
|
||||
**STOP** after each question. Wait for the response before asking the next.
|
||||
|
||||
**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4.
|
||||
|
||||
**If the vibe shifts mid-session** — the user starts in builder mode but says "actually I think this could be a real company" or mentions customers, revenue, fundraising — upgrade to Startup mode naturally. Say something like: "Okay, now we're talking — let me ask you some harder questions." Then switch to the Phase 2A questions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.5: Related Design Discovery
|
||||
|
||||
After the user states the problem (first question in Phase 2A or 2B), search existing design docs for keyword overlap.
|
||||
|
||||
Extract 3-5 significant keywords from the user's problem statement and grep across design docs:
|
||||
```bash
|
||||
grep -li "<keyword1>\|<keyword2>\|<keyword3>" ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null
|
||||
```
|
||||
|
||||
If matches found, read the matching design docs and surface them:
|
||||
- "FYI: Related design found — '{title}' by {user} on {date} (branch: {branch}). Key overlap: {1-line summary of relevant section}."
|
||||
- Ask via question: "Should we build on this prior design or start fresh?"
|
||||
|
||||
This enables cross-team discovery — multiple users exploring the same project will see each other's design docs in `~/.gstack/projects/`.
|
||||
|
||||
If no matches found, proceed silently.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.75: Landscape Awareness
|
||||
|
||||
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.
|
||||
|
||||
**Privacy gate:** Before searching, use question: "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 provider. 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."
|
||||
|
||||
If WebSearch is unavailable, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||||
|
||||
**Startup mode:** WebSearch for:
|
||||
- "[problem space] startup approach {current year}"
|
||||
- "[problem space] common mistakes"
|
||||
- "why [incumbent solution] fails" OR "why [incumbent solution] works"
|
||||
|
||||
**Builder mode:** WebSearch for:
|
||||
- "[thing being built] existing solutions"
|
||||
- "[thing being built] open source alternatives"
|
||||
- "best [thing category] {current year}"
|
||||
|
||||
Read the top 2-3 results. Run the three-layer synthesis:
|
||||
- **[Layer 1]** What does everyone already know about this space?
|
||||
- **[Layer 2]** What are the search results and current discourse saying?
|
||||
- **[Layer 3]** Given what WE learned in Phase 2A/2B — is there a reason the conventional approach is wrong?
|
||||
|
||||
**Eureka check:** If Layer 3 reasoning reveals a genuine insight, name it: "EUREKA: Everyone does X because they assume [assumption]. But [evidence from our conversation] suggests that's wrong here. This means [implication]." Log the eureka moment (see preamble).
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Premise Challenge
|
||||
|
||||
Before proposing solutions, challenge the premises:
|
||||
|
||||
1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution?
|
||||
2. **What happens if we do nothing?** Real pain point or hypothetical one?
|
||||
3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused.
|
||||
4. **Startup mode only:** Synthesize the diagnostic evidence from Phase 2A. Does it support this direction? Where are the gaps?
|
||||
|
||||
Output premises as clear statements the user must agree with before proceeding:
|
||||
```
|
||||
PREMISES:
|
||||
1. [statement] — agree/disagree?
|
||||
2. [statement] — agree/disagree?
|
||||
3. [statement] — agree/disagree?
|
||||
```
|
||||
|
||||
Use question to confirm. If the user disagrees with a premise, revise understanding and loop back.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3.5: Cross-Model Second Opinion (optional)
|
||||
|
||||
**Binary check first — no question if unavailable:**
|
||||
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
If `CODEX_NOT_AVAILABLE`: skip Phase 3.5 entirely — no message, no question. Proceed directly to Phase 4.
|
||||
|
||||
If `CODEX_AVAILABLE`: use question:
|
||||
|
||||
> Want a second opinion from a different AI model? Codex will independently review your problem statement, key answers, premises, and any landscape findings from this session. It hasn't 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 Codex 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
|
||||
CODEX_PROMPT_FILE=$(mktemp /tmp/gstack-codex-oh-XXXXXXXX.txt)
|
||||
```
|
||||
|
||||
Write the full prompt (context block + instructions) to this file. Use the mode-appropriate variant:
|
||||
|
||||
**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:
|
||||
|
||||
```bash
|
||||
TMPERR_OH=$(mktemp /tmp/codex-oh-err-XXXXXXXX)
|
||||
codex exec "$(cat "$CODEX_PROMPT_FILE")" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR_OH"
|
||||
```
|
||||
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_OH"
|
||||
rm -f "$TMPERR_OH" "$CODEX_PROMPT_FILE"
|
||||
```
|
||||
|
||||
**Error handling:** All errors are non-blocking — Codex 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. Skipping second opinion."
|
||||
- **Timeout:** "Codex timed out after 5 minutes. Skipping second opinion."
|
||||
- **Empty response:** "Codex returned no response. Stderr: <paste relevant error>. Skipping second opinion."
|
||||
|
||||
On any error, proceed to Phase 4 — do NOT fall back to a Claude subagent (this is brainstorming, not adversarial review).
|
||||
|
||||
4. **Presentation:**
|
||||
|
||||
```
|
||||
SECOND OPINION (Codex):
|
||||
════════════════════════════════════════════════════════════
|
||||
<full codex output, verbatim — do not truncate or summarize>
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
5. **Cross-model synthesis:** After presenting Codex output, provide 3-5 bullet synthesis:
|
||||
- Where Claude agrees with Codex
|
||||
- Where Claude disagrees and why
|
||||
- Whether Codex's challenged premise changes Claude's recommendation
|
||||
|
||||
6. **Premise revision check:** If Codex challenged an agreed premise, use question:
|
||||
|
||||
> 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).
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Alternatives Generation (MANDATORY)
|
||||
|
||||
Produce 2-3 distinct implementation approaches. This is NOT optional.
|
||||
|
||||
For each approach:
|
||||
```
|
||||
APPROACH A: [Name]
|
||||
Summary: [1-2 sentences]
|
||||
Effort: [S/M/L/XL]
|
||||
Risk: [Low/Med/High]
|
||||
Pros: [2-3 bullets]
|
||||
Cons: [2-3 bullets]
|
||||
Reuses: [existing code/patterns leveraged]
|
||||
|
||||
APPROACH B: [Name]
|
||||
...
|
||||
|
||||
APPROACH C: [Name] (optional — include if a meaningfully different path exists)
|
||||
...
|
||||
```
|
||||
|
||||
Rules:
|
||||
- At least 2 approaches required. 3 preferred for non-trivial designs.
|
||||
- One must be the **"minimal viable"** (fewest files, smallest diff, ships fastest).
|
||||
- One must be the **"ideal architecture"** (best long-term trajectory, most elegant).
|
||||
- One can be **creative/lateral** (unexpected approach, different framing of the problem).
|
||||
- If Codex proposed a prototype in Phase 3.5, consider using it as a starting point for the creative/lateral approach.
|
||||
|
||||
**RECOMMENDATION:** Choose [X] because [one-line reason].
|
||||
|
||||
Present via question. Do NOT proceed without user approval of the approach.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Write to a temp file:
|
||||
```bash
|
||||
SKETCH_FILE="/tmp/gstack-sketch-$(date +%s).html"
|
||||
```
|
||||
|
||||
**Step 3: Render and capture**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto "file://$SKETCH_FILE"
|
||||
${GSTACK_BROWSE} screenshot /tmp/gstack-sketch.png
|
||||
```
|
||||
|
||||
If `$B` is not available (browse binary not set up), skip the render step. Tell the
|
||||
user: "Visual sketch requires the browse binary. Run the setup script to enable it."
|
||||
|
||||
**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 `/tmp/gstack-sketch.png` 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
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
If Codex is available, use question:
|
||||
> "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, launch both voices simultaneously:
|
||||
|
||||
1. **Codex** (via Bash, `model_reasoning_effort="medium"`):
|
||||
```bash
|
||||
TMPERR_SKETCH=$(mktemp /tmp/codex-sketch-XXXXXXXX)
|
||||
codex exec "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." -s read-only -c 'model_reasoning_effort="medium"' --enable web_search_cached 2>"$TMPERR_SKETCH"
|
||||
```
|
||||
Use a 5-minute timeout (`timeout: 300000`). After completion: `cat "$TMPERR_SKETCH" && rm -f "$TMPERR_SKETCH"`
|
||||
|
||||
2. **Claude subagent** (via Agent tool):
|
||||
"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."
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4.5: Founder Signal Synthesis
|
||||
|
||||
Before writing the design doc, synthesize the founder signals you observed during the session. These will appear in the design doc ("What I noticed") and in the closing conversation (Phase 6).
|
||||
|
||||
Track which of these signals appeared during the session:
|
||||
- Articulated a **real problem** someone actually has (not hypothetical)
|
||||
- Named **specific users** (people, not categories — "Sarah at Acme Corp" not "enterprises")
|
||||
- **Pushed back** on premises (conviction, not compliance)
|
||||
- Their project solves a problem **other people need**
|
||||
- Has **domain expertise** — knows this space from the inside
|
||||
- Showed **taste** — cared about getting the details right
|
||||
- Showed **agency** — actually building, not just planning
|
||||
- **Defended premise with reasoning** against cross-model challenge (kept original premise when Codex disagreed AND articulated specific reasoning for why — dismissal without reasoning does not count)
|
||||
|
||||
Count the signals. You'll use this count in Phase 6 to determine which tier of closing message to use.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Design Doc
|
||||
|
||||
Write the design document to the project directory.
|
||||
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
USER=$(whoami)
|
||||
DATETIME=$(date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
**Design lineage:** Before writing, check for existing design docs on this branch:
|
||||
```bash
|
||||
PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
```
|
||||
If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.
|
||||
|
||||
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`:
|
||||
|
||||
### Startup mode design doc template:
|
||||
|
||||
```markdown
|
||||
# Design: {title}
|
||||
|
||||
Generated by /office-hours on {date}
|
||||
Branch: {branch}
|
||||
Repo: {owner/repo}
|
||||
Status: DRAFT
|
||||
Mode: Startup
|
||||
Supersedes: {prior filename — omit this line if first design on this branch}
|
||||
|
||||
## Problem Statement
|
||||
{from Phase 2A}
|
||||
|
||||
## Demand Evidence
|
||||
{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}
|
||||
|
||||
## Status Quo
|
||||
{from Q2 — concrete current workflow users live with today}
|
||||
|
||||
## Target User & Narrowest Wedge
|
||||
{from Q3 + Q4 — the specific human and the smallest version worth paying for}
|
||||
|
||||
## Constraints
|
||||
{from Phase 2A}
|
||||
|
||||
## Premises
|
||||
{from Phase 3}
|
||||
|
||||
## Cross-Model Perspective
|
||||
{If Codex ran in Phase 3.5: Codex's independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase of what Codex said. If Codex did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
|
||||
|
||||
## Approaches Considered
|
||||
### Approach A: {name}
|
||||
{from Phase 4}
|
||||
### Approach B: {name}
|
||||
{from Phase 4}
|
||||
|
||||
## Recommended Approach
|
||||
{chosen approach with rationale}
|
||||
|
||||
## Open Questions
|
||||
{any unresolved questions from the office hours}
|
||||
|
||||
## Success Criteria
|
||||
{measurable criteria from Phase 2A}
|
||||
|
||||
## Dependencies
|
||||
{blockers, prerequisites, related work}
|
||||
|
||||
## The Assignment
|
||||
{one concrete real-world action the founder should take next — not "go build it"}
|
||||
|
||||
## What I noticed about how you think
|
||||
{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
|
||||
```
|
||||
|
||||
### Builder mode design doc template:
|
||||
|
||||
```markdown
|
||||
# Design: {title}
|
||||
|
||||
Generated by /office-hours on {date}
|
||||
Branch: {branch}
|
||||
Repo: {owner/repo}
|
||||
Status: DRAFT
|
||||
Mode: Builder
|
||||
Supersedes: {prior filename — omit this line if first design on this branch}
|
||||
|
||||
## Problem Statement
|
||||
{from Phase 2B}
|
||||
|
||||
## What Makes This Cool
|
||||
{the core delight, novelty, or "whoa" factor}
|
||||
|
||||
## Constraints
|
||||
{from Phase 2B}
|
||||
|
||||
## Premises
|
||||
{from Phase 3}
|
||||
|
||||
## Cross-Model Perspective
|
||||
{If Codex ran in Phase 3.5: Codex's independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase of what Codex said. If Codex did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
|
||||
|
||||
## Approaches Considered
|
||||
### Approach A: {name}
|
||||
{from Phase 4}
|
||||
### Approach B: {name}
|
||||
{from Phase 4}
|
||||
|
||||
## Recommended Approach
|
||||
{chosen approach with rationale}
|
||||
|
||||
## Open Questions
|
||||
{any unresolved questions from the office hours}
|
||||
|
||||
## Success Criteria
|
||||
{what "done" looks like}
|
||||
|
||||
## Next Steps
|
||||
{concrete build tasks — what to implement first, second, third}
|
||||
|
||||
## What I noticed about how you think
|
||||
{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spec Review Loop
|
||||
|
||||
Before presenting the document to the user for approval, run an adversarial review.
|
||||
|
||||
**Step 1: Dispatch reviewer subagent**
|
||||
|
||||
Use the Agent tool to dispatch an independent reviewer. The reviewer has fresh context
|
||||
and cannot see the brainstorming conversation — only the document. This ensures genuine
|
||||
adversarial independence.
|
||||
|
||||
Prompt the subagent with:
|
||||
- The file path of the document just written
|
||||
- "Read this document and review it on 5 dimensions. For each dimension, note PASS or
|
||||
list specific issues with suggested fixes. At the end, output a quality score (1-10)
|
||||
across all dimensions."
|
||||
|
||||
**Dimensions:**
|
||||
1. **Completeness** — Are all requirements addressed? Missing edge cases?
|
||||
2. **Consistency** — Do parts of the document agree with each other? Contradictions?
|
||||
3. **Clarity** — Could an engineer implement this without asking questions? Ambiguous language?
|
||||
4. **Scope** — Does the document creep beyond the original problem? YAGNI violations?
|
||||
5. **Feasibility** — Can this actually be built with the stated approach? Hidden complexity?
|
||||
|
||||
The subagent should return:
|
||||
- A quality score (1-10)
|
||||
- PASS if no issues, or a numbered list of issues with dimension, description, and fix
|
||||
|
||||
**Step 2: Fix and re-dispatch**
|
||||
|
||||
If the reviewer returns issues:
|
||||
1. Fix each issue in the document on disk (use Edit tool)
|
||||
2. Re-dispatch the reviewer subagent with the updated document
|
||||
3. Maximum 3 iterations total
|
||||
|
||||
**Convergence guard:** If the reviewer returns the same issues on consecutive iterations
|
||||
(the fix didn't resolve them or the reviewer disagrees with the fix), stop the loop
|
||||
and persist those issues as "Reviewer Concerns" in the document rather than looping
|
||||
further.
|
||||
|
||||
If the subagent fails, times out, or is unavailable — skip the review loop entirely.
|
||||
Tell the user: "Spec review unavailable — presenting unreviewed doc." The document is
|
||||
already written to disk; the review is a quality bonus, not a gate.
|
||||
|
||||
**Step 3: Report and persist metrics**
|
||||
|
||||
After the loop completes (PASS, max iterations, or convergence guard):
|
||||
|
||||
1. Tell the user the result — summary by default:
|
||||
"Your doc survived N rounds of adversarial review. M issues caught and fixed.
|
||||
Quality score: X/10."
|
||||
If they ask "what did the reviewer find?", show the full reviewer output.
|
||||
|
||||
2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns"
|
||||
section to the document listing each unresolved issue. Downstream skills will see this.
|
||||
|
||||
3. Append metrics:
|
||||
```bash
|
||||
mkdir -p ~/.gstack/analytics
|
||||
echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> ~/.gstack/analytics/spec-review.jsonl 2>/dev/null || true
|
||||
```
|
||||
Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review.
|
||||
|
||||
---
|
||||
|
||||
Present the reviewed design doc to the user via question:
|
||||
- A) Approve — mark Status: APPROVED and proceed to handoff
|
||||
- B) Revise — specify which sections need changes (loop back to revise those sections)
|
||||
- C) Start over — return to Phase 2
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Handoff — Founder Discovery
|
||||
|
||||
Once the design doc is APPROVED, deliver the closing sequence. This is three beats with a deliberate pause between them. Every user gets all three beats regardless of mode (startup or builder). The intensity varies by founder signal strength, not by mode.
|
||||
|
||||
### Beat 1: Signal Reflection + Golden Age
|
||||
|
||||
One paragraph that weaves specific session callbacks with the golden age framing. Reference actual things the user said — quote their words back to them.
|
||||
|
||||
**Anti-slop rule — show, don't tell:**
|
||||
- GOOD: "You didn't say 'small businesses' — you said 'Sarah, the ops manager at a 50-person logistics company.' That specificity is rare."
|
||||
- BAD: "You showed great specificity in identifying your target user."
|
||||
- GOOD: "You pushed back when I challenged premise #2. Most people just agree."
|
||||
- BAD: "You demonstrated conviction and independent thinking."
|
||||
|
||||
Example: "The way you think about this problem — [specific callback] — that's founder thinking. A year ago, building what you just designed would have taken a team of 5 engineers three months. Today you can build it this weekend with Claude Code. The engineering barrier is gone. What remains is taste — and you just demonstrated that."
|
||||
|
||||
### Beat 2: "One more thing."
|
||||
|
||||
After the signal reflection, output a separator and "One more thing." — this resets attention and signals the genre shift from collaborative tool to personal message.
|
||||
|
||||
---
|
||||
|
||||
One more thing.
|
||||
|
||||
### Beat 3: Garry's Personal Plea
|
||||
|
||||
Use the founder signal count from Phase 4.5 to select the right tier.
|
||||
|
||||
**Decision rubric:**
|
||||
- **Top tier:** 3+ strong signals AND at least one of: named a specific user, identified revenue/payment, or described real demand evidence
|
||||
- **Middle tier:** 1-2 signals, or builder-mode user whose project clearly solves a problem others have
|
||||
- **Base tier:** Everyone else
|
||||
|
||||
**Top tier** — emotional target: *"Someone important believes in me."* Chosen, not marketed to.
|
||||
|
||||
Say:
|
||||
|
||||
> A personal note from me, Garry Tan, the creator of GStack: what you just experienced is about 10% of the value you'd get working with a YC partner at Y Combinator. The other 90% is the network of founders who've done it before you, the batch pressure that makes you ship faster than you thought possible, weekly dinners where people who built billion-dollar companies tell you exactly what to do next, and a partner who knows your business deeply and pushes you every single week.
|
||||
>
|
||||
> GStack thinks you are among the top people who could do this.
|
||||
|
||||
Then use question: "Would you consider applying to Y Combinator?"
|
||||
|
||||
- If yes → run `open https://ycombinator.com/apply?ref=gstack` and say: "Bring this design doc to your YC interview. It's better than most pitch decks."
|
||||
- If no → respond warmly: "Totally fair. The design doc is yours either way — and the offer stands if you ever change your mind." Then proceed to next-skill recs. No pressure, no guilt, no re-ask.
|
||||
|
||||
**Middle tier** — emotional target: *"I might be onto something."* Validation + curiosity.
|
||||
|
||||
Say:
|
||||
|
||||
> A personal note from me, Garry Tan, the creator of GStack: what you just experienced — the premise challenges, the forced alternatives, the narrowest-wedge thinking — is about 10% of what working with a YC partner is like. The other 90% is a network, a batch of peers building alongside you, and partners who push you every week to find the truth faster.
|
||||
>
|
||||
> You're building something real. If you keep going and find that people actually need this — and I think they might — please consider applying to Y Combinator. Thank you for using GStack.
|
||||
>
|
||||
> **ycombinator.com/apply?ref=gstack**
|
||||
|
||||
**Base tier** — emotional target: *"I didn't know I could be a founder."* Identity expansion, worldview shift.
|
||||
|
||||
Say:
|
||||
|
||||
> A personal note from me, Garry Tan, the creator of GStack: the skills you're demonstrating right now — taste, ambition, agency, the willingness to sit with hard questions about what you're building — those are exactly the traits we look for in YC founders. You may not be thinking about starting a company today, and that's fine. But founders are everywhere, and this is the golden age. A single person with AI can now build what used to take a team of 20.
|
||||
>
|
||||
> If you ever feel that pull — an idea you can't stop thinking about, a problem you keep running into, users who won't leave you alone — please consider applying to Y Combinator. Thank you for using GStack. I mean it.
|
||||
>
|
||||
> **ycombinator.com/apply?ref=gstack**
|
||||
|
||||
## HARD STOP RULE
|
||||
|
||||
**This skill ends here. Do NOT automatically continue to any other skill.**
|
||||
**Do NOT call /plan-ceo-review, /plan-eng-review, /plan-design-review, or any implementation skill.**
|
||||
**Do NOT write code, scaffold files, or start implementation.**
|
||||
**The user must explicitly invoke the next skill if they want to continue.**
|
||||
|
||||
### Next-skill recommendations (informational only)
|
||||
|
||||
After the plea, suggest the next step — but STOP after suggesting. Do not execute.
|
||||
|
||||
- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
|
||||
- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
|
||||
- **`/plan-design-review`** for visual/UX design review
|
||||
|
||||
The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Never start implementation.** This skill produces design docs, not code. Not even scaffolding.
|
||||
- **Questions ONE AT A TIME.** Never batch multiple questions into one question.
|
||||
- **The assignment is mandatory.** Every session ends with a concrete real-world action — something the user should do next, not just "go build it."
|
||||
- **If user provides a fully formed plan:** skip Phase 2 (questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives.
|
||||
- **Completion status:**
|
||||
- DONE — design doc APPROVED
|
||||
- DONE_WITH_CONCERNS — design doc approved but with open questions listed
|
||||
- NEEDS_CONTEXT — user left questions unanswered, design incomplete
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,581 @@
|
|||
---
|
||||
name: plan-design-review
|
||||
description: "Designer's eye plan review — interactive, like CEO and Eng review. Rates each design dimension 0-10, explains what would make it a 10, then fixes the plan to get there. Works in plan mode. For live "
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /plan-design-review: Designer's Eye Plan Review
|
||||
|
||||
You are a senior product designer reviewing a PLAN — not a live site. Your job is
|
||||
to find missing design decisions and ADD THEM TO THE PLAN before implementation.
|
||||
|
||||
The output of this skill is a better plan, not a document about the plan.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
You are not here to rubber-stamp this plan's UI. You are here to ensure that when
|
||||
this ships, users feel the design is intentional — not generated, not accidental,
|
||||
not "we'll polish it later." Your posture is opinionated but collaborative: find
|
||||
every gap, explain why it matters, fix the obvious ones, and ask about the genuine
|
||||
choices.
|
||||
|
||||
Do NOT make any code changes. Do NOT start implementation. Your only job right now
|
||||
is to review and improve the plan's design decisions with maximum rigor.
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. Empty states are features. "No items found." is not a design. Every empty state needs warmth, a primary action, and context.
|
||||
2. Every screen has a hierarchy. What does the user see first, second, third? If everything competes, nothing wins.
|
||||
3. Specificity over vibes. "Clean, modern UI" is not a design decision. Name the font, the spacing scale, the interaction pattern.
|
||||
4. Edge cases are user experiences. 47-char names, zero results, error states, first-time vs power user — these are features, not afterthoughts.
|
||||
5. AI slop is the enemy. Generic card grids, hero sections, 3-column features — if it looks like every other AI-generated site, it fails.
|
||||
6. Responsive is not "stacked on mobile." Each viewport gets intentional design.
|
||||
7. Accessibility is not optional. Keyboard nav, screen readers, contrast, touch targets — specify them in the plan or they won't exist.
|
||||
8. Subtraction default. If a UI element doesn't earn its pixels, cut it. Feature bloat kills products faster than missing features.
|
||||
9. Trust is earned at the pixel level. Every interface decision either builds or erodes user trust.
|
||||
|
||||
## Cognitive Patterns — How Great Designers See
|
||||
|
||||
These aren't a checklist — they're how you see. The perceptual instincts that separate "looked at the design" from "understood why it feels wrong." Let them run automatically as you review.
|
||||
|
||||
1. **Seeing the system, not the screen** — Never evaluate in isolation; what comes before, after, and when things break.
|
||||
2. **Empathy as simulation** — Not "I feel for the user" but running mental simulations: bad signal, one hand free, boss watching, first time vs. 1000th time.
|
||||
3. **Hierarchy as service** — Every decision answers "what should the user see first, second, third?" Respecting their time, not prettifying pixels.
|
||||
4. **Constraint worship** — Limitations force clarity. "If I can only show 3 things, which 3 matter most?"
|
||||
5. **The question reflex** — First instinct is questions, not opinions. "Who is this for? What did they try before this?"
|
||||
6. **Edge case paranoia** — What if the name is 47 chars? Zero results? Network fails? Colorblind? RTL language?
|
||||
7. **The "Would I notice?" test** — Invisible = perfect. The highest compliment is not noticing the design.
|
||||
8. **Principled taste** — "This feels wrong" is traceable to a broken principle. Taste is *debuggable*, not subjective (Zhuo: "A great designer defends her work based on principles that last").
|
||||
9. **Subtraction default** — "As little design as possible" (Rams). "Subtract the obvious, add the meaningful" (Maeda).
|
||||
10. **Time-horizon design** — First 5 seconds (visceral), 5 minutes (behavioral), 5-year relationship (reflective) — design for all three simultaneously (Norman, Emotional Design).
|
||||
11. **Design for trust** — Every design decision either builds or erodes trust. Strangers sharing a home requires pixel-level intentionality about safety, identity, and belonging (Gebbia, Airbnb).
|
||||
12. **Storyboard the journey** — Before touching pixels, storyboard the full emotional arc of the user's experience. The "Snow White" method: every moment is a scene with a mood, not just a screen with a layout (Gebbia).
|
||||
|
||||
Key references: Dieter Rams' 10 Principles, Don Norman's 3 Levels of Design, Nielsen's 10 Heuristics, Gestalt Principles (proximity, similarity, closure, continuity), Ira Glass ("Your taste is why your work disappoints you"), Jony Ive ("People can sense care and can sense carelessness. Different and new is relatively easy. Doing something that's genuinely better is very hard."), Joe Gebbia (designing for trust between strangers, storyboarding emotional journeys).
|
||||
|
||||
When reviewing a plan, empathy as simulation runs automatically. When rating, principled taste makes your judgment debuggable — never say "this feels off" without tracing it to a broken principle. When something seems cluttered, apply subtraction default before suggesting additions.
|
||||
|
||||
## Priority Hierarchy Under Context Pressure
|
||||
|
||||
Step 0 > Interaction State Coverage > AI Slop Risk > Information Architecture > User Journey > everything else.
|
||||
Never skip Step 0, interaction states, or AI slop assessment. These are the highest-leverage design dimensions.
|
||||
|
||||
## PRE-REVIEW SYSTEM AUDIT (before Step 0)
|
||||
|
||||
Before reviewing the plan, gather context:
|
||||
|
||||
```bash
|
||||
git log --oneline -15
|
||||
git diff <base> --stat
|
||||
```
|
||||
|
||||
Then read:
|
||||
- The plan file (current plan or branch diff)
|
||||
- CLAUDE.md — project conventions
|
||||
- DESIGN.md — if it exists, ALL design decisions calibrate against it
|
||||
- TODOS.md — any design-related TODOs this plan touches
|
||||
|
||||
Map:
|
||||
* What is the UI scope of this plan? (pages, components, interactions)
|
||||
* Does a DESIGN.md exist? If not, flag as a gap.
|
||||
* Are there existing design patterns in the codebase to align with?
|
||||
* What prior design reviews exist? (check reviews.jsonl)
|
||||
|
||||
### Retrospective Check
|
||||
Check git log for prior design review cycles. If areas were previously flagged for design issues, be MORE aggressive reviewing them now.
|
||||
|
||||
### UI Scope Detection
|
||||
Analyze the plan. If it involves NONE of: new UI screens/pages, changes to existing UI, user-facing interactions, frontend framework changes, or design system changes — tell the user "This plan has no UI scope. A design review isn't applicable." and exit early. Don't force design review on a backend change.
|
||||
|
||||
Report findings before proceeding to Step 0.
|
||||
|
||||
## Step 0: Design Scope Assessment
|
||||
|
||||
### 0A. Initial Design Rating
|
||||
Rate the plan's overall design completeness 0-10.
|
||||
- "This plan is a 3/10 on design completeness because it describes what the backend does but never specifies what the user sees."
|
||||
- "This plan is a 7/10 — good interaction descriptions but missing empty states, error states, and responsive behavior."
|
||||
|
||||
Explain what a 10 looks like for THIS plan.
|
||||
|
||||
### 0B. DESIGN.md Status
|
||||
- If DESIGN.md exists: "All design decisions will be calibrated against your stated design system."
|
||||
- If no DESIGN.md: "No design system found. Recommend running /design-consultation first. Proceeding with universal design principles."
|
||||
|
||||
### 0C. Existing Design Leverage
|
||||
What existing UI patterns, components, or design decisions in the codebase should this plan reuse? Don't reinvent what already works.
|
||||
|
||||
### 0D. Focus Areas
|
||||
question: "I've rated this plan {N}/10 on design completeness. The biggest gaps are {X, Y, Z}. Want me to review all 7 dimensions, or focus on specific areas?"
|
||||
|
||||
**STOP.** Do NOT proceed until user responds.
|
||||
|
||||
## Design Outside Voices (parallel)
|
||||
|
||||
Use question:
|
||||
> "Want outside design voices before the detailed review? Codex evaluates against OpenAI's design hard rules + litmus checks; Claude subagent does an independent completeness review."
|
||||
>
|
||||
> A) Yes — run outside design voices
|
||||
> B) No — proceed without
|
||||
|
||||
If user chooses B, skip this step and continue.
|
||||
|
||||
**Check Codex availability:**
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
**If Codex is available**, launch both voices simultaneously:
|
||||
|
||||
1. **Codex design voice** (via Bash):
|
||||
```bash
|
||||
TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX)
|
||||
codex exec "Read the plan file at [plan-file-path]. Evaluate this plan's UI/UX design against these criteria.
|
||||
|
||||
HARD REJECTION — flag if ANY apply:
|
||||
1. Generic SaaS card grid as first impression
|
||||
2. Beautiful image with weak brand
|
||||
3. Strong headline with no clear action
|
||||
4. Busy imagery behind text
|
||||
5. Sections repeating same mood statement
|
||||
6. Carousel with no narrative purpose
|
||||
7. App UI made of stacked cards instead of layout
|
||||
|
||||
LITMUS CHECKS — answer YES or NO for each:
|
||||
1. Brand/product unmistakable in first screen?
|
||||
2. One strong visual anchor present?
|
||||
3. Page understandable by scanning headlines only?
|
||||
4. Each section has one job?
|
||||
5. Are cards actually necessary?
|
||||
6. Does motion improve hierarchy or atmosphere?
|
||||
7. Would design feel premium with all decorative shadows removed?
|
||||
|
||||
HARD RULES — first classify as MARKETING/LANDING PAGE vs APP UI vs HYBRID, then flag violations of the matching rule set:
|
||||
- MARKETING: First viewport as one composition, brand-first hierarchy, full-bleed hero, 2-3 intentional motions, composition-first layout
|
||||
- APP UI: Calm surface hierarchy, dense but readable, utility language, minimal chrome
|
||||
- UNIVERSAL: CSS variables for colors, no default font stacks, one job per section, cards earn existence
|
||||
|
||||
For each finding: what's wrong, what will happen if it ships unresolved, and the specific fix. Be opinionated. No hedging." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DESIGN"
|
||||
```
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN"
|
||||
```
|
||||
|
||||
2. **Claude design subagent** (via Agent tool):
|
||||
Dispatch a subagent with this prompt:
|
||||
"Read the plan file at [plan-file-path]. You are an independent senior product designer reviewing this plan. You have NOT seen any prior review. Evaluate:
|
||||
|
||||
1. Information hierarchy: what does the user see first, second, third? Is it right?
|
||||
2. Missing states: loading, empty, error, success, partial — which are unspecified?
|
||||
3. User journey: what's the emotional arc? Where does it break?
|
||||
4. Specificity: does the plan describe SPECIFIC UI ("48px Söhne Bold header, #1a1a1a on white") or generic patterns ("clean modern card-based layout")?
|
||||
5. What design decisions will haunt the implementer if left ambiguous?
|
||||
|
||||
For each finding: what's wrong, severity (critical/high/medium), and the fix."
|
||||
|
||||
**Error handling (all non-blocking):**
|
||||
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate."
|
||||
- **Timeout:** "Codex timed out after 5 minutes."
|
||||
- **Empty response:** "Codex returned no response."
|
||||
- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`.
|
||||
- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review."
|
||||
|
||||
Present Codex output under a `CODEX SAYS (design critique):` header.
|
||||
Present subagent output under a `CLAUDE SUBAGENT (design completeness):` header.
|
||||
|
||||
**Synthesis — Litmus scorecard:**
|
||||
|
||||
```
|
||||
DESIGN OUTSIDE VOICES — LITMUS SCORECARD:
|
||||
═══════════════════════════════════════════════════════════════
|
||||
Check Claude Codex Consensus
|
||||
─────────────────────────────────────── ─────── ─────── ─────────
|
||||
1. Brand unmistakable in first screen? — — —
|
||||
2. One strong visual anchor? — — —
|
||||
3. Scannable by headlines only? — — —
|
||||
4. Each section has one job? — — —
|
||||
5. Cards actually necessary? — — —
|
||||
6. Motion improves hierarchy? — — —
|
||||
7. Premium without decorative shadows? — — —
|
||||
─────────────────────────────────────── ─────── ─────── ─────────
|
||||
Hard rejections triggered: — — —
|
||||
═══════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
Fill in each cell from the Codex and subagent outputs. CONFIRMED = both agree. DISAGREE = models differ. NOT SPEC'D = not enough info to evaluate.
|
||||
|
||||
**Pass integration (respects existing 7-pass contract):**
|
||||
- Hard rejections → raised as the FIRST items in Pass 1, tagged `[HARD REJECTION]`
|
||||
- Litmus DISAGREE items → raised in the relevant pass with both perspectives
|
||||
- Litmus CONFIRMED failures → pre-loaded as known issues in the relevant pass
|
||||
- Passes can skip discovery and go straight to fixing for pre-identified issues
|
||||
|
||||
**Log the result:**
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable".
|
||||
|
||||
## The 0-10 Rating Method
|
||||
|
||||
For each design section, rate the plan 0-10 on that dimension. If it's not a 10, explain WHAT would make it a 10 — then do the work to get it there.
|
||||
|
||||
Pattern:
|
||||
1. Rate: "Information Architecture: 4/10"
|
||||
2. Gap: "It's a 4 because the plan doesn't define content hierarchy. A 10 would have clear primary/secondary/tertiary for every screen."
|
||||
3. Fix: Edit the plan to add what's missing
|
||||
4. Re-rate: "Now 8/10 — still missing mobile nav hierarchy"
|
||||
5. question if there's a genuine design choice to resolve
|
||||
6. Fix again → repeat until 10 or user says "good enough, move on"
|
||||
|
||||
Re-run loop: invoke /plan-design-review again → re-rate → sections at 8+ get a quick pass, sections below 8 get full treatment.
|
||||
|
||||
## Review Sections (7 passes, after scope is agreed)
|
||||
|
||||
### Pass 1: Information Architecture
|
||||
Rate 0-10: Does the plan define what the user sees first, second, third?
|
||||
FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.
|
||||
|
||||
### Pass 2: Interaction State Coverage
|
||||
Rate 0-10: Does the plan specify loading, empty, error, success, partial states?
|
||||
FIX TO 10: Add interaction state table to the plan:
|
||||
```
|
||||
FEATURE | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
|
||||
---------------------|---------|-------|-------|---------|--------
|
||||
[each UI feature] | [spec] | [spec]| [spec]| [spec] | [spec]
|
||||
```
|
||||
For each state: describe what the user SEES, not backend behavior.
|
||||
Empty states are features — specify warmth, primary action, context.
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 3: User Journey & Emotional Arc
|
||||
Rate 0-10: Does the plan consider the user's emotional experience?
|
||||
FIX TO 10: Add user journey storyboard:
|
||||
```
|
||||
STEP | USER DOES | USER FEELS | PLAN SPECIFIES?
|
||||
-----|------------------|-----------------|----------------
|
||||
1 | Lands on page | [what emotion?] | [what supports it?]
|
||||
...
|
||||
```
|
||||
Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 4: AI Slop Risk
|
||||
Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns?
|
||||
FIX TO 10: Rewrite vague UI descriptions with specific alternatives.
|
||||
|
||||
### Design Hard Rules
|
||||
|
||||
**Classifier — determine rule set before evaluating:**
|
||||
- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules
|
||||
- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules
|
||||
- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections
|
||||
|
||||
**Hard rejection criteria** (instant-fail patterns — flag if ANY apply):
|
||||
1. Generic SaaS card grid as first impression
|
||||
2. Beautiful image with weak brand
|
||||
3. Strong headline with no clear action
|
||||
4. Busy imagery behind text
|
||||
5. Sections repeating same mood statement
|
||||
6. Carousel with no narrative purpose
|
||||
7. App UI made of stacked cards instead of layout
|
||||
|
||||
**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring):
|
||||
1. Brand/product unmistakable in first screen?
|
||||
2. One strong visual anchor present?
|
||||
3. Page understandable by scanning headlines only?
|
||||
4. Each section has one job?
|
||||
5. Are cards actually necessary?
|
||||
6. Does motion improve hierarchy or atmosphere?
|
||||
7. Would design feel premium with all decorative shadows removed?
|
||||
|
||||
**Landing page rules** (apply when classifier = MARKETING/LANDING):
|
||||
- First viewport reads as one composition, not a dashboard
|
||||
- Brand-first hierarchy: brand > headline > body > CTA
|
||||
- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
|
||||
- No flat single-color backgrounds — use gradients, images, subtle patterns
|
||||
- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
|
||||
- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
|
||||
- No cards in hero. Cards only when card IS the interaction
|
||||
- One job per section: one purpose, one headline, one short supporting sentence
|
||||
- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal)
|
||||
- Color: define CSS variables, avoid purple-on-white defaults, one accent color default
|
||||
- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting"
|
||||
- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document
|
||||
|
||||
**App UI rules** (apply when classifier = APP UI):
|
||||
- Calm surface hierarchy, strong typography, few colors
|
||||
- Dense but readable, minimal chrome
|
||||
- Organize: primary workspace, navigation, secondary context, one accent
|
||||
- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
|
||||
- Copy: utility language — orientation, status, action. Not mood/brand/aspiration
|
||||
- Cards only when card IS the interaction
|
||||
- Section headings state what area is or what user can do ("Selected KPIs", "Plan status")
|
||||
|
||||
**Universal rules** (apply to ALL types):
|
||||
- Define CSS variables for color system
|
||||
- No default font stacks (Inter, Roboto, Arial, system)
|
||||
- One job per section
|
||||
- "If deleting 30% of the copy improves it, keep deleting"
|
||||
- Cards earn their existence — no decorative card grids
|
||||
|
||||
**AI Slop blacklist** (the 10 patterns that scream "AI-generated"):
|
||||
1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
|
||||
2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
|
||||
3. Icons in colored circles as section decoration (SaaS starter template look)
|
||||
4. Centered everything (`text-align: center` on all headings, descriptions, cards)
|
||||
5. Uniform bubbly border-radius on every element (same large radius on everything)
|
||||
6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
|
||||
7. Emoji as design elements (rockets in headings, emoji as bullet points)
|
||||
8. Colored left-border on cards (`border-left: 3px solid <accent>`)
|
||||
9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
|
||||
10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
|
||||
|
||||
Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology.
|
||||
- "Cards with icons" → what differentiates these from every SaaS template?
|
||||
- "Hero section" → what makes this hero feel like THIS product?
|
||||
- "Clean, modern UI" → meaningless. Replace with actual design decisions.
|
||||
- "Dashboard with widgets" → what makes this NOT every other dashboard?
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 5: Design System Alignment
|
||||
Rate 0-10: Does the plan align with DESIGN.md?
|
||||
FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
|
||||
Flag any new component — does it fit the existing vocabulary?
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 6: Responsive & Accessibility
|
||||
Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers?
|
||||
FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements.
|
||||
**STOP.** question once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 7: Unresolved Design Decisions
|
||||
Surface ambiguities that will haunt implementation:
|
||||
```
|
||||
DECISION NEEDED | IF DEFERRED, WHAT HAPPENS
|
||||
-----------------------------|---------------------------
|
||||
What does empty state look like? | Engineer ships "No items found."
|
||||
Mobile nav pattern? | Desktop nav hides behind hamburger
|
||||
...
|
||||
```
|
||||
Each decision = one question with recommendation + WHY + alternatives. Edit the plan with each decision as it's made.
|
||||
|
||||
## CRITICAL RULE — How to ask questions
|
||||
Follow the question format from the Preamble above. Additional rules for plan design reviews:
|
||||
* **One issue = one question call.** Never combine multiple issues into one question.
|
||||
* Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
|
||||
* Present 2-3 options. For each: effort to specify now, risk if deferred.
|
||||
* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use question when there is a genuine design choice with meaningful tradeoffs.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
### "NOT in scope" section
|
||||
Design decisions considered and explicitly deferred, with one-line rationale each.
|
||||
|
||||
### "What already exists" section
|
||||
Existing DESIGN.md, UI patterns, and components that the plan should reuse.
|
||||
|
||||
### TODOS.md updates
|
||||
After all review passes are complete, present each potential TODO as its own individual question. Never batch TODOs — one per question. Never silently skip this step.
|
||||
|
||||
For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
|
||||
* **What:** One-line description of the work.
|
||||
* **Why:** The concrete problem it solves or value it unlocks.
|
||||
* **Pros:** What you gain by doing this work.
|
||||
* **Cons:** Cost, complexity, or risks of doing it.
|
||||
* **Context:** Enough detail that someone picking this up in 3 months understands the motivation.
|
||||
* **Depends on / blocked by:** Any prerequisites.
|
||||
|
||||
Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
|
||||
|
||||
### Completion Summary
|
||||
```
|
||||
+====================================================================+
|
||||
| DESIGN PLAN REVIEW — COMPLETION SUMMARY |
|
||||
+====================================================================+
|
||||
| System Audit | [DESIGN.md status, UI scope] |
|
||||
| Step 0 | [initial rating, focus areas] |
|
||||
| Pass 1 (Info Arch) | ___/10 → ___/10 after fixes |
|
||||
| Pass 2 (States) | ___/10 → ___/10 after fixes |
|
||||
| Pass 3 (Journey) | ___/10 → ___/10 after fixes |
|
||||
| Pass 4 (AI Slop) | ___/10 → ___/10 after fixes |
|
||||
| Pass 5 (Design Sys) | ___/10 → ___/10 after fixes |
|
||||
| Pass 6 (Responsive) | ___/10 → ___/10 after fixes |
|
||||
| Pass 7 (Decisions) | ___ resolved, ___ deferred |
|
||||
+--------------------------------------------------------------------+
|
||||
| NOT in scope | written (___ items) |
|
||||
| What already exists | written |
|
||||
| TODOS.md updates | ___ items proposed |
|
||||
| Decisions made | ___ added to plan |
|
||||
| Decisions deferred | ___ (listed below) |
|
||||
| Overall design score | ___/10 → ___/10 |
|
||||
+====================================================================+
|
||||
```
|
||||
|
||||
If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
|
||||
If any below 8: note what's unresolved and why (user chose to defer).
|
||||
|
||||
### Unresolved Decisions
|
||||
If any question goes unanswered, note it here. Never silently default to an option.
|
||||
|
||||
## Review Log
|
||||
|
||||
After producing the Completion Summary above, persist the review result.
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
|
||||
`~/.gstack/` (user config directory, not project files). The skill preamble
|
||||
already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
|
||||
the same pattern. The review dashboard depends on this data. Skipping this
|
||||
command breaks the review readiness dashboard in /ship.
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Substitute values from the Completion Summary:
|
||||
- **TIMESTAMP**: current ISO 8601 datetime
|
||||
- **STATUS**: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
|
||||
- **initial_score**: initial overall design score before fixes (0-10)
|
||||
- **overall_score**: final overall design score after fixes (0-10)
|
||||
- **unresolved**: number of unresolved design decisions
|
||||
- **decisions_made**: number of design decisions added to the plan
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
## Review Readiness Dashboard
|
||||
|
||||
After completing the review, read the review log and config to display the dashboard.
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display:
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
| REVIEW READINESS DASHBOARD |
|
||||
+====================================================================+
|
||||
| Review | Runs | Last Run | Status | Required |
|
||||
|-----------------|------|---------------------|-----------|----------|
|
||||
| Eng Review | 1 | 2026-03-16 15:00 | CLEAR | YES |
|
||||
| CEO Review | 0 | — | — | no |
|
||||
| Design Review | 0 | — | — | no |
|
||||
| Adversarial | 0 | — | — | no |
|
||||
| Outside Voice | 0 | — | — | no |
|
||||
+--------------------------------------------------------------------+
|
||||
| VERDICT: CLEARED — Eng Review passed |
|
||||
+====================================================================+
|
||||
```
|
||||
|
||||
**Review tiers:**
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
|
||||
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
|
||||
- **Adversarial Review (automatic):** Auto-scales by diff size. Small diffs (<50 lines) skip adversarial. Medium diffs (50–199) get cross-model adversarial. Large diffs (200+) get all 4 passes: Claude structured, Codex structured, Claude adversarial subagent, Codex adversarial. No configuration needed.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
|
||||
|
||||
**Verdict logic:**
|
||||
- **CLEARED**: Eng Review has >= 1 entry within 7 days with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
|
||||
- CEO, Design, and Codex reviews are shown for context but never block shipping
|
||||
- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
|
||||
|
||||
**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
|
||||
- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
|
||||
- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
|
||||
- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
|
||||
- If all reviews match the current HEAD, do not display any staleness notes
|
||||
|
||||
## Plan File Review Report
|
||||
|
||||
After displaying the Review Readiness Dashboard in conversation output, also update the
|
||||
**plan file** itself so review status is visible to anyone reading the plan.
|
||||
|
||||
### Detect the plan file
|
||||
|
||||
1. Check if there is an active plan file in this conversation (the host provides plan file
|
||||
paths in system messages — look for plan file references in the conversation context).
|
||||
2. If not found, skip this section silently — not every review runs in plan mode.
|
||||
|
||||
### Generate the report
|
||||
|
||||
Read the review log output you already have from the Review Readiness Dashboard step above.
|
||||
Parse each JSONL entry. Each skill logs different fields:
|
||||
|
||||
- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
|
||||
→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
|
||||
→ If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
|
||||
- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
|
||||
→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"
|
||||
- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
|
||||
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
|
||||
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
|
||||
|
||||
All fields needed for the Findings column are now present in the JSONL entries.
|
||||
For the review you just completed, you may use richer details from your own Completion
|
||||
Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
|
||||
|
||||
Produce this markdown table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines (omit any that are empty/not applicable):
|
||||
|
||||
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
|
||||
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
|
||||
- **UNRESOLVED:** total unresolved decisions across all reviews
|
||||
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
|
||||
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
|
||||
|
||||
### Write to the plan file
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file
|
||||
(not just at the end — content may have been added after it).
|
||||
- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\`
|
||||
through either the next \`## \` heading or end of file, whichever comes first. This ensures
|
||||
content added after the report section is preserved, not eaten. If the Edit fails
|
||||
(e.g., concurrent edit changed the content), re-read the plan file and retry once.
|
||||
- If no such section exists, **append it** to the end of the plan file.
|
||||
- Always place it as the very last section in the plan file. If it was found mid-file,
|
||||
move it: delete the old location and append at the end.
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
|
||||
|
||||
**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate).
|
||||
|
||||
Use question to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
|
||||
## Formatting Rules
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
* Label with NUMBER + LETTER (e.g., "3A", "3B").
|
||||
* One sentence max per option.
|
||||
* After each pass, pause and wait for feedback.
|
||||
* Rate before and after each pass for scannability.
|
||||
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
name: plan-eng-review
|
||||
description: "Eng manager-mode plan review. Lock in the execution plan — architecture, data flow, diagrams, edge cases, test coverage, performance. Walks through issues interactively with opinionated recommendati"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL RULE — How to ask questions
|
||||
Follow the question format from the Preamble above. Additional rules for plan reviews:
|
||||
* **One issue = one question call.** Never combine multiple issues into one question.
|
||||
* Describe the problem concretely, with file and line references.
|
||||
* Present 2-3 options, including "do nothing" where that's reasonable.
|
||||
* For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
|
||||
* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use question when there is a genuine decision with meaningful tradeoffs.
|
||||
|
||||
## Required outputs
|
||||
|
||||
### "NOT in scope" section
|
||||
Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
|
||||
|
||||
### "What already exists" section
|
||||
List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
|
||||
|
||||
### TODOS.md updates
|
||||
After all review sections are complete, present each potential TODO as its own individual question. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
|
||||
|
||||
For each TODO, describe:
|
||||
* **What:** One-line description of the work.
|
||||
* **Why:** The concrete problem it solves or value it unlocks.
|
||||
* **Pros:** What you gain by doing this work.
|
||||
* **Cons:** Cost, complexity, or risks of doing it.
|
||||
* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
|
||||
* **Depends on / blocked by:** Any prerequisites or ordering constraints.
|
||||
|
||||
Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
|
||||
|
||||
Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
|
||||
|
||||
### Diagrams
|
||||
The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
|
||||
|
||||
### Failure modes
|
||||
For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
|
||||
1. A test covers that failure
|
||||
2. Error handling exists for it
|
||||
3. The user would see a clear error or a silent failure
|
||||
|
||||
If any failure mode has no test AND no error handling AND would be silent, flag it as a **critical gap**.
|
||||
|
||||
### Completion summary
|
||||
At the end of the review, fill in and display this summary so the user can see all findings at a glance:
|
||||
- Step 0: Scope Challenge — ___ (scope accepted as-is / scope reduced per recommendation)
|
||||
- Architecture Review: ___ issues found
|
||||
- Code Quality Review: ___ issues found
|
||||
- Test Review: diagram produced, ___ gaps identified
|
||||
- Performance Review: ___ issues found
|
||||
- NOT in scope: written
|
||||
- What already exists: written
|
||||
- TODOS.md updates: ___ items proposed to user
|
||||
- Failure modes: ___ critical gaps flagged
|
||||
- Outside voice: ran (codex/claude) / skipped
|
||||
- Lake Score: X/Y recommendations chose complete option
|
||||
|
||||
## Retrospective learning
|
||||
Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
|
||||
|
||||
## Formatting rules
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
* Label with NUMBER + LETTER (e.g., "3A", "3B").
|
||||
* One sentence max per option. Pick in under 5 seconds.
|
||||
* After each review section, pause and ask for feedback before moving on.
|
||||
|
||||
## Review Log
|
||||
|
||||
After producing the Completion Summary above, persist the review result.
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
|
||||
`~/.gstack/` (user config directory, not project files). The skill preamble
|
||||
already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
|
||||
the same pattern. The review dashboard depends on this data. Skipping this
|
||||
command breaks the review readiness dashboard in /ship.
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"issues_found":N,"mode":"MODE","commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Substitute values from the Completion Summary:
|
||||
- **TIMESTAMP**: current ISO 8601 datetime
|
||||
- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
|
||||
- **unresolved**: number from "Unresolved decisions" count
|
||||
- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
|
||||
- **issues_found**: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
|
||||
- **MODE**: FULL_REVIEW / SCOPE_REDUCED
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
## Review Readiness Dashboard
|
||||
|
||||
After completing the review, read the review log and config to display the dashboard.
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display:
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
| REVIEW READINESS DASHBOARD |
|
||||
+====================================================================+
|
||||
| Review | Runs | Last Run | Status | Required |
|
||||
|-----------------|------|---------------------|-----------|----------|
|
||||
| Eng Review | 1 | 2026-03-16 15:00 | CLEAR | YES |
|
||||
| CEO Review | 0 | — | — | no |
|
||||
| Design Review | 0 | — | — | no |
|
||||
| Adversarial | 0 | — | — | no |
|
||||
| Outside Voice | 0 | — | — | no |
|
||||
+--------------------------------------------------------------------+
|
||||
| VERDICT: CLEARED — Eng Review passed |
|
||||
+====================================================================+
|
||||
```
|
||||
|
||||
**Review tiers:**
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
|
||||
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
|
||||
- **Adversarial Review (automatic):** Auto-scales by diff size. Small diffs (<50 lines) skip adversarial. Medium diffs (50–199) get cross-model adversarial. Large diffs (200+) get all 4 passes: Claude structured, Codex structured, Claude adversarial subagent, Codex adversarial. No configuration needed.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
|
||||
|
||||
**Verdict logic:**
|
||||
- **CLEARED**: Eng Review has >= 1 entry within 7 days with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
|
||||
- CEO, Design, and Codex reviews are shown for context but never block shipping
|
||||
- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
|
||||
|
||||
**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
|
||||
- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
|
||||
- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
|
||||
- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
|
||||
- If all reviews match the current HEAD, do not display any staleness notes
|
||||
|
||||
## Plan File Review Report
|
||||
|
||||
After displaying the Review Readiness Dashboard in conversation output, also update the
|
||||
**plan file** itself so review status is visible to anyone reading the plan.
|
||||
|
||||
### Detect the plan file
|
||||
|
||||
1. Check if there is an active plan file in this conversation (the host provides plan file
|
||||
paths in system messages — look for plan file references in the conversation context).
|
||||
2. If not found, skip this section silently — not every review runs in plan mode.
|
||||
|
||||
### Generate the report
|
||||
|
||||
Read the review log output you already have from the Review Readiness Dashboard step above.
|
||||
Parse each JSONL entry. Each skill logs different fields:
|
||||
|
||||
- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
|
||||
→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
|
||||
→ If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
|
||||
- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
|
||||
→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"
|
||||
- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
|
||||
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
|
||||
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
|
||||
|
||||
All fields needed for the Findings column are now present in the JSONL entries.
|
||||
For the review you just completed, you may use richer details from your own Completion
|
||||
Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
|
||||
|
||||
Produce this markdown table:
|
||||
|
||||
\`\`\`markdown
|
||||
## GSTACK REVIEW REPORT
|
||||
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines (omit any that are empty/not applicable):
|
||||
|
||||
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
|
||||
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
|
||||
- **UNRESOLVED:** total unresolved decisions across all reviews
|
||||
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
|
||||
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
|
||||
|
||||
### Write to the plan file
|
||||
|
||||
**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
|
||||
file you are allowed to edit in plan mode. The plan file review report is part of the
|
||||
plan's living status.
|
||||
|
||||
- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file
|
||||
(not just at the end — content may have been added after it).
|
||||
- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\`
|
||||
through either the next \`## \` heading or end of file, whichever comes first. This ensures
|
||||
content added after the report section is preserved, not eaten. If the Edit fails
|
||||
(e.g., concurrent edit changed the content), re-read the plan file and retry once.
|
||||
- If no such section exists, **append it** to the end of the plan file.
|
||||
- Always place it as the very last section in the plan file. If it was found mid-file,
|
||||
move it: delete the old location and append at the end.
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
|
||||
|
||||
**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
|
||||
|
||||
**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
|
||||
|
||||
**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
|
||||
|
||||
Use question with only the applicable options:
|
||||
- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
|
||||
- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
|
||||
- **C)** Ready to implement — run /ship when done
|
||||
|
||||
## Unresolved decisions
|
||||
If the user does not respond to an question or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
|
||||
|
|
@ -0,0 +1,334 @@
|
|||
---
|
||||
name: qa-only
|
||||
description: "Report-only QA testing. Systematically tests a web application and produces a structured report with health score, screenshots, and repro steps — but never fixes anything. Use when asked to "just re"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Test Plan Context
|
||||
|
||||
Before falling back to git diff heuristics, check for richer test plan sources:
|
||||
|
||||
1. **Project-scoped test plans:** Check `~/.gstack/projects/` for recent `*-test-plan-*.md` files for this repo
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
ls -t ~/.gstack/projects/$SLUG/*-test-plan-*.md 2>/dev/null | head -1
|
||||
```
|
||||
2. **Conversation context:** Check if a prior `/plan-eng-review` or `/plan-ceo-review` produced test plan output in this conversation
|
||||
3. **Use whichever source is richer.** Fall back to git diff analysis only if neither is available.
|
||||
|
||||
---
|
||||
|
||||
## Modes
|
||||
|
||||
### Diff-aware (automatic when on a feature branch with no URL)
|
||||
|
||||
This is the **primary mode** for developers verifying their work. When the user says `/qa` without a URL and the repo is on a feature branch, automatically:
|
||||
|
||||
1. **Analyze the branch diff** to understand what changed:
|
||||
```bash
|
||||
git diff main...HEAD --name-only
|
||||
git log main..HEAD --oneline
|
||||
```
|
||||
|
||||
2. **Identify affected pages/routes** from the changed files:
|
||||
- Controller/route files → which URL paths they serve
|
||||
- View/template/component files → which pages render them
|
||||
- Model/service files → which pages use those models (check controllers that reference them)
|
||||
- CSS/style files → which pages include those stylesheets
|
||||
- API endpoints → test them directly with `${GSTACK_BROWSE} js "await fetch('/api/...')"`
|
||||
- Static pages (markdown, HTML) → navigate to them directly
|
||||
|
||||
**If no obvious pages/routes are identified from the diff:** Do not skip browser testing. The user invoked /qa because they want browser-based verification. Fall back to Quick mode — navigate to the homepage, follow the top 5 navigation targets, check console for errors, and test any interactive elements found. Backend, config, and infrastructure changes affect app behavior — always verify the app still works.
|
||||
|
||||
3. **Detect the running app** — check common local dev ports:
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto http://localhost:3000 2>/dev/null && echo "Found app on :3000" || \
|
||||
${GSTACK_BROWSE} goto http://localhost:4000 2>/dev/null && echo "Found app on :4000" || \
|
||||
${GSTACK_BROWSE} goto http://localhost:8080 2>/dev/null && echo "Found app on :8080"
|
||||
```
|
||||
If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.
|
||||
|
||||
4. **Test each affected page/route:**
|
||||
- Navigate to the page
|
||||
- Take a screenshot
|
||||
- Check console for errors
|
||||
- If the change was interactive (forms, buttons, flows), test the interaction end-to-end
|
||||
- Use `snapshot -D` before and after actions to verify the change had the expected effect
|
||||
|
||||
5. **Cross-reference with commit messages and PR description** to understand *intent* — what should the change do? Verify it actually does that.
|
||||
|
||||
6. **Check TODOS.md** (if it exists) for known bugs or issues related to the changed files. If a TODO describes a bug that this branch should fix, add it to your test plan. If you find a new bug during QA that isn't in TODOS.md, note it in the report.
|
||||
|
||||
7. **Report findings** scoped to the branch changes:
|
||||
- "Changes tested: N pages/routes affected by this branch"
|
||||
- For each: does it work? Screenshot evidence.
|
||||
- Any regressions on adjacent pages?
|
||||
|
||||
**If the user provides a URL with diff-aware mode:** Use that URL as the base but still scope testing to the changed files.
|
||||
|
||||
### Full (default when URL is provided)
|
||||
Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score. Takes 5-15 minutes depending on app size.
|
||||
|
||||
### Quick (`--quick`)
|
||||
30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score. No detailed issue documentation.
|
||||
|
||||
### Regression (`--regression <baseline>`)
|
||||
Run full mode, then load `baseline.json` from a previous run. Diff: which issues are fixed? Which are new? What's the score delta? Append regression section to report.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Initialize
|
||||
|
||||
1. Find browse binary (see Setup above)
|
||||
2. Create output directories
|
||||
3. Copy report template from `qa/templates/qa-report-template.md` to output dir
|
||||
4. Start timer for duration tracking
|
||||
|
||||
### Phase 2: Authenticate (if needed)
|
||||
|
||||
**If the user specified auth credentials:**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <login-url>
|
||||
${GSTACK_BROWSE} snapshot -i # find the login form
|
||||
${GSTACK_BROWSE} fill @e3 "user@example.com"
|
||||
${GSTACK_BROWSE} fill @e4 "[REDACTED]" # NEVER include real passwords in report
|
||||
${GSTACK_BROWSE} click @e5 # submit
|
||||
${GSTACK_BROWSE} snapshot -D # verify login succeeded
|
||||
```
|
||||
|
||||
**If the user provided a cookie file:**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} cookie-import cookies.json
|
||||
${GSTACK_BROWSE} goto <target-url>
|
||||
```
|
||||
|
||||
**If 2FA/OTP is required:** Ask the user for the code and wait.
|
||||
|
||||
**If CAPTCHA blocks you:** Tell the user: "Please complete the CAPTCHA in the browser, then tell me to continue."
|
||||
|
||||
### Phase 3: Orient
|
||||
|
||||
Get a map of the application:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <target-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/initial.png"
|
||||
${GSTACK_BROWSE} links # map navigation structure
|
||||
${GSTACK_BROWSE} console --errors # any errors on landing?
|
||||
```
|
||||
|
||||
**Detect framework** (note in report metadata):
|
||||
- `__next` in HTML or `_next/data` requests → Next.js
|
||||
- `csrf-token` meta tag → Rails
|
||||
- `wp-content` in URLs → WordPress
|
||||
- Client-side routing with no page reloads → SPA
|
||||
|
||||
**For SPAs:** The `links` command may return few results because navigation is client-side. Use `snapshot -i` to find nav elements (buttons, menu items) instead.
|
||||
|
||||
### Phase 4: Explore
|
||||
|
||||
Visit pages systematically. At each page:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <page-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
```
|
||||
|
||||
Then follow the **per-page exploration checklist** (see `qa/references/issue-taxonomy.md`):
|
||||
|
||||
1. **Visual scan** — Look at the annotated screenshot for layout issues
|
||||
2. **Interactive elements** — Click buttons, links, controls. Do they work?
|
||||
3. **Forms** — Fill and submit. Test empty, invalid, edge cases
|
||||
4. **Navigation** — Check all paths in and out
|
||||
5. **States** — Empty state, loading, error, overflow
|
||||
6. **Console** — Any new JS errors after interactions?
|
||||
7. **Responsiveness** — Check mobile viewport if relevant:
|
||||
```bash
|
||||
${GSTACK_BROWSE} viewport 375x812
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/page-mobile.png"
|
||||
${GSTACK_BROWSE} viewport 1280x720
|
||||
```
|
||||
|
||||
**Depth judgment:** Spend more time on core features (homepage, dashboard, checkout, search) and less on secondary pages (about, terms, privacy).
|
||||
|
||||
**Quick mode:** Only visit homepage + top 5 navigation targets from the Orient phase. Skip the per-page checklist — just check: loads? Console errors? Broken links visible?
|
||||
|
||||
### Phase 5: Document
|
||||
|
||||
Document each issue **immediately when found** — don't batch them.
|
||||
|
||||
**Two evidence tiers:**
|
||||
|
||||
**Interactive bugs** (broken flows, dead buttons, form failures):
|
||||
1. Take a screenshot before the action
|
||||
2. Perform the action
|
||||
3. Take a screenshot showing the result
|
||||
4. Use `snapshot -D` to show what changed
|
||||
5. Write repro steps referencing screenshots
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
|
||||
${GSTACK_BROWSE} click @e5
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
|
||||
${GSTACK_BROWSE} snapshot -D
|
||||
```
|
||||
|
||||
**Static bugs** (typos, layout issues, missing images):
|
||||
1. Take a single annotated screenshot showing the problem
|
||||
2. Describe what's wrong
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"
|
||||
```
|
||||
|
||||
**Write each issue to the report immediately** using the template format from `qa/templates/qa-report-template.md`.
|
||||
|
||||
### Phase 6: Wrap Up
|
||||
|
||||
1. **Compute health score** using the rubric below
|
||||
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues
|
||||
3. **Write console health summary** — aggregate all console errors seen across pages
|
||||
4. **Update severity counts** in the summary table
|
||||
5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework
|
||||
6. **Save baseline** — write `baseline.json` with:
|
||||
```json
|
||||
{
|
||||
"date": "YYYY-MM-DD",
|
||||
"url": "<target>",
|
||||
"healthScore": N,
|
||||
"issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
|
||||
"categoryScores": { "console": N, "links": N, ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Regression mode:** After writing the report, load the baseline file. Compare:
|
||||
- Health score delta
|
||||
- Issues fixed (in baseline but not current)
|
||||
- New issues (in current but not baseline)
|
||||
- Append the regression section to the report
|
||||
|
||||
---
|
||||
|
||||
## Health Score Rubric
|
||||
|
||||
Compute each category score (0-100), then take the weighted average.
|
||||
|
||||
### Console (weight: 15%)
|
||||
- 0 errors → 100
|
||||
- 1-3 errors → 70
|
||||
- 4-10 errors → 40
|
||||
- 10+ errors → 10
|
||||
|
||||
### Links (weight: 10%)
|
||||
- 0 broken → 100
|
||||
- Each broken link → -15 (minimum 0)
|
||||
|
||||
### Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)
|
||||
Each category starts at 100. Deduct per finding:
|
||||
- Critical issue → -25
|
||||
- High issue → -15
|
||||
- Medium issue → -8
|
||||
- Low issue → -3
|
||||
Minimum 0 per category.
|
||||
|
||||
### Weights
|
||||
| Category | Weight |
|
||||
|----------|--------|
|
||||
| Console | 15% |
|
||||
| Links | 10% |
|
||||
| Visual | 10% |
|
||||
| Functional | 20% |
|
||||
| UX | 15% |
|
||||
| Performance | 10% |
|
||||
| Content | 5% |
|
||||
| Accessibility | 15% |
|
||||
|
||||
### Final Score
|
||||
`score = Σ (category_score × weight)`
|
||||
|
||||
---
|
||||
|
||||
## Framework-Specific Guidance
|
||||
|
||||
### Next.js
|
||||
- Check console for hydration errors (`Hydration failed`, `Text content did not match`)
|
||||
- Monitor `_next/data` requests in network — 404s indicate broken data fetching
|
||||
- Test client-side navigation (click links, don't just `goto`) — catches routing issues
|
||||
- Check for CLS (Cumulative Layout Shift) on pages with dynamic content
|
||||
|
||||
### Rails
|
||||
- Check for N+1 query warnings in console (if development mode)
|
||||
- Verify CSRF token presence in forms
|
||||
- Test Turbo/Stimulus integration — do page transitions work smoothly?
|
||||
- Check for flash messages appearing and dismissing correctly
|
||||
|
||||
### WordPress
|
||||
- Check for plugin conflicts (JS errors from different plugins)
|
||||
- Verify admin bar visibility for logged-in users
|
||||
- Test REST API endpoints (`/wp-json/`)
|
||||
- Check for mixed content warnings (common with WP)
|
||||
|
||||
### General SPA (React, Vue, Angular)
|
||||
- Use `snapshot -i` for navigation — `links` command misses client-side routes
|
||||
- Check for stale state (navigate away and back — does data refresh?)
|
||||
- Test browser back/forward — does the app handle history correctly?
|
||||
- Check for memory leaks (monitor console after extended use)
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
1. **Repro is everything.** Every issue needs at least one screenshot. No exceptions.
|
||||
2. **Verify before documenting.** Retry the issue once to confirm it's reproducible, not a fluke.
|
||||
3. **Never include credentials.** Write `[REDACTED]` for passwords in repro steps.
|
||||
4. **Write incrementally.** Append each issue to the report as you find it. Don't batch.
|
||||
5. **Never read source code.** Test as a user, not a developer.
|
||||
6. **Check console after every interaction.** JS errors that don't surface visually are still bugs.
|
||||
7. **Test like a user.** Use realistic data. Walk through complete workflows end-to-end.
|
||||
8. **Depth over breadth.** 5-10 well-documented issues with evidence > 20 vague descriptions.
|
||||
9. **Never delete output files.** Screenshots and reports accumulate — that's intentional.
|
||||
10. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses.
|
||||
11. **Show screenshots to the user.** After every `${GSTACK_BROWSE} screenshot`, `${GSTACK_BROWSE} snapshot -a -o`, or `${GSTACK_BROWSE} responsive` command, use the Read tool on the output file(s) so the user can see them inline. For `responsive` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user.
|
||||
12. **Never refuse to use the browser.** When the user invokes /qa or /qa-only, they are requesting browser-based testing. Never suggest evals, unit tests, or other alternatives as a substitute. Even if the diff appears to have no UI changes, backend changes affect app behavior — always open the browser and test.
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Write the report to both local and project-scoped locations:
|
||||
|
||||
**Local:** `.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md`
|
||||
|
||||
**Project-scoped:** Write test outcome artifact for cross-session context:
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md`
|
||||
|
||||
### Output Structure
|
||||
|
||||
```
|
||||
.gstack/qa-reports/
|
||||
├── qa-report-{domain}-{YYYY-MM-DD}.md # Structured report
|
||||
├── screenshots/
|
||||
│ ├── initial.png # Landing page annotated screenshot
|
||||
│ ├── issue-001-step-1.png # Per-issue evidence
|
||||
│ ├── issue-001-result.png
|
||||
│ └── ...
|
||||
└── baseline.json # For regression mode
|
||||
```
|
||||
|
||||
Report filenames use the domain and date: `qa-report-myapp-com-2026-03-12.md`
|
||||
|
||||
---
|
||||
|
||||
## Additional Rules (qa-only specific)
|
||||
|
||||
11. **Never fix bugs.** Find and document only. Do not read source code, edit files, or suggest fixes in the report. Your job is to report what's broken, not to fix it. Use `/qa` for the test-fix-verify loop.
|
||||
12. **No test framework detected?** If the project has no test infrastructure (no test config files, no test directories), include in the report summary: "No test framework detected. Run `/qa` to bootstrap one and enable regression test generation."
|
||||
|
|
@ -0,0 +1,740 @@
|
|||
---
|
||||
name: qa
|
||||
description: "Systematically QA test a web application and fix bugs found. Runs QA testing, then iteratively fixes bugs in source code, committing each fix atomically and re-verifying. Use when asked to "qa", "QA","
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /qa: Test → Fix → Verify
|
||||
|
||||
You are a QA engineer AND a bug-fix engineer. Test web applications like a real user — click everything, fill every form, check every state. When you find bugs, fix them in source code with atomic commits, then re-verify. Produce a structured report with before/after evidence.
|
||||
|
||||
## Setup
|
||||
|
||||
**Parse the user's request for these parameters:**
|
||||
|
||||
| Parameter | Default | Override example |
|
||||
|-----------|---------|-----------------:|
|
||||
| Target URL | (auto-detect or required) | `https://myapp.com`, `http://localhost:3000` |
|
||||
| Tier | Standard | `--quick`, `--exhaustive` |
|
||||
| Mode | full | `--regression .gstack/qa-reports/baseline.json` |
|
||||
| Output dir | `.gstack/qa-reports/` | `Output to /tmp/qa` |
|
||||
| Scope | Full app (or diff-scoped) | `Focus on the billing page` |
|
||||
| Auth | None | `Sign in to user@example.com`, `Import cookies from cookies.json` |
|
||||
|
||||
**Tiers determine which issues get fixed:**
|
||||
- **Quick:** Fix critical + high severity only
|
||||
- **Standard:** + medium severity (default)
|
||||
- **Exhaustive:** + low/cosmetic severity
|
||||
|
||||
**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below). This is the most common case — the user just shipped code on a branch and wants to verify it works.
|
||||
|
||||
**Check for clean working tree:**
|
||||
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
If the output is non-empty (working tree is dirty), **STOP** and use question:
|
||||
|
||||
"Your working tree has uncommitted changes. /qa needs a clean tree so each bug fix gets its own atomic commit."
|
||||
|
||||
- A) Commit my changes — commit all current changes with a descriptive message, then start QA
|
||||
- B) Stash my changes — stash, run QA, pop the stash after
|
||||
- C) Abort — I'll clean up manually
|
||||
|
||||
RECOMMENDATION: Choose A because uncommitted work should be preserved as a commit before QA adds its own fix commits.
|
||||
|
||||
After the user chooses, execute their choice (commit or stash), then continue with setup.
|
||||
|
||||
**Find the browse binary:**
|
||||
|
||||
## SETUP (run this check BEFORE any browse command)
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
B=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/${GSTACK_OPENCODE_DIR}/browse/dist/browse" ] && B="$_ROOT/${GSTACK_OPENCODE_DIR}/browse/dist/browse"
|
||||
[ -z "$B" ] && B=${GSTACK_OPENCODE_DIR}/browse/dist/browse
|
||||
if [ -x "$B" ]; then
|
||||
echo "READY: $B"
|
||||
else
|
||||
echo "NEEDS_SETUP"
|
||||
fi
|
||||
```
|
||||
|
||||
If `NEEDS_SETUP`:
|
||||
1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
|
||||
2. Run: `cd <SKILL_DIR> && ./setup`
|
||||
3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
|
||||
|
||||
**Check test framework (bootstrap if needed):**
|
||||
|
||||
## Test Framework Bootstrap
|
||||
|
||||
**Detect existing test framework and project runtime:**
|
||||
|
||||
```bash
|
||||
# Detect project runtime
|
||||
[ -f Gemfile ] && echo "RUNTIME:ruby"
|
||||
[ -f package.json ] && echo "RUNTIME:node"
|
||||
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
|
||||
[ -f go.mod ] && echo "RUNTIME:go"
|
||||
[ -f Cargo.toml ] && echo "RUNTIME:rust"
|
||||
[ -f composer.json ] && echo "RUNTIME:php"
|
||||
[ -f mix.exs ] && echo "RUNTIME:elixir"
|
||||
# Detect sub-frameworks
|
||||
[ -f Gemfile ] && grep -q "rails" Gemfile 2>/dev/null && echo "FRAMEWORK:rails"
|
||||
[ -f package.json ] && grep -q '"next"' package.json 2>/dev/null && echo "FRAMEWORK:nextjs"
|
||||
# Check for existing test infrastructure
|
||||
ls jest.config.* vitest.config.* playwright.config.* .rspec pytest.ini pyproject.toml phpunit.xml 2>/dev/null
|
||||
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
|
||||
# Check opt-out marker
|
||||
[ -f .gstack/no-test-bootstrap ] && echo "BOOTSTRAP_DECLINED"
|
||||
```
|
||||
|
||||
**If test framework detected** (config files or test directories found):
|
||||
Print "Test framework detected: {name} ({N} existing tests). Skipping bootstrap."
|
||||
Read 2-3 existing test files to learn conventions (naming, imports, assertion style, setup patterns).
|
||||
Store conventions as prose context for use in Phase 8e.5 or Step 3.4. **Skip the rest of bootstrap.**
|
||||
|
||||
**If BOOTSTRAP_DECLINED** appears: Print "Test bootstrap previously declined — skipping." **Skip the rest of bootstrap.**
|
||||
|
||||
**If NO runtime detected** (no config files found): Use question:
|
||||
"I couldn't detect your project's language. What runtime are you using?"
|
||||
Options: A) Node.js/TypeScript B) Ruby/Rails C) Python D) Go E) Rust F) PHP G) Elixir H) This project doesn't need tests.
|
||||
If user picks H → write `.gstack/no-test-bootstrap` and continue without tests.
|
||||
|
||||
**If runtime detected but no test framework — bootstrap:**
|
||||
|
||||
### B2. Research best practices
|
||||
|
||||
Use WebSearch to find current best practices for the detected runtime:
|
||||
- `"[runtime] best test framework 2025 2026"`
|
||||
- `"[framework A] vs [framework B] comparison"`
|
||||
|
||||
If WebSearch is unavailable, use this built-in knowledge table:
|
||||
|
||||
| Runtime | Primary recommendation | Alternative |
|
||||
|---------|----------------------|-------------|
|
||||
| Ruby/Rails | minitest + fixtures + capybara | rspec + factory_bot + shoulda-matchers |
|
||||
| Node.js | vitest + @testing-library | jest + @testing-library |
|
||||
| Next.js | vitest + @testing-library/react + playwright | jest + cypress |
|
||||
| Python | pytest + pytest-cov | unittest |
|
||||
| Go | stdlib testing + testify | stdlib only |
|
||||
| Rust | cargo test (built-in) + mockall | — |
|
||||
| PHP | phpunit + mockery | pest |
|
||||
| Elixir | ExUnit (built-in) + ex_machina | — |
|
||||
|
||||
### B3. Framework selection
|
||||
|
||||
Use question:
|
||||
"I detected this is a [Runtime/Framework] project with no test framework. I researched current best practices. Here are the options:
|
||||
A) [Primary] — [rationale]. Includes: [packages]. Supports: unit, integration, smoke, e2e
|
||||
B) [Alternative] — [rationale]. Includes: [packages]
|
||||
C) Skip — don't set up testing right now
|
||||
RECOMMENDATION: Choose A because [reason based on project context]"
|
||||
|
||||
If user picks C → write `.gstack/no-test-bootstrap`. Tell user: "If you change your mind later, delete `.gstack/no-test-bootstrap` and re-run." Continue without tests.
|
||||
|
||||
If multiple runtimes detected (monorepo) → ask which runtime to set up first, with option to do both sequentially.
|
||||
|
||||
### B4. Install and configure
|
||||
|
||||
1. Install the chosen packages (npm/bun/gem/pip/etc.)
|
||||
2. Create minimal config file
|
||||
3. Create directory structure (test/, spec/, etc.)
|
||||
4. Create one example test matching the project's code to verify setup works
|
||||
|
||||
If package installation fails → debug once. If still failing → revert with `git checkout -- package.json package-lock.json` (or equivalent for the runtime). Warn user and continue without tests.
|
||||
|
||||
### B4.5. First real tests
|
||||
|
||||
Generate 3-5 real tests for existing code:
|
||||
|
||||
1. **Find recently changed files:** `git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -10`
|
||||
2. **Prioritize by risk:** Error handlers > business logic with conditionals > API endpoints > pure functions
|
||||
3. **For each file:** Write one test that tests real behavior with meaningful assertions. Never `expect(x).toBeDefined()` — test what the code DOES.
|
||||
4. Run each test. Passes → keep. Fails → fix once. Still fails → delete silently.
|
||||
5. Generate at least 1 test, cap at 5.
|
||||
|
||||
Never import secrets, API keys, or credentials in test files. Use environment variables or test fixtures.
|
||||
|
||||
### B5. Verify
|
||||
|
||||
```bash
|
||||
# Run the full test suite to confirm everything works
|
||||
{detected test command}
|
||||
```
|
||||
|
||||
If tests fail → debug once. If still failing → revert all bootstrap changes and warn user.
|
||||
|
||||
### B5.5. CI/CD pipeline
|
||||
|
||||
```bash
|
||||
# Check CI provider
|
||||
ls -d .github/ 2>/dev/null && echo "CI:github"
|
||||
ls .gitlab-ci.yml .circleci/ bitrise.yml 2>/dev/null
|
||||
```
|
||||
|
||||
If `.github/` exists (or no CI detected — default to GitHub Actions):
|
||||
Create `.github/workflows/test.yml` with:
|
||||
- `runs-on: ubuntu-latest`
|
||||
- Appropriate setup action for the runtime (setup-node, setup-ruby, setup-python, etc.)
|
||||
- The same test command verified in B5
|
||||
- Trigger: push + pull_request
|
||||
|
||||
If non-GitHub CI detected → skip CI generation with note: "Detected {provider} — CI pipeline generation supports GitHub Actions only. Add test step to your existing pipeline manually."
|
||||
|
||||
### B6. Create TESTING.md
|
||||
|
||||
First check: If TESTING.md already exists → read it and update/append rather than overwriting. Never destroy existing content.
|
||||
|
||||
Write TESTING.md with:
|
||||
- Philosophy: "100% test coverage is the key to great vibe coding. Tests let you move fast, trust your instincts, and ship with confidence — without them, vibe coding is just yolo coding. With tests, it's a superpower."
|
||||
- Framework name and version
|
||||
- How to run tests (the verified command from B5)
|
||||
- Test layers: Unit tests (what, where, when), Integration tests, Smoke tests, E2E tests
|
||||
- Conventions: file naming, assertion style, setup/teardown patterns
|
||||
|
||||
### B7. Update CLAUDE.md
|
||||
|
||||
First check: If CLAUDE.md already has a `## Testing` section → skip. Don't duplicate.
|
||||
|
||||
Append a `## Testing` section:
|
||||
- Run command and test directory
|
||||
- Reference to TESTING.md
|
||||
- Test expectations:
|
||||
- 100% test coverage is the goal — tests make vibe coding safe
|
||||
- When writing new functions, write a corresponding test
|
||||
- When fixing a bug, write a regression test
|
||||
- When adding error handling, write a test that triggers the error
|
||||
- When adding a conditional (if/else, switch), write tests for BOTH paths
|
||||
- Never commit code that makes existing tests fail
|
||||
|
||||
### B8. Commit
|
||||
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
Only commit if there are changes. Stage all bootstrap files (config, test directory, TESTING.md, CLAUDE.md, .github/workflows/test.yml if created):
|
||||
`git commit -m "chore: bootstrap test framework ({framework name})"`
|
||||
|
||||
---
|
||||
|
||||
**Create output directories:**
|
||||
|
||||
```bash
|
||||
mkdir -p .gstack/qa-reports/screenshots
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Plan Context
|
||||
|
||||
Before falling back to git diff heuristics, check for richer test plan sources:
|
||||
|
||||
1. **Project-scoped test plans:** Check `~/.gstack/projects/` for recent `*-test-plan-*.md` files for this repo
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)"
|
||||
ls -t ~/.gstack/projects/$SLUG/*-test-plan-*.md 2>/dev/null | head -1
|
||||
```
|
||||
2. **Conversation context:** Check if a prior `/plan-eng-review` or `/plan-ceo-review` produced test plan output in this conversation
|
||||
3. **Use whichever source is richer.** Fall back to git diff analysis only if neither is available.
|
||||
|
||||
---
|
||||
|
||||
## Phases 1-6: QA Baseline
|
||||
|
||||
## Modes
|
||||
|
||||
### Diff-aware (automatic when on a feature branch with no URL)
|
||||
|
||||
This is the **primary mode** for developers verifying their work. When the user says `/qa` without a URL and the repo is on a feature branch, automatically:
|
||||
|
||||
1. **Analyze the branch diff** to understand what changed:
|
||||
```bash
|
||||
git diff main...HEAD --name-only
|
||||
git log main..HEAD --oneline
|
||||
```
|
||||
|
||||
2. **Identify affected pages/routes** from the changed files:
|
||||
- Controller/route files → which URL paths they serve
|
||||
- View/template/component files → which pages render them
|
||||
- Model/service files → which pages use those models (check controllers that reference them)
|
||||
- CSS/style files → which pages include those stylesheets
|
||||
- API endpoints → test them directly with `${GSTACK_BROWSE} js "await fetch('/api/...')"`
|
||||
- Static pages (markdown, HTML) → navigate to them directly
|
||||
|
||||
**If no obvious pages/routes are identified from the diff:** Do not skip browser testing. The user invoked /qa because they want browser-based verification. Fall back to Quick mode — navigate to the homepage, follow the top 5 navigation targets, check console for errors, and test any interactive elements found. Backend, config, and infrastructure changes affect app behavior — always verify the app still works.
|
||||
|
||||
3. **Detect the running app** — check common local dev ports:
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto http://localhost:3000 2>/dev/null && echo "Found app on :3000" || \
|
||||
${GSTACK_BROWSE} goto http://localhost:4000 2>/dev/null && echo "Found app on :4000" || \
|
||||
${GSTACK_BROWSE} goto http://localhost:8080 2>/dev/null && echo "Found app on :8080"
|
||||
```
|
||||
If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.
|
||||
|
||||
4. **Test each affected page/route:**
|
||||
- Navigate to the page
|
||||
- Take a screenshot
|
||||
- Check console for errors
|
||||
- If the change was interactive (forms, buttons, flows), test the interaction end-to-end
|
||||
- Use `snapshot -D` before and after actions to verify the change had the expected effect
|
||||
|
||||
5. **Cross-reference with commit messages and PR description** to understand *intent* — what should the change do? Verify it actually does that.
|
||||
|
||||
6. **Check TODOS.md** (if it exists) for known bugs or issues related to the changed files. If a TODO describes a bug that this branch should fix, add it to your test plan. If you find a new bug during QA that isn't in TODOS.md, note it in the report.
|
||||
|
||||
7. **Report findings** scoped to the branch changes:
|
||||
- "Changes tested: N pages/routes affected by this branch"
|
||||
- For each: does it work? Screenshot evidence.
|
||||
- Any regressions on adjacent pages?
|
||||
|
||||
**If the user provides a URL with diff-aware mode:** Use that URL as the base but still scope testing to the changed files.
|
||||
|
||||
### Full (default when URL is provided)
|
||||
Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score. Takes 5-15 minutes depending on app size.
|
||||
|
||||
### Quick (`--quick`)
|
||||
30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score. No detailed issue documentation.
|
||||
|
||||
### Regression (`--regression <baseline>`)
|
||||
Run full mode, then load `baseline.json` from a previous run. Diff: which issues are fixed? Which are new? What's the score delta? Append regression section to report.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Initialize
|
||||
|
||||
1. Find browse binary (see Setup above)
|
||||
2. Create output directories
|
||||
3. Copy report template from `qa/templates/qa-report-template.md` to output dir
|
||||
4. Start timer for duration tracking
|
||||
|
||||
### Phase 2: Authenticate (if needed)
|
||||
|
||||
**If the user specified auth credentials:**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <login-url>
|
||||
${GSTACK_BROWSE} snapshot -i # find the login form
|
||||
${GSTACK_BROWSE} fill @e3 "user@example.com"
|
||||
${GSTACK_BROWSE} fill @e4 "[REDACTED]" # NEVER include real passwords in report
|
||||
${GSTACK_BROWSE} click @e5 # submit
|
||||
${GSTACK_BROWSE} snapshot -D # verify login succeeded
|
||||
```
|
||||
|
||||
**If the user provided a cookie file:**
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} cookie-import cookies.json
|
||||
${GSTACK_BROWSE} goto <target-url>
|
||||
```
|
||||
|
||||
**If 2FA/OTP is required:** Ask the user for the code and wait.
|
||||
|
||||
**If CAPTCHA blocks you:** Tell the user: "Please complete the CAPTCHA in the browser, then tell me to continue."
|
||||
|
||||
### Phase 3: Orient
|
||||
|
||||
Get a map of the application:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <target-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/initial.png"
|
||||
${GSTACK_BROWSE} links # map navigation structure
|
||||
${GSTACK_BROWSE} console --errors # any errors on landing?
|
||||
```
|
||||
|
||||
**Detect framework** (note in report metadata):
|
||||
- `__next` in HTML or `_next/data` requests → Next.js
|
||||
- `csrf-token` meta tag → Rails
|
||||
- `wp-content` in URLs → WordPress
|
||||
- Client-side routing with no page reloads → SPA
|
||||
|
||||
**For SPAs:** The `links` command may return few results because navigation is client-side. Use `snapshot -i` to find nav elements (buttons, menu items) instead.
|
||||
|
||||
### Phase 4: Explore
|
||||
|
||||
Visit pages systematically. At each page:
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <page-url>
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
```
|
||||
|
||||
Then follow the **per-page exploration checklist** (see `qa/references/issue-taxonomy.md`):
|
||||
|
||||
1. **Visual scan** — Look at the annotated screenshot for layout issues
|
||||
2. **Interactive elements** — Click buttons, links, controls. Do they work?
|
||||
3. **Forms** — Fill and submit. Test empty, invalid, edge cases
|
||||
4. **Navigation** — Check all paths in and out
|
||||
5. **States** — Empty state, loading, error, overflow
|
||||
6. **Console** — Any new JS errors after interactions?
|
||||
7. **Responsiveness** — Check mobile viewport if relevant:
|
||||
```bash
|
||||
${GSTACK_BROWSE} viewport 375x812
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/page-mobile.png"
|
||||
${GSTACK_BROWSE} viewport 1280x720
|
||||
```
|
||||
|
||||
**Depth judgment:** Spend more time on core features (homepage, dashboard, checkout, search) and less on secondary pages (about, terms, privacy).
|
||||
|
||||
**Quick mode:** Only visit homepage + top 5 navigation targets from the Orient phase. Skip the per-page checklist — just check: loads? Console errors? Broken links visible?
|
||||
|
||||
### Phase 5: Document
|
||||
|
||||
Document each issue **immediately when found** — don't batch them.
|
||||
|
||||
**Two evidence tiers:**
|
||||
|
||||
**Interactive bugs** (broken flows, dead buttons, form failures):
|
||||
1. Take a screenshot before the action
|
||||
2. Perform the action
|
||||
3. Take a screenshot showing the result
|
||||
4. Use `snapshot -D` to show what changed
|
||||
5. Write repro steps referencing screenshots
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
|
||||
${GSTACK_BROWSE} click @e5
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
|
||||
${GSTACK_BROWSE} snapshot -D
|
||||
```
|
||||
|
||||
**Static bugs** (typos, layout issues, missing images):
|
||||
1. Take a single annotated screenshot showing the problem
|
||||
2. Describe what's wrong
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"
|
||||
```
|
||||
|
||||
**Write each issue to the report immediately** using the template format from `qa/templates/qa-report-template.md`.
|
||||
|
||||
### Phase 6: Wrap Up
|
||||
|
||||
1. **Compute health score** using the rubric below
|
||||
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues
|
||||
3. **Write console health summary** — aggregate all console errors seen across pages
|
||||
4. **Update severity counts** in the summary table
|
||||
5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework
|
||||
6. **Save baseline** — write `baseline.json` with:
|
||||
```json
|
||||
{
|
||||
"date": "YYYY-MM-DD",
|
||||
"url": "<target>",
|
||||
"healthScore": N,
|
||||
"issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
|
||||
"categoryScores": { "console": N, "links": N, ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Regression mode:** After writing the report, load the baseline file. Compare:
|
||||
- Health score delta
|
||||
- Issues fixed (in baseline but not current)
|
||||
- New issues (in current but not baseline)
|
||||
- Append the regression section to the report
|
||||
|
||||
---
|
||||
|
||||
## Health Score Rubric
|
||||
|
||||
Compute each category score (0-100), then take the weighted average.
|
||||
|
||||
### Console (weight: 15%)
|
||||
- 0 errors → 100
|
||||
- 1-3 errors → 70
|
||||
- 4-10 errors → 40
|
||||
- 10+ errors → 10
|
||||
|
||||
### Links (weight: 10%)
|
||||
- 0 broken → 100
|
||||
- Each broken link → -15 (minimum 0)
|
||||
|
||||
### Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)
|
||||
Each category starts at 100. Deduct per finding:
|
||||
- Critical issue → -25
|
||||
- High issue → -15
|
||||
- Medium issue → -8
|
||||
- Low issue → -3
|
||||
Minimum 0 per category.
|
||||
|
||||
### Weights
|
||||
| Category | Weight |
|
||||
|----------|--------|
|
||||
| Console | 15% |
|
||||
| Links | 10% |
|
||||
| Visual | 10% |
|
||||
| Functional | 20% |
|
||||
| UX | 15% |
|
||||
| Performance | 10% |
|
||||
| Content | 5% |
|
||||
| Accessibility | 15% |
|
||||
|
||||
### Final Score
|
||||
`score = Σ (category_score × weight)`
|
||||
|
||||
---
|
||||
|
||||
## Framework-Specific Guidance
|
||||
|
||||
### Next.js
|
||||
- Check console for hydration errors (`Hydration failed`, `Text content did not match`)
|
||||
- Monitor `_next/data` requests in network — 404s indicate broken data fetching
|
||||
- Test client-side navigation (click links, don't just `goto`) — catches routing issues
|
||||
- Check for CLS (Cumulative Layout Shift) on pages with dynamic content
|
||||
|
||||
### Rails
|
||||
- Check for N+1 query warnings in console (if development mode)
|
||||
- Verify CSRF token presence in forms
|
||||
- Test Turbo/Stimulus integration — do page transitions work smoothly?
|
||||
- Check for flash messages appearing and dismissing correctly
|
||||
|
||||
### WordPress
|
||||
- Check for plugin conflicts (JS errors from different plugins)
|
||||
- Verify admin bar visibility for logged-in users
|
||||
- Test REST API endpoints (`/wp-json/`)
|
||||
- Check for mixed content warnings (common with WP)
|
||||
|
||||
### General SPA (React, Vue, Angular)
|
||||
- Use `snapshot -i` for navigation — `links` command misses client-side routes
|
||||
- Check for stale state (navigate away and back — does data refresh?)
|
||||
- Test browser back/forward — does the app handle history correctly?
|
||||
- Check for memory leaks (monitor console after extended use)
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
1. **Repro is everything.** Every issue needs at least one screenshot. No exceptions.
|
||||
2. **Verify before documenting.** Retry the issue once to confirm it's reproducible, not a fluke.
|
||||
3. **Never include credentials.** Write `[REDACTED]` for passwords in repro steps.
|
||||
4. **Write incrementally.** Append each issue to the report as you find it. Don't batch.
|
||||
5. **Never read source code.** Test as a user, not a developer.
|
||||
6. **Check console after every interaction.** JS errors that don't surface visually are still bugs.
|
||||
7. **Test like a user.** Use realistic data. Walk through complete workflows end-to-end.
|
||||
8. **Depth over breadth.** 5-10 well-documented issues with evidence > 20 vague descriptions.
|
||||
9. **Never delete output files.** Screenshots and reports accumulate — that's intentional.
|
||||
10. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses.
|
||||
11. **Show screenshots to the user.** After every `${GSTACK_BROWSE} screenshot`, `${GSTACK_BROWSE} snapshot -a -o`, or `${GSTACK_BROWSE} responsive` command, use the Read tool on the output file(s) so the user can see them inline. For `responsive` (3 files), Read all three. This is critical — without it, screenshots are invisible to the user.
|
||||
12. **Never refuse to use the browser.** When the user invokes /qa or /qa-only, they are requesting browser-based testing. Never suggest evals, unit tests, or other alternatives as a substitute. Even if the diff appears to have no UI changes, backend changes affect app behavior — always open the browser and test.
|
||||
|
||||
Record baseline health score at end of Phase 6.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
.gstack/qa-reports/
|
||||
├── qa-report-{domain}-{YYYY-MM-DD}.md # Structured report
|
||||
├── screenshots/
|
||||
│ ├── initial.png # Landing page annotated screenshot
|
||||
│ ├── issue-001-step-1.png # Per-issue evidence
|
||||
│ ├── issue-001-result.png
|
||||
│ ├── issue-001-before.png # Before fix (if fixed)
|
||||
│ ├── issue-001-after.png # After fix (if fixed)
|
||||
│ └── ...
|
||||
└── baseline.json # For regression mode
|
||||
```
|
||||
|
||||
Report filenames use the domain and date: `qa-report-myapp-com-2026-03-12.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Triage
|
||||
|
||||
Sort all discovered issues by severity, then decide which to fix based on the selected tier:
|
||||
|
||||
- **Quick:** Fix critical + high only. Mark medium/low as "deferred."
|
||||
- **Standard:** Fix critical + high + medium. Mark low as "deferred."
|
||||
- **Exhaustive:** Fix all, including cosmetic/low severity.
|
||||
|
||||
Mark issues that cannot be fixed from source code (e.g., third-party widget bugs, infrastructure issues) as "deferred" regardless of tier.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Fix Loop
|
||||
|
||||
For each fixable issue, in severity order:
|
||||
|
||||
### 8a. Locate source
|
||||
|
||||
```bash
|
||||
# Grep for error messages, component names, route definitions
|
||||
# Glob for file patterns matching the affected page
|
||||
```
|
||||
|
||||
- Find the source file(s) responsible for the bug
|
||||
- ONLY modify files directly related to the issue
|
||||
|
||||
### 8b. Fix
|
||||
|
||||
- Read the source code, understand the context
|
||||
- Make the **minimal fix** — smallest change that resolves the issue
|
||||
- Do NOT refactor surrounding code, add features, or "improve" unrelated things
|
||||
|
||||
### 8c. Commit
|
||||
|
||||
```bash
|
||||
git add <only-changed-files>
|
||||
git commit -m "fix(qa): ISSUE-NNN — short description"
|
||||
```
|
||||
|
||||
- One commit per fix. Never bundle multiple fixes.
|
||||
- Message format: `fix(qa): ISSUE-NNN — short description`
|
||||
|
||||
### 8d. Re-test
|
||||
|
||||
- Navigate back to the affected page
|
||||
- Take **before/after screenshot pair**
|
||||
- Check console for errors
|
||||
- Use `snapshot -D` to verify the change had the expected effect
|
||||
|
||||
```bash
|
||||
${GSTACK_BROWSE} goto <affected-url>
|
||||
${GSTACK_BROWSE} screenshot "$REPORT_DIR/screenshots/issue-NNN-after.png"
|
||||
${GSTACK_BROWSE} console --errors
|
||||
${GSTACK_BROWSE} snapshot -D
|
||||
```
|
||||
|
||||
### 8e. Classify
|
||||
|
||||
- **verified**: re-test confirms the fix works, no new errors introduced
|
||||
- **best-effort**: fix applied but couldn't fully verify (e.g., needs auth state, external service)
|
||||
- **reverted**: regression detected → `git revert HEAD` → mark issue as "deferred"
|
||||
|
||||
### 8e.5. Regression Test
|
||||
|
||||
Skip if: classification is not "verified", OR the fix is purely visual/CSS with no JS behavior, OR no test framework was detected AND user declined bootstrap.
|
||||
|
||||
**1. Study the project's existing test patterns:**
|
||||
|
||||
Read 2-3 test files closest to the fix (same directory, same code type). Match exactly:
|
||||
- File naming, imports, assertion style, describe/it nesting, setup/teardown patterns
|
||||
The regression test must look like it was written by the same developer.
|
||||
|
||||
**2. Trace the bug's codepath, then write a regression test:**
|
||||
|
||||
Before writing the test, trace the data flow through the code you just fixed:
|
||||
- What input/state triggered the bug? (the exact precondition)
|
||||
- What codepath did it follow? (which branches, which function calls)
|
||||
- Where did it break? (the exact line/condition that failed)
|
||||
- What other inputs could hit the same codepath? (edge cases around the fix)
|
||||
|
||||
The test MUST:
|
||||
- Set up the precondition that triggered the bug (the exact state that made it break)
|
||||
- Perform the action that exposed the bug
|
||||
- Assert the correct behavior (NOT "it renders" or "it doesn't throw")
|
||||
- If you found adjacent edge cases while tracing, test those too (e.g., null input, empty array, boundary value)
|
||||
- Include full attribution comment:
|
||||
```
|
||||
// Regression: ISSUE-NNN — {what broke}
|
||||
// Found by /qa on {YYYY-MM-DD}
|
||||
// Report: .gstack/qa-reports/qa-report-{domain}-{date}.md
|
||||
```
|
||||
|
||||
Test type decision:
|
||||
- Console error / JS exception / logic bug → unit or integration test
|
||||
- Broken form / API failure / data flow bug → integration test with request/response
|
||||
- Visual bug with JS behavior (broken dropdown, animation) → component test
|
||||
- Pure CSS → skip (caught by QA reruns)
|
||||
|
||||
Generate unit tests. Mock all external dependencies (DB, API, Redis, file system).
|
||||
|
||||
Use auto-incrementing names to avoid collisions: check existing `{name}.regression-*.test.{ext}` files, take max number + 1.
|
||||
|
||||
**3. Run only the new test file:**
|
||||
|
||||
```bash
|
||||
{detected test command} {new-test-file}
|
||||
```
|
||||
|
||||
**4. Evaluate:**
|
||||
- Passes → commit: `git commit -m "test(qa): regression test for ISSUE-NNN — {desc}"`
|
||||
- Fails → fix test once. Still failing → delete test, defer.
|
||||
- Taking >2 min exploration → skip and defer.
|
||||
|
||||
**5. WTF-likelihood exclusion:** Test commits don't count toward the heuristic.
|
||||
|
||||
### 8f. Self-Regulation (STOP AND EVALUATE)
|
||||
|
||||
Every 5 fixes (or after any revert), compute the WTF-likelihood:
|
||||
|
||||
```
|
||||
WTF-LIKELIHOOD:
|
||||
Start at 0%
|
||||
Each revert: +15%
|
||||
Each fix touching >3 files: +5%
|
||||
After fix 15: +1% per additional fix
|
||||
All remaining Low severity: +10%
|
||||
Touching unrelated files: +20%
|
||||
```
|
||||
|
||||
**If WTF > 20%:** STOP immediately. Show the user what you've done so far. Ask whether to continue.
|
||||
|
||||
**Hard cap: 50 fixes.** After 50 fixes, stop regardless of remaining issues.
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Final QA
|
||||
|
||||
After all fixes are applied:
|
||||
|
||||
1. Re-run QA on all affected pages
|
||||
2. Compute final health score
|
||||
3. **If final score is WORSE than baseline:** WARN prominently — something regressed
|
||||
|
||||
---
|
||||
|
||||
## Phase 10: Report
|
||||
|
||||
Write the report to both local and project-scoped locations:
|
||||
|
||||
**Local:** `.gstack/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md`
|
||||
|
||||
**Project-scoped:** Write test outcome artifact for cross-session context:
|
||||
```bash
|
||||
eval "$(${GSTACK_OPENCODE_DIR}/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
||||
```
|
||||
Write to `~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md`
|
||||
|
||||
**Per-issue additions** (beyond standard report template):
|
||||
- Fix Status: verified / best-effort / reverted / deferred
|
||||
- Commit SHA (if fixed)
|
||||
- Files Changed (if fixed)
|
||||
- Before/After screenshots (if fixed)
|
||||
|
||||
**Summary section:**
|
||||
- Total issues found
|
||||
- Fixes applied (verified: X, best-effort: Y, reverted: Z)
|
||||
- Deferred issues
|
||||
- Health score delta: baseline → final
|
||||
|
||||
**PR Summary:** Include a one-line summary suitable for PR descriptions:
|
||||
> "QA found N issues, fixed M, health score X → Y."
|
||||
|
||||
---
|
||||
|
||||
## Phase 11: TODOS.md Update
|
||||
|
||||
If the repo has a `TODOS.md`:
|
||||
|
||||
1. **New deferred bugs** → add as TODOs with severity, category, and repro steps
|
||||
2. **Fixed bugs that were in TODOS.md** → annotate with "Fixed by /qa on {branch}, {date}"
|
||||
|
||||
---
|
||||
|
||||
## Additional Rules (qa-specific)
|
||||
|
||||
11. **Clean working tree required.** If dirty, use question to offer commit/stash/abort before proceeding.
|
||||
12. **One commit per fix.** Never bundle multiple fixes into one commit.
|
||||
13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files.
|
||||
14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately.
|
||||
15. **Self-regulate.** Follow the WTF-likelihood heuristic. When in doubt, stop and ask.
|
||||
|
|
@ -0,0 +1,811 @@
|
|||
---
|
||||
name: retro
|
||||
description: "Weekly engineering retrospective. Analyzes commit history, work patterns, and code quality metrics with persistent history and trend tracking. Team-aware: breaks down per-person contributions with pra"
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# /retro — Weekly Engineering Retrospective
|
||||
|
||||
Generates a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics. Team-aware: identifies the user running the command, then analyzes every contributor with per-person praise and growth opportunities. Designed for a senior IC/CTO-level builder using Claude Code as a force multiplier.
|
||||
|
||||
## User-invocable
|
||||
When the user types `/retro`, run this skill.
|
||||
|
||||
## Arguments
|
||||
- `/retro` — default: last 7 days
|
||||
- `/retro 24h` — last 24 hours
|
||||
- `/retro 14d` — last 14 days
|
||||
- `/retro 30d` — last 30 days
|
||||
- `/retro compare` — compare current window vs prior same-length window
|
||||
- `/retro compare 14d` — compare with explicit window
|
||||
- `/retro global` — cross-project retro across all AI coding tools (7d default)
|
||||
- `/retro global 14d` — cross-project retro with explicit window
|
||||
|
||||
## Instructions
|
||||
|
||||
Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`).
|
||||
|
||||
**Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since="2026-03-11T00:00:00"` for git log queries — the explicit `T00:00:00` suffix ensures git starts from midnight. Without it, git uses the current wall-clock time (e.g., `--since="2026-03-11"` at 11pm means 11pm, not midnight). For week units, multiply by 7 to get days (e.g., `2w` = 14 days back). For hour (`h`) units, use `--since="N hours ago"` since midnight alignment does not apply to sub-day windows.
|
||||
|
||||
**Argument validation:** If the argument doesn't match a number followed by `d`, `h`, or `w`, the word `compare` (optionally followed by a window), or the word `global` (optionally followed by a window), show this usage and stop:
|
||||
```
|
||||
Usage: /retro [window | compare | global]
|
||||
/retro — last 7 days (default)
|
||||
/retro 24h — last 24 hours
|
||||
/retro 14d — last 14 days
|
||||
/retro 30d — last 30 days
|
||||
/retro compare — compare this period vs prior period
|
||||
/retro compare 14d — compare with explicit window
|
||||
/retro global — cross-project retro across all AI tools (7d default)
|
||||
/retro global 14d — cross-project retro with explicit window
|
||||
```
|
||||
|
||||
**If the first argument is `global`:** Skip the normal repo-scoped retro (Steps 1-14). Instead, follow the **Global Retrospective** flow at the end of this document. The optional second argument is the time window (default 7d). This mode does NOT require being inside a git repo.
|
||||
|
||||
### Step 1: Gather Raw Data
|
||||
|
||||
First, fetch origin and identify the current user:
|
||||
```bash
|
||||
git fetch origin <default> --quiet
|
||||
# Identify who is running the retro
|
||||
git config user.name
|
||||
git config user.email
|
||||
```
|
||||
|
||||
The name returned by `git config user.name` is **"you"** — the person reading this retro. All other authors are teammates. Use this to orient the narrative: "your" commits vs teammate contributions.
|
||||
|
||||
Run ALL of these git commands in parallel (they are independent):
|
||||
|
||||
```bash
|
||||
# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
|
||||
git log origin/<default> --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
|
||||
|
||||
# 2. Per-commit test vs total LOC breakdown with author
|
||||
# Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
|
||||
# Separate test files (matching test/|spec/|__tests__/) from production files.
|
||||
git log origin/<default> --since="<window>" --format="COMMIT:%H|%aN" --numstat
|
||||
|
||||
# 3. Commit timestamps for session detection and hourly distribution (with author)
|
||||
git log origin/<default> --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
|
||||
|
||||
# 4. Files most frequently changed (hotspot analysis)
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
|
||||
|
||||
# 5. PR numbers from commit messages (extract #NNN patterns)
|
||||
git log origin/<default> --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'
|
||||
|
||||
# 6. Per-author file hotspots (who touches what)
|
||||
git log origin/<default> --since="<window>" --format="AUTHOR:%aN" --name-only
|
||||
|
||||
# 7. Per-author commit counts (quick summary)
|
||||
git shortlog origin/<default> --since="<window>" -sn --no-merges
|
||||
|
||||
# 8. Greptile triage history (if available)
|
||||
cat ~/.gstack/greptile-history.md 2>/dev/null || true
|
||||
|
||||
# 9. TODOS.md backlog (if available)
|
||||
cat TODOS.md 2>/dev/null || true
|
||||
|
||||
# 10. Test file count
|
||||
find . -name '*.test.*' -o -name '*.spec.*' -o -name '*_test.*' -o -name '*_spec.*' 2>/dev/null | grep -v node_modules | wc -l
|
||||
|
||||
# 11. Regression test commits in window
|
||||
git log origin/<default> --since="<window>" --oneline --grep="test(qa):" --grep="test(design):" --grep="test: coverage"
|
||||
|
||||
# 12. gstack skill usage telemetry (if available)
|
||||
cat ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
|
||||
# 12. Test files changed in window
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -E '\.(test|spec)\.' | sort -u | wc -l
|
||||
```
|
||||
|
||||
### Step 2: Compute Metrics
|
||||
|
||||
Calculate and present these metrics in a summary table:
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Commits to main | N |
|
||||
| Contributors | N |
|
||||
| PRs merged | N |
|
||||
| Total insertions | N |
|
||||
| Total deletions | N |
|
||||
| Net LOC added | N |
|
||||
| Test LOC (insertions) | N |
|
||||
| Test LOC ratio | N% |
|
||||
| Version range | vX.Y.Z.W → vX.Y.Z.W |
|
||||
| Active days | N |
|
||||
| Detected sessions | N |
|
||||
| Avg LOC/session-hour | N |
|
||||
| Greptile signal | N% (Y catches, Z FPs) |
|
||||
| Test Health | N total tests · M added this period · K regression tests |
|
||||
|
||||
Then show a **per-author leaderboard** immediately below:
|
||||
|
||||
```
|
||||
Contributor Commits +/- Top area
|
||||
You (garry) 32 +2400/-300 browse/
|
||||
alice 12 +800/-150 app/services/
|
||||
bob 3 +120/-40 tests/
|
||||
```
|
||||
|
||||
Sort by commits descending. The current user (from `git config user.name`) always appears first, labeled "You (name)".
|
||||
|
||||
**Greptile signal (if history exists):** Read `~/.gstack/greptile-history.md` (fetched in Step 1, command 8). Filter entries within the retro time window by date. Count entries by type: `fix`, `fp`, `already-fixed`. Compute signal ratio: `(fix + already-fixed) / (fix + already-fixed + fp)`. If no entries exist in the window or the file doesn't exist, skip the Greptile metric row. Skip unparseable lines silently.
|
||||
|
||||
**Backlog Health (if TODOS.md exists):** Read `TODOS.md` (fetched in Step 1, command 9). Compute:
|
||||
- Total open TODOs (exclude items in `## Completed` section)
|
||||
- P0/P1 count (critical/urgent items)
|
||||
- P2 count (important items)
|
||||
- Items completed this period (items in Completed section with dates within the retro window)
|
||||
- Items added this period (cross-reference git log for commits that modified TODOS.md within the window)
|
||||
|
||||
Include in the metrics table:
|
||||
```
|
||||
| Backlog Health | N open (X P0/P1, Y P2) · Z completed this period |
|
||||
```
|
||||
|
||||
If TODOS.md doesn't exist, skip the Backlog Health row.
|
||||
|
||||
**Skill Usage (if analytics exist):** Read `~/.gstack/analytics/skill-usage.jsonl` if it exists. Filter entries within the retro time window by `ts` field. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name. Present as:
|
||||
|
||||
```
|
||||
| Skill Usage | /ship(12) /qa(8) /review(5) · 3 safety hook fires |
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Skill Usage row.
|
||||
|
||||
**Eureka Moments (if logged):** Read `~/.gstack/analytics/eureka.jsonl` if it exists. Filter entries within the retro time window by `ts` field. For each eureka moment, show the skill that flagged it, the branch, and a one-line summary of the insight. Present as:
|
||||
|
||||
```
|
||||
| Eureka Moments | 2 this period |
|
||||
```
|
||||
|
||||
If moments exist, list them:
|
||||
```
|
||||
EUREKA /office-hours (branch: garrytan/auth-rethink): "Session tokens don't need server storage — browser crypto API makes client-side JWT validation viable"
|
||||
EUREKA /plan-eng-review (branch: garrytan/cache-layer): "Redis isn't needed here — Bun's built-in LRU cache handles this workload"
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Eureka Moments row.
|
||||
|
||||
### Step 3: Commit Time Distribution
|
||||
|
||||
Show hourly histogram in local time using bar chart:
|
||||
|
||||
```
|
||||
Hour Commits ████████████████
|
||||
00: 4 ████
|
||||
07: 5 █████
|
||||
...
|
||||
```
|
||||
|
||||
Identify and call out:
|
||||
- Peak hours
|
||||
- Dead zones
|
||||
- Whether pattern is bimodal (morning/evening) or continuous
|
||||
- Late-night coding clusters (after 10pm)
|
||||
|
||||
### Step 4: Work Session Detection
|
||||
|
||||
Detect sessions using **45-minute gap** threshold between consecutive commits. For each session report:
|
||||
- Start/end time (Pacific)
|
||||
- Number of commits
|
||||
- Duration in minutes
|
||||
|
||||
Classify sessions:
|
||||
- **Deep sessions** (50+ min)
|
||||
- **Medium sessions** (20-50 min)
|
||||
- **Micro sessions** (<20 min, typically single-commit fire-and-forget)
|
||||
|
||||
Calculate:
|
||||
- Total active coding time (sum of session durations)
|
||||
- Average session length
|
||||
- LOC per hour of active time
|
||||
|
||||
### Step 5: Commit Type Breakdown
|
||||
|
||||
Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
|
||||
|
||||
```
|
||||
feat: 20 (40%) ████████████████████
|
||||
fix: 27 (54%) ███████████████████████████
|
||||
refactor: 2 ( 4%) ██
|
||||
```
|
||||
|
||||
Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
|
||||
|
||||
### Step 6: Hotspot Analysis
|
||||
|
||||
Show top 10 most-changed files. Flag:
|
||||
- Files changed 5+ times (churn hotspots)
|
||||
- Test files vs production files in the hotspot list
|
||||
- VERSION/CHANGELOG frequency (version discipline indicator)
|
||||
|
||||
### Step 7: PR Size Distribution
|
||||
|
||||
From commit diffs, estimate PR sizes and bucket them:
|
||||
- **Small** (<100 LOC)
|
||||
- **Medium** (100-500 LOC)
|
||||
- **Large** (500-1500 LOC)
|
||||
- **XL** (1500+ LOC)
|
||||
|
||||
### Step 8: Focus Score + Ship of the Week
|
||||
|
||||
**Focus score:** Calculate the percentage of commits touching the single most-changed top-level directory (e.g., `app/services/`, `app/views/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
|
||||
|
||||
**Ship of the week:** Auto-identify the single highest-LOC PR in the window. Highlight it:
|
||||
- PR number and title
|
||||
- LOC changed
|
||||
- Why it matters (infer from commit messages and files touched)
|
||||
|
||||
### Step 9: Team Member Analysis
|
||||
|
||||
For each contributor (including the current user), compute:
|
||||
|
||||
1. **Commits and LOC** — total commits, insertions, deletions, net LOC
|
||||
2. **Areas of focus** — which directories/files they touched most (top 3)
|
||||
3. **Commit type mix** — their personal feat/fix/refactor/test breakdown
|
||||
4. **Session patterns** — when they code (their peak hours), session count
|
||||
5. **Test discipline** — their personal test LOC ratio
|
||||
6. **Biggest ship** — their single highest-impact commit or PR in the window
|
||||
|
||||
**For the current user ("You"):** This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
|
||||
|
||||
**For each teammate:** Write 2-3 sentences covering what they worked on and their pattern. Then:
|
||||
|
||||
- **Praise** (1-2 specific things): Anchor in actual commits. Not "great work" — say exactly what was good. Examples: "Shipped the entire auth middleware rewrite in 3 focused sessions with 45% test coverage", "Every PR under 200 LOC — disciplined decomposition."
|
||||
- **Opportunity for growth** (1 specific thing): Frame as a leveling-up suggestion, not criticism. Anchor in actual data. Examples: "Test ratio was 12% this week — adding test coverage to the payment module before it gets more complex would pay off", "5 fix commits on the same file suggest the original PR could have used a review pass."
|
||||
|
||||
**If only one contributor (solo repo):** Skip the team breakdown and proceed as before — the retro is personal.
|
||||
|
||||
**If there are Co-Authored-By trailers:** Parse `Co-Authored-By:` lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., `noreply@anthropic.com`) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
|
||||
|
||||
### Step 10: Week-over-Week Trends (if window >= 14d)
|
||||
|
||||
If the time window is 14 days or more, split into weekly buckets and show trends:
|
||||
- Commits per week (total and per-author)
|
||||
- LOC per week
|
||||
- Test ratio per week
|
||||
- Fix ratio per week
|
||||
- Session count per week
|
||||
|
||||
### Step 11: Streak Tracking
|
||||
|
||||
Count consecutive days with at least 1 commit to origin/<default>, going back from today. Track both team streak and personal streak:
|
||||
|
||||
```bash
|
||||
# Team streak: all unique commit dates (local time) — no hard cutoff
|
||||
git log origin/<default> --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
|
||||
# Personal streak: only the current user's commits
|
||||
git log origin/<default> --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
```
|
||||
|
||||
Count backward from today — how many consecutive days have at least one commit? This queries the full history so streaks of any length are reported accurately. Display both:
|
||||
- "Team shipping streak: 47 consecutive days"
|
||||
- "Your shipping streak: 32 consecutive days"
|
||||
|
||||
### Step 12: Load History & Compare
|
||||
|
||||
Before saving the new snapshot, check for prior retro history:
|
||||
|
||||
```bash
|
||||
ls -t .context/retros/*.json 2>/dev/null
|
||||
```
|
||||
|
||||
**If prior retros exist:** Load the most recent one using the Read tool. Calculate deltas for key metrics and include a **Trends vs Last Retro** section:
|
||||
```
|
||||
Last Now Delta
|
||||
Test ratio: 22% → 41% ↑19pp
|
||||
Sessions: 10 → 14 ↑4
|
||||
LOC/hour: 200 → 350 ↑75%
|
||||
Fix ratio: 54% → 30% ↓24pp (improving)
|
||||
Commits: 32 → 47 ↑47%
|
||||
Deep sessions: 3 → 5 ↑2
|
||||
```
|
||||
|
||||
**If no prior retros exist:** Skip the comparison section and append: "First retro recorded — run again next week to see trends."
|
||||
|
||||
### Step 13: Save Retro History
|
||||
|
||||
After computing all metrics (including streak) and loading any prior history for comparison, save a JSON snapshot:
|
||||
|
||||
```bash
|
||||
mkdir -p .context/retros
|
||||
```
|
||||
|
||||
Determine the next sequence number for today (substitute the actual date for `$(date +%Y-%m-%d)`):
|
||||
```bash
|
||||
# Count existing retros for today to get next sequence number
|
||||
today=$(date +%Y-%m-%d)
|
||||
existing=$(ls .context/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
|
||||
next=$((existing + 1))
|
||||
# Save as .context/retros/${today}-${next}.json
|
||||
```
|
||||
|
||||
Use the Write tool to save the JSON file with this schema:
|
||||
```json
|
||||
{
|
||||
"date": "2026-03-08",
|
||||
"window": "7d",
|
||||
"metrics": {
|
||||
"commits": 47,
|
||||
"contributors": 3,
|
||||
"prs_merged": 12,
|
||||
"insertions": 3200,
|
||||
"deletions": 800,
|
||||
"net_loc": 2400,
|
||||
"test_loc": 1300,
|
||||
"test_ratio": 0.41,
|
||||
"active_days": 6,
|
||||
"sessions": 14,
|
||||
"deep_sessions": 5,
|
||||
"avg_session_minutes": 42,
|
||||
"loc_per_session_hour": 350,
|
||||
"feat_pct": 0.40,
|
||||
"fix_pct": 0.30,
|
||||
"peak_hour": 22,
|
||||
"ai_assisted_commits": 32
|
||||
},
|
||||
"authors": {
|
||||
"Garry Tan": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "browse/" },
|
||||
"Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "app/services/" }
|
||||
},
|
||||
"version_range": ["1.16.0.0", "1.16.1.0"],
|
||||
"streak_days": 47,
|
||||
"tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
|
||||
"greptile": {
|
||||
"fixes": 3,
|
||||
"fps": 1,
|
||||
"already_fixed": 2,
|
||||
"signal_pct": 83
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (command 10 returns > 0). If any has no data, omit the field entirely.
|
||||
|
||||
Include test health data in the JSON when test files exist:
|
||||
```json
|
||||
"test_health": {
|
||||
"total_test_files": 47,
|
||||
"tests_added_this_period": 5,
|
||||
"regression_test_commits": 3,
|
||||
"test_files_changed": 8
|
||||
}
|
||||
```
|
||||
|
||||
Include backlog data in the JSON when TODOS.md exists:
|
||||
```json
|
||||
"backlog": {
|
||||
"total_open": 28,
|
||||
"p0_p1": 2,
|
||||
"p2": 8,
|
||||
"completed_this_period": 3,
|
||||
"added_this_period": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Step 14: Write the Narrative
|
||||
|
||||
Structure the output as:
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
|
||||
```
|
||||
|
||||
## Engineering Retro: [date range]
|
||||
|
||||
### Summary Table
|
||||
(from Step 2)
|
||||
|
||||
### Trends vs Last Retro
|
||||
(from Step 11, loaded before save — skip if first retro)
|
||||
|
||||
### Time & Session Patterns
|
||||
(from Steps 3-4)
|
||||
|
||||
Narrative interpreting what the team-wide patterns mean:
|
||||
- When the most productive hours are and what drives them
|
||||
- Whether sessions are getting longer or shorter over time
|
||||
- Estimated hours per day of active coding (team aggregate)
|
||||
- Notable patterns: do team members code at the same time or in shifts?
|
||||
|
||||
### Shipping Velocity
|
||||
(from Steps 5-7)
|
||||
|
||||
Narrative covering:
|
||||
- Commit type mix and what it reveals
|
||||
- PR size distribution and what it reveals about shipping cadence
|
||||
- Fix-chain detection (sequences of fix commits on the same subsystem)
|
||||
- Version bump discipline
|
||||
|
||||
### Code Quality Signals
|
||||
- Test LOC ratio trend
|
||||
- Hotspot analysis (are the same files churning?)
|
||||
- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
|
||||
|
||||
### Test Health
|
||||
- Total test files: N (from command 10)
|
||||
- Tests added this period: M (from command 12 — test files changed)
|
||||
- Regression test commits: list `test(qa):` and `test(design):` and `test: coverage` commits from command 11
|
||||
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
|
||||
- If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make vibe coding safe."
|
||||
|
||||
### Focus & Highlights
|
||||
(from Step 8)
|
||||
- Focus score with interpretation
|
||||
- Ship of the week callout
|
||||
|
||||
### Your Week (personal deep-dive)
|
||||
(from Step 9, for the current user only)
|
||||
|
||||
This is the section the user cares most about. Include:
|
||||
- Their personal commit count, LOC, test ratio
|
||||
- Their session patterns and peak hours
|
||||
- Their focus areas
|
||||
- Their biggest ship
|
||||
- **What you did well** (2-3 specific things anchored in commits)
|
||||
- **Where to level up** (1-2 specific, actionable suggestions)
|
||||
|
||||
### Team Breakdown
|
||||
(from Step 9, for each teammate — skip if solo repo)
|
||||
|
||||
For each teammate (sorted by commits descending), write a section:
|
||||
|
||||
#### [Name]
|
||||
- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
|
||||
- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
|
||||
- "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
|
||||
- "Added integration tests for every new endpoint, not just happy paths"
|
||||
- "Fixed the N+1 query that was causing 2s load times on the dashboard"
|
||||
- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
|
||||
- "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
|
||||
- "Most commits land in a single burst — spacing work across the day could reduce context-switching fatigue"
|
||||
- "All commits land between 1-4am — sustainable pace matters for code quality long-term"
|
||||
|
||||
**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
|
||||
|
||||
### Top 3 Team Wins
|
||||
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
|
||||
- What it was
|
||||
- Who shipped it
|
||||
- Why it matters (product/architecture impact)
|
||||
|
||||
### 3 Things to Improve
|
||||
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
|
||||
|
||||
### Week-over-Week Trends
|
||||
(if applicable, from Step 10)
|
||||
|
||||
---
|
||||
|
||||
## Global Retrospective Mode
|
||||
|
||||
When the user runs `/retro global` (or `/retro global 14d`), follow this flow instead of the repo-scoped Steps 1-14. This mode works from any directory — it does NOT require being inside a git repo.
|
||||
|
||||
### Global Step 1: Compute time window
|
||||
|
||||
Same midnight-aligned logic as the regular retro. Default 7d. The second argument after `global` is the window (e.g., `14d`, `30d`, `24h`).
|
||||
|
||||
### Global Step 2: Run discovery
|
||||
|
||||
Locate and run the discovery script using this fallback chain:
|
||||
|
||||
```bash
|
||||
DISCOVER_BIN=""
|
||||
[ -x ${GSTACK_OPENCODE_DIR}/bin/gstack-global-discover ] && DISCOVER_BIN=${GSTACK_OPENCODE_DIR}/bin/gstack-global-discover
|
||||
[ -z "$DISCOVER_BIN" ] && [ -x ${GSTACK_OPENCODE_DIR}/bin/gstack-global-discover ] && DISCOVER_BIN=${GSTACK_OPENCODE_DIR}/bin/gstack-global-discover
|
||||
[ -z "$DISCOVER_BIN" ] && which gstack-global-discover >/dev/null 2>&1 && DISCOVER_BIN=$(which gstack-global-discover)
|
||||
[ -z "$DISCOVER_BIN" ] && [ -f bin/gstack-global-discover.ts ] && DISCOVER_BIN="bun run bin/gstack-global-discover.ts"
|
||||
echo "DISCOVER_BIN: $DISCOVER_BIN"
|
||||
```
|
||||
|
||||
If no binary is found, tell the user: "Discovery script not found. Run `bun run build` in the gstack directory to compile it." and stop.
|
||||
|
||||
Run the discovery:
|
||||
```bash
|
||||
$DISCOVER_BIN --since "<window>" --format json 2>/tmp/gstack-discover-stderr
|
||||
```
|
||||
|
||||
Read the stderr output from `/tmp/gstack-discover-stderr` for diagnostic info. Parse the JSON output from stdout.
|
||||
|
||||
If `total_sessions` is 0, say: "No AI coding sessions found in the last <window>. Try a longer window: `/retro global 30d`" and stop.
|
||||
|
||||
### Global Step 3: Run git log on each discovered repo
|
||||
|
||||
For each repo in the discovery JSON's `repos` array, find the first valid path in `paths[]` (directory exists with `.git/`). If no valid path exists, skip the repo and note it.
|
||||
|
||||
**For local-only repos** (where `remote` starts with `local:`): skip `git fetch` and use the local default branch. Use `git log HEAD` instead of `git log origin/$DEFAULT`.
|
||||
|
||||
**For repos with remotes:**
|
||||
|
||||
```bash
|
||||
git -C <path> fetch origin --quiet 2>/dev/null
|
||||
```
|
||||
|
||||
Detect the default branch for each repo: first try `git symbolic-ref refs/remotes/origin/HEAD`, then check common branch names (`main`, `master`), then fall back to `git rev-parse --abbrev-ref HEAD`. Use the detected branch as `<default>` in the commands below.
|
||||
|
||||
```bash
|
||||
# Commits with stats
|
||||
git -C <path> log origin/$DEFAULT --since="<start_date>T00:00:00" --format="%H|%aN|%ai|%s" --shortstat
|
||||
|
||||
# Commit timestamps for session detection, streak, and context switching
|
||||
git -C <path> log origin/$DEFAULT --since="<start_date>T00:00:00" --format="%at|%aN|%ai|%s" | sort -n
|
||||
|
||||
# Per-author commit counts
|
||||
git -C <path> shortlog origin/$DEFAULT --since="<start_date>T00:00:00" -sn --no-merges
|
||||
|
||||
# PR numbers from commit messages
|
||||
git -C <path> log origin/$DEFAULT --since="<start_date>T00:00:00" --format="%s" | grep -oE '#[0-9]+' | sort -n | uniq
|
||||
```
|
||||
|
||||
For repos that fail (deleted paths, network errors): skip and note "N repos could not be reached."
|
||||
|
||||
### Global Step 4: Compute global shipping streak
|
||||
|
||||
For each repo, get commit dates (capped at 365 days):
|
||||
|
||||
```bash
|
||||
git -C <path> log origin/$DEFAULT --since="365 days ago" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
```
|
||||
|
||||
Union all dates across all repos. Count backward from today — how many consecutive days have at least one commit to ANY repo? If the streak hits 365 days, display as "365+ days".
|
||||
|
||||
### Global Step 5: Compute context switching metric
|
||||
|
||||
From the commit timestamps gathered in Step 3, group by date. For each date, count how many distinct repos had commits that day. Report:
|
||||
- Average repos/day
|
||||
- Maximum repos/day
|
||||
- Which days were focused (1 repo) vs. fragmented (3+ repos)
|
||||
|
||||
### Global Step 6: Per-tool productivity patterns
|
||||
|
||||
From the discovery JSON, analyze tool usage patterns:
|
||||
- Which AI tool is used for which repos (exclusive vs. shared)
|
||||
- Session count per tool
|
||||
- Behavioral patterns (e.g., "Codex used exclusively for myapp, Claude Code for everything else")
|
||||
|
||||
### Global Step 7: Aggregate and generate narrative
|
||||
|
||||
Structure the output with the **shareable personal card first**, then the full
|
||||
team/project breakdown below. The personal card is designed to be screenshot-friendly
|
||||
— everything someone would want to share on X/Twitter in one clean block.
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 14: 5 projects, 138 commits, 250k LOC across 5 repos | 48 AI sessions | Streak: 52d 🔥
|
||||
```
|
||||
|
||||
## 🚀 Your Week: [user name] — [date range]
|
||||
|
||||
This section is the **shareable personal card**. It contains ONLY the current user's
|
||||
stats — no team data, no project breakdowns. Designed to screenshot and post.
|
||||
|
||||
Use the user identity from `git config user.name` to filter all per-repo git data.
|
||||
Aggregate across all repos to compute personal totals.
|
||||
|
||||
Render as a single visually clean block. Left border only — no right border (LLMs
|
||||
can't align right borders reliably). Pad repo names to the longest name so columns
|
||||
align cleanly. Never truncate project names.
|
||||
|
||||
```
|
||||
╔═══════════════════════════════════════════════════════════════
|
||||
║ [USER NAME] — Week of [date]
|
||||
╠═══════════════════════════════════════════════════════════════
|
||||
║
|
||||
║ [N] commits across [M] projects
|
||||
║ +[X]k LOC added · [Y]k LOC deleted · [Z]k net
|
||||
║ [N] AI coding sessions (CC: X, Codex: Y, Gemini: Z)
|
||||
║ [N]-day shipping streak 🔥
|
||||
║
|
||||
║ PROJECTS
|
||||
║ ─────────────────────────────────────────────────────────
|
||||
║ [repo_name_full] [N] commits +[X]k LOC [solo/team]
|
||||
║ [repo_name_full] [N] commits +[X]k LOC [solo/team]
|
||||
║ [repo_name_full] [N] commits +[X]k LOC [solo/team]
|
||||
║
|
||||
║ SHIP OF THE WEEK
|
||||
║ [PR title] — [LOC] lines across [N] files
|
||||
║
|
||||
║ TOP WORK
|
||||
║ • [1-line description of biggest theme]
|
||||
║ • [1-line description of second theme]
|
||||
║ • [1-line description of third theme]
|
||||
║
|
||||
║ Powered by gstack · github.com/garrytan/gstack
|
||||
╚═══════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
**Rules for the personal card:**
|
||||
- Only show repos where the user has commits. Skip repos with 0 commits.
|
||||
- Sort repos by user's commit count descending.
|
||||
- **Never truncate repo names.** Use the full repo name (e.g., `analyze_transcripts`
|
||||
not `analyze_trans`). Pad the name column to the longest repo name so all columns
|
||||
align. If names are long, widen the box — the box width adapts to content.
|
||||
- For LOC, use "k" formatting for thousands (e.g., "+64.0k" not "+64010").
|
||||
- Role: "solo" if user is the only contributor, "team" if others contributed.
|
||||
- Ship of the Week: the user's single highest-LOC PR across ALL repos.
|
||||
- Top Work: 3 bullet points summarizing the user's major themes, inferred from
|
||||
commit messages. Not individual commits — synthesize into themes.
|
||||
E.g., "Built /retro global — cross-project retrospective with AI session discovery"
|
||||
not "feat: gstack-global-discover" + "feat: /retro global template".
|
||||
- The card must be self-contained. Someone seeing ONLY this block should understand
|
||||
the user's week without any surrounding context.
|
||||
- Do NOT include team members, project totals, or context switching data here.
|
||||
|
||||
**Personal streak:** Use the user's own commits across all repos (filtered by
|
||||
`--author`) to compute a personal streak, separate from the team streak.
|
||||
|
||||
---
|
||||
|
||||
## Global Engineering Retro: [date range]
|
||||
|
||||
Everything below is the full analysis — team data, project breakdowns, patterns.
|
||||
This is the "deep dive" that follows the shareable card.
|
||||
|
||||
### All Projects Overview
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Projects active | N |
|
||||
| Total commits (all repos, all contributors) | N |
|
||||
| Total LOC | +N / -N |
|
||||
| AI coding sessions | N (CC: X, Codex: Y, Gemini: Z) |
|
||||
| Active days | N |
|
||||
| Global shipping streak (any contributor, any repo) | N consecutive days |
|
||||
| Context switches/day | N avg (max: M) |
|
||||
|
||||
### Per-Project Breakdown
|
||||
For each repo (sorted by commits descending):
|
||||
- Repo name (with % of total commits)
|
||||
- Commits, LOC, PRs merged, top contributor
|
||||
- Key work (inferred from commit messages)
|
||||
- AI sessions by tool
|
||||
|
||||
**Your Contributions** (sub-section within each project):
|
||||
For each project, add a "Your contributions" block showing the current user's
|
||||
personal stats within that repo. Use the user identity from `git config user.name`
|
||||
to filter. Include:
|
||||
- Your commits / total commits (with %)
|
||||
- Your LOC (+insertions / -deletions)
|
||||
- Your key work (inferred from YOUR commit messages only)
|
||||
- Your commit type mix (feat/fix/refactor/chore/docs breakdown)
|
||||
- Your biggest ship in this repo (highest-LOC commit or PR)
|
||||
|
||||
If the user is the only contributor, say "Solo project — all commits are yours."
|
||||
If the user has 0 commits in a repo (team project they didn't touch this period),
|
||||
say "No commits this period — [N] AI sessions only." and skip the breakdown.
|
||||
|
||||
Format:
|
||||
```
|
||||
**Your contributions:** 47/244 commits (19%), +4.2k/-0.3k LOC
|
||||
Key work: Writer Chat, email blocking, security hardening
|
||||
Biggest ship: PR #605 — Writer Chat eats the admin bar (2,457 ins, 46 files)
|
||||
Mix: feat(3) fix(2) chore(1)
|
||||
```
|
||||
|
||||
### Cross-Project Patterns
|
||||
- Time allocation across projects (% breakdown, use YOUR commits not total)
|
||||
- Peak productivity hours aggregated across all repos
|
||||
- Focused vs. fragmented days
|
||||
- Context switching trends
|
||||
|
||||
### Tool Usage Analysis
|
||||
Per-tool breakdown with behavioral patterns:
|
||||
- Claude Code: N sessions across M repos — patterns observed
|
||||
- Codex: N sessions across M repos — patterns observed
|
||||
- Gemini: N sessions across M repos — patterns observed
|
||||
|
||||
### Ship of the Week (Global)
|
||||
Highest-impact PR across ALL projects. Identify by LOC and commit messages.
|
||||
|
||||
### 3 Cross-Project Insights
|
||||
What the global view reveals that no single-repo retro could show.
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Considering the full cross-project picture.
|
||||
|
||||
---
|
||||
|
||||
### Global Step 8: Load history & compare
|
||||
|
||||
```bash
|
||||
ls -t ~/.gstack/retros/global-*.json 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
**Only compare against a prior retro with the same `window` value** (e.g., 7d vs 7d). If the most recent prior retro has a different window, skip comparison and note: "Prior global retro used a different window — skipping comparison."
|
||||
|
||||
If a matching prior retro exists, load it with the Read tool. Show a **Trends vs Last Global Retro** table with deltas for key metrics: total commits, LOC, sessions, streak, context switches/day.
|
||||
|
||||
If no prior global retros exist, append: "First global retro recorded — run again next week to see trends."
|
||||
|
||||
### Global Step 9: Save snapshot
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.gstack/retros
|
||||
```
|
||||
|
||||
Determine the next sequence number for today:
|
||||
```bash
|
||||
today=$(date +%Y-%m-%d)
|
||||
existing=$(ls ~/.gstack/retros/global-${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
|
||||
next=$((existing + 1))
|
||||
```
|
||||
|
||||
Use the Write tool to save JSON to `~/.gstack/retros/global-${today}-${next}.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "global",
|
||||
"date": "2026-03-21",
|
||||
"window": "7d",
|
||||
"projects": [
|
||||
{
|
||||
"name": "gstack",
|
||||
"remote": "https://github.com/garrytan/gstack",
|
||||
"commits": 47,
|
||||
"insertions": 3200,
|
||||
"deletions": 800,
|
||||
"sessions": { "claude_code": 15, "codex": 3, "gemini": 0 }
|
||||
}
|
||||
],
|
||||
"totals": {
|
||||
"commits": 182,
|
||||
"insertions": 15300,
|
||||
"deletions": 4200,
|
||||
"projects": 5,
|
||||
"active_days": 6,
|
||||
"sessions": { "claude_code": 48, "codex": 8, "gemini": 3 },
|
||||
"global_streak_days": 52,
|
||||
"avg_context_switches_per_day": 2.1
|
||||
},
|
||||
"tweetable": "Week of Mar 14: 5 projects, 182 commits, 15.3k LOC | CC: 48, Codex: 8, Gemini: 3 | Focus: gstack (58%) | Streak: 52d"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compare Mode
|
||||
|
||||
When the user runs `/retro compare` (or `/retro compare 14d`):
|
||||
|
||||
1. Compute metrics for the current window (default 7d) using the midnight-aligned start date (same logic as the main retro — e.g., if today is 2026-03-18 and window is 7d, use `--since="2026-03-11T00:00:00"`)
|
||||
2. Compute metrics for the immediately prior same-length window using both `--since` and `--until` with midnight-aligned dates to avoid overlap (e.g., for a 7d window starting 2026-03-11: prior window is `--since="2026-03-04T00:00:00" --until="2026-03-11T00:00:00"`)
|
||||
3. Show a side-by-side comparison table with deltas and arrows
|
||||
4. Write a brief narrative highlighting the biggest improvements and regressions
|
||||
5. Save only the current-window snapshot to `.context/retros/` (same as a normal retro run); do **not** persist the prior-window metrics.
|
||||
|
||||
## Tone
|
||||
|
||||
- Encouraging but candid, no coddling
|
||||
- Specific and concrete — always anchor in actual commits/code
|
||||
- Skip generic praise ("great job!") — say exactly what was good and why
|
||||
- Frame improvements as leveling up, not criticism
|
||||
- **Praise should feel like something you'd actually say in a 1:1** — specific, earned, genuine
|
||||
- **Growth suggestions should feel like investment advice** — "this is worth your time because..." not "you failed at..."
|
||||
- Never compare teammates against each other negatively. Each person's section stands on its own.
|
||||
- Keep total output around 3000-4500 words (slightly longer to accommodate team sections)
|
||||
- Use markdown tables and code blocks for data, prose for narrative
|
||||
- Output directly to the conversation — do NOT write to filesystem (except the `.context/retros/` JSON snapshot)
|
||||
|
||||
## Important Rules
|
||||
|
||||
- ALL narrative output goes directly to the user in the conversation. The ONLY file written is the `.context/retros/` JSON snapshot.
|
||||
- Use `origin/<default>` for all git queries (not local main which may be stale)
|
||||
- Display all timestamps in the user's local timezone (do not override `TZ`)
|
||||
- If the window has zero commits, say so and suggest a different window
|
||||
- Round LOC/hour to nearest 50
|
||||
- Treat merge commits as PR boundaries
|
||||
- Do not read CLAUDE.md or other docs — this skill is self-contained
|
||||
- On first run (no prior retros), skip comparison sections gracefully
|
||||
- **Global mode:** Does NOT require being inside a git repo. Saves snapshots to `~/.gstack/retros/` (not `.context/retros/`). Gracefully skip AI tools that aren't installed. Only compare against prior global retros with the same window value. If streak hits 365d cap, display as "365+ days".
|
||||
|
|
@ -0,0 +1,598 @@
|
|||
---
|
||||
name: review
|
||||
description: "Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust boundary violations, conditional side effects, and other structural issues. Use when asked to "review this PR", ""
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
# Pre-Landing PR Review
|
||||
|
||||
You are running the `/review` workflow. Analyze the current branch's diff against the base branch for structural issues that tests don't catch.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Check branch
|
||||
|
||||
1. Run `git branch --show-current` to get the current branch.
|
||||
2. If on the base branch, output: **"Nothing to review — you're on the base branch or have no changes against it."** and stop.
|
||||
3. Run `git fetch origin <base> --quiet && git diff origin/<base> --stat` to check if there's a diff. If no diff, output the same message and stop.
|
||||
|
||||
---
|
||||
|
||||
## Step 1.5: Scope Drift Detection
|
||||
|
||||
Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?**
|
||||
|
||||
1. Read `TODOS.md` (if it exists). Read PR description (`gh pr view --json body --jq .body 2>/dev/null || true`).
|
||||
Read commit messages (`git log origin/<base>..HEAD --oneline`).
|
||||
**If no PR exists:** rely on commit messages and TODOS.md for stated intent — this is the common case since /review runs before /ship creates the PR.
|
||||
2. Identify the **stated intent** — what was this branch supposed to accomplish?
|
||||
3. Run `git diff origin/<base> --stat` and compare the files changed against the stated intent.
|
||||
4. Evaluate with skepticism:
|
||||
|
||||
**SCOPE CREEP detection:**
|
||||
- Files changed that are unrelated to the stated intent
|
||||
- New features or refactors not mentioned in the plan
|
||||
- "While I was in there..." changes that expand blast radius
|
||||
|
||||
**MISSING REQUIREMENTS detection:**
|
||||
- Requirements from TODOS.md/PR description not addressed in the diff
|
||||
- Test coverage gaps for stated requirements
|
||||
- Partial implementations (started but not finished)
|
||||
|
||||
5. Output (before the main review begins):
|
||||
```
|
||||
Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING]
|
||||
Intent: <1-line summary of what was requested>
|
||||
Delivered: <1-line summary of what the diff actually does>
|
||||
[If drift: list each out-of-scope change]
|
||||
[If missing: list each unaddressed requirement]
|
||||
```
|
||||
|
||||
6. This is **INFORMATIONAL** — does not block the review. Proceed to Step 2.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Read the checklist
|
||||
|
||||
Read `.claude/skills/review/checklist.md`.
|
||||
|
||||
**If the file cannot be read, STOP and report the error.** Do not proceed without the checklist.
|
||||
|
||||
---
|
||||
|
||||
## Step 2.5: Check for Greptile review comments
|
||||
|
||||
Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, classify, and **escalation detection** steps.
|
||||
|
||||
**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
|
||||
|
||||
**If Greptile comments are found:** Store the classifications (VALID & ACTIONABLE, VALID BUT ALREADY FIXED, FALSE POSITIVE, SUPPRESSED) — you will need them in Step 5.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Get the diff
|
||||
|
||||
Fetch the latest base branch to avoid false positives from stale local state:
|
||||
|
||||
```bash
|
||||
git fetch origin <base> --quiet
|
||||
```
|
||||
|
||||
Run `git diff origin/<base>` to get the full diff. This includes both committed and uncommitted changes against the latest base branch.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Two-pass review
|
||||
|
||||
Apply the checklist against the diff in two passes:
|
||||
|
||||
1. **Pass 1 (CRITICAL):** SQL & Data Safety, Race Conditions & Concurrency, LLM Output Trust Boundary, Enum & Value Completeness
|
||||
2. **Pass 2 (INFORMATIONAL):** Conditional Side Effects, Magic Numbers & String Coupling, Dead Code & Consistency, LLM Prompt Issues, Test Gaps, View/Frontend, Performance & Bundle Impact
|
||||
|
||||
**Enum & Value Completeness requires reading code OUTSIDE the diff.** When the diff introduces a new enum value, status, tier, or type constant, use Grep to find all files that reference sibling values, then Read those files to check if the new value is handled. This is the one category where within-diff review is insufficient.
|
||||
|
||||
**Search-before-recommending:** When recommending a fix pattern (especially for concurrency, caching, auth, or framework-specific behavior):
|
||||
- Verify the pattern is current best practice for the framework version in use
|
||||
- Check if a built-in solution exists in newer versions before recommending a workaround
|
||||
- Verify API signatures against current docs (APIs change between versions)
|
||||
|
||||
Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge.
|
||||
|
||||
Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.
|
||||
|
||||
---
|
||||
|
||||
## Step 4.5: Design Review (conditional)
|
||||
|
||||
## Design Review (conditional, diff-scoped)
|
||||
|
||||
Check if the diff touches frontend files using `gstack-diff-scope`:
|
||||
|
||||
```bash
|
||||
source <(${GSTACK_OPENCODE_DIR}/bin/gstack-diff-scope <base> 2>/dev/null)
|
||||
```
|
||||
|
||||
**If `SCOPE_FRONTEND=false`:** Skip design review silently. No output.
|
||||
|
||||
**If `SCOPE_FRONTEND=true`:**
|
||||
|
||||
1. **Check for DESIGN.md.** If `DESIGN.md` or `design-system.md` exists in the repo root, read it. All design findings are calibrated against it — patterns blessed in DESIGN.md are not flagged. If not found, use universal design principles.
|
||||
|
||||
2. **Read `.claude/skills/review/design-checklist.md`.** If the file cannot be read, skip design review with a note: "Design checklist not found — skipping design review."
|
||||
|
||||
3. **Read each changed frontend file** (full file, not just diff hunks). Frontend files are identified by the patterns listed in the checklist.
|
||||
|
||||
4. **Apply the design checklist** against the changed files. For each item:
|
||||
- **[HIGH] mechanical CSS fix** (`outline: none`, `!important`, `font-size < 16px`): classify as AUTO-FIX
|
||||
- **[HIGH/MEDIUM] design judgment needed**: classify as ASK
|
||||
- **[LOW] intent-based detection**: present as "Possible — verify visually or run /design-review"
|
||||
|
||||
5. **Include findings** in the review output under a "Design Review" header, following the output format in the checklist. Design findings merge with code review findings into the same Fix-First flow.
|
||||
|
||||
6. **Log the result** for the Review Readiness Dashboard:
|
||||
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"design-review-lite","timestamp":"TIMESTAMP","status":"STATUS","findings":N,"auto_fixed":M,"commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Substitute: TIMESTAMP = ISO 8601 datetime, STATUS = "clean" if 0 findings or "issues_found", N = total findings, M = auto-fixed count, COMMIT = output of `git rev-parse --short HEAD`.
|
||||
|
||||
7. **Codex design voice** (optional, automatic if available):
|
||||
|
||||
```bash
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
```
|
||||
|
||||
If Codex is available, run a lightweight design check on the diff:
|
||||
|
||||
```bash
|
||||
TMPERR_DRL=$(mktemp /tmp/codex-drl-XXXXXXXX)
|
||||
codex exec "Review the git diff on this branch. Run 7 litmus checks (YES/NO each): 1. Brand/product unmistakable in first screen? 2. One strong visual anchor present? 3. Page understandable by scanning headlines only? 4. Each section has one job? 5. Are cards actually necessary? 6. Does motion improve hierarchy or atmosphere? 7. Would design feel premium with all decorative shadows removed? Flag any hard rejections: 1. Generic SaaS card grid as first impression 2. Beautiful image with weak brand 3. Strong headline with no clear action 4. Busy imagery behind text 5. Sections repeating same mood statement 6. Carousel with no narrative purpose 7. App UI made of stacked cards instead of layout 5 most important design findings only. Reference file:line." -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached 2>"$TMPERR_DRL"
|
||||
```
|
||||
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_DRL" && rm -f "$TMPERR_DRL"
|
||||
```
|
||||
|
||||
**Error handling:** All errors are non-blocking. On auth failure, timeout, or empty response — skip with a brief note and continue.
|
||||
|
||||
Present Codex output under a `CODEX (design):` header, merged with the checklist findings above.
|
||||
|
||||
Include any design findings alongside the findings from Step 4. They follow the same Fix-First flow in Step 5 — AUTO-FIX for mechanical CSS fixes, ASK for everything else.
|
||||
|
||||
---
|
||||
|
||||
## Step 4.75: Test Coverage Diagram
|
||||
|
||||
100% coverage is the goal. Evaluate every codepath changed in the diff and identify test gaps. Gaps become INFORMATIONAL findings that follow the Fix-First flow.
|
||||
|
||||
### Test Framework Detection
|
||||
|
||||
Before analyzing coverage, detect the project's test framework:
|
||||
|
||||
1. **Read CLAUDE.md** — look for a `## Testing` section with test command and framework name. If found, use that as the authoritative source.
|
||||
2. **If CLAUDE.md has no testing section, auto-detect:**
|
||||
|
||||
```bash
|
||||
# Detect project runtime
|
||||
[ -f Gemfile ] && echo "RUNTIME:ruby"
|
||||
[ -f package.json ] && echo "RUNTIME:node"
|
||||
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
|
||||
[ -f go.mod ] && echo "RUNTIME:go"
|
||||
[ -f Cargo.toml ] && echo "RUNTIME:rust"
|
||||
# Check for existing test infrastructure
|
||||
ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
|
||||
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
|
||||
```
|
||||
|
||||
3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
|
||||
|
||||
**Step 1. Trace every codepath changed** using `git diff origin/<base>...HEAD`:
|
||||
|
||||
Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:
|
||||
|
||||
1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.
|
||||
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
|
||||
- Where does input come from? (request params, props, database, API call)
|
||||
- What transforms it? (validation, mapping, computation)
|
||||
- Where does it go? (database write, API response, rendered output, side effect)
|
||||
- What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
|
||||
3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
|
||||
- Every function/method that was added or modified
|
||||
- Every conditional branch (if/else, switch, ternary, guard clause, early return)
|
||||
- Every error path (try/catch, rescue, error boundary, fallback)
|
||||
- Every call to another function (trace into it — does IT have untested branches?)
|
||||
- Every edge: what happens with null input? Empty array? Invalid type?
|
||||
|
||||
This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.
|
||||
|
||||
**Step 2. Map user flows, interactions, and error states:**
|
||||
|
||||
Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
|
||||
|
||||
- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
|
||||
- **Interaction edge cases:** What happens when the user does something unexpected?
|
||||
- Double-click/rapid resubmit
|
||||
- Navigate away mid-operation (back button, close tab, click another link)
|
||||
- Submit with stale data (page sat open for 30 minutes, session expired)
|
||||
- Slow connection (API takes 10 seconds — what does the user see?)
|
||||
- Concurrent actions (two tabs, same form)
|
||||
- **Error states the user can see:** For every error the code handles, what does the user actually experience?
|
||||
- Is there a clear error message or a silent failure?
|
||||
- Can the user recover (retry, go back, fix input) or are they stuck?
|
||||
- What happens with no network? With a 500 from the API? With invalid data from the server?
|
||||
- **Empty/zero/boundary states:** What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?
|
||||
|
||||
Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.
|
||||
|
||||
**Step 3. Check each branch against existing tests:**
|
||||
|
||||
Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:
|
||||
- Function `processPayment()` → look for `billing.test.ts`, `billing.spec.ts`, `test/billing_test.rb`
|
||||
- An if/else → look for tests covering BOTH the true AND false path
|
||||
- An error handler → look for a test that triggers that specific error condition
|
||||
- A call to `helperFn()` that has its own branches → those branches need tests too
|
||||
- A user flow → look for an integration or E2E test that walks through the journey
|
||||
- An interaction edge case → look for a test that simulates the unexpected action
|
||||
|
||||
Quality scoring rubric:
|
||||
- ★★★ Tests behavior with edge cases AND error paths
|
||||
- ★★ Tests correct behavior, happy path only
|
||||
- ★ Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")
|
||||
|
||||
### E2E Test Decision Matrix
|
||||
|
||||
When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:
|
||||
|
||||
**RECOMMEND E2E (mark as [→E2E] in the diagram):**
|
||||
- Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
|
||||
- Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
|
||||
- Auth/payment/data-destruction flows — too important to trust unit tests alone
|
||||
|
||||
**RECOMMEND EVAL (mark as [→EVAL] in the diagram):**
|
||||
- Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
|
||||
- Changes to prompt templates, system instructions, or tool definitions
|
||||
|
||||
**STICK WITH UNIT TESTS:**
|
||||
- Pure function with clear inputs/outputs
|
||||
- Internal helper with no side effects
|
||||
- Edge case of a single function (null input, empty array)
|
||||
- Obscure/rare flow that isn't customer-facing
|
||||
|
||||
### REGRESSION RULE (mandatory)
|
||||
|
||||
**IRON RULE:** When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is written immediately. No question. No skipping. Regressions are the highest-priority test because they prove something broke.
|
||||
|
||||
A regression is when:
|
||||
- The diff modifies existing behavior (not new code)
|
||||
- The existing test suite (if any) doesn't cover the changed path
|
||||
- The change introduces a new failure mode for existing callers
|
||||
|
||||
When uncertain whether a change is a regression, err on the side of writing the test.
|
||||
|
||||
Format: commit as `test: regression test for {what broke}`
|
||||
|
||||
**Step 4. Output ASCII coverage diagram:**
|
||||
|
||||
Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:
|
||||
|
||||
```
|
||||
CODE PATH COVERAGE
|
||||
===========================
|
||||
[+] src/services/billing.ts
|
||||
│
|
||||
├── processPayment()
|
||||
│ ├── [★★★ TESTED] Happy path + card declined + timeout — billing.test.ts:42
|
||||
│ ├── [GAP] Network timeout — NO TEST
|
||||
│ └── [GAP] Invalid currency — NO TEST
|
||||
│
|
||||
└── refundPayment()
|
||||
├── [★★ TESTED] Full refund — billing.test.ts:89
|
||||
└── [★ TESTED] Partial refund (checks non-throw only) — billing.test.ts:101
|
||||
|
||||
USER FLOW COVERAGE
|
||||
===========================
|
||||
[+] Payment checkout flow
|
||||
│
|
||||
├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
|
||||
├── [GAP] [→E2E] Double-click submit — needs E2E, not just unit
|
||||
├── [GAP] Navigate away during payment — unit test sufficient
|
||||
└── [★ TESTED] Form validation errors (checks render only) — checkout.test.ts:40
|
||||
|
||||
[+] Error states
|
||||
│
|
||||
├── [★★ TESTED] Card declined message — billing.test.ts:58
|
||||
├── [GAP] Network timeout UX (what does user see?) — NO TEST
|
||||
└── [GAP] Empty cart submission — NO TEST
|
||||
|
||||
[+] LLM integration
|
||||
│
|
||||
└── [GAP] [→EVAL] Prompt template change — needs eval test
|
||||
|
||||
─────────────────────────────────
|
||||
COVERAGE: 5/13 paths tested (38%)
|
||||
Code paths: 3/5 (60%)
|
||||
User flows: 2/8 (25%)
|
||||
QUALITY: ★★★: 2 ★★: 2 ★: 1
|
||||
GAPS: 8 paths need tests (2 need E2E, 1 needs eval)
|
||||
─────────────────────────────────
|
||||
```
|
||||
|
||||
**Fast path:** All paths covered → "Step 4.75: All new code paths have test coverage ✓" Continue.
|
||||
|
||||
**Step 5. Generate tests for gaps (Fix-First):**
|
||||
|
||||
If test framework is detected and gaps were identified:
|
||||
- Classify each gap as AUTO-FIX or ASK per the Fix-First Heuristic:
|
||||
- **AUTO-FIX:** Simple unit tests for pure functions, edge cases of existing tested functions
|
||||
- **ASK:** E2E tests, tests requiring new test infrastructure, tests for ambiguous behavior
|
||||
- For AUTO-FIX gaps: generate the test, run it, commit as `test: coverage for {feature}`
|
||||
- For ASK gaps: include in the Fix-First batch question with the other review findings
|
||||
- For paths marked [→E2E]: always ASK (E2E tests are higher-effort and need user confirmation)
|
||||
- For paths marked [→EVAL]: always ASK (eval tests need user confirmation on quality criteria)
|
||||
|
||||
If no test framework detected → include gaps as INFORMATIONAL findings only, no generation.
|
||||
|
||||
**Diff is test-only changes:** Skip Step 4.75 entirely: "No new application code paths to audit."
|
||||
|
||||
This step subsumes the "Test Gaps" category from Pass 2 — do not duplicate findings between the checklist Test Gaps item and this coverage diagram. Include any coverage gaps alongside the findings from Step 4 and Step 4.5. They follow the same Fix-First flow — gaps are INFORMATIONAL findings.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Fix-First Review
|
||||
|
||||
**Every finding gets action — not just critical ones.**
|
||||
|
||||
Output a summary header: `Pre-Landing Review: N issues (X critical, Y informational)`
|
||||
|
||||
### Step 5a: Classify each finding
|
||||
|
||||
For each finding, classify as AUTO-FIX or ASK per the Fix-First Heuristic in
|
||||
checklist.md. Critical findings lean toward ASK; informational findings lean
|
||||
toward AUTO-FIX.
|
||||
|
||||
### Step 5b: Auto-fix all AUTO-FIX items
|
||||
|
||||
Apply each fix directly. For each one, output a one-line summary:
|
||||
`[AUTO-FIXED] [file:line] Problem → what you did`
|
||||
|
||||
### Step 5c: Batch-ask about ASK items
|
||||
|
||||
If there are ASK items remaining, present them in ONE question:
|
||||
|
||||
- List each item with a number, the severity label, the problem, and a recommended fix
|
||||
- For each item, provide options: A) Fix as recommended, B) Skip
|
||||
- Include an overall RECOMMENDATION
|
||||
|
||||
Example format:
|
||||
```
|
||||
I auto-fixed 5 issues. 2 need your input:
|
||||
|
||||
1. [CRITICAL] app/models/post.rb:42 — Race condition in status transition
|
||||
Fix: Add `WHERE status = 'draft'` to the UPDATE
|
||||
→ A) Fix B) Skip
|
||||
|
||||
2. [INFORMATIONAL] app/services/generator.rb:88 — LLM output not type-checked before DB write
|
||||
Fix: Add JSON schema validation
|
||||
→ A) Fix B) Skip
|
||||
|
||||
RECOMMENDATION: Fix both — #1 is a real race condition, #2 prevents silent data corruption.
|
||||
```
|
||||
|
||||
If 3 or fewer ASK items, you may use individual question calls instead of batching.
|
||||
|
||||
### Step 5d: Apply user-approved fixes
|
||||
|
||||
Apply fixes for items where the user chose "Fix." Output what was fixed.
|
||||
|
||||
If no ASK items exist (everything was AUTO-FIX), skip the question entirely.
|
||||
|
||||
### Verification of claims
|
||||
|
||||
Before producing the final review output:
|
||||
- If you claim "this pattern is safe" → cite the specific line proving safety
|
||||
- If you claim "this is handled elsewhere" → read and cite the handling code
|
||||
- If you claim "tests cover this" → name the test file and method
|
||||
- Never say "likely handled" or "probably tested" — verify or flag as unknown
|
||||
|
||||
**Rationalization prevention:** "This looks fine" is not a finding. Either cite evidence it IS fine, or flag it as unverified.
|
||||
|
||||
### Greptile comment resolution
|
||||
|
||||
After outputting your own findings, if Greptile comments were classified in Step 2.5:
|
||||
|
||||
**Include a Greptile summary in your output header:** `+ N Greptile comments (X valid, Y fixed, Z FP)`
|
||||
|
||||
Before replying to any comment, run the **Escalation Detection** algorithm from greptile-triage.md to determine whether to use Tier 1 (friendly) or Tier 2 (firm) reply templates.
|
||||
|
||||
1. **VALID & ACTIONABLE comments:** These are included in your findings — they follow the Fix-First flow (auto-fixed if mechanical, batched into ASK if not) (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses A (fix), reply using the **Fix reply template** from greptile-triage.md (include inline diff + explanation). If the user chooses C (false positive), reply using the **False Positive reply template** (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
2. **FALSE POSITIVE comments:** Present each one via question:
|
||||
- Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
|
||||
- Explain concisely why it's a false positive
|
||||
- Options:
|
||||
- A) Reply to Greptile explaining why this is incorrect (recommended if clearly wrong)
|
||||
- B) Fix it anyway (if low-effort and harmless)
|
||||
- C) Ignore — don't reply, don't fix
|
||||
|
||||
If the user chooses A, reply using the **False Positive reply template** from greptile-triage.md (include evidence + suggested re-rank), save to both per-project and global greptile-history.
|
||||
|
||||
3. **VALID BUT ALREADY FIXED comments:** Reply using the **Already Fixed reply template** from greptile-triage.md — no question needed:
|
||||
- Include what was done and the fixing commit SHA
|
||||
- Save to both per-project and global greptile-history
|
||||
|
||||
4. **SUPPRESSED comments:** Skip silently — these are known false positives from previous triage.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.5: TODOS cross-reference
|
||||
|
||||
Read `TODOS.md` in the repository root (if it exists). Cross-reference the PR against open TODOs:
|
||||
|
||||
- **Does this PR close any open TODOs?** If yes, note which items in your output: "This PR addresses TODO: <title>"
|
||||
- **Does this PR create work that should become a TODO?** If yes, flag it as an informational finding.
|
||||
- **Are there related TODOs that provide context for this review?** If yes, reference them when discussing related findings.
|
||||
|
||||
If TODOS.md doesn't exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.6: Documentation staleness check
|
||||
|
||||
Cross-reference the diff against documentation files. For each `.md` file in the repo root (README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, etc.):
|
||||
|
||||
1. Check if code changes in the diff affect features, components, or workflows described in that doc file.
|
||||
2. If the doc file was NOT updated in this branch but the code it describes WAS changed, flag it as an INFORMATIONAL finding:
|
||||
"Documentation may be stale: [file] describes [feature/component] but code changed in this branch. Consider running `/document-release`."
|
||||
|
||||
This is informational only — never critical. The fix action is `/document-release`.
|
||||
|
||||
If no documentation files exist, skip this step silently.
|
||||
|
||||
---
|
||||
|
||||
## Step 5.7: Adversarial review (auto-scaled)
|
||||
|
||||
Adversarial review thoroughness scales automatically based on diff size. No configuration needed.
|
||||
|
||||
**Detect diff size and tool availability:**
|
||||
|
||||
```bash
|
||||
DIFF_INS=$(git diff origin/<base> --stat | tail -1 | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo "0")
|
||||
DIFF_DEL=$(git diff origin/<base> --stat | tail -1 | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo "0")
|
||||
DIFF_TOTAL=$((DIFF_INS + DIFF_DEL))
|
||||
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
# Respect old opt-out
|
||||
OLD_CFG=$(${GSTACK_OPENCODE_DIR}/bin/gstack-config get codex_reviews 2>/dev/null || true)
|
||||
echo "DIFF_SIZE: $DIFF_TOTAL"
|
||||
echo "OLD_CFG: ${OLD_CFG:-not_set}"
|
||||
```
|
||||
|
||||
If `OLD_CFG` is `disabled`: skip this step silently. Continue to the next step.
|
||||
|
||||
**User override:** If the user explicitly requested a specific tier (e.g., "run all passes", "paranoid review", "full adversarial", "do all 4 passes", "thorough review"), honor that request regardless of diff size. Jump to the matching tier section.
|
||||
|
||||
**Auto-select tier based on diff size:**
|
||||
- **Small (< 50 lines changed):** Skip adversarial review entirely. Print: "Small diff ($DIFF_TOTAL lines) — adversarial review skipped." Continue to the next step.
|
||||
- **Medium (50–199 lines changed):** Run Codex adversarial challenge (or Claude adversarial subagent if Codex unavailable). Jump to the "Medium tier" section.
|
||||
- **Large (200+ lines changed):** Run all remaining passes — Codex structured review + Claude adversarial subagent + Codex adversarial. Jump to the "Large tier" section.
|
||||
|
||||
---
|
||||
|
||||
### Medium tier (50–199 lines)
|
||||
|
||||
Claude's structured review already ran. Now add a **cross-model adversarial challenge**.
|
||||
|
||||
**If Codex is available:** run the Codex adversarial challenge. **If Codex is NOT available:** fall back to the Claude adversarial subagent instead.
|
||||
|
||||
**Codex adversarial:**
|
||||
|
||||
```bash
|
||||
TMPERR_ADV=$(mktemp /tmp/codex-adv-XXXXXXXX)
|
||||
codex exec "Review the changes on this branch against the base branch. Run git diff origin/<base> to see the diff. Your job is to find ways this code will fail in production. Think like an attacker and a chaos engineer. Find edge cases, race conditions, security holes, resource leaks, failure modes, and silent data corruption paths. Be adversarial. Be thorough. No compliments — just the problems." -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR_ADV"
|
||||
```
|
||||
|
||||
Set the Bash tool's `timeout` parameter to `300000` (5 minutes). Do NOT use the `timeout` shell command — it doesn't exist on macOS. After the command completes, read stderr:
|
||||
```bash
|
||||
cat "$TMPERR_ADV"
|
||||
```
|
||||
|
||||
Present the full output verbatim. This is informational — it never blocks shipping.
|
||||
|
||||
**Error handling:** All errors are non-blocking — adversarial review 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."
|
||||
- **Timeout:** "Codex timed out after 5 minutes."
|
||||
- **Empty response:** "Codex returned no response. Stderr: <paste relevant error>."
|
||||
|
||||
On any Codex error, fall back to the Claude adversarial subagent automatically.
|
||||
|
||||
**Claude adversarial subagent** (fallback when Codex unavailable or errored):
|
||||
|
||||
Dispatch via the Agent tool. The subagent has fresh context — no checklist bias from the structured review. This genuine independence catches things the primary reviewer is blind to.
|
||||
|
||||
Subagent prompt:
|
||||
"Read the diff for this branch with `git diff origin/<base>`. Think like an attacker and a chaos engineer. Your job is to find ways this code will fail in production. Look for: edge cases, race conditions, security holes, resource leaks, failure modes, silent data corruption, logic errors that produce wrong results silently, error handling that swallows failures, and trust boundary violations. Be adversarial. Be thorough. No compliments — just the problems. For each finding, classify as FIXABLE (you know how to fix it) or INVESTIGATE (needs human judgment)."
|
||||
|
||||
Present findings under an `ADVERSARIAL REVIEW (Claude subagent):` header. **FIXABLE findings** flow into the same Fix-First pipeline as the structured review. **INVESTIGATE findings** are presented as informational.
|
||||
|
||||
If the subagent fails or times out: "Claude adversarial subagent unavailable. Continuing without adversarial review."
|
||||
|
||||
**Persist the review result:**
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"adversarial-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","tier":"medium","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Substitute STATUS: "clean" if no findings, "issues_found" if findings exist. SOURCE: "codex" if Codex ran, "claude" if subagent ran. If both failed, do NOT persist.
|
||||
|
||||
**Cleanup:** Run `rm -f "$TMPERR_ADV"` after processing (if Codex was used).
|
||||
|
||||
---
|
||||
|
||||
### Large tier (200+ lines)
|
||||
|
||||
Claude's structured review already ran. Now run **all three remaining passes** for maximum coverage:
|
||||
|
||||
**1. Codex structured review (if available):**
|
||||
```bash
|
||||
TMPERR=$(mktemp /tmp/codex-review-XXXXXXXX)
|
||||
codex review --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"
|
||||
```
|
||||
|
||||
Set the Bash tool's `timeout` parameter to `300000` (5 minutes). Do NOT use the `timeout` shell command — it doesn't exist on macOS. Present output under `CODEX SAYS (code review):` header.
|
||||
Check for `[P1]` markers: found → `GATE: FAIL`, not found → `GATE: PASS`.
|
||||
|
||||
If GATE is FAIL, use question:
|
||||
```
|
||||
Codex found N critical issues in the diff.
|
||||
|
||||
A) Investigate and fix now (recommended)
|
||||
B) Continue — review will still complete
|
||||
```
|
||||
|
||||
If A: address the findings. Re-run `codex review` to verify.
|
||||
|
||||
Read stderr for errors (same error handling as medium tier).
|
||||
|
||||
After stderr: `rm -f "$TMPERR"`
|
||||
|
||||
**2. Claude adversarial subagent:** Dispatch a subagent with the adversarial prompt (same prompt as medium tier). This always runs regardless of Codex availability.
|
||||
|
||||
**3. Codex adversarial challenge (if available):** Run `codex exec` with the adversarial prompt (same as medium tier).
|
||||
|
||||
If Codex is not available for steps 1 and 3, note to the user: "Codex CLI not found — large-diff review ran Claude structured + Claude adversarial (2 of 4 passes). Install Codex for full 4-pass coverage: `npm install -g @openai/codex`"
|
||||
|
||||
**Persist the review result AFTER all passes complete** (not after each sub-step):
|
||||
```bash
|
||||
${GSTACK_OPENCODE_DIR}/bin/gstack-review-log '{"skill":"adversarial-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","tier":"large","gate":"GATE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Substitute: STATUS = "clean" if no findings across ALL passes, "issues_found" if any pass found issues. SOURCE = "both" if Codex ran, "claude" if only Claude subagent ran. GATE = the Codex structured review gate result ("pass"/"fail"), or "informational" if Codex was unavailable. If all passes failed, do NOT persist.
|
||||
|
||||
---
|
||||
|
||||
### Cross-model synthesis (medium and large tiers)
|
||||
|
||||
After all passes complete, synthesize findings across all sources:
|
||||
|
||||
```
|
||||
ADVERSARIAL REVIEW SYNTHESIS (auto: TIER, N lines):
|
||||
════════════════════════════════════════════════════════════
|
||||
High confidence (found by multiple sources): [findings agreed on by >1 pass]
|
||||
Unique to Claude structured review: [from earlier step]
|
||||
Unique to Claude adversarial: [from subagent, if ran]
|
||||
Unique to Codex: [from codex adversarial or code review, if ran]
|
||||
Models used: Claude structured ✓ Claude adversarial ✓/✗ Codex ✓/✗
|
||||
════════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
High-confidence findings (agreed on by multiple sources) should be prioritized for fixes.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
|
||||
- **Fix-first, not read-only.** AUTO-FIX items are applied directly. ASK items are only applied after user approval. Never commit, push, or create PRs — that's /ship's job.
|
||||
- **Be terse.** One line problem, one line fix. No preamble.
|
||||
- **Only flag real problems.** Skip anything that's fine.
|
||||
- **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence. Never post vague replies.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: setup-browser-cookies
|
||||
description: "Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the headless browse session. Opens an interactive picker UI where you select which cookie domains to import. Use before QA "
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: setup-deploy
|
||||
description: "Configure deployment settings for /land-and-deploy. Detects your deploy platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), production URL, health check endpoints, and deploy s"
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: unfreeze
|
||||
description: "Clear the freeze boundary set by /freeze, allowing edits to all directories again. Use when you want to widen edit scope without ending the session. Use when asked to "unfreeze", "unlock edits", "remo"
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -0,0 +1 @@
|
|||
Subproject commit 7fbf68bb3f253ef799f38862fb1cb0b62d756a64
|
||||
Loading…
Reference in New Issue