opengstack 0.14.0 → 0.14.2

package/AGENTS.md

@@ -1,10 +1,10 @@
-# OpenGStack — AI Engineering Workflow
+# opengstack — AI Engineering Workflow
 
-OpenGStack is a collection of SKILL.md files that give AI agents structured roles for
+opengstack is a collection of SKILL.md files that give AI agents structured roles for
 software development. Each skill is a specialist: CEO reviewer, eng manager,
 designer, QA lead, release engineer, debugger, and more.
 
-Forked from garrytan/gstack with telemetry removed.
+Forked from with telemetry removed.
 
 ## Available skills
 
@@ -44,4 +44,4 @@ This fork has all telemetry, analytics, and tracking removed. Your usage stays l
 
 ## Sync from Upstream
 
-This repo syncs daily from garrytan/gstack via GitHub Actions.
+This repo syncs daily from via GitHub Actions.

package/CLAUDE.md

@@ -1,23 +1,23 @@
-# gstack development
+# opengstack development
 
 ## Commands
 
 ```bash
-bun install          # install dependencies
-bun test             # run free tests (browse + snapshot + skill validation)
-bun run test:evals   # run paid evals: LLM judge + E2E (diff-based, ~$4/run max)
-bun run test:evals:all  # run ALL paid evals regardless of diff
-bun run test:gate    # run gate-tier tests only (CI default, blocks merge)
-bun run test:periodic  # run periodic-tier tests only (weekly cron / manual)
-bun run test:e2e     # run E2E tests only (diff-based, ~$3.85/run max)
+bun install # install dependencies
+bun test # run free tests (browse + snapshot + skill validation)
+bun run test:evals # run paid evals: LLM judge + E2E (diff-based, ~$4/run max)
+bun run test:evals:all # run ALL paid evals regardless of diff
+bun run test:gate # run gate-tier tests only (CI default, blocks merge)
+bun run test:periodic # run periodic-tier tests only (weekly cron / manual)
+bun run test:e2e # run E2E tests only (diff-based, ~$3.85/run max)
 bun run test:e2e:all # run ALL E2E tests regardless of diff
-bun run eval:select  # show which tests would run based on current diff
-bun run dev <cmd>    # run CLI in dev mode, e.g. bun run dev goto https://example.com
-bun run build        # gen docs + compile binaries
-bun run gen:skill-docs  # regenerate SKILL.md files from templates
-bun run skill:check  # health dashboard for all skills
-bun run dev:skill    # watch mode: auto-regen + validate on change
-bun run eval:list    # list all eval runs from ~/.gstack-dev/evals/
+bun run eval:select # show which tests would run based on current diff
+bun run dev <cmd> # run CLI in dev mode, e.g. bun run dev goto https://example.com
+bun run build # gen docs + compile binaries
+bun run gen:skill-docs # regenerate SKILL.md files from templates
+bun run skill:check # health dashboard for all skills
+bun run dev:skill # watch mode: auto-regen + validate on change
+bun run eval:list # list all eval runs from ~/.opengstack-dev/evals/
 bun run eval:compare # compare two eval runs (auto-picks most recent)
 bun run eval:summary # aggregate stats across all eval runs
 ```
@@ -25,7 +25,7 @@ bun run eval:summary # aggregate stats across all eval runs
 `test:evals` requires `ANTHROPIC_API_KEY`. Codex E2E tests (`test/codex-e2e.test.ts`)
 use Codex's own auth from `~/.codex/` config — no `OPENAI_API_KEY` env var needed.
 E2E tests stream progress in real-time (tool-by-tool via `--output-format stream-json
---verbose`). Results are persisted to `~/.gstack-dev/evals/` with auto-comparison
+--verbose`). Results are persisted to `~/.opengstack-dev/evals/` with auto-comparison
 against the previous run.
 
 **Diff-based test selection:** `test:evals` and `test:e2e` auto-select tests based
@@ -45,8 +45,8 @@ periodic tests run weekly via cron or manually. Use `EVALS_TIER=gate` or
 ## Testing
 
 ```bash
