npm - opengstack - Versions diffs - 0.13.4 - Mend

opengstack 0.13.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/AGENTS.md +47 -0
package/CLAUDE.md +370 -0
package/LICENSE +21 -0
package/README.md +80 -0
package/SKILL.md +226 -0
package/autoplan/SKILL.md +96 -0
package/autoplan/SKILL.md.tmpl +694 -0
package/benchmark/SKILL.md +358 -0
package/benchmark/SKILL.md.tmpl +222 -0
package/browse/SKILL.md +396 -0
package/browse/SKILL.md.tmpl +131 -0
package/canary/SKILL.md +89 -0
package/canary/SKILL.md.tmpl +212 -0
package/careful/SKILL.md +58 -0
package/careful/SKILL.md.tmpl +56 -0
package/codex/SKILL.md +90 -0
package/codex/SKILL.md.tmpl +417 -0
package/connect-chrome/SKILL.md +87 -0
package/connect-chrome/SKILL.md.tmpl +195 -0
package/cso/SKILL.md +93 -0
package/cso/SKILL.md.tmpl +606 -0
package/design-consultation/SKILL.md +94 -0
package/design-consultation/SKILL.md.tmpl +415 -0
package/design-review/SKILL.md +94 -0
package/design-review/SKILL.md.tmpl +290 -0
package/design-shotgun/SKILL.md +91 -0
package/design-shotgun/SKILL.md.tmpl +285 -0
package/docs/designs/CHROME_VS_CHROMIUM_EXPLORATION.md +84 -0
package/docs/designs/CONDUCTOR_CHROME_SIDEBAR_INTEGRATION.md +57 -0
package/docs/designs/CONDUCTOR_SESSION_API.md +108 -0
package/docs/designs/DESIGN_SHOTGUN.md +451 -0
package/docs/designs/DESIGN_TOOLS_V1.md +622 -0
package/docs/skills.md +880 -0
package/document-release/SKILL.md +91 -0
package/document-release/SKILL.md.tmpl +359 -0
package/freeze/SKILL.md +78 -0
package/freeze/SKILL.md.tmpl +77 -0
package/gstack-upgrade/SKILL.md +224 -0
package/gstack-upgrade/SKILL.md.tmpl +222 -0
package/guard/SKILL.md +78 -0
package/guard/SKILL.md.tmpl +77 -0
package/investigate/SKILL.md +105 -0
package/investigate/SKILL.md.tmpl +194 -0
package/land-and-deploy/SKILL.md +88 -0
package/land-and-deploy/SKILL.md.tmpl +881 -0
package/office-hours/SKILL.md +96 -0
package/office-hours/SKILL.md.tmpl +645 -0
package/package.json +43 -0
package/plan-ceo-review/SKILL.md +94 -0
package/plan-ceo-review/SKILL.md.tmpl +811 -0
package/plan-design-review/SKILL.md +92 -0
package/plan-design-review/SKILL.md.tmpl +446 -0
package/plan-eng-review/SKILL.md +93 -0
package/plan-eng-review/SKILL.md.tmpl +303 -0
package/qa/SKILL.md +95 -0
package/qa/SKILL.md.tmpl +316 -0
package/qa-only/SKILL.md +89 -0
package/qa-only/SKILL.md.tmpl +101 -0
package/retro/SKILL.md +89 -0
package/retro/SKILL.md.tmpl +820 -0
package/review/SKILL.md +92 -0
package/review/SKILL.md.tmpl +281 -0
package/scripts/cleanup.py +100 -0
package/scripts/filter-skills.sh +114 -0
package/scripts/filter_skills.py +140 -0
package/setup-browser-cookies/SKILL.md +216 -0
package/setup-browser-cookies/SKILL.md.tmpl +81 -0
package/setup-deploy/SKILL.md +92 -0
package/setup-deploy/SKILL.md.tmpl +215 -0
package/ship/SKILL.md +90 -0
package/ship/SKILL.md.tmpl +636 -0
package/unfreeze/SKILL.md +37 -0
package/unfreeze/SKILL.md.tmpl +36 -0

package/docs/designs/DESIGN_SHOTGUN.md ADDED Viewed

