diff --git a/CHANGELOG.md b/CHANGELOG.md index 327811a2..0707a58c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,25 +1,25 @@ # Changelog -## [0.13.9.0] - 2026-03-29 — Sidebar CSS Inspector + Per-Tab Agents +## [0.13.11.0] - 2026-03-30 — Sidebar CSS Inspector + Per-Tab Agents -The sidebar is now a visual design tool. Pick any element on the page and see the full CSS rule cascade, box model, and computed styles right in the Side Panel. Edit styles live and see changes instantly. Each browser tab gets its own independent agent, so you can work on multiple pages simultaneously without cross-talk. +The sidebar is now a visual design tool. Pick any element on the page and see the full CSS rule cascade, box model, and computed styles right in the Side Panel. Edit styles live and see changes instantly. Each browser tab gets its own independent agent, so you can work on multiple pages simultaneously without cross-talk. Cleanup is LLM-powered... the agent snapshots the page, understands it semantically, and removes the junk while keeping the site's identity. ### Added - **CSS Inspector in the sidebar.** Click "Pick Element", hover over anything, click it, and the sidebar shows the full CSS rule cascade with specificity badges, source file:line, box model visualization (gstack palette colors), and computed styles. Like Chrome DevTools, but inside the sidebar. - **Live style editing.** `$B style .selector property value` modifies CSS rules in real time via CDP. Changes show instantly on the page. Undo with `$B style --undo`. -- **Per-tab agents.** Each browser tab gets its own Claude agent process. Switch tabs in the browser and the sidebar swaps to that tab's chat history. Ask questions about different pages in parallel without agents fighting over which tab is active. -- **Tab tracking.** User-created tabs (Cmd+T, right-click "Open in new tab") are automatically tracked. The sidebar tab bar updates in real time. Click a tab in the sidebar to switch the browser. Close a tab and it disappears from the bar. -- **Page cleanup.** `$B cleanup --all` removes ads, cookie banners, sticky headers, and social widgets for clean screenshots. +- **Per-tab agents.** Each browser tab gets its own Claude agent process via `BROWSE_TAB` env var. Switch tabs in the browser and the sidebar swaps to that tab's chat history. Ask questions about different pages in parallel without agents fighting over which tab is active. +- **Tab tracking.** User-created tabs (Cmd+T, right-click "Open in new tab") are automatically tracked via `context.on('page')`. The sidebar tab bar updates in real time. Click a tab in the sidebar to switch the browser. Close a tab and it disappears. +- **LLM-powered page cleanup.** The cleanup button sends a prompt to the sidebar agent (which IS an LLM). The agent runs a deterministic first pass, snapshots the page, analyzes what's left, and removes clutter intelligently while preserving site branding. Works on any site without brittle CSS selectors. - **Pretty screenshots.** `$B prettyscreenshot --cleanup --scroll-to ".pricing" ~/Desktop/hero.png` combines cleanup, scroll positioning, and screenshot in one command. - **Stop button.** A red stop button appears in the sidebar when an agent is working. Click it to cancel the current task. - **CSP fallback for inspector.** Sites with strict Content Security Policy (like SF Chronicle) now get a basic picker via the always-loaded content script. You see computed styles, box model, and same-origin CSS rules. Full CDP mode on sites that allow it. -- **Cleanup button in sidebar.** One click removes ads, cookie banners, sticky headers, and social widgets. Spinner while it works, notification when done. -- **Screenshot button in sidebar.** One click captures a screenshot. Shows the saved file path in the chat. +- **Cleanup + Screenshot buttons in chat toolbar.** Not hidden in debug... right there in the chat. Disabled when disconnected so you don't get error spam. ### Fixed - **Inspector message allowlist.** The background.js allowlist was missing all inspector message types, silently rejecting them. The inspector was broken for all pages, not just CSP-restricted ones. (Found by Codex review.) +- **Sticky nav preservation.** Cleanup no longer removes the site's top nav bar. Sorts sticky elements by position and preserves the first full-width element near the top. ### Changed @@ -27,6 +27,44 @@ The sidebar is now a visual design tool. Pick any element on the page and see th - **Input placeholder** is "Ask about this page..." (more inviting than the old placeholder). - **System prompt** includes prompt injection defense and allowed-commands whitelist from the security audit. +## [0.13.10.0] - 2026-03-29 — Office Hours Gets a Reading List + +Repeat /office-hours users now get fresh, curated resources every session instead of the same YC closing. 34 hand-picked videos and essays from Garry Tan, Lightcone Podcast, YC Startup School, and Paul Graham, contextually matched to what came up during the session. The system remembers what it already showed you, so you never see the same recommendation twice. + +### Added + +- **Rotating founder resources in /office-hours closing.** 34 curated resources across 5 categories (Garry Tan videos, YC Backstory, Lightcone Podcast, YC Startup School, Paul Graham essays). Claude picks 2-3 per session based on session context, not randomly. +- **Resource dedup log.** Tracks which resources were shown in `~/.gstack/projects/$SLUG/resources-shown.jsonl` so repeat users always see fresh content. +- **Resource selection analytics.** Logs which resources get picked to `skill-usage.jsonl` so you can see patterns over time. +- **Browser-open offer.** After showing resources, offers to open them in your browser so you can check them out later. + +### Fixed + +- **Build script chmod safety net.** `bun build --compile` output now gets `chmod +x` explicitly, preventing "permission denied" errors when binaries lose execute permission during workspace cloning or file transfer. + +## [0.13.9.0] - 2026-03-29 — Composable Skills + +Skills can now load other skills inline. Write `{{INVOKE_SKILL:office-hours}}` in a template and the generator emits the right "read file, skip preamble, follow instructions" prose automatically. Handles host-aware paths and customizable skip lists. + +### Added + +- **`{{INVOKE_SKILL:skill-name}}` resolver.** Composable skill loading as a first-class resolver. Emits host-aware prose that tells Claude or Codex to read another skill's SKILL.md and follow it inline, skipping preamble sections. Supports optional `skip=` parameter for additional sections to skip. +- **Parameterized resolver support.** The placeholder regex now handles `{{NAME:arg1:arg2}}`, enabling resolvers that take arguments at generation time. Fully backward compatible with existing `{{NAME}}` patterns. +- **`{{CHANGELOG_WORKFLOW}}` resolver.** Changelog generation logic extracted from /ship into a reusable resolver. Includes voice guidance ("lead with what the user can now do") inline. +- **Frontmatter `name:` for skill registration.** Setup script and gen-skill-docs now read `name:` from SKILL.md frontmatter for symlink naming. Enables directory names that differ from invocation names (e.g., `run-tests/` directory registered as `/test`). +- **Proactive skill routing.** Skills now ask once to add routing rules to your project's CLAUDE.md. This makes Claude invoke the right skill automatically instead of answering directly. Your choice is remembered in `~/.gstack/config.yaml`. +- **Annotated config file.** `~/.gstack/config.yaml` now gets a documented header on first creation explaining every setting. Edit it anytime. + +### Changed + +- **BENEFITS_FROM now delegates to INVOKE_SKILL.** Eliminated duplicated skip-list logic. The prerequisite offer wrapper stays in BENEFITS_FROM, but the actual "read and follow" instructions come from INVOKE_SKILL. +- **/plan-ceo-review mid-session fallback uses INVOKE_SKILL.** The "user can't articulate the problem, offer /office-hours" path now uses the composable resolver instead of inline prose. +- **Stronger routing language.** office-hours, investigate, and ship descriptions now say "Proactively invoke" instead of "Proactively suggest" for more reliable automatic skill invocation. + +### Fixed + +- **Config grep anchored to line start.** Commented header lines no longer shadow real config values. + ## [0.13.8.0] - 2026-03-29 — Security Audit Round 2 Browse output is now wrapped in trust boundary markers so agents can tell page content from tool output. Markers are escape-proof. The Chrome extension validates message senders. CDP binds to localhost only. Bun installs use checksum verification. diff --git a/CLAUDE.md b/CLAUDE.md index b5162aa9..362b8f32 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -258,6 +258,23 @@ not what was already on main. 3. Does an existing entry on this branch already cover earlier work? (If yes, replace 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. diff --git a/SKILL.md b/SKILL.md index 721653f5..9e6377f6 100644 --- a/SKILL.md +++ b/SKILL.md @@ -68,6 +68,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -149,6 +157,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice **Tone:** direct, concrete, sharp, never corporate, never academic. Sound like a builder, not a consultant. Name the file, the function, the command. No filler, no throat-clearing. @@ -271,28 +322,37 @@ Then write a `## GSTACK REVIEW REPORT` section to the end of the plan file: file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -If `PROACTIVE` is `false`: do NOT proactively suggest other gstack skills during this session. -Only run skills the user explicitly invokes. This preference persists across sessions via -`gstack-config`. +If `PROACTIVE` is `false`: do NOT proactively invoke or suggest other gstack skills during +this session. Only run skills the user explicitly invokes. This preference persists across +sessions via `gstack-config`. -If `PROACTIVE` is `true` (default): suggest adjacent gstack skills when relevant to the -user's workflow stage: -- Brainstorming → /office-hours -- Strategy → /plan-ceo-review -- Architecture → /plan-eng-review -- Design → /plan-design-review or /design-consultation -- Auto-review → /autoplan -- Debugging → /investigate -- QA → /qa -- Code review → /review -- Visual audit → /design-review -- Shipping → /ship -- Docs → /document-release -- Retro → /retro -- Second opinion → /codex -- Prod safety → /careful or /guard -- Scoped edits → /freeze or /unfreeze -- Upgrades → /gstack-upgrade +If `PROACTIVE` is `true` (default): **invoke the Skill tool** when the user's request +matches a skill's purpose. Do NOT answer directly when a skill exists for the task. +Use the Skill tool to invoke it. The skill has specialized workflows, checklists, and +quality gates that produce better results than answering inline. + +**Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** +- User describes a new idea, asks "is this worth building", wants to brainstorm → invoke `/office-hours` +- User asks about strategy, scope, ambition, "think bigger" → invoke `/plan-ceo-review` +- User asks to review architecture, lock in the plan → invoke `/plan-eng-review` +- User asks about design system, brand, visual identity → invoke `/design-consultation` +- User asks to review design of a plan → invoke `/plan-design-review` +- User wants all reviews done automatically → invoke `/autoplan` +- User reports a bug, error, broken behavior, asks "why is this broken" → invoke `/investigate` +- User asks to test the site, find bugs, QA → invoke `/qa` +- User asks to review code, check the diff, pre-landing review → invoke `/review` +- User asks about visual polish, design audit of a live site → invoke `/design-review` +- User asks to ship, deploy, push, create a PR → invoke `/ship` +- User asks to update docs after shipping → invoke `/document-release` +- User asks for a weekly retro, what did we ship → invoke `/retro` +- User asks for a second opinion, codex review → invoke `/codex` +- User asks for safety mode, careful mode → invoke `/careful` or `/guard` +- User asks to restrict edits to a directory → invoke `/freeze` or `/unfreeze` +- User asks to upgrade gstack → invoke `/gstack-upgrade` + +**Do NOT answer the user's question directly when a matching skill exists.** The skill +provides a structured, multi-step workflow that is always better than an ad-hoc answer. +Invoke the skill first. If no skill matches, answer directly as usual. If the user opts out of suggestions, run `gstack-config set proactive false`. If they opt back in, run `gstack-config set proactive true`. diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index fcc0900b..1c8f12a8 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -16,28 +16,37 @@ allowed-tools: {{PREAMBLE}} -If `PROACTIVE` is `false`: do NOT proactively suggest other gstack skills during this session. -Only run skills the user explicitly invokes. This preference persists across sessions via -`gstack-config`. +If `PROACTIVE` is `false`: do NOT proactively invoke or suggest other gstack skills during +this session. Only run skills the user explicitly invokes. This preference persists across +sessions via `gstack-config`. -If `PROACTIVE` is `true` (default): suggest adjacent gstack skills when relevant to the -user's workflow stage: -- Brainstorming → /office-hours -- Strategy → /plan-ceo-review -- Architecture → /plan-eng-review -- Design → /plan-design-review or /design-consultation -- Auto-review → /autoplan -- Debugging → /investigate -- QA → /qa -- Code review → /review -- Visual audit → /design-review -- Shipping → /ship -- Docs → /document-release -- Retro → /retro -- Second opinion → /codex -- Prod safety → /careful or /guard -- Scoped edits → /freeze or /unfreeze -- Upgrades → /gstack-upgrade +If `PROACTIVE` is `true` (default): **invoke the Skill tool** when the user's request +matches a skill's purpose. Do NOT answer directly when a skill exists for the task. +Use the Skill tool to invoke it. The skill has specialized workflows, checklists, and +quality gates that produce better results than answering inline. + +**Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** +- User describes a new idea, asks "is this worth building", wants to brainstorm → invoke `/office-hours` +- User asks about strategy, scope, ambition, "think bigger" → invoke `/plan-ceo-review` +- User asks to review architecture, lock in the plan → invoke `/plan-eng-review` +- User asks about design system, brand, visual identity → invoke `/design-consultation` +- User asks to review design of a plan → invoke `/plan-design-review` +- User wants all reviews done automatically → invoke `/autoplan` +- User reports a bug, error, broken behavior, asks "why is this broken" → invoke `/investigate` +- User asks to test the site, find bugs, QA → invoke `/qa` +- User asks to review code, check the diff, pre-landing review → invoke `/review` +- User asks about visual polish, design audit of a live site → invoke `/design-review` +- User asks to ship, deploy, push, create a PR → invoke `/ship` +- User asks to update docs after shipping → invoke `/document-release` +- User asks for a weekly retro, what did we ship → invoke `/retro` +- User asks for a second opinion, codex review → invoke `/codex` +- User asks for safety mode, careful mode → invoke `/careful` or `/guard` +- User asks to restrict edits to a directory → invoke `/freeze` or `/unfreeze` +- User asks to upgrade gstack → invoke `/gstack-upgrade` + +**Do NOT answer the user's question directly when a matching skill exists.** The skill +provides a structured, multi-step workflow that is always better than an ad-hoc answer. +Invoke the skill first. If no skill matches, answer directly as usual. If the user opts out of suggestions, run `gstack-config set proactive false`. If they opt back in, run `gstack-config set proactive true`. diff --git a/VERSION b/VERSION index 1ef377f3..202259fd 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.13.9.0 +0.13.11.0 diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index f827fcba..2754cef0 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -77,6 +77,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -158,6 +166,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. @@ -426,10 +477,11 @@ 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: -`~/.claude/skills/gstack/office-hours/SKILL.md` +Read the `/office-hours` skill file at `~/.claude/skills/gstack/office-hours/SKILL.md` using the Read tool. -Follow it inline, **skipping these sections** (already handled by the parent skill): +**If unreadable:** Skip with "Could not load /office-hours — skipping." and continue. + +Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill): - Preamble (run first) - AskUserQuestion Format - Completeness Principle — Boil the Lake @@ -437,9 +489,13 @@ Follow it inline, **skipping these sections** (already handled by the parent ski - Contributor Mode - Completion Status Protocol - Telemetry (run last) +- Step 0: Detect platform and base branch +- Review Readiness Dashboard +- Plan File Review Report +- Prerequisite Skill Offer +- Plan Status Footer -If the Read fails (file not found), say: -"Could not load /office-hours — proceeding with standard review." +Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below. After /office-hours completes, re-run the design doc check: ```bash diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index d2c7b4f7..8fe4bc94 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -70,6 +70,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -151,6 +159,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice **Tone:** direct, concrete, sharp, never corporate, never academic. Sound like a builder, not a consultant. Name the file, the function, the command. No filler, no throat-clearing. diff --git a/bin/gstack-config b/bin/gstack-config index 08549a29..c118a322 100755 --- a/bin/gstack-config +++ b/bin/gstack-config @@ -13,6 +13,38 @@ set -euo pipefail STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}" CONFIG_FILE="$STATE_DIR/config.yaml" +# Annotated header for new config files. Written once on first `set`. +CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on next skill run. +# Docs: https://github.com/garrytan/gstack +# +# ─── Behavior ──────────────────────────────────────────────────────── +# proactive: true # Auto-invoke skills when your request matches one. +# # Set to false to only run skills you type explicitly. +# +# routing_declined: false # Set to true to skip the CLAUDE.md routing injection +# # prompt. Set back to false to be asked again. +# +# ─── Telemetry ─────────────────────────────────────────────────────── +# telemetry: anonymous # off | anonymous | community +# # off — no data sent, no local analytics +# # anonymous — counter only, no device ID +# # community — usage data + stable device ID +# +# ─── Updates ───────────────────────────────────────────────────────── +# auto_upgrade: false # true = silently upgrade on session start +# update_check: true # false = suppress version check notifications +# +# ─── Skill naming ──────────────────────────────────────────────────── +# skill_prefix: false # true = namespace skills as /gstack-qa, /gstack-ship +# # false = short names /qa, /ship +# +# ─── Advanced ──────────────────────────────────────────────────────── +# codex_reviews: enabled # disabled = skip Codex adversarial reviews in /ship +# gstack_contributor: false # true = file field reports when gstack misbehaves +# skip_eng_review: false # true = skip eng review gate in /ship (not recommended) +# +' + case "${1:-}" in get) KEY="${2:?Usage: gstack-config get }" @@ -21,7 +53,7 @@ case "${1:-}" in echo "Error: key must contain only alphanumeric characters and underscores" >&2 exit 1 fi - grep -F "${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true + grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true ;; set) KEY="${2:?Usage: gstack-config set }" @@ -32,12 +64,16 @@ case "${1:-}" in exit 1 fi mkdir -p "$STATE_DIR" + # Write annotated header on first creation + if [ ! -f "$CONFIG_FILE" ]; then + printf '%s' "$CONFIG_HEADER" > "$CONFIG_FILE" + fi # Escape sed special chars in value and drop embedded newlines ESC_VALUE="$(printf '%s' "$VALUE" | head -1 | sed 's/[&/\]/\\&/g')" - if grep -qF "${KEY}:" "$CONFIG_FILE" 2>/dev/null; then + if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then # Portable in-place edit (BSD sed uses -i '', GNU sed uses -i without arg) _tmpfile="$(mktemp "${CONFIG_FILE}.XXXXXX")" - sed "s/^${KEY}:.*/${KEY}: ${ESC_VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE" + sed "/^${KEY}:/s/.*/${KEY}: ${ESC_VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE" else echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE" fi diff --git a/browse/SKILL.md b/browse/SKILL.md index 5c5177ca..9ad795bc 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -70,6 +70,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -151,6 +159,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice **Tone:** direct, concrete, sharp, never corporate, never academic. Sound like a builder, not a consultant. Name the file, the function, the command. No filler, no throat-clearing. diff --git a/browse/test/gstack-config.test.ts b/browse/test/gstack-config.test.ts index d3efc1ce..a00af609 100644 --- a/browse/test/gstack-config.test.ts +++ b/browse/test/gstack-config.test.ts @@ -135,4 +135,62 @@ describe('gstack-config', () => { const { stdout } = run(['get', 'test_special']); expect(stdout).toBe('a/b&c\\d'); }); + + // ─── annotated header ────────────────────────────────────── + test('first set writes annotated header with docs', () => { + run(['set', 'telemetry', 'off']); + const content = readFileSync(join(stateDir, 'config.yaml'), 'utf-8'); + expect(content).toContain('# gstack configuration'); + expect(content).toContain('edit freely'); + expect(content).toContain('proactive:'); + expect(content).toContain('telemetry:'); + expect(content).toContain('auto_upgrade:'); + expect(content).toContain('skill_prefix:'); + expect(content).toContain('routing_declined:'); + expect(content).toContain('codex_reviews:'); + expect(content).toContain('skip_eng_review:'); + }); + + test('header written only once, not duplicated on second set', () => { + run(['set', 'foo', 'bar']); + run(['set', 'baz', 'qux']); + const content = readFileSync(join(stateDir, 'config.yaml'), 'utf-8'); + const headerCount = (content.match(/# gstack configuration/g) || []).length; + expect(headerCount).toBe(1); + }); + + test('header does not break get on commented-out keys', () => { + run(['set', 'telemetry', 'community']); + // Header contains "# telemetry: anonymous" as a comment example. + // get should return the real value, not the comment. + const { stdout } = run(['get', 'telemetry']); + expect(stdout).toBe('community'); + }); + + test('existing config file is not overwritten with header', () => { + writeFileSync(join(stateDir, 'config.yaml'), 'existing: value\n'); + run(['set', 'new_key', 'new_value']); + const content = readFileSync(join(stateDir, 'config.yaml'), 'utf-8'); + expect(content).toContain('existing: value'); + expect(content).not.toContain('# gstack configuration'); + }); + + // ─── routing_declined ────────────────────────────────────── + test('routing_declined defaults to empty (not set)', () => { + const { stdout } = run(['get', 'routing_declined']); + expect(stdout).toBe(''); + }); + + test('routing_declined can be set and read', () => { + run(['set', 'routing_declined', 'true']); + const { stdout } = run(['get', 'routing_declined']); + expect(stdout).toBe('true'); + }); + + test('routing_declined can be reset to false', () => { + run(['set', 'routing_declined', 'true']); + run(['set', 'routing_declined', 'false']); + const { stdout } = run(['get', 'routing_declined']); + expect(stdout).toBe('false'); + }); }); diff --git a/canary/SKILL.md b/canary/SKILL.md index 59987e30..6197b3c4 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -70,6 +70,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -151,6 +159,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/codex/SKILL.md b/codex/SKILL.md index a3c82621..a3eb12cf 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -71,6 +71,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -152,6 +160,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/connect-chrome/SKILL.md b/connect-chrome/SKILL.md index 49abe502..c863b171 100644 --- a/connect-chrome/SKILL.md +++ b/connect-chrome/SKILL.md @@ -68,6 +68,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -149,6 +157,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/cso/SKILL.md b/cso/SKILL.md index 783a5ee0..3945884c 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -74,6 +74,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -155,6 +163,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 25ab6fbd..3901ada1 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -75,6 +75,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -156,6 +164,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 515efb30..c152835c 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -75,6 +75,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -156,6 +164,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index ac30aa5f..609907d6 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -72,6 +72,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -153,6 +161,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/document-release/SKILL.md b/document-release/SKILL.md index e7f80c9e..a1c6ede9 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -72,6 +72,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -153,6 +161,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 565cc640..ab940d17 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -7,8 +7,9 @@ description: | analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis". - Proactively suggest when the user reports errors, unexpected behavior, or - is troubleshooting why something stopped working. (gstack) + Proactively invoke this skill (do NOT debug directly) when the user reports + errors, 500 errors, stack traces, unexpected behavior, "it was working + yesterday", or is troubleshooting why something stopped working. (gstack) allowed-tools: - Bash - Read @@ -86,6 +87,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -167,6 +176,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/investigate/SKILL.md.tmpl b/investigate/SKILL.md.tmpl index 4da2a708..3004300e 100644 --- a/investigate/SKILL.md.tmpl +++ b/investigate/SKILL.md.tmpl @@ -7,8 +7,9 @@ description: | analyze, hypothesize, implement. Iron Law: no fixes without root cause. Use when asked to "debug this", "fix this bug", "why is this broken", "investigate this error", or "root cause analysis". - Proactively suggest when the user reports errors, unexpected behavior, or - is troubleshooting why something stopped working. (gstack) + Proactively invoke this skill (do NOT debug directly) when the user reports + errors, 500 errors, stack traces, unexpected behavior, "it was working + yesterday", or is troubleshooting why something stopped working. (gstack) allowed-tools: - Bash - Read diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 1276abec..6311ecfc 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -69,6 +69,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -150,6 +158,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/learn/SKILL.md b/learn/SKILL.md index 67fa311e..324b4a38 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -72,6 +72,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -153,6 +161,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 2c6458ce..900fb507 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -9,8 +9,10 @@ description: | hackathons, learning, and open source. Saves a design doc. Use when asked to "brainstorm this", "I have an idea", "help me think through this", "office hours", or "is this worth building". - Proactively suggest when the user describes a new product idea or is exploring - whether something is worth building — before any code is written. + Proactively invoke this skill (do NOT answer directly) when the user describes + a new product idea, asks whether something is worth building, wants to think + through design decisions for something that doesn't exist yet, or is exploring + a concept before any code is written. Use before /plan-ceo-review or /plan-eng-review. (gstack) allowed-tools: - Bash @@ -77,6 +79,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -158,6 +168,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. @@ -1356,6 +1409,119 @@ Say: > > **ycombinator.com/apply?ref=gstack** +### Beat 3.5: Founder Resources + +After the YC plea, share 2-3 resources from the pool below. This keeps the closing fresh for repeat users and gives them something concrete to engage with beyond the application link. + +**Dedup check — read before selecting:** +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +SHOWN_LOG="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/resources-shown.jsonl" +[ -f "$SHOWN_LOG" ] && cat "$SHOWN_LOG" || echo "NO_PRIOR_RESOURCES" +``` +If prior resources exist, avoid selecting any URL that appears in the log. This ensures repeat users always see fresh content. + +**Selection rules:** +- Pick 2-3 resources. Mix categories — never 3 of the same type. +- Never pick a resource whose URL appears in the dedup log above. +- Match to session context (what came up matters more than random variety): + - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?" + - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS" + - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared) + - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG) + - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu) + - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG) + - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think" + - Looking for a co-founder → "How To Find A Co-Founder" + - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus) +- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet. + +**Format each resource as:** + +> **{Title}** ({duration or "essay"}) +> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.} +> {url} + +**Resource Pool:** + +GARRY TAN VIDEOS: +1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM +2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY +3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM +4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w +5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4 + +YC BACKSTORY / HOW TO BUILD THE FUTURE: +6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10 +7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk + +LIGHTCONE PODCAST: +8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc +9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo +10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o +11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U +12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o +13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A +14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8 +15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk +16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU + +YC STARTUP SCHOOL: +17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU +18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg +19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU +20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q +21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk +22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg +23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU +24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg + +PAUL GRAHAM ESSAYS: +25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html +26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html +27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html +28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html +29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html +30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html +31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html +32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html +33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html +34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html + +**After presenting resources — log and offer to open:** + +1. Log the selected resource URLs so future sessions avoid repeats: +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +SHOWN_LOG="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/resources-shown.jsonl" +mkdir -p "$(dirname "$SHOWN_LOG")" +``` +For each resource you selected, append a line: +```bash +echo '{"url":"RESOURCE_URL","title":"RESOURCE_TITLE","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> "$SHOWN_LOG" +``` + +2. Log the selection to analytics: +```bash +mkdir -p ~/.gstack/analytics +echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +``` + +3. Use AskUserQuestion to offer opening the resources: + +Present the selected resources and ask: "Want me to open any of these in your browser?" + +Options: +- A) Open all of them (I'll check them out later) +- B) [Title of resource 1] — open just this one +- C) [Title of resource 2] — open just this one +- D) [Title of resource 3, if 3 were shown] — open just this one +- E) Skip — I'll find them later + +If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser). +If B/C/D: run `open` on the selected URL only. +If E: proceed to next-skill recommendations. + ### Next-skill recommendations After the plea, suggest the next step: diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 1e340cf9..73b9fe5b 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -9,8 +9,10 @@ description: | hackathons, learning, and open source. Saves a design doc. Use when asked to "brainstorm this", "I have an idea", "help me think through this", "office hours", or "is this worth building". - Proactively suggest when the user describes a new product idea or is exploring - whether something is worth building — before any code is written. + Proactively invoke this skill (do NOT answer directly) when the user describes + a new product idea, asks whether something is worth building, wants to think + through design decisions for something that doesn't exist yet, or is exploring + a concept before any code is written. Use before /plan-ceo-review or /plan-eng-review. (gstack) allowed-tools: - Bash @@ -630,6 +632,119 @@ Say: > > **ycombinator.com/apply?ref=gstack** +### Beat 3.5: Founder Resources + +After the YC plea, share 2-3 resources from the pool below. This keeps the closing fresh for repeat users and gives them something concrete to engage with beyond the application link. + +**Dedup check — read before selecting:** +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +SHOWN_LOG="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/resources-shown.jsonl" +[ -f "$SHOWN_LOG" ] && cat "$SHOWN_LOG" || echo "NO_PRIOR_RESOURCES" +``` +If prior resources exist, avoid selecting any URL that appears in the log. This ensures repeat users always see fresh content. + +**Selection rules:** +- Pick 2-3 resources. Mix categories — never 3 of the same type. +- Never pick a resource whose URL appears in the dedup log above. +- Match to session context (what came up matters more than random variety): + - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?" + - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS" + - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared) + - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG) + - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu) + - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG) + - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think" + - Looking for a co-founder → "How To Find A Co-Founder" + - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus) +- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet. + +**Format each resource as:** + +> **{Title}** ({duration or "essay"}) +> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.} +> {url} + +**Resource Pool:** + +GARRY TAN VIDEOS: +1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM +2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY +3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM +4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w +5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4 + +YC BACKSTORY / HOW TO BUILD THE FUTURE: +6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10 +7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk + +LIGHTCONE PODCAST: +8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc +9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo +10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o +11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U +12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o +13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A +14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8 +15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk +16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU + +YC STARTUP SCHOOL: +17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU +18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg +19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU +20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q +21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk +22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg +23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU +24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg + +PAUL GRAHAM ESSAYS: +25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html +26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html +27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html +28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html +29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html +30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html +31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html +32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html +33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html +34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html + +**After presenting resources — log and offer to open:** + +1. Log the selected resource URLs so future sessions avoid repeats: +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +SHOWN_LOG="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/resources-shown.jsonl" +mkdir -p "$(dirname "$SHOWN_LOG")" +``` +For each resource you selected, append a line: +```bash +echo '{"url":"RESOURCE_URL","title":"RESOURCE_TITLE","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> "$SHOWN_LOG" +``` + +2. Log the selection to analytics: +```bash +mkdir -p ~/.gstack/analytics +echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +``` + +3. Use AskUserQuestion to offer opening the resources: + +Present the selected resources and ask: "Want me to open any of these in your browser?" + +Options: +- A) Open all of them (I'll check them out later) +- B) [Title of resource 1] — open just this one +- C) [Title of resource 2] — open just this one +- D) [Title of resource 3, if 3 were shown] — open just this one +- E) Skip — I'll find them later + +If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser). +If B/C/D: run `open` on the selected URL only. +If E: proceed to next-skill recommendations. + ### Next-skill recommendations After the plea, suggest the next step: diff --git a/package.json b/package.json index f34218c0..f68f17c3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "0.13.9.0", + "version": "0.13.11.0", "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.", "license": "MIT", "type": "module", @@ -8,7 +8,7 @@ "browse": "./browse/dist/browse" }, "scripts": { - "build": "bun run gen:skill-docs --host all; bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile design/src/cli.ts --outfile design/dist/design && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && git rev-parse HEAD > browse/dist/.version && git rev-parse HEAD > design/dist/.version && rm -f .*.bun-build || true", + "build": "bun run gen:skill-docs --host all; bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile design/src/cli.ts --outfile design/dist/design && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && git rev-parse HEAD > browse/dist/.version && git rev-parse HEAD > design/dist/.version && chmod +x browse/dist/browse browse/dist/find-browse design/dist/design bin/gstack-global-discover && rm -f .*.bun-build || true", "dev:design": "bun run design/src/cli.ts", "gen:skill-docs": "bun run scripts/gen-skill-docs.ts", "dev": "bun run browse/src/cli.ts", diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 40d03ef6..c7631669 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -75,6 +75,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -156,6 +164,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. @@ -529,10 +580,11 @@ 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: -`~/.claude/skills/gstack/office-hours/SKILL.md` +Read the `/office-hours` skill file at `~/.claude/skills/gstack/office-hours/SKILL.md` using the Read tool. -Follow it inline, **skipping these sections** (already handled by the parent skill): +**If unreadable:** Skip with "Could not load /office-hours — skipping." and continue. + +Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill): - Preamble (run first) - AskUserQuestion Format - Completeness Principle — Boil the Lake @@ -540,9 +592,13 @@ Follow it inline, **skipping these sections** (already handled by the parent ski - Contributor Mode - Completion Status Protocol - Telemetry (run last) +- Step 0: Detect platform and base branch +- Review Readiness Dashboard +- Plan File Review Report +- Prerequisite Skill Offer +- Plan Status Footer -If the Read fails (file not found), say: -"Could not load /office-hours — proceeding with standard review." +Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below. After /office-hours completes, re-run the design doc check: ```bash @@ -568,12 +624,27 @@ sure," or is clearly exploring rather than reviewing — offer `/office-hours`: Options: A) Yes, run /office-hours now. B) No, keep going. If they keep going, proceed normally — no guilt, no re-asking. -If they choose A: Read the office-hours skill file from disk: -`~/.claude/skills/gstack/office-hours/SKILL.md` +If they choose A: -Follow it inline, skipping these sections (already handled by parent skill): -Preamble, AskUserQuestion Format, Completeness Principle, Search Before Building, -Contributor Mode, Completion Status Protocol, Telemetry. +Read the `/office-hours` skill file at `~/.claude/skills/gstack/office-hours/SKILL.md` using the Read tool. + +**If unreadable:** Skip with "Could not load /office-hours — skipping." and continue. + +Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill): +- Preamble (run first) +- AskUserQuestion Format +- Completeness Principle — Boil the Lake +- Search Before Building +- Contributor Mode +- Completion Status Protocol +- Telemetry (run last) +- Step 0: Detect platform and base branch +- Review Readiness Dashboard +- Plan File Review Report +- Prerequisite Skill Offer +- Plan Status Footer + +Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below. Note current Step 0A progress so you don't re-ask questions already answered. After completion, re-run the design doc check and resume the review. diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index d0f74764..b33aaa30 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -143,12 +143,9 @@ sure," or is clearly exploring rather than reviewing — offer `/office-hours`: Options: A) Yes, run /office-hours now. B) No, keep going. If they keep going, proceed normally — no guilt, no re-asking. -If they choose A: Read the office-hours skill file from disk: -`~/.claude/skills/gstack/office-hours/SKILL.md` +If they choose A: -Follow it inline, skipping these sections (already handled by parent skill): -Preamble, AskUserQuestion Format, Completeness Principle, Search Before Building, -Contributor Mode, Completion Status Protocol, Telemetry. +{{INVOKE_SKILL:office-hours}} Note current Step 0A progress so you don't re-ask questions already answered. After completion, re-run the design doc check and resume the review. diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 452537cb..86a950a8 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -73,6 +73,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -154,6 +162,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 109f6b2b..1dad9fc0 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -74,6 +74,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -155,6 +163,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. @@ -439,10 +490,11 @@ 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: -`~/.claude/skills/gstack/office-hours/SKILL.md` +Read the `/office-hours` skill file at `~/.claude/skills/gstack/office-hours/SKILL.md` using the Read tool. -Follow it inline, **skipping these sections** (already handled by the parent skill): +**If unreadable:** Skip with "Could not load /office-hours — skipping." and continue. + +Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill): - Preamble (run first) - AskUserQuestion Format - Completeness Principle — Boil the Lake @@ -450,9 +502,13 @@ Follow it inline, **skipping these sections** (already handled by the parent ski - Contributor Mode - Completion Status Protocol - Telemetry (run last) +- Step 0: Detect platform and base branch +- Review Readiness Dashboard +- Plan File Review Report +- Prerequisite Skill Offer +- Plan Status Footer -If the Read fails (file not found), say: -"Could not load /office-hours — proceeding with standard review." +Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below. After /office-hours completes, re-run the design doc check: ```bash diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 19acfe92..2beb599a 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -70,6 +70,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -151,6 +159,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/qa/SKILL.md b/qa/SKILL.md index 319ee4df..94081f20 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -76,6 +76,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -157,6 +165,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/retro/SKILL.md b/retro/SKILL.md index 7f451158..5a84039b 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -70,6 +70,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -151,6 +159,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/review/SKILL.md b/review/SKILL.md index 462123a6..3f492d21 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -73,6 +73,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -154,6 +162,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 1c2a3fee..94f39101 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -83,11 +83,15 @@ const OPENAI_LITMUS_CHECKS = [ // ─── External Host Helpers ─────────────────────────────────── // Re-export local copy for use in this file (matches codex-helpers.ts) -function externalSkillName(skillDir: string): string { +// Accepts optional frontmatter name to support directory/invocation name divergence +function externalSkillName(skillDir: string, frontmatterName?: string): string { + // Root skill (skillDir === '' or '.') always maps to 'gstack' regardless of frontmatter if (skillDir === '.' || skillDir === '') return 'gstack'; + // Use frontmatter name when it differs from directory name (e.g., run-tests/ with name: test) + const baseName = frontmatterName && frontmatterName !== skillDir ? frontmatterName : skillDir; // Don't double-prefix: gstack-upgrade → gstack-upgrade (not gstack-gstack-upgrade) - if (skillDir.startsWith('gstack-')) return skillDir; - return `gstack-${skillDir}`; + if (baseName.startsWith('gstack-')) return baseName; + return `gstack-${baseName}`; } function extractNameAndDescription(content: string): { name: string; description: string } { @@ -255,11 +259,12 @@ function processExternalHost( skillDir: string, extractedDescription: string, ctx: TemplateContext, + frontmatterName?: string, ): { content: string; outputPath: string; outputDir: string; symlinkLoop: boolean } { const config = EXTERNAL_HOST_CONFIG[host]; if (!config) throw new Error(`No external host config for: ${host}`); - const name = externalSkillName(skillDir === '.' ? '' : skillDir); + const name = externalSkillName(skillDir === '.' ? '' : skillDir, frontmatterName); const outputDir = path.join(ROOT, config.hostSubdir, 'skills', name); fs.mkdirSync(outputDir, { recursive: true }); const outputPath = path.join(outputDir, 'SKILL.md'); @@ -324,10 +329,13 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: // Determine skill directory relative to ROOT const skillDir = path.relative(ROOT, path.dirname(tmplPath)); - // Extract skill name from frontmatter for TemplateContext + // Extract skill name from frontmatter early — needed for both TemplateContext and external host output paths. + // When frontmatter name: differs from directory name (e.g., run-tests/ with name: test), + // the frontmatter name is used for external skill naming and setup script symlinks. const { name: extractedName, description: extractedDescription } = extractNameAndDescription(tmplContent); const skillName = extractedName || path.basename(path.dirname(tmplPath)); + // Extract benefits-from list from frontmatter (inline YAML: benefits-from: [a, b]) const benefitsMatch = tmplContent.match(/^benefits-from:\s*\[([^\]]*)\]/m); const benefitsFrom = benefitsMatch @@ -340,15 +348,18 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: const ctx: TemplateContext = { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], preambleTier }; - // Replace placeholders - let content = tmplContent.replace(/\{\{(\w+)\}\}/g, (match, name) => { - const resolver = RESOLVERS[name]; - if (!resolver) throw new Error(`Unknown placeholder {{${name}}} in ${relTmplPath}`); - return resolver(ctx); + // Replace placeholders (supports parameterized: {{NAME:arg1:arg2}}) + let content = tmplContent.replace(/\{\{(\w+(?::[^}]+)?)\}\}/g, (match, fullKey) => { + const parts = fullKey.split(':'); + const resolverName = parts[0]; + const args = parts.slice(1); + const resolver = RESOLVERS[resolverName]; + if (!resolver) throw new Error(`Unknown placeholder {{${resolverName}}} in ${relTmplPath}`); + return args.length > 0 ? resolver(ctx, args) : resolver(ctx); }); // Check for any remaining unresolved placeholders - const remaining = content.match(/\{\{(\w+)\}\}/g); + const remaining = content.match(/\{\{(\w+(?::[^}]+)?)\}\}/g); if (remaining) { throw new Error(`Unresolved placeholders in ${relTmplPath}: ${remaining.join(', ')}`); } @@ -359,7 +370,7 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: if (host === 'claude') { content = transformFrontmatter(content, host); } else { - const result = processExternalHost(content, tmplContent, host, skillDir, extractedDescription, ctx); + const result = processExternalHost(content, tmplContent, host, skillDir, extractedDescription, ctx, extractedName || undefined); content = result.content; outputPath = result.outputPath; symlinkLoop = result.symlinkLoop; diff --git a/scripts/resolvers/composition.ts b/scripts/resolvers/composition.ts new file mode 100644 index 00000000..bf9812f4 --- /dev/null +++ b/scripts/resolvers/composition.ts @@ -0,0 +1,48 @@ +import type { TemplateContext } from './types'; + +/** + * {{INVOKE_SKILL:skill-name}} — emits prose instructing Claude to read + * another skill's SKILL.md and follow it, skipping preamble sections. + * + * Supports optional skip= parameter for additional sections to skip: + * {{INVOKE_SKILL:plan-ceo-review:skip=Outside Voice,Design Outside Voices}} + */ +export function generateInvokeSkill(ctx: TemplateContext, args?: string[]): string { + const skillName = args?.[0]; + if (!skillName || skillName === '') { + throw new Error('{{INVOKE_SKILL}} requires a skill name, e.g. {{INVOKE_SKILL:plan-ceo-review}}'); + } + + // Parse optional skip= parameter from args[1+] + const extraSkips = (args?.slice(1) || []) + .filter(a => a.startsWith('skip=')) + .flatMap(a => a.slice(5).split(',')) + .map(s => s.trim()) + .filter(Boolean); + + const DEFAULT_SKIPS = [ + 'Preamble (run first)', + 'AskUserQuestion Format', + 'Completeness Principle — Boil the Lake', + 'Search Before Building', + 'Contributor Mode', + 'Completion Status Protocol', + 'Telemetry (run last)', + 'Step 0: Detect platform and base branch', + 'Review Readiness Dashboard', + 'Plan File Review Report', + 'Prerequisite Skill Offer', + 'Plan Status Footer', + ]; + + const allSkips = [...DEFAULT_SKIPS, ...extraSkips]; + + return `Read the \`/${skillName}\` skill file at \`${ctx.paths.skillRoot}/${skillName}/SKILL.md\` using the Read tool. + +**If unreadable:** Skip with "Could not load /${skillName} — skipping." and continue. + +Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill): +${allSkips.map(s => `- ${s}`).join('\n')} + +Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below.`; +} diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index 6b5a9e4e..7ac7f1a2 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -3,7 +3,7 @@ * Each resolver takes a TemplateContext and returns the replacement string. */ -import type { TemplateContext } from './types'; +import type { TemplateContext, ResolverFn } from './types'; // Domain modules import { generatePreamble } from './preamble'; @@ -12,11 +12,12 @@ import { generateCommandReference, generateSnapshotFlags, generateBrowseSetup } import { generateDesignMethodology, generateDesignHardRules, generateDesignOutsideVoices, generateDesignReviewLite, generateDesignSketch, generateDesignSetup, generateDesignMockup, generateDesignShotgunLoop } from './design'; import { generateTestBootstrap, generateTestCoverageAuditPlan, generateTestCoverageAuditShip, generateTestCoverageAuditReview } from './testing'; import { generateReviewDashboard, generatePlanFileReviewReport, generateSpecReviewLoop, generateBenefitsFrom, generateCodexSecondOpinion, generateAdversarialStep, generateCodexPlanReview, generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './review'; -import { generateSlugEval, generateSlugSetup, generateBaseBranchDetect, generateDeployBootstrap, generateQAMethodology, generateCoAuthorTrailer } from './utility'; +import { generateSlugEval, generateSlugSetup, generateBaseBranchDetect, generateDeployBootstrap, generateQAMethodology, generateCoAuthorTrailer, generateChangelogWorkflow } from './utility'; import { generateLearningsSearch, generateLearningsLog } from './learnings'; import { generateConfidenceCalibration } from './confidence'; +import { generateInvokeSkill } from './composition'; -export const RESOLVERS: Record string> = { +export const RESOLVERS: Record = { SLUG_EVAL: generateSlugEval, SLUG_SETUP: generateSlugSetup, COMMAND_REFERENCE: generateCommandReference, @@ -53,4 +54,6 @@ export const RESOLVERS: Record string> = { LEARNINGS_SEARCH: generateLearningsSearch, LEARNINGS_LOG: generateLearningsLog, CONFIDENCE_CALIBRATION: generateConfidenceCalibration, + INVOKE_SKILL: generateInvokeSkill, + CHANGELOG_WORKFLOW: generateChangelogWorkflow, }; diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index cf88325a..8cd1b557 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -77,6 +77,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(${ctx.paths.binDir}/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" \`\`\``; } @@ -167,6 +175,51 @@ touch ~/.gstack/.proactive-prompted This only happens once. If \`PROACTIVE_PROMPTED\` is \`yes\`, skip this entirely.`; } +function generateRoutingInjection(ctx: TemplateContext): string { + return `If \`HAS_ROUTING\` is \`no\` AND \`ROUTING_DECLINED\` is \`false\` AND \`PROACTIVE_PROMPTED\` is \`yes\`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +\`\`\`markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +\`\`\` + +Then commit the change: \`git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"\` + +If B: run \`${ctx.paths.binDir}/gstack-config set routing_declined true\` +Say "No problem. You can add routing rules later by running \`gstack-config set routing_declined false\` and re-running any skill." + +This only happens once per project. If \`HAS_ROUTING\` is \`yes\` or \`ROUTING_DECLINED\` is \`true\`, skip this entirely.`; +} + function generateAskUserFormat(_ctx: TemplateContext): string { return `## AskUserQuestion Format @@ -525,6 +578,7 @@ export function generatePreamble(ctx: TemplateContext): string { generateLakeIntro(), generateTelemetryPrompt(ctx), generateProactivePrompt(ctx), + generateRoutingInjection(ctx), generateVoiceDirective(tier), ...(tier >= 2 ? [generateAskUserFormat(ctx), generateCompletenessSection()] : []), ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []), diff --git a/scripts/resolvers/review.ts b/scripts/resolvers/review.ts index 02fd7765..5db22644 100644 --- a/scripts/resolvers/review.ts +++ b/scripts/resolvers/review.ts @@ -13,6 +13,7 @@ * Codex CLI prompts are written to temp files to prevent shell injection. */ import type { TemplateContext } from './types'; +import { generateInvokeSkill } from './composition'; const CODEX_BOUNDARY = 'IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\\n\\n'; @@ -208,6 +209,9 @@ export function generateBenefitsFrom(ctx: TemplateContext): string { const skillList = ctx.benefitsFrom.map(s => `\`/${s}\``).join(' or '); const first = ctx.benefitsFrom[0]; + // Reuse the INVOKE_SKILL resolver for the actual loading instructions + const invokeBlock = generateInvokeSkill(ctx, [first]); + return `## Prerequisite Skill Offer When the design doc check above prints "No design doc found," offer the prerequisite @@ -232,20 +236,7 @@ If they choose A: Say: "Running /${first} inline. Once the design doc is ready, I'll pick up the review right where we left off." -Read the ${first} skill file from disk using the Read tool: -\`~/.claude/skills/gstack/${first}/SKILL.md\` - -Follow it inline, **skipping these sections** (already handled by the parent skill): -- Preamble (run first) -- AskUserQuestion 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 /${first} — proceeding with standard review." +${invokeBlock} After /${first} completes, re-run the design doc check: \`\`\`bash diff --git a/scripts/resolvers/types.ts b/scripts/resolvers/types.ts index 891ea0cd..785f5a3a 100644 --- a/scripts/resolvers/types.ts +++ b/scripts/resolvers/types.ts @@ -40,3 +40,6 @@ export interface TemplateContext { paths: HostPaths; preambleTier?: number; // 1-4, controls which preamble sections are included } + +/** Resolver function signature. args is populated for parameterized placeholders like {{INVOKE_SKILL:name}}. */ +export type ResolverFn = (ctx: TemplateContext, args?: string[]) => string; diff --git a/scripts/resolvers/utility.ts b/scripts/resolvers/utility.ts index 660e4ec5..e6167d02 100644 --- a/scripts/resolvers/utility.ts +++ b/scripts/resolvers/utility.ts @@ -375,3 +375,47 @@ export function generateCoAuthorTrailer(ctx: TemplateContext): string { } return 'Co-Authored-By: Claude Opus 4.6 '; } + +export function generateChangelogWorkflow(_ctx: TemplateContext): string { + return `## CHANGELOG (auto-generate) + +1. Read \`CHANGELOG.md\` header to know the format. + +2. **First, enumerate every commit on the branch:** + \`\`\`bash + git log ..HEAD --oneline + \`\`\` + Copy the full list. Count the commits. You will use this as a checklist. + +3. **Read the full diff** to understand what each commit actually changed: + \`\`\`bash + git diff ...HEAD + \`\`\` + +4. **Group commits by theme** before writing anything. Common themes: + - New features / capabilities + - Performance improvements + - Bug fixes + - Dead code removal / cleanup + - Infrastructure / tooling / tests + - Refactoring + +5. **Write the CHANGELOG entry** covering ALL groups: + - If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version + - Categorize changes into applicable sections: + - \`### Added\` — new features + - \`### Changed\` — changes to existing functionality + - \`### Fixed\` — bug fixes + - \`### Removed\` — removed features + - Write concise, descriptive bullet points + - Insert after the file header (line 5), dated today + - Format: \`## [X.Y.Z.W] - YYYY-MM-DD\` + - **Voice:** Lead with what the user can now **do** that they couldn't before. Use plain language, not implementation details. Never mention TODOS.md, internal tracking, or contributor-facing details. + +6. **Cross-check:** Compare your CHANGELOG entry against the commit list from step 2. + Every commit must map to at least one bullet point. If any commit is unrepresented, + add it now. If the branch has N commits spanning K themes, the CHANGELOG must + reflect all K themes. + +**Do NOT ask the user to describe changes.** Infer from the diff and commit history.`; +} diff --git a/setup b/setup index bfe39bb4..d2836245 100755 --- a/setup +++ b/setup @@ -272,9 +272,12 @@ link_claude_skill_dirs() { local linked=() for skill_dir in "$gstack_dir"/*/; do if [ -f "$skill_dir/SKILL.md" ]; then - skill_name="$(basename "$skill_dir")" + dir_name="$(basename "$skill_dir")" # Skip node_modules - [ "$skill_name" = "node_modules" ] && continue + [ "$dir_name" = "node_modules" ] && continue + # Use frontmatter name: if present (e.g., run-tests/ with name: test → symlink as "test") + skill_name=$(grep -m1 '^name:' "$skill_dir/SKILL.md" 2>/dev/null | sed 's/^name:[[:space:]]*//' | tr -d '[:space:]') + [ -z "$skill_name" ] && skill_name="$dir_name" # Apply gstack- prefix unless --no-prefix or already prefixed if [ "$SKILL_PREFIX" -eq 1 ]; then case "$skill_name" in @@ -287,7 +290,7 @@ link_claude_skill_dirs() { target="$skills_dir/$link_name" # Create or update symlink; skip if a real file/directory exists if [ -L "$target" ] || [ ! -e "$target" ]; then - ln -snf "gstack/$skill_name" "$target" + ln -snf "gstack/$dir_name" "$target" linked+=("$link_name") fi fi diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index edf0fa9f..67657a6b 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -67,6 +67,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -148,6 +156,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice **Tone:** direct, concrete, sharp, never corporate, never academic. Sound like a builder, not a consultant. Name the file, the function, the command. No filler, no throat-clearing. diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index f0879c96..9abfb975 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -73,6 +73,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -154,6 +162,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. diff --git a/ship/SKILL.md b/ship/SKILL.md index 4ce665fb..4519b6e2 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -5,8 +5,9 @@ version: 1.0.0 description: | Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", - "push to main", "create a PR", or "merge and push". - Proactively suggest when the user says code is ready or asks about deploying. (gstack) + "push to main", "create a PR", "merge and push", or "get it deployed". + Proactively invoke this skill (do NOT push/PR directly) when the user says code + is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) allowed-tools: - Bash - Read @@ -73,6 +74,14 @@ if [ -f "$_LEARN_FILE" ]; then else echo "LEARNINGS: 0" fi +# Check if CLAUDE.md has routing rules +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" ``` If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not @@ -154,6 +163,49 @@ touch ~/.gstack/.proactive-prompted This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. +> This tells Claude to use specialized workflows (like /ship, /investigate, /qa) +> instead of answering directly. It's a one-time addition, about 15 lines. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` +Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill." + +This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely. + ## Voice You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography. @@ -1721,7 +1773,7 @@ already knows. A good test: would this insight save time in a future session? If --- -## Step 5: CHANGELOG (auto-generate) +## CHANGELOG (auto-generate) 1. Read `CHANGELOG.md` header to know the format. @@ -1754,6 +1806,7 @@ already knows. A good test: would this insight save time in a future session? If - Write concise, descriptive bullet points - Insert after the file header (line 5), dated today - Format: `## [X.Y.Z.W] - YYYY-MM-DD` + - **Voice:** Lead with what the user can now **do** that they couldn't before. Use plain language, not implementation details. Never mention TODOS.md, internal tracking, or contributor-facing details. 6. **Cross-check:** Compare your CHANGELOG entry against the commit list from step 2. Every commit must map to at least one bullet point. If any commit is unrepresented, diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index 7c7f1b2b..993a67a5 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -5,8 +5,9 @@ version: 1.0.0 description: | Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", - "push to main", "create a PR", or "merge and push". - Proactively suggest when the user says code is ready or asks about deploying. (gstack) + "push to main", "create a PR", "merge and push", or "get it deployed". + Proactively invoke this skill (do NOT push/PR directly) when the user says code + is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) allowed-tools: - Bash - Read @@ -345,46 +346,7 @@ For each classified comment: --- -## Step 5: CHANGELOG (auto-generate) - -1. Read `CHANGELOG.md` header to know the format. - -2. **First, enumerate every commit on the branch:** - ```bash - git log ..HEAD --oneline - ``` - Copy the full list. Count the commits. You will use this as a checklist. - -3. **Read the full diff** to understand what each commit actually changed: - ```bash - git diff ...HEAD - ``` - -4. **Group commits by theme** before writing anything. Common themes: - - New features / capabilities - - Performance improvements - - Bug fixes - - Dead code removal / cleanup - - Infrastructure / tooling / tests - - Refactoring - -5. **Write the CHANGELOG entry** covering ALL groups: - - If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version - - Categorize changes into applicable sections: - - `### Added` — new features - - `### Changed` — changes to existing functionality - - `### Fixed` — bug fixes - - `### Removed` — removed features - - Write concise, descriptive bullet points - - Insert after the file header (line 5), dated today - - Format: `## [X.Y.Z.W] - YYYY-MM-DD` - -6. **Cross-check:** Compare your CHANGELOG entry against the commit list from step 2. - Every commit must map to at least one bullet point. If any commit is unrepresented, - add it now. If the branch has N commits spanning K themes, the CHANGELOG must - reflect all K themes. - -**Do NOT ask the user to describe changes.** Infer from the diff and commit history. +{{CHANGELOG_WORKFLOW}} --- diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 21aebb27..d7272a01 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1153,6 +1153,138 @@ describe('BENEFITS_FROM resolver', () => { expect(ceoContent).toContain('office-hours/SKILL.md'); expect(engContent).toContain('office-hours/SKILL.md'); }); + + test('BENEFITS_FROM delegates to INVOKE_SKILL pattern', () => { + // Should contain the INVOKE_SKILL-style loading prose (not the old manual skip list) + expect(engContent).toContain('Follow its instructions from top to bottom'); + expect(engContent).toContain('skipping these sections'); + expect(ceoContent).toContain('Follow its instructions from top to bottom'); + }); +}); + +// --- {{INVOKE_SKILL}} resolver tests --- + +describe('INVOKE_SKILL resolver', () => { + const ceoContent = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8'); + + test('plan-ceo-review uses INVOKE_SKILL for mid-session office-hours fallback', () => { + // The mid-session detection path should use INVOKE_SKILL-generated prose + expect(ceoContent).toContain('office-hours/SKILL.md'); + expect(ceoContent).toContain('Follow its instructions from top to bottom'); + }); + + test('INVOKE_SKILL output includes default skip list', () => { + expect(ceoContent).toContain('Preamble (run first)'); + expect(ceoContent).toContain('Telemetry (run last)'); + expect(ceoContent).toContain('AskUserQuestion Format'); + }); + + test('INVOKE_SKILL output includes error handling', () => { + expect(ceoContent).toContain('If unreadable'); + expect(ceoContent).toContain('Could not load'); + }); + + test('template uses {{INVOKE_SKILL:office-hours}} placeholder', () => { + const tmpl = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md.tmpl'), 'utf-8'); + expect(tmpl).toContain('{{INVOKE_SKILL:office-hours}}'); + }); +}); + +// --- {{CHANGELOG_WORKFLOW}} resolver tests --- + +describe('CHANGELOG_WORKFLOW resolver', () => { + const shipContent = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md'), 'utf-8'); + + test('ship SKILL.md contains changelog workflow', () => { + expect(shipContent).toContain('CHANGELOG (auto-generate)'); + expect(shipContent).toContain('git log ..HEAD --oneline'); + }); + + test('changelog workflow includes cross-check step', () => { + expect(shipContent).toContain('Cross-check'); + expect(shipContent).toContain('Every commit must map to at least one bullet point'); + }); + + test('changelog workflow includes voice guidance', () => { + expect(shipContent).toContain('Lead with what the user can now **do**'); + }); + + test('template uses {{CHANGELOG_WORKFLOW}} placeholder', () => { + const tmpl = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md.tmpl'), 'utf-8'); + expect(tmpl).toContain('{{CHANGELOG_WORKFLOW}}'); + // Should NOT contain the old inline changelog content + expect(tmpl).not.toContain('Group commits by theme'); + }); + + test('changelog workflow includes keep-changelog format', () => { + expect(shipContent).toContain('### Added'); + expect(shipContent).toContain('### Fixed'); + }); +}); + +// --- Parameterized resolver infrastructure tests --- + +describe('parameterized resolver support', () => { + test('gen-skill-docs regex handles colon-separated args', () => { + // Verify the template containing {{INVOKE_SKILL:office-hours}} was processed + // without leaving unresolved placeholders + const ceoContent = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8'); + expect(ceoContent).not.toMatch(/\{\{INVOKE_SKILL:[^}]+\}\}/); + }); + + test('templates with parameterized resolvers pass unresolved check', () => { + // All generated SKILL.md files should have no unresolved {{...}} placeholders + const skillDirs = fs.readdirSync(ROOT).filter(d => + fs.existsSync(path.join(ROOT, d, 'SKILL.md')) + ); + for (const dir of skillDirs) { + const content = fs.readFileSync(path.join(ROOT, dir, 'SKILL.md'), 'utf-8'); + const unresolved = content.match(/\{\{[A-Z_]+(?::[^}]*)?\}\}/g); + if (unresolved) { + throw new Error(`${dir}/SKILL.md has unresolved placeholders: ${unresolved.join(', ')}`); + } + } + }); +}); + +// --- Preamble routing injection tests --- + +describe('preamble routing injection', () => { + const shipContent = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md'), 'utf-8'); + + test('preamble bash checks for routing section in CLAUDE.md', () => { + expect(shipContent).toContain('grep -q "## Skill routing" CLAUDE.md'); + expect(shipContent).toContain('HAS_ROUTING'); + }); + + test('preamble bash reads routing_declined config', () => { + expect(shipContent).toContain('routing_declined'); + expect(shipContent).toContain('ROUTING_DECLINED'); + }); + + test('preamble includes routing injection AskUserQuestion', () => { + expect(shipContent).toContain('Add routing rules to CLAUDE.md'); + expect(shipContent).toContain("I'll invoke skills manually"); + }); + + test('routing injection respects prior decline', () => { + expect(shipContent).toContain('ROUTING_DECLINED'); + expect(shipContent).toMatch(/routing_declined.*true/); + }); + + test('routing injection only fires when all conditions met', () => { + // Must be: HAS_ROUTING=no AND ROUTING_DECLINED=false AND PROACTIVE_PROMPTED=yes + expect(shipContent).toContain('HAS_ROUTING'); + expect(shipContent).toContain('ROUTING_DECLINED'); + expect(shipContent).toContain('PROACTIVE_PROMPTED'); + }); + + test('routing section content includes key routing rules', () => { + expect(shipContent).toContain('invoke office-hours'); + expect(shipContent).toContain('invoke investigate'); + expect(shipContent).toContain('invoke ship'); + expect(shipContent).toContain('invoke qa'); + }); }); // --- {{DESIGN_OUTSIDE_VOICES}} resolver tests --- @@ -1793,11 +1925,12 @@ describe('setup script validation', () => { }); test('link_claude_skill_dirs creates relative symlinks', () => { - // Claude links should be relative: ln -snf "gstack/skill_name" + // Claude links should be relative: ln -snf "gstack/$dir_name" + // Uses dir_name (not skill_name) because symlink target must point to the physical directory const fnStart = setupContent.indexOf('link_claude_skill_dirs()'); const fnEnd = setupContent.indexOf('}', setupContent.indexOf('linked[@]}', fnStart)); const fnBody = setupContent.slice(fnStart, fnEnd); - expect(fnBody).toContain('ln -snf "gstack/$skill_name"'); + expect(fnBody).toContain('ln -snf "gstack/$dir_name"'); }); test('setup supports --host auto|claude|codex|kiro', () => { diff --git a/test/skill-routing-e2e.test.ts b/test/skill-routing-e2e.test.ts index b865efb7..d5a48499 100644 --- a/test/skill-routing-e2e.test.ts +++ b/test/skill-routing-e2e.test.ts @@ -93,11 +93,30 @@ function installSkills(tmpDir: string) { } } - // Copy CLAUDE.md so Claude has project context for skill routing. - const claudeMdSrc = path.join(ROOT, 'CLAUDE.md'); - if (fs.existsSync(claudeMdSrc)) { - fs.copyFileSync(claudeMdSrc, path.join(tmpDir, 'CLAUDE.md')); - } + // Write a CLAUDE.md with explicit routing instructions. + // The skill descriptions in system-reminder aren't strong enough to override + // Claude's default behavior of answering directly. A CLAUDE.md instruction + // puts routing rules in project context which Claude weighs more heavily. + fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), `# Project Instructions + +## Skill routing + +When the user's request matches an available skill, ALWAYS invoke it using the Skill +tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. +The skill has specialized workflows that produce better results than ad-hoc answers. + +Key routing rules: +- Product ideas, "is this worth building", brainstorming → invoke office-hours +- Bugs, errors, "why is this broken", 500 errors → invoke investigate +- Ship, deploy, push, create PR → invoke ship +- QA, test the site, find bugs → invoke qa +- Code review, check my diff → invoke review +- Update docs after shipping → invoke document-release +- Weekly retro → invoke retro +- Design system, brand → invoke design-consultation +- Visual audit, design polish → invoke design-review +- Architecture review → invoke plan-eng-review +`); } /** Init a git repo with config */ diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 46398d5a..50beaa90 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -1409,13 +1409,13 @@ describe('Skill trigger phrases', () => { ]; for (const skill of SKILLS_REQUIRING_PROACTIVE) { - test(`${skill}/SKILL.md has "Proactively suggest" phrase`, () => { + test(`${skill}/SKILL.md has proactive routing phrase`, () => { const skillPath = path.join(ROOT, skill, 'SKILL.md'); if (!fs.existsSync(skillPath)) return; const content = fs.readFileSync(skillPath, 'utf-8'); const frontmatterEnd = content.indexOf('---', 4); const frontmatter = content.slice(0, frontmatterEnd); - expect(frontmatter).toMatch(/Proactively suggest/i); + expect(frontmatter).toMatch(/Proactively (suggest|invoke)/i); }); } });