From 8c3c39b5220f7fb0c53af5362863a2377f756279 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Nov 2026 11:26:15 +0800 Subject: [PATCH] List the new guides in the README and fix the install doc's hook count (#4403) * List the new guides in the README and fix the install doc's hook count Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Name the opt-in skill hooks in the manual uninstall steps Review-Finding: docs/install.md:29:docs-accuracy reader=core Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Mention the uninstall doc in the changelog entry Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Point the install and uninstall docs at the opt-in skill-gate hooks Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- README.md | 2 ++ changelog.d/docs-index-and-install-hooks.md | 1 + docs/install.md | 10 +++++++++- docs/uninstall.md | 6 ++++-- 4 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 changelog.d/docs-index-and-install-hooks.md diff --git a/README.md b/README.md index e7d04738b..11ebe35ed 100644 --- a/README.md +++ b/README.md @@ -270,6 +270,8 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file | [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets | | [Preview a frontend](docs/howto-preview-a-frontend.md) | The loopback preview with canned API answers that `/design-review --build` checks, its fixtures, the state inventory, and the `gstack-design-build` receipt | | [First Production Deploy](docs/howto-bring-up-a-first-deploy.md) | What to do when `/setup-deploy` says nothing is deployed yet: hosting, env and secrets, DNS, checking it works, then back to `/setup-deploy` | +| [Land a fix in someone else's repo](docs/howto-land-a-fix-in-someone-elses-repo.md) | Read their rules, search for the same fix, run every guard their CI runs before opening, keep it small, answer each review point in a new commit | +| [Run a human playtest](docs/howto-run-human-playtests.md) | Ask about moments and where people would stop, and why a back-to-back pick between two builds measures the order, not the build | | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge | | [GBrain quick tour](docs/gbrain-quick-tour.md) | The four setup paths, MCP registration, the per-repo trust policy, memory sync, Conductor env vars | | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` | diff --git a/changelog.d/docs-index-and-install-hooks.md b/changelog.d/docs-index-and-install-hooks.md new file mode 100644 index 000000000..94daa40d6 --- /dev/null +++ b/changelog.d/docs-index-and-install-hooks.md @@ -0,0 +1 @@ +- **The README lists the two new guides, and the install doc counts its hooks right.** The README's docs table links the guides for landing a fix in someone else's repository and for running a human playtest. `docs/install.md` no longer says setup registers "up to three hook families" before naming a fourth, and it now mentions the two hooks that stay off until you turn them on, skill routing and skill contracts. The manual uninstall steps in `docs/uninstall.md` now name those two hooks too. diff --git a/docs/install.md b/docs/install.md index 96cc1c0b9..30ddb2960 100644 --- a/docs/install.md +++ b/docs/install.md @@ -26,7 +26,7 @@ Swap `required` for `optional` if you'd rather nudge teammates than block them. ## Hooks that `./setup` registers -`./setup` registers up to three hook families in `~/.claude/settings.json`, every one pointing at the canonical install. In team mode it registers the `SessionStart` auto-update hook (`gstack-session-update`; `./setup --no-team` skips it). It asks before registering the AskUserQuestion `PreToolUse` (preference enforcement) and `PostToolUse` (deterministic answer capture) hooks that `/plan-tune` uses at runtime; `./setup` never writes them silently. `docs/uninstall.md` lists the same families when telling you what to remove by hand. +`./setup` registers the hooks below in `~/.claude/settings.json`, every one pointing at the canonical install. In team mode it registers the `SessionStart` auto-update hook (`gstack-session-update`; `./setup --no-team` skips it). It asks before registering the AskUserQuestion `PreToolUse` (preference enforcement) and `PostToolUse` (deterministic answer capture) hooks that `/plan-tune` uses at runtime; `./setup` never writes them silently. `docs/uninstall.md` lists the same families when telling you what to remove by hand. `./setup` also registers one default-on Stop hook: `gstack-timeline-stop` (closes dangling session-timeline entries when a session @@ -39,6 +39,14 @@ explicit "no" removes a live registration. `GSTACK_TIMELINE_STOP_HOOK=no` and --source gstack-timeline-stop` removes it by hand, and `gstack-uninstall` removes it too. +Two more hooks are off by default and registered only when you turn them on: +skill routing (`./setup --skill-routing`, a `UserPromptSubmit` hook that names +the gstack skill a prompt fits) and skill contracts (`./setup --skill-contracts`, +a `Stop` hook that blocks once when a skill ends without its required outputs); +see [skill-routing-and-contracts.md](skill-routing-and-contracts.md). The +opt-in skill gates (`./setup --ceo-review-gate`, `./setup --autoplan-gate`) +register their own hooks the same way; see [skill-gates.md](skill-gates.md). + Hook registration is canonical-only: every hook command points at the stable `~/.claude/skills/gstack` install, never the tree setup ran from, so deleting a worktree or Conductor workspace can't leave dead hooks erroring in your diff --git a/docs/uninstall.md b/docs/uninstall.md index a3dea4127..a5a5a2ce9 100644 --- a/docs/uninstall.md +++ b/docs/uninstall.md @@ -125,8 +125,10 @@ Manual removal leaves gstack's hook entries behind in `~/.claude/settings.json` (the uninstall script removes all of them for you, including entries whose `_gstack_source` tag was stripped). Edit that file and delete every hook whose command path points into `.claude/skills/gstack/`: the SessionStart auto-update -hook, the AskUserQuestion PreToolUse/PostToolUse hooks, and the Stop hooks -(session timeline, plus verify-gate if you opted in). Left in place, they error +hook, the AskUserQuestion PreToolUse/PostToolUse hooks, the Stop hooks +(session timeline, plus verify-gate and skill contracts if you opted in), and +the skill-routing UserPromptSubmit hook if you turned it on, and the +/plan-ceo-review and /autoplan skill-gate hooks if you turned those on. Left in place, they error on every matching event once the install directory is gone. If you turned on the OpenClaw or Hermes [start hook](hosts.md#start-hook),