-bun test             # run before every commit — free, <2s
-bun run test:evals   # run before shipping — paid, diff-based (~$4/run max)
+bun test # run before every commit — free, <2s
+bun run test:evals # run before shipping — paid, diff-based (~$4/run max)
 ```
 
 `bun test` runs skill validation, gen-skill-docs quality checks, and browse
@@ -56,62 +56,62 @@ tests via `claude -p`. Both must pass before creating a PR.
 ## Project structure
 
 ```
-gstack/
-├── browse/          # Headless browser CLI (Playwright)
-│   ├── src/         # CLI + server + commands
-│   │   ├── commands.ts  # Command registry (single source of truth)
-│   │   └── snapshot.ts  # SNAPSHOT_FLAGS metadata array
-│   ├── test/        # Integration tests + fixtures
-│   └── dist/        # Compiled binary
-├── scripts/         # Build + DX tooling
-│   ├── gen-skill-docs.ts  # Template → SKILL.md generator
-│   ├── resolvers/   # Template resolver modules (preamble, design, review, etc.)
-│   ├── skill-check.ts     # Health dashboard
-│   └── dev-skill.ts       # Watch mode
-├── test/            # Skill validation + eval tests
-│   ├── helpers/     # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts
-│   ├── fixtures/    # Ground truth JSON, planted-bug fixtures, eval baselines
-│   ├── skill-validation.test.ts  # Tier 1: static validation (free, <1s)
-│   ├── gen-skill-docs.test.ts    # Tier 1: generator quality (free, <1s)
-│   ├── skill-llm-eval.test.ts   # Tier 3: LLM-as-judge (~$0.15/run)
-│   └── skill-e2e-*.test.ts       # Tier 2: E2E via claude -p (~$3.85/run, split by category)
-├── qa-only/         # /qa-only skill (report-only QA, no fixes)
-├── plan-design-review/  # /plan-design-review skill (report-only design audit)
-├── design-review/    # /design-review skill (design audit + fix loop)
-├── ship/            # Ship workflow skill
-├── review/          # PR review skill
+OpenGStack/
+├── browse/ # Headless browser CLI (Playwright)
+│ ├── src/ # CLI + server + commands
+│ │ ├── commands.ts # Command registry (single source of truth)
+│ │ └── snapshot.ts # SNAPSHOT_FLAGS metadata array
+│ ├── test/ # Integration tests + fixtures
+│ └── dist/ # Compiled binary
+├── scripts/ # Build + DX tooling
+│ ├── gen-skill-docs.ts # Template → SKILL.md generator
+│ ├── resolvers/ # Template resolver modules (preamble, design, review, etc.)
+│ ├── skill-check.ts # Health dashboard
+│ └── dev-skill.ts # Watch mode
+├── test/ # Skill validation + eval tests
+│ ├── helpers/ # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts
+│ ├── fixtures/ # Ground truth JSON, planted-bug fixtures, eval baselines
+│ ├── skill-validation.test.ts # Tier 1: static validation (free, <1s)
+│ ├── gen-skill-docs.test.ts # Tier 1: generator quality (free, <1s)
+│ ├── skill-llm-eval.test.ts # Tier 3: LLM-as-judge (~$0.15/run)
+│ └── skill-e2e-*.test.ts # Tier 2: E2E via claude -p (~$3.85/run, split by category)
+├── qa-only/ # /qa-only skill (report-only QA, no fixes)
+├── plan-design-review/ # /plan-design-review skill (report-only design audit)
+├── design-review/ # /design-review skill (design audit + fix loop)
+├── ship/ # Ship workflow skill
+├── review/ # PR review skill
 ├── plan-ceo-review/ # /plan-ceo-review skill
 ├── plan-eng-review/ # /plan-eng-review skill