@@ -0,0 +1,451 @@
+# Design: Design Shotgun — Browser-to-Agent Feedback Loop
+Generated on 2026-03-27
+Branch: garrytan/agent-design-tools
+Status: LIVING DOCUMENT — update as bugs are found and fixed
+## What This Feature Does
+Design Shotgun generates multiple AI design mockups, opens them side-by-side in the
+user's real browser as a comparison board, and collects structured feedback (pick a
+favorite, rate alternatives, leave notes, request regeneration). The feedback flows
+back to the coding agent, which acts on it: either proceeding with the approved
+variant or generating new variants and reloading the board.
+The user never leaves their browser tab. The agent never asks redundant questions.
+The board is the feedback mechanism.
+## The Core Problem: Two Worlds That Must Talk
+```
+  ┌─────────────────────┐          ┌──────────────────────┐
+  │   USER'S BROWSER    │          │   CODING AGENT       │
+  │   (real Chrome)     │          │   (Claude Code /     │
+  │                     │          │    Conductor)         │
+  │  Comparison board   │          │                      │
+  │  with buttons:      │   ???    │  Needs to know:      │
+  │  - Submit           │ ──────── │  - What was picked   │
+  │  - Regenerate       │          │  - Star ratings      │
+  │  - More like this   │          │  - Comments          │
+  │  - Remix            │          │  - Regen requested?  │
+  └─────────────────────┘          └──────────────────────┘
+```
+The "???" is the hard part. The user clicks a button in Chrome. The agent running in
+a terminal needs to know about it. These are two completely separate processes with
+no shared memory, no shared event bus, no WebSocket connection.
+## Architecture: How the Linkage Works
+```
+  USER'S BROWSER                    $D serve (Bun HTTP)              AGENT
+  ═══════════════                   ═══════════════════              ═════
+       │                                   │                           │
+       │  GET /                            │                           │
+       │ ◄─────── serves board HTML ──────►│                           │
+       │    (with __GSTACK_SERVER_URL      │                           │
+       │     injected into <head>)         │                           │
+       │                                   │                           │
+       │  [user rates, picks, comments]    │                           │
+       │                                   │                           │
+       │  POST /api/feedback               │                           │
+       │ ─────── {preferred:"A",...} ─────►│                           │
+       │                                   │                           │
+       │  ◄── {received:true} ────────────│                           │
+       │                                   │── writes feedback.json ──►│
+       │  [inputs disabled,                │   (or feedback-pending    │
+       │   "Return to agent" shown]        │    .json for regen)       │
+       │                                   │                           │
+       │                                   │                  [agent polls
+       │                                   │                   every 5s,
+       │                                   │                   reads file]
+```
+### The Three Files
+| File | Written when | Means | Agent action |
+|------|-------------|-------|-------------|
+| `feedback.json` | User clicks Submit | Final selection, done | Read it, proceed |
+| `feedback-pending.json` | User clicks Regenerate/More Like This | Wants new options | Read it, delete it, generate new variants, reload board |
+| `feedback.json` (round 2+) | User clicks Submit after regeneration | Final selection after iteration | Read it, proceed |
+### The State Machine
+```
+  $D serve starts
+       │
+       ▼
+  ┌──────────┐
+  │ SERVING  │◄──────────────────────────────────────┐
+  │          │                                        │
+  │ Board is │  POST /api/feedback                    │
+  │ live,    │  {regenerated: true}                   │
+  │ waiting  │──────────────────►┌──────────────┐     │
+  │          │                   │ REGENERATING │     │
+  │          │                   │              │     │
+  └────┬─────┘                   │ Agent has    │     │
+       │                         │ 10 min to    │     │
+       │  POST /api/feedback     │ POST new     │     │
+       │  {regenerated: false}   │ board HTML   │     │
+       │                         └──────┬───────┘     │
+       ▼                                │             │
+  ┌──────────┐                POST /api/reload        │
+  │  DONE    │                {html: "/new/board"}    │
+  │          │                          │             │
+  │ exit 0   │                          ▼             │
+  └──────────┘                   ┌──────────────┐     │
+                                 │  RELOADING   │─────┘
+                                 │              │
+                                 │ Board auto-  │
+                                 │ refreshes    │
+                                 │ (same tab)   │
+                                 └──────────────┘
+```
+### Port Discovery
+The agent backgrounds `$D serve` and reads stderr for the port:
+```
+SERVE_STARTED: port=54321 html=/path/to/board.html
+SERVE_BROWSER_OPENED: url=http://127.0.0.1:54321
+```
+The agent parses `port=XXXXX` from stderr. This port is needed later to POST
+`/api/reload` when the user requests regeneration. If the agent loses the port
+number, it cannot reload the board.
+### Why 127.0.0.1, Not localhost
+`localhost` can resolve to IPv6 `::1` on some systems while Bun.serve() listens
+on IPv4 only. More importantly, `localhost` sends all dev cookies for every domain
+the developer has been working on. On a machine with many active sessions, this
+blows past Bun's default header size limit (HTTP 431 error). `127.0.0.1` avoids
+both issues.
+## Every Edge Case and Pitfall
+### 1. The Zombie Form Problem
+**What:** User submits feedback, the POST succeeds, the server exits. But the HTML
+page is still open in Chrome. It looks interactive. The user might edit their
+feedback and click Submit again. Nothing happens because the server is gone.
+**Fix:** After successful POST, the board JS:
+- Disables ALL inputs (buttons, radios, textareas, star ratings)
+- Hides the Regenerate bar entirely
+- Replaces the Submit button with: "Feedback received! Return to your coding agent."
+- Shows: "Want to make more changes? Run `/design-shotgun` again."
+- The page becomes a read-only record of what was submitted
+**Implemented in:** `compare.ts:showPostSubmitState()` (line 484)
+### 2. The Dead Server Problem
+**What:** The server times out (10 min default) or crashes while the user still has
+the board open. User clicks Submit. The fetch() fails silently.
+**Fix:** The `postFeedback()` function has a `.catch()` handler. On network failure:
+- Shows red error banner: "Connection lost"
+- Displays the collected feedback JSON in a copyable `<pre>` block
+- User can copy-paste it directly into their coding agent
+**Implemented in:** `compare.ts:showPostFailure()` (line 546)
+### 3. The Stale Regeneration Spinner
+**What:** User clicks Regenerate. Board shows spinner and polls `/api/progress`
+every 2 seconds. Agent crashes or takes too long to generate new variants. The
+spinner spins forever.
+**Fix:** Progress polling has a hard 5-minute timeout (150 polls x 2s interval).
+After 5 minutes:
+- Spinner replaced with: "Something went wrong."
+- Shows: "Run `/design-shotgun` again in your coding agent."
+- Polling stops. Page becomes informational.
+**Implemented in:** `compare.ts:startProgressPolling()` (line 511)
+### 4. The file:// URL Problem (THE ORIGINAL BUG)
+**What:** The skill template originally used `$B goto file:///path/to/board.html`.
+But `browse/src/url-validation.ts:71` blocks `file://` URLs for security. The
+fallback `open file://...` opens the user's macOS browser, but `$B eval` polls
+Playwright's headless browser (different process, never loaded the page).
+Agent polls empty DOM forever.
+**Fix:** `$D serve` serves over HTTP. Never use `file://` for the board. The
+`--serve` flag on `$D compare` combines board generation and HTTP serving in
+one command.
+**Evidence:** See `.context/attachments/image-v2.png` — a real user hit this exact
+bug. The agent correctly diagnosed: (1) `$B goto` rejects `file://` URLs,
+(2) no polling loop even with the browse daemon.
+### 5. The Double-Click Race
+**What:** User clicks Submit twice rapidly. Two POST requests arrive at the server.
+First one sets state to "done" and schedules exit(0) in 100ms. Second one arrives
+during that 100ms window.
+**Current state:** NOT fully guarded. The `handleFeedback()` function doesn't check
+if state is already "done" before processing. The second POST would succeed and
+write a second `feedback.json` (harmless, same data). The exit still fires after
+100ms.
+**Risk:** Low. The board disables all inputs on the first successful POST response,
+so a second click would need to arrive within ~1ms. And both writes would contain
+the same feedback data.
+**Potential fix:** Add `if (state === 'done') return Response.json({error: 'already submitted'}, {status: 409})` at the top of `handleFeedback()`.
+### 6. The Port Coordination Problem
+**What:** Agent backgrounds `$D serve` and parses `port=54321` from stderr. Agent
+needs this port later to POST `/api/reload` during regeneration. If the agent
+loses context (conversation compresses, context window fills up), it may not
+remember the port.
+**Current state:** The port is printed to stderr once. The agent must remember it.
+There is no port file written to disk.
+**Potential fix:** Write a `serve.pid` or `serve.port` file next to the board HTML
+on startup. Agent can read it anytime:
+```bash
+cat "$_DESIGN_DIR/serve.port"  # → 54321
+```
+### 7. The Feedback File Cleanup Problem
+**What:** `feedback-pending.json` from a regeneration round is left on disk. If the
+agent crashes before reading it, the next `$D serve` session finds a stale file.
+**Current state:** The polling loop in the resolver template says to delete
+`feedback-pending.json` after reading it. But this depends on the agent following
+instructions perfectly. Stale files could confuse a new session.
+**Potential fix:** `$D serve` could check for and delete stale feedback files on
+startup. Or: name files with timestamps (`feedback-pending-1711555200.json`).
+### 8. Sequential Generate Rule
+**What:** The underlying OpenAI GPT Image API rate-limits concurrent image generation
+requests. When 3 `$D generate` calls run in parallel, 1 succeeds and 2 get aborted.
+**Fix:** The skill template must explicitly say: "Generate mockups ONE AT A TIME.
+Do not parallelize `$D generate` calls." This is a prompt-level instruction, not
+a code-level lock. The design binary does not enforce sequential execution.
+**Risk:** Agents are trained to parallelize independent work. Without an explicit
+instruction, they will try to run 3 generates simultaneously. This wastes API calls
+and money.
+### 9. The AskUserQuestion Redundancy
+**What:** After the user submits feedback via the board (with preferred variant,
+ratings, comments all in the JSON), the agent asks them again: "Which variant do
+you prefer?" This is annoying. The whole point of the board is to avoid this.
+**Fix:** The skill template must say: "Do NOT use AskUserQuestion to ask the user's
+preference. Read `feedback.json`, it contains their selection. Only AskUserQuestion
+to confirm you understood correctly, not to re-ask."
+### 10. The CORS Problem
+**What:** If the board HTML references external resources (fonts, images from CDN),
+the browser sends requests with `Origin: http://127.0.0.1:PORT`. Most CDNs allow
+this, but some might block it.
+**Current state:** The server does not set CORS headers. The board HTML is
+self-contained (images base64-encoded, styles inline), so this hasn't been an
+issue in practice.
+**Risk:** Low for current design. Would matter if the board loaded external
+resources.
+### 11. The Large Payload Problem
+**What:** No size limit on POST bodies to `/api/feedback`. If the board somehow
+sends a multi-MB payload, `req.json()` will parse it all into memory.
+**Current state:** In practice, feedback JSON is ~500 bytes to ~2KB. The risk is
+theoretical, not practical. The board JS constructs a fixed-shape JSON object.
+### 12. The fs.writeFileSync Error
+**What:** `feedback.json` write in `serve.ts:138` uses `fs.writeFileSync()` with no
+try/catch. If the disk is full or the directory is read-only, this throws and
+crashes the server. The user sees a spinner forever (server is dead, but board
+doesn't know).
+**Risk:** Low in practice (the board HTML was just written to the same directory,
+proving it's writable). But a try/catch with a 500 response would be cleaner.
+## The Complete Flow (Step by Step)
+### Happy Path: User Picks on First Try
+```
+1. Agent runs: $D compare --images "A.png,B.png,C.png" --output board.html --serve &
+2. $D serve starts Bun.serve() on random port (e.g. 54321)
+3. $D serve opens http://127.0.0.1:54321 in user's browser
+4. $D serve prints to stderr: SERVE_STARTED: port=54321 html=/path/board.html
+5. $D serve writes board HTML with injected __GSTACK_SERVER_URL
+6. User sees comparison board with 3 variants side by side
+7. User picks Option B, rates A: 3/5, B: 5/5, C: 2/5
+8. User writes "B has better spacing, go with that" in overall feedback
+9. User clicks Submit
+10. Board JS POSTs to http://127.0.0.1:54321/api/feedback
+    Body: {"preferred":"B","ratings":{"A":3,"B":5,"C":2},"overall":"B has better spacing","regenerated":false}
+11. Server writes feedback.json to disk (next to board.html)
+12. Server prints feedback JSON to stdout
+13. Server responds {received:true, action:"submitted"}
+14. Board disables all inputs, shows "Return to your coding agent"
+15. Server exits with code 0 after 100ms
+16. Agent's polling loop finds feedback.json
+17. Agent reads it, summarizes to user, proceeds
+```
+### Regeneration Path: User Wants Different Options
+```
+1-6.  Same as above
+7.  User clicks "Totally different" chiclet
+8.  User clicks Regenerate
+9.  Board JS POSTs to /api/feedback
+    Body: {"regenerated":true,"regenerateAction":"different","preferred":"","ratings":{},...}
+10. Server writes feedback-pending.json to disk
+11. Server state → "regenerating"
+12. Server responds {received:true, action:"regenerate"}
+13. Board shows spinner: "Generating new designs..."
+14. Board starts polling GET /api/progress every 2s
+    Meanwhile, in the agent:
+15. Agent's polling loop finds feedback-pending.json
+16. Agent reads it, deletes it
+17. Agent runs: $D variants --brief "totally different direction" --count 3
+    (ONE AT A TIME, not parallel)
+18. Agent runs: $D compare --images "new-A.png,new-B.png,new-C.png" --output board-v2.html
+19. Agent POSTs: curl -X POST http://127.0.0.1:54321/api/reload -d '{"html":"/path/board-v2.html"}'
+20. Server swaps htmlContent to new board
+21. Server state → "serving" (from reloading)
+22. Board's next /api/progress poll returns {"status":"serving"}
+23. Board auto-refreshes: window.location.reload()
+24. User sees new board with 3 fresh variants
+25. User picks one, clicks Submit → happy path from step 10
+```
+### "More Like This" Path
+```
+Same as regeneration, except:
+- regenerateAction is "more_like_B" (references the variant)
+- Agent uses $D iterate --image B.png --brief "more like this, keep the spacing"
+  instead of $D variants
+```
+### Fallback Path: $D serve Fails
+```
+1. Agent tries $D compare --serve, it fails (binary missing, port error, etc.)
+2. Agent falls back to: open file:///path/board.html
+3. Agent uses AskUserQuestion: "I've opened the design board. Which variant
+   do you prefer? Any feedback?"
+4. User responds in text
+5. Agent proceeds with text feedback (no structured JSON)
+```
+## Files That Implement This
+| File | Role |
+|------|------|
+| `design/src/serve.ts` | HTTP server, state machine, file writing, browser launch |
+| `design/src/compare.ts` | Board HTML generation, JS for ratings/picks/regen, POST logic, post-submit lifecycle |
+| `design/src/cli.ts` | CLI entry point, wires `serve` and `compare --serve` commands |
+| `design/src/commands.ts` | Command registry, defines `serve` and `compare` with their args |
+| `scripts/resolvers/design.ts` | `generateDesignShotgunLoop()` — template resolver that outputs the polling loop and reload instructions |
+| `design-shotgun/SKILL.md.tmpl` | Skill template that orchestrates the full flow: context gathering, variant generation, `{{DESIGN_SHOTGUN_LOOP}}`, feedback confirmation |
+| `design/test/serve.test.ts` | Unit tests for HTTP endpoints and state transitions |
+| `design/test/feedback-roundtrip.test.ts` | E2E test: browser click → JS fetch → HTTP POST → file on disk |
+| `browse/test/compare-board.test.ts` | DOM-level tests for the comparison board UI |
+## What Could Still Go Wrong
+### Known Risks (ordered by likelihood)
+1. **Agent doesn't follow sequential generate rule** — most LLMs want to parallelize. Without enforcement in the binary, this is a prompt-level instruction that can be ignored.
+2. **Agent loses port number** — context compression drops the stderr output. Agent can't reload the board. Mitigation: write port to a file.
+3. **Stale feedback files** — leftover `feedback-pending.json` from a crashed session confuses the next run. Mitigation: clean on startup.
+4. **fs.writeFileSync crash** — no try/catch on the feedback file write. Silent server death if disk is full. User sees infinite spinner.
+5. **Progress polling drift** — `setInterval(fn, 2000)` over 5 minutes. In practice, JavaScript timers are accurate enough. But if the browser tab is backgrounded, Chrome may throttle intervals to once per minute.
+### Things That Work Well
+1. **Dual-channel feedback** — stdout for foreground mode, files for background mode. Both always active. Agent can use whichever works.
+2. **Self-contained HTML** — board has all CSS, JS, and base64-encoded images inline. No external dependencies. Works offline.
+3. **Same-tab regeneration** — user stays in one tab. Board auto-refreshes via `/api/progress` polling + `window.location.reload()`. No tab explosion.
+4. **Graceful degradation** — POST failure shows copyable JSON. Progress timeout shows clear error message. No silent failures.
+5. **Post-submit lifecycle** — board becomes read-only after submit. No zombie forms. Clear "what to do next" message.
+## Test Coverage
+### What's Tested
+| Flow | Test | File |
+|------|------|------|
+| Submit → feedback.json on disk | browser click → file | `feedback-roundtrip.test.ts` |
+| Post-submit UI lockdown | inputs disabled, success shown | `feedback-roundtrip.test.ts` |
+| Regenerate → feedback-pending.json | chiclet + regen click → file | `feedback-roundtrip.test.ts` |
+| "More like this" → specific action | more_like_B in JSON | `feedback-roundtrip.test.ts` |
+| Spinner after regenerate | DOM shows loading text | `feedback-roundtrip.test.ts` |
+| Full regen → reload → submit | 2-round trip | `feedback-roundtrip.test.ts` |
+| Server starts on random port | port 0 binding | `serve.test.ts` |
+| HTML injection of server URL | __GSTACK_SERVER_URL check | `serve.test.ts` |
+| Invalid JSON rejection | 400 response | `serve.test.ts` |
+| HTML file validation | exit 1 if missing | `serve.test.ts` |
+| Timeout behavior | exit 1 after timeout | `serve.test.ts` |
+| Board DOM structure | radios, stars, chiclets | `compare-board.test.ts` |
+### What's NOT Tested
+| Gap | Risk | Priority |
+|-----|------|----------|
+| Double-click submit race | Low — inputs disable on first response | P3 |
+| Progress polling timeout (150 iterations) | Medium — 5 min is long to wait in a test | P2 |
+| Server crash during regeneration | Medium — user sees infinite spinner | P2 |
+| Network timeout during POST | Low — localhost is fast | P3 |
+| Backgrounded Chrome tab throttling intervals | Medium — could extend 5-min timeout to 30+ min | P2 |
+| Large feedback payload | Low — board constructs fixed-shape JSON | P3 |
+| Concurrent sessions (two boards, one server) | Low — each $D serve gets its own port | P3 |
+| Stale feedback file from prior session | Medium — could confuse new polling loop | P2 |
+## Potential Improvements
+### Short-term (this branch)
+1. **Write port to file** — `serve.ts` writes `serve.port` to disk on startup. Agent reads it anytime. 5 lines.
+2. **Clean stale files on startup** — `serve.ts` deletes `feedback*.json` before starting. 3 lines.
+3. **Guard double-click** — check `state === 'done'` at top of `handleFeedback()`. 2 lines.
+4. **try/catch file write** — wrap `fs.writeFileSync` in try/catch, return 500 on failure. 5 lines.
+### Medium-term (follow-up)
+5. **WebSocket instead of polling** — replace `setInterval` + `GET /api/progress` with a WebSocket connection. Board gets instant notification when new HTML is ready. Eliminates polling drift and backgrounded-tab throttling. ~50 lines in serve.ts + ~20 lines in compare.ts.
+6. **Port file for agent** — write `{"port": 54321, "pid": 12345, "html": "/path/board.html"}` to `$_DESIGN_DIR/serve.json`. Agent reads this instead of parsing stderr. Makes the system more robust to context loss.
+7. **Feedback schema validation** — validate the POST body against a JSON schema before writing. Catch malformed feedback early instead of confusing the agent downstream.
+### Long-term (design direction)
+8. **Persistent design server** — instead of launching `$D serve` per session, run a long-lived design daemon (like the browse daemon). Multiple boards share one server. Eliminates cold start. But adds daemon lifecycle management complexity.
+9. **Real-time collaboration** — two agents (or one agent + one human) working on the same board simultaneously. Server broadcasts state changes via WebSocket. Requires conflict resolution on feedback.