From 18fc95c0a0c016a4181967470e704cfbd603cf28 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 18 Apr 2026 11:38:57 +0800 Subject: [PATCH] docs(v1): README hero reframe + writing-style + CHANGELOG + version bump to 1.0.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: - Hero removes "600,000+ lines of production code" framing; replaces with the computed 2013-vs-2026 pro-rata multiple (via anchor, filled by the update-readme-throughput build step). - Hiring callout: "ship real products at AI-coding speed" instead of "10K+ LOC/day." - New Writing Style section (~80 words) between Quick start and Install: "v1 prompts = simpler" framing, outcome-language example, terse-mode opt-out, pointer to /plan-tune. CLAUDE.md: one-paragraph Writing style (V1) note under project conventions, linking to preamble resolver + V1 design docs. CHANGELOG.md: V1 entry on top of v0.19.0.0 with user-facing narrative (what changes, how to opt out, for-contributors notes). Mentions scope reduction — pacing overhaul ships in V1.1. CONTRIBUTING.md: one-paragraph note on jargon-list.json maintenance (PR to add/remove terms; regenerate via gen:skill-docs). VERSION + package.json: bump to 1.0.0.0. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 24 ++++++++++++++++++++++++ CLAUDE.md | 12 ++++++++++++ CONTRIBUTING.md | 19 +++++++++++++++++++ README.md | 8 ++++++-- VERSION | 2 +- package.json | 2 +- 6 files changed, 63 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8eb93af8..02ca09c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## [1.0.0.0] - 2026-04-18 + +### Added +- **v1 prompts = simpler.** Every skill's output (tier 2 and up) explains technical terms on first use with a one-sentence gloss, frames questions in outcome terms ("what breaks for your users if..." instead of "is this endpoint idempotent?"), and keeps sentences short and direct. Good writing for everyone — not just non-technical folks. Engineers benefit too. +- **Terse opt-out for power users.** `gstack-config set explain_level terse` switches every skill back to the older, tighter prose style — no glosses, no outcome-framing layer. Binary switch, sticks across all skills. +- **Curated jargon list.** A repo-owned list of ~50 technical terms (idempotent, race condition, N+1, backpressure, and friends) at `scripts/jargon-list.json`. These are the terms gstack glosses. Terms not on the list are assumed plain-English enough. Add terms via PR. +- **Real LOC receipts in the README.** Replaced the "600,000+ lines of production code" hero framing with a computed 2013-vs-2026 pro-rata multiple on logical code change, with honest caveats about public-vs-private repos. The script that computes it is at `scripts/garry-output-comparison.ts` and uses [scc](https://github.com/boyter/scc). Raw LOC is still in `/retro` output for context, just no longer the headline. +- **Smarter `/retro` metrics.** `/retro` now leads with features shipped, commits, and PRs merged — logical SLOC added comes next, and raw LOC is demoted to context-only. Because ten lines of a good fix is not less shipping than ten thousand lines of scaffold. +- **Upgrade prompt on first run.** When you upgrade to this version, the first skill you run will ask once whether you want to keep the new default writing style or restore V0 prose with `gstack-config set explain_level terse`. One-time, flag-file gated, never asks again. + +### Changed +- **README hero reframed.** No more "10K-20K lines per day" claim. Focuses on products shipped + features + the pro-rata multiple on logical code change, which is the honest metric now that AI writes most of the code. The point isn't who typed it, it's what shipped. +- **Hiring callout reframed.** Replaced "ship 10K+ LOC/day" with "ship real products at AI-coding speed." + +### For contributors +- New `scripts/resolvers/preamble.ts` Writing Style section, injected for tier ≥ 2 skills. Composes with the existing AskUserQuestion Format section (Format = how the question is structured, Style = the prose quality of the content inside). Jargon list is baked into generated SKILL.md prose at `gen-skill-docs` time — zero runtime cost, edit the JSON and regenerate. +- New `bin/gstack-config` validation for `explain_level` values. Unknown values print a warning and default to `default`. Annotated header documents the new key. +- New one-shot upgrade migration at `gstack-upgrade/migrations/v1.0.0.0.sh`, matching existing `v0.15.2.0.sh` / `v0.16.2.0.sh` pattern. Flag-file gated. +- New throughput pipeline: `scripts/garry-output-comparison.ts` (scc preflight + author-scoped SLOC across 2013 + 2026), `scripts/update-readme-throughput.ts` (reads the JSON, replaces `` anchor), `scripts/setup-scc.sh` (OS-detecting installer invoked only when running the throughput script — scc is not a package.json dependency). +- Two-string marker pattern in README to prevent the pipeline from destroying its own update path: `GSTACK-THROUGHPUT-PLACEHOLDER` (stable anchor) vs `GSTACK-THROUGHPUT-PENDING` (explicit missing-build marker CI rejects). +- V0 dormancy negative tests — the 5D psychographic dimensions (scope_appetite, risk_tolerance, detail_preference, autonomy, architecture_care) and 8 archetype names (Cathedral Builder, Ship-It Pragmatist, Deep Craft, Taste Maker, Solo Operator, Consultant, Wedge Hunter, Builder-Coach) must not appear in default-mode skill output. Keeps the V0 machinery dormant until V2. +- **Pacing improvements ship in V1.1.** The scope originally considered (review ranking, Silent Decisions block, max-3-per-phase cap, flip mechanism) was extracted to `docs/designs/PACING_UPDATES_V0.md` after three engineering-review passes revealed structural gaps that couldn't be closed with plan-text editing. V1.1 picks it up with real V1 baseline data. +- Design doc: `docs/designs/PLAN_TUNING_V1.md`. Full review history: CEO + Codex (×2 passes, 45 findings integrated) + DX (TRIAGE) + Eng (×3 passes — last pass drove the scope reduction). + ## [0.19.0.0] - 2026-04-17 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 074b6122..fb60358e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -179,6 +179,18 @@ Rules: - **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." +## Writing style (V1) + +Default output from every tier-≥2 skill follows the Writing Style section in +`scripts/resolvers/preamble.ts`: jargon glossed on first use (curated list in +`scripts/jargon-list.json`, baked at gen-skill-docs time), questions framed in +outcome terms ("what breaks for your users if...") not implementation terms, +short sentences, decisions close with user impact. Power users who want the +tighter V0 prose set `gstack-config set explain_level terse` (binary switch, +no middle mode). See `docs/designs/PLAN_TUNING_V1.md` for the full design +rationale. The review pacing overhaul that originally tried to ride alongside +writing-style was extracted to V1.1 — see `docs/designs/PACING_UPDATES_V0.md`. + ## Browser interaction When you need to interact with a browser (QA, dogfooding, cookie setup), use the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 15378e21..256de8b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -230,6 +230,25 @@ For template authoring best practices (natural language over bash-isms, dynamic To add a browse command, add it to `browse/src/commands.ts`. To add a snapshot flag, add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts`. Then rebuild. +## Jargon list (V1 writing style) + +gstack's Writing Style section (injected into every tier-≥2 skill's preamble) +glosses technical terms on first use per skill invocation. The list of terms +that qualify for glossing lives at `scripts/jargon-list.json` — ~50 curated +high-frequency terms (idempotent, race condition, N+1, backpressure, etc.). +Terms not on the list are assumed plain-English enough. + +**Adding or removing a term:** open a PR editing `scripts/jargon-list.json`. +Run `bun run gen:skill-docs` after the edit — terms are baked into every +generated SKILL.md at gen time, so changes take effect only after regeneration. +No runtime loading; no user-side override. The repo list is the source of truth. + +Good candidates for addition: high-frequency terms that non-technical users +encounter in review output without context (common database/concurrency +terminology, security jargon, frontend framework concepts). Don't add terms +that only appear in one or two niche skills — the cost-to-value trade isn't +worth the review overhead. + ## Multi-host development gstack generates SKILL.md files for 8 hosts from one set of `.tmpl` templates. diff --git a/README.md b/README.md index d0065930..f173a8f5 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ When I heard Karpathy say this, I wanted to find out how. How does one person sh 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. +**gstack is my answer.** I've been building products for twenty years, and right now I'm shipping more products than I ever have. In the last 60 days: 3 production services, 40+ shipped features, part-time, while running YC full-time. On logical code change — not raw LOC, which AI inflates — my 2026 output is my 2013 output pro-rata. (Public repos only; private work at both eras is excluded to make the comparison apples-to-apples.) AI wrote most of it. The point isn't who typed it, it's what shipped. **2026 — 1,237 contributions and counting:** @@ -38,6 +38,10 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source 5. Run `/qa` on your staging URL 6. Stop there. You'll know if this is for you. +## Writing style + +v1 prompts = simpler. gstack's default output explains technical terms on first use, frames questions in outcome terms ("what breaks for your users if..."), and keeps sentences short. Good writing for everyone, not just non-technical folks. If you'd rather read the older, tighter prose style with no glosses, run `gstack-config set explain_level terse` — it sticks across all skills. You can also tune how often gstack asks you questions with `/plan-tune`. + ## 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) @@ -349,7 +353,7 @@ 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? +> **We're hiring.** Want to ship real products at AI-coding speed and help harden gstack? > Come work at YC — [ycombinator.com/software](https://ycombinator.com/software) > Extremely competitive salary and equity. San Francisco, Dogpatch District. diff --git a/VERSION b/VERSION index b4ee4869..1921233b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.19.0.0 +1.0.0.0 diff --git a/package.json b/package.json index bb0b5cc3..cfc1703c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "0.19.0.0", + "version": "1.0.0.0", "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.", "license": "MIT", "type": "module",