-├── autoplan/        # /autoplan skill (auto-review pipeline: CEO → design → eng)
-├── benchmark/       # /benchmark skill (performance regression detection)
-├── canary/          # /canary skill (post-deploy monitoring loop)
-├── codex/           # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
+├── autoplan/ # /autoplan skill (auto-review pipeline: CEO → design → eng)
+├── benchmark/ # /benchmark skill (performance regression detection)
+├── canary/ # /canary skill (post-deploy monitoring loop)
+├── codex/ # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
 ├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
-├── office-hours/    # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
-├── investigate/     # /investigate skill (systematic root-cause debugging)
-├── retro/           # Retrospective skill (includes /retro global cross-project mode)
-├── bin/             # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.)
+├── office-hours/ # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
+├── investigate/ # /investigate skill (systematic root-cause debugging)
+├── retro/ # Retrospective skill (includes /retro global cross-project mode)
+├── bin/ # CLI utilities (opengstack-repo-mode, opengstack-slug, opengstack-config, etc.)
 ├── document-release/ # /document-release skill (post-ship doc updates)
-├── cso/             # /cso skill (OWASP Top 10 + STRIDE security audit)
+├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit)
 ├── design-consultation/ # /design-consultation skill (design system from scratch)
-├── design-shotgun/  # /design-shotgun skill (visual design exploration)
-├── connect-chrome/  # /connect-chrome skill (headed Chrome with side panel)
-├── design/          # Design binary CLI (GPT Image API)
-│   ├── src/         # CLI + commands (generate, variants, compare, serve, etc.)
-│   ├── test/        # Integration tests
-│   └── dist/        # Compiled binary
-├── extension/       # Chrome extension (side panel + activity feed)
-├── lib/             # Shared libraries (worktree.ts)
-├── docs/designs/    # Design documents
-├── setup-deploy/    # /setup-deploy skill (one-time deploy config)
-├── .github/         # CI workflows + Docker image
-│   ├── workflows/   # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml
-│   └── docker/      # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
-├── setup            # One-time setup: build binary + symlink skills
-├── SKILL.md         # Generated from SKILL.md.tmpl (don't edit directly)
-├── SKILL.md.tmpl    # Template: edit this, run gen:skill-docs
-├── ETHOS.md         # Builder philosophy (Boil the Lake, Search Before Building)
-└── package.json     # Build scripts for browse
+├── design-shotgun/ # /design-shotgun skill (visual design exploration)
+├── connect-chrome/ # /connect-chrome skill (headed Chrome with side panel)
+├── design/ # Design binary CLI (GPT Image API)
+│ ├── src/ # CLI + commands (generate, variants, compare, serve, etc.)
+│ ├── test/ # Integration tests
+│ └── dist/ # Compiled binary
+├── extension/ # Chrome extension (side panel + activity feed + CSS inspector)
+├── lib/ # Shared libraries (worktree.ts)
+├── docs/designs/ # Design documents
+├── setup-deploy/ # /setup-deploy skill (one-time deploy config)
+├── .github/ # CI workflows + Docker image
+│ ├── workflows/ # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml
+│ └── docker/ # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
+├── setup # One-time setup: build binary + symlink skills
+├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly)
+├── SKILL.md.tmpl # Template: edit this, run gen:skill-docs
+├── ETHOS.md # Builder philosophy (Boil the Lake, Search Before Building)
+└── package.json # Build scripts for browse
 ```
 
 ## SKILL.md workflow
@@ -137,11 +137,11 @@ Skills must NEVER hardcode framework-specific commands, file patterns, or direct
 structures. Instead:
 
 1. **Read CLAUDE.md** for project-specific config (test commands, eval commands, etc.)
-2. **If missing, AskUserQuestion** — let the user tell you or let gstack search the repo
+2. **If missing, AskUserQuestion** — let the user tell you or let opengstack search the repo
 3. **Persist the answer to CLAUDE.md** so we never have to ask again
 
 This applies to test commands, eval commands, deploy commands, and any other
-project-specific behavior. The project owns its config; gstack reads it.
+project-specific behavior. The project owns its config; opengstack reads it.
 
 ## Writing SKILL templates
 
@@ -150,15 +150,15 @@ Each bash code block runs in a separate shell — variables do not persist betwe
 
 Rules:
 - **Use natural language for logic and state.** Don't use shell variables to pass
-  state between code blocks. Instead, tell Claude what to remember and reference
-  it in prose (e.g., "the base branch detected in Step 0").
+ state between code blocks. Instead, tell Claude what to remember and reference
+ it in prose (e.g., "the base branch detected in Step 0").
 - **Don't hardcode branch names.** Detect `main`/`master`/etc dynamically via
-  `gh pr view` or `gh repo view`. Use `{{BASE_BRANCH_DETECT}}` for PR-targeting
-  skills. Use "the base branch" in prose, `<base>` in code block placeholders.
+ `gh pr view` or `gh repo view`. Use `{{BASE_BRANCH_DETECT}}` for PR-targeting
+ skills. Use "the base branch" in prose, `<base>` in code block placeholders.
 - **Keep bash blocks self-contained.** Each code block should work independently.
-  If a block needs context from a previous step, restate it in the prose above.
+ If a block needs context from a previous step, restate it in the prose above.
 - **Express conditionals as English.** Instead of nested `if/elif/else` in bash,
-  write numbered decision steps: "1. If X, do Y. 2. Otherwise, do Z."
+ write numbered decision steps: "1. If X, do Y. 2. Otherwise, do Z."
 
 ## Browser interaction
 
@@ -169,27 +169,27 @@ project uses.
 
 ## Vendored symlink awareness
 
-When developing gstack, `.claude/skills/gstack` may be a symlink back to this
+When developing OpenGStack, `.claude/skills/opengstack` may be a symlink back to this
 working directory (gitignored). This means skill changes are **live immediately** —
 great for rapid iteration, risky during big refactors where half-written skills
-could break other Claude Code sessions using gstack concurrently.
+could break other Claude Code sessions using opengstack concurrently.
 
-**Check once per session:** Run `ls -la .claude/skills/gstack` to see if it's a
+**Check once per session:** Run `ls -la .claude/skills/opengstack` to see if it's a
 symlink or a real copy. If it's a symlink to your working directory, be aware that:
-- Template changes + `bun run gen:skill-docs` immediately affect all gstack invocations
-- Breaking changes to SKILL.md.tmpl files can break concurrent gstack sessions
-- During large refactors, remove the symlink (`rm .claude/skills/gstack`) so the
-  global install at `~/.claude/skills/gstack/` is used instead
-
-**Prefix setting:** Skill symlinks use either short names (`qa -> gstack/qa`) or
-namespaced (`gstack-qa -> gstack/qa`), controlled by `skill_prefix` in
-`~/.gstack/config.yaml`. When vendoring into a project, run `./setup` after
+- Template changes + `bun run gen:skill-docs` immediately affect all opengstack invocations
+- Breaking changes to SKILL.md.tmpl files can break concurrent opengstack sessions
+- During large refactors, remove the symlink (`rm .claude/skills/opengstack`) so the
+ global install at `~/.claude/skills/opengstack/` is used instead
+
+**Prefix setting:** Skill symlinks use either short names (`qa -> OpenGStack/qa`) or
+namespaced (`opengstack-qa -> OpenGStack/qa`), controlled by `skill_prefix` in
+`~/.opengstack/config.yaml`. When vendoring into a project, run `./setup` after
 symlinking to create the per-skill symlinks with your preferred naming. Pass
 `--no-prefix` or `--prefix` to skip the interactive prompt.
 
 **For plan reviews:** When reviewing plans that modify skill templates or the
 gen-skill-docs pipeline, consider whether the changes should be tested in isolation
-before going live (especially if the user is actively using gstack in other windows).
+before going live (especially if the user is actively using opengstack in other windows).
 
 ## Compiled binaries — NEVER commit browse/dist/ or design/dist/
 
@@ -226,14 +226,14 @@ changes into logical commits and push.
 When reviewing or merging community PRs, **always AskUserQuestion** before accepting
 any commit that:
 
-1. **Touches ETHOS.md** — this file is Garry's personal builder philosophy. No edits
-   from external contributors or AI agents, period.
+1. **Touches ETHOS.md** — this file is The project's builder philosophy. No edits
+ from external contributors or AI agents, period.
 2. **Removes or softens promotional material** — YC references, founder perspective,
-   and product voice are intentional. PRs that frame these as "unnecessary" or
-   "too promotional" must be rejected.
-3. **Changes Garry's voice** — the tone, humor, directness, and perspective in skill
-   templates, CHANGELOG, and docs are not generic. PRs that rewrite voice to be
-   more "neutral" or "professional" must be rejected.
+ and product voice are intentional. PRs that frame these as "unnecessary" or
+ "too promotional" must be rejected.
+3. **Changes The author's voice** — the tone, humor, directness, and perspective in skill
+ templates, CHANGELOG, and docs are not generic. PRs that rewrite voice to be
+ more "neutral" or "professional" must be rejected.
 
 Even if the agent strongly believes a change improves the project, these three
 categories require explicit user approval via AskUserQuestion. No exceptions.
@@ -249,31 +249,48 @@ not what was already on main.
 - At `/ship` time (Step 5), not during development or mid-branch.
 - The entry covers ALL commits on this branch vs the base branch.
 - Never fold new work into an existing CHANGELOG entry from a prior version that
-  already landed on main. If main has v0.10.0.0 and your branch adds features,
-  bump to v0.10.1.0 with a new entry — don't edit the v0.10.0.0 entry.
+ already landed on main. If main has v0.10.0.0 and your branch adds features,
+ bump to v0.10.1.0 with a new entry — don't edit the v0.10.0.0 entry.
 
 **Key questions before writing:**
 1. What branch am I on? What did THIS branch change?
 2. Is the base branch version already released? (If yes, bump and create new entry.)
 3. Does an existing entry on this branch already cover earlier work? (If yes, replace
-   it with one unified entry for the final version.)
+ it with one unified entry for the final version.)
+
+**Merging main does NOT mean adopting main's version.** When you merge origin/main into
+a feature branch, main may bring new CHANGELOG entries and a higher VERSION. Your branch
+still needs its OWN version bump on top. If main is at v0.13.8.0 and your branch adds
+features, bump to v0.13.9.0 with a new entry. Never jam your changes into an entry that
+already landed on main. Your entry goes on top because your branch lands next.
+
+**After merging main, always check:**
+- Does CHANGELOG have your branch's own entry separate from main's entries?
+- Is VERSION higher than main's VERSION?
+- Is your entry the topmost entry in CHANGELOG (above main's latest)?
+If any answer is no, fix it before continuing.
+
+**After any CHANGELOG edit that moves, adds, or removes entries,** immediately run
+`grep "^## \[" CHANGELOG.md` and verify the full version sequence is contiguous
+with no gaps or duplicates before committing. If a version is missing, the edit
+broke something. Fix it before moving on.
 
 CHANGELOG.md is **for users**, not contributors. Write it like product release notes:
 
 - Lead with what the user can now **do** that they couldn't before. Sell the feature.
 - Use plain language, not implementation details. "You can now..." not "Refactored the..."
 - **Never mention TODOS.md, internal tracking, eval infrastructure, or contributor-facing
-  details.** These are invisible to users and meaningless to them.
+ details.** These are invisible to users and meaningless to them.
 - Put contributor/internal changes in a separate "For contributors" section at the bottom.
 - Every entry should make someone think "oh nice, I want to try that."
 - No jargon: say "every question now tells you which project and branch you're in" not
-  "AskUserQuestion format standardized across skill templates via preamble resolver."
+ "AskUserQuestion format standardized across skill templates via preamble resolver."
 
 ## AI effort compression
 
-When estimating or discussing effort, always show both human-team and CC+gstack time:
+When estimating or discussing effort, always show both human-team and CC+opengstack time:
 
-| Task type | Human team | CC+gstack | Compression |
+| Task type | Human team | CC+opengstack | Compression |
 |-----------|-----------|-----------|-------------|
 | Boilerplate / scaffolding | 2 days | 15 min | ~100x |
 | Test writing | 1 day | 15 min | ~50x |
@@ -301,7 +318,7 @@ builder philosophy.
 
 ## Local plans
 
-Contributors can store long-range vision docs and design documents in `~/.gstack-dev/plans/`.
+Contributors can store long-range vision docs and design documents in `~/.opengstack-dev/plans/`.
 These are local-only (not checked in). When reviewing TODOS.md, check `plans/` for candidates
 that may be ready to promote to TODOs or implement.
 
@@ -316,7 +333,7 @@ regenerated SKILL.md shifts prompt context.
 1. Run the same eval on main (or base branch) and show it fails there too
 2. If it passes on main but fails on the branch — it IS your change. Trace the blame.
 3. If you can't run on main, say "unverified — may or may not be related" and flag it
-   as a risk in the PR body
+ as a risk in the PR body
 
 "Pre-existing" without receipts is a lazy claim. Prove it or don't say it.
 
@@ -359,12 +376,12 @@ Also when running targeted E2E tests to debug failures:
 
 ## Deploying to the active skill
 
-The active skill lives at `~/.claude/skills/gstack/`. After making changes:
+The active skill lives at `~/.claude/skills/opengstack/`. After making changes:
 
 1. Push your branch
-2. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main`
-3. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
+2. Fetch and reset in the skill directory: `cd ~/.claude/skills/opengstack && git fetch origin && git reset --hard origin/main`
+3. Rebuild: `cd ~/.claude/skills/opengstack && bun run build`
 
 Or copy the binaries directly:
