@runchr/gstack-antigravity 0.1.1 → 0.1.3

package/.agents/skills/gstack/ETHOS.md

@@ -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.

package/.agents/skills/gstack/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garry Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.agents/skills/gstack/README.md

@@ -0,0 +1,228 @@
+# gstack
+
+> "I don't think I've typed like a line of code probably since December, basically, which is an extremely large change." — [Andrej Karpathy](https://fortune.com/2026/03/21/andrej-karpathy-openai-cofounder-ai-agents-coding-state-of-psychosis-openclaw/), No Priors podcast, March 2026
+
+When I heard Karpathy say this, I wanted to find out how. How does one person ship like a team of twenty? Peter Steinberger built [OpenClaw](https://github.com/openclaw/openclaw) — 247K GitHub stars — essentially solo with AI agents. The revolution is here. A single builder with the right tooling can move faster than a traditional team.
+
+I'm [Garry Tan](https://x.com/garrytan), President & CEO of [Y Combinator](https://www.ycombinator.com/). I've worked with thousands of startups — Coinbase, Instacart, Rippling — when they were one or two people in a garage. Before YC, I was one of the first eng/PM/designers at Palantir, cofounded Posterous (sold to Twitter), and built Bookface, YC's internal social network.
+
+**gstack is my answer.** I've been building products for twenty years, and right now I'm shipping more code than I ever have. In the last 60 days: **600,000+ lines of production code** (35% tests), **10,000-20,000 lines per day**, part-time, while running YC full-time. Here's my last `/retro` across 3 projects: **140,751 lines added, 362 commits, ~115k net LOC** in one week.
+
+**2026 — 1,237 contributions and counting:**
+
+![GitHub contributions 2026 — 1,237 contributions, massive acceleration in Jan-Mar](docs/images/github-2026.png)
+
+**2013 — when I built Bookface at YC (772 contributions):**
+
+![GitHub contributions 2013 — 772 contributions building Bookface at YC](docs/images/github-2013.png)
+
+Same person. Different era. The difference is the tooling.
+
+**gstack is how I do it.** It turns Claude Code into a virtual engineering team — a CEO who rethinks the product, an eng manager who locks architecture, a designer who catches AI slop, a reviewer who finds production bugs, a QA lead who opens a real browser, a security officer who runs OWASP + STRIDE audits, and a release engineer who ships the PR. Twenty specialists and eight power tools, all slash commands, all Markdown, all free, MIT license.
+
+This is my open source software factory. I use it every day. I'm sharing it because these tools should be available to everyone.
+
+Fork it. Improve it. Make it yours. And if you want to hate on free open source software — you're welcome to, but I'd rather you just try it first.
+
+**Who this is for:**
+- **Founders and CEOs** — especially technical ones who still want to ship
+- **First-time Claude Code users** — structured roles instead of a blank prompt
+- **Tech leads and staff engineers** — rigorous review, QA, and release automation on every PR
+
+## Quick start
+
+1. Install gstack (30 seconds — see below)
+2. Run `/office-hours` — describe what you're building
+3. Run `/plan-ceo-review` on any feature idea
+4. Run `/review` on any branch with changes
+5. Run `/qa` on your staging URL
+6. Stop there. You'll know if this is for you.
+
+## Install — 30 seconds
+
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) v1.0+, [Node.js](https://nodejs.org/) (Windows only)
+
+### Step 1: Install on your machine
+
+Open Claude Code and paste this. Claude does the rest.
+
+> Install gstack: run **`git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it.
+
+### Step 2: Add to your repo so teammates get it (optional)
+
+> Add gstack to this project: run **`cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup`** then add a "gstack" section to this project's CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, and tells Claude that if gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.
+
+Real files get committed to your repo (not a submodule), so `git clone` just works. Everything lives inside `.claude/`. Nothing touches your PATH or runs in the background.
+
+### Codex, Gemini CLI, or Cursor
+
+gstack works on any agent that supports the [SKILL.md standard](https://github.com/anthropics/claude-code). Skills live in `.agents/skills/` and are discovered automatically.
+
+```bash
+git clone https://github.com/garrytan/gstack.git ~/.codex/skills/gstack
+cd ~/.codex/skills/gstack && ./setup --host codex
+```
+
+Or let setup auto-detect which agents you have installed:
+
+```bash
+git clone https://github.com/garrytan/gstack.git ~/gstack
+cd ~/gstack && ./setup --host auto
+```
+
+This installs to `~/.claude/skills/gstack` and/or `~/.codex/skills/gstack` depending on what's available. All 28 skills work across all supported agents. Hook-based safety skills (careful, freeze, guard) use inline safety advisory prose on non-Claude hosts.
+
+## See it work
+
+```
+You:    I want to build a daily briefing app for my calendar.
+You:    /office-hours
+Claude: [asks about the pain — specific examples, not hypotheticals]
+
+You:    Multiple Google calendars, events with stale info, wrong locations.
+        Prep takes forever and the results aren't good enough...
+
+Claude: I'm going to push back on the framing. You said "daily briefing
+        app." But what you actually described is a personal chief of
+        staff AI.
+        [extracts 5 capabilities you didn't realize you were describing]
+        [challenges 4 premises — you agree, disagree, or adjust]
+        [generates 3 implementation approaches with effort estimates]
+        RECOMMENDATION: Ship the narrowest wedge tomorrow, learn from
+        real usage. The full vision is a 3-month project — start with
+        the daily briefing that actually works.
+        [writes design doc → feeds into downstream skills automatically]
+
+You:    /plan-ceo-review
+        [reads the design doc, challenges scope, runs 10-section review]
+
+You:    /plan-eng-review
+        [ASCII diagrams for data flow, state machines, error paths]
+        [test matrix, failure modes, security concerns]
+
+You:    Approve plan. Exit plan mode.
+        [writes 2,400 lines across 11 files. ~8 minutes.]
+
+You:    /review
+        [AUTO-FIXED] 2 issues. [ASK] Race condition → you approve fix.
+
+You:    /qa https://staging.myapp.com
+        [opens real browser, clicks through flows, finds and fixes a bug]
+
+You:    /ship
+        Tests: 42 → 51 (+9 new). PR: github.com/you/app/pull/42
+```
+
+You said "daily briefing app." The agent said "you're building a chief of staff AI" — because it listened to your pain, not your feature request. Eight commands, end to end. That is not a copilot. That is a team.
+
+## The sprint
+
+gstack is a process, not a collection of tools. The skills run in the order a sprint runs:
+
+**Think → Plan → Build → Review → Test → Ship → Reflect**
+
+Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-ceo-review` reads. `/plan-eng-review` writes a test plan that `/qa` picks up. `/review` catches bugs that `/ship` verifies are fixed. Nothing falls through the cracks because every step knows what came before it.
+
+| Skill | Your specialist | What they do |
+|-------|----------------|--------------|
+| `/office-hours` | **YC Office Hours** | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. Design doc feeds into every downstream skill. |
+| `/plan-ceo-review` | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. |
+| `/plan-eng-review` | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. |
+| `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. |
+| `/design-consultation` | **Design Partner** | Build a complete design system from scratch. Researches the landscape, proposes creative risks, generates realistic product mockups. |
+| `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. |
+| `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
+| `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
+| `/qa` | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
+| `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Pure bug report without code changes. |
+| `/cso` | **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 17 false positive exclusions, 8/10+ confidence gate, independent finding verification. Each finding includes a concrete exploit scenario. |
+| `/ship` | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. |
+| `/land-and-deploy` | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
+| `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. |
+| `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |
+| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
+| `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). |
+| `/browse` | **QA Engineer** | Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
+| `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
+| `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. |
+
+### Power tools
+
+| Skill | What it does |
+|-------|-------------|
+| `/codex` | **Second Opinion** — independent code review from OpenAI Codex CLI. Three modes: review (pass/fail gate), adversarial challenge, and open consultation. Cross-model analysis when both `/review` and `/codex` have run. |
+| `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). Say "be careful" to activate. Override any warning. |
+| `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. |
+| `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. |
+| `/unfreeze` | **Unlock** — remove the `/freeze` boundary. |
+| `/setup-deploy` | **Deploy Configurator** — one-time setup for `/land-and-deploy`. Detects your platform, production URL, and deploy commands. |
+| `/gstack-upgrade` | **Self-Updater** — upgrade gstack to latest. Detects global vs vendored install, syncs both, shows what changed. |
+
+**[Deep dives with examples and philosophy for every skill →](docs/skills.md)**
+
+## Parallel sprints
+
+gstack works well with one sprint. It gets interesting with ten running at once.
+
+[Conductor](https://conductor.build) runs multiple Claude Code sessions in parallel — each in its own isolated workspace. One session on `/office-hours`, another on `/review`, a third implementing a feature, a fourth running `/qa`. All at the same time. The sprint structure is what makes parallelism work — without a process, ten agents is ten sources of chaos. With a process, each agent knows exactly what to do and when to stop.
+
+---
+
+Free, MIT licensed, open source. No premium tier, no waitlist.
+
+I open sourced how I build software. You can fork it and make it your own.
+
+> **We're hiring.** Want to ship 10K+ LOC/day and help harden gstack?
+> Come work at YC — [ycombinator.com/software](https://ycombinator.com/software)
+> Extremely competitive salary and equity. San Francisco, Dogpatch District.
+
+## Docs
+
+| Doc | What it covers |
+|-----|---------------|
+| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
+| [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Lake, Search Before Building, three layers of knowledge |
+| [Architecture](ARCHITECTURE.md) | Design decisions and system internals |
+| [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
+| [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |
+| [Changelog](CHANGELOG.md) | What's new in every version |
+
+## Privacy & Telemetry
+
+gstack includes **opt-in** usage telemetry to help improve the project. Here's exactly what happens:
+
+- **Default is off.** Nothing is sent anywhere unless you explicitly say yes.
+- **On first run,** gstack asks if you want to share anonymous usage data. You can say no.
+- **What's sent (if you opt in):** skill name, duration, success/fail, gstack version, OS. That's it.
+- **What's never sent:** code, file paths, repo names, branch names, prompts, or any user-generated content.
+- **Change anytime:** `gstack-config set telemetry off` disables everything instantly.
+
+Data is stored in [Supabase](https://supabase.com) (open source Firebase alternative). The schema is in [`supabase/migrations/001_telemetry.sql`](supabase/migrations/001_telemetry.sql) — you can verify exactly what's collected. The Supabase publishable key in the repo is a public key (like a Firebase API key) — row-level security policies restrict it to insert-only access.
+
+**Local analytics are always available.** Run `gstack-analytics` to see your personal usage dashboard from the local JSONL file — no remote data needed.
+
+## Troubleshooting
+
+**Skill not showing up?** `cd ~/.claude/skills/gstack && ./setup`
+
+**`/browse` fails?** `cd ~/.claude/skills/gstack && bun install && bun run build`
+
+**Stale install?** Run `/gstack-upgrade` — or set `auto_upgrade: true` in `~/.gstack/config.yaml`
+
+**Windows users:** gstack works on Windows 11 via Git Bash or WSL. Node.js is required in addition to Bun — Bun has a known bug with Playwright's pipe transport on Windows ([bun#4253](https://github.com/oven-sh/bun/issues/4253)). The browse server automatically falls back to Node.js. Make sure both `bun` and `node` are on your PATH.
+
+**Claude says it can't see the skills?** Make sure your project's `CLAUDE.md` has a gstack section. Add this:
+
+```
+## gstack
+Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.
+Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
+/design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse,
+/qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro,
+/investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard,
+/unfreeze, /gstack-upgrade.
+```
+
+## License
+
+MIT. Free forever. Go build something.