-- `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
-- `cp design/dist/design ~/.claude/skills/gstack/design/dist/design`
+- `cp browse/dist/browse ~/.claude/skills/opengstack/browse/dist/browse`
+- `cp design/dist/design ~/.claude/skills/opengstack/design/dist/design`

package/README.md

@@ -13,9 +13,9 @@ Skills auto-install to `~/.claude/skills/` via symlink.
 ## CLI
 
 ```bash
-opengstack --help       # Show all commands
-opengstack --list       # List available skills
-opengstack --install    # Re-install skills (if needed)
+opengstack --help # Show all commands
+opengstack --list # List available skills
+opengstack --install # Re-install skills (if needed)
 ```
 
 ## Usage
@@ -29,6 +29,8 @@ In opencode/Claude, type any skill name with `/`:
 | `/plan-eng-review` | Lock architecture & edge cases |
 | `/plan-design-review` | Rate design decisions 0-10 |
 | `/design-consultation` | Build a design system from scratch |
+| `/design-shotgun` | Generate multiple design variants |
+| `/design-html` | Production HTML with Pretext |
 | `/design-review` | Design audit + fix loop |
 | `/review` | Pre-landing PR review |
 | `/investigate` | Root-cause debugging |
@@ -40,6 +42,8 @@ In opencode/Claude, type any skill name with `/`:
 | `/retro` | Weekly engineering retrospective |
 | `/browse` | Headless browser (real Chromium) |
 | `/setup-browser-cookies` | Import cookies for auth testing |
+| `/setup-deploy` | One-time deploy configurator |
+| `/connect-chrome` | Launch Chrome with side panel |
 | `/careful` | Warn before destructive ops |
 | `/freeze` | Lock edits to one directory |
 | `/guard` | Activate careful + freeze |
@@ -49,10 +53,11 @@ In opencode/Claude, type any skill name with `/`:
 | `/canary` | Post-deploy monitoring |
 | `/benchmark` | Performance regression detection |
 | `/cso` | Security audit |
+| `/learn` | Manage project learnings |
 
-## Why OpenGStack?
+## Why opengstack?
 
-Forked from [garrytan/gstack](https://github.com/garrytan/gstack) with telemetry and vendor references removed. Your usage stays local.
+Forked from gstack with telemetry and vendor references removed. Your usage stays local.
 
 ## License