docs: add Cognitive Mode Switching workflow + gstack integration (v3.34.9)

- guide/workflows/gstack-workflow.md (new): Cognitive Mode Switching pattern — 6 gears table, pre-implementation strategic gate concept, /browse non-MCP native Chromium daemon architecture (~100ms/cmd), full ship cycle demo. Reference impl: gstack by Garry Tan (YC CEO). - examples/commands/plan-ceo-review.md (new): strategic product gate template with 3 modes (SCOPE EXPANSION / HOLD SCOPE / REDUCTION) - examples/commands/plan-eng-review.md (new): engineering architecture gate template with Mermaid diagrams, failure modes, test matrix - guide/workflows/README.md: add entry + 2 Quick Selection Guide rows - guide/ecosystem/third-party-tools.md: gstack in Plugin Ecosystem - machine-readable/reference.yaml: v3.34.9, 11 new gstack entries Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-13 10:34:51 +01:00 · 2026-03-13 10:34:51 +01:00 · 1728b6de39
commit 1728b6de39
parent ded3a9858d
6 changed files with 665 additions and 7 deletions
--- a/examples/commands/plan-ceo-review.md
+++ b/examples/commands/plan-ceo-review.md
@ -0,0 +1,137 @@
+---
+name: plan-ceo-review
+description: Strategic product gate — challenge the brief, find the 10-star product hiding inside the request, before writing any code
+version: 1.0.0
+inspired-by: https://github.com/garrytan/gstack
+---
+
+# /plan-ceo-review — Strategic Product Gate
+
+Pre-implementation command. Inserts an explicit gate between "I have a request" and "I start coding". Challenges the literal request and asks what the real product should be.
+
+**Use in plan mode, before any implementation.**
+
+---
+
+## The Problem This Solves
+
+Claude Code is optimized to build what you ask. If you say "add X", it builds X. It will not ask whether X is actually the right product. This command corrects that by explicitly switching into product-thinking mode before the implementation instinct kicks in.
+
+---
+
+## When to Use
+
+- Before implementing any significant feature request
+- Especially when the request is specific ("add photo upload") — specificity often signals the requester has already collapsed the solution space
+- When you want to pressure-test a direction before committing engineering time
+
+---
+
+## Three Modes
+
+The command asks the user to choose one before proceeding:
+
+| Mode | Posture | Use when |
+|------|---------|----------|
+| **SCOPE EXPANSION** | Find the 10-star product, push scope up | Direction is fuzzy, want to dream |
+| **HOLD SCOPE** | Accept direction, make the plan bulletproof | Direction is locked, want rigor |
+| **SCOPE REDUCTION** | Strip to minimum viable, cut ruthlessly | Overloaded backlog, need to ship fast |
+
+The assistant commits to the selected mode and does not drift mid-review.
+
+---
+
+## Prompt Template
+
+```markdown
+# /plan-ceo-review
+
+You are in CEO / founder review mode. Your job is NOT to implement anything.
+Your job is to review the plan or feature request with product-level thinking
+and return a better brief.
+
+## Step 0: Choose Mode
+
+Ask the user which mode to use (if not specified):
+- SCOPE EXPANSION: Find the 10-star product. Push scope up. What's the version
+  that feels inevitable and delightful?
+- HOLD SCOPE: Accept the direction. Make this plan bulletproof. Catch every
+  failure mode and unstated assumption.
+- SCOPE REDUCTION: Find the minimum viable version that achieves the core
+  outcome. Cut everything else.
+
+Once the user selects, commit to that mode for the entire review.
+
+## Step 1: Restate the Request
+
+Summarize the literal request in 1-2 sentences. Be precise — not editorialized.
+
+## Step 2: Challenge the Premise
+
+Ask the more important question: what is this product actually FOR?
+
+- What is the user's real job-to-be-done?
+- Is the literal request the best way to solve it?
+- What assumption is the request making that might be wrong?
+
+## Step 3: The Real Product (EXPANSION) / Bulletproof Plan (HOLD) / MVP (REDUCTION)
+
+**SCOPE EXPANSION**: Describe the 10-star version of this product.
+- What would make this 10x better for 2x the effort?
+- What do users actually want, not what they asked for?
+- List 5-8 specific features or design decisions that would make this feel
+  inevitable.
+
+**HOLD SCOPE**: Accept the direction. Now find everything that can go wrong.
+- Unstated assumptions in the request
+- Edge cases that are not covered
+- Missing error states
+- UX gaps
+- Security or trust boundary issues
+- Operational concerns (monitoring, rollback, data migration)
+
+**SCOPE REDUCTION**: What is the smallest version that proves the core value?
+- What is the one thing this must do?
+- What can be cut without losing the point?
+- What can be deferred to v2?
+
+## Step 4: Recommendation
+
+Return one of:
+- **Proceed as stated** — the original request is the right product
+- **Reframe** — here is the better brief (with specifics)
+- **Reject** — here is why this is the wrong direction, and what to build instead
+
+Do NOT make any code changes. This is a review, not an implementation.
+```
+
+---
+
+## Example
+
+**Input**: "Let sellers upload a photo for their listing"
+
+**Output (SCOPE EXPANSION)**:
+> "Photo upload" is not the feature. The real job is helping sellers create listings that actually sell.
+>
+> Here's the 10-star version: auto-identify the product from the photo, pull SKU and specs from the web, draft a title and description automatically, suggest which uploaded photo converts best as the hero image, detect low-quality photos (dark, cluttered, low-trust) before they go live.
+>
+> **Recommendation**: Reframe. The brief should be "smart listing creation from photo" not "photo upload".
+
+---
+
+## Integration with Other Commands
+
+```
+/plan-ceo-review    → lock product direction
+/plan-eng-review    → lock technical architecture
+[implement]
+/review             → paranoid pre-merge check
+/ship               → release
+```
+
+## See Also
+
+- [Cognitive Mode Switching](../../guide/workflows/gstack-workflow.md) — full workflow context
+- [plan-eng-review](./plan-eng-review.md) — next step after direction is locked
+- [plan-start](./plan-start.md) — native plan mode command
--- a/examples/commands/plan-eng-review.md
+++ b/examples/commands/plan-eng-review.md
@ -0,0 +1,195 @@
+---
+name: plan-eng-review
+description: Engineering architecture gate — lock architecture, diagrams, edge cases, and test matrix before writing implementation code
+version: 1.0.0
+inspired-by: https://github.com/garrytan/gstack
+---
+
+# /plan-eng-review — Engineering Architecture Gate
+
+Post-direction, pre-implementation command. Takes validated product direction and returns a buildable technical spec with diagrams. Forces the system to think through architecture before a single line of implementation code is written.
+
+**Use after `/plan-ceo-review` has locked direction. Still in plan mode.**
+
+---
+
+## The Problem This Solves
+
+Once product direction is locked, the next failure mode is vague architecture. "The system will handle it" is not a plan. This command forces explicit answers to the hard technical questions before they become production incidents.
+
+The key unlock: **forcing diagram generation**. Diagrams surface hidden assumptions that prose keeps vague. A sequence diagram makes you specify who calls what. A state machine makes you enumerate every failure mode explicitly.
+
+---
+
+## When to Use
+
+- After product direction is validated (post `/plan-ceo-review` or equivalent)
+- Before any implementation work starts on a non-trivial feature
+- When the feature has async components, external dependencies, or multi-step flows
+- Any time "the architecture is clear" needs to be proven, not assumed
+
+---
+
+## What It Should Produce
+
+| Output | Why it matters |
+|--------|----------------|
+| Architecture diagram (Mermaid) | Makes component boundaries explicit |
+| Data flow diagram | Shows where data transforms and who owns what |
+| State machine for core flow | Forces enumeration of all states including failures |
+| Sync vs async boundary decisions | Prevents "just make it async" without reasoning |
+| Failure mode inventory | Every failure path, not just happy path |
+| Trust boundary map | Where do you accept external input? What do you validate? |
+| Test matrix | What needs to be tested and at which layer |
+
+---
+
+## Prompt Template
+
+```markdown
+# /plan-eng-review
+
+You are in engineering manager / tech lead mode. Direction is locked.
+Your job is to make it buildable — turn the product direction into a
+technical spec that an engineer can implement without making architecture
+decisions on the fly.
+
+Do NOT question the product direction. Do NOT suggest scope changes.
+Do NOT implement anything. Return a technical spec.
+
+## Step 1: Restate the Feature
+
+1-2 sentences: what is being built. Confirm you are working from the
+correct brief.
+
+## Step 2: Architecture Diagram
+
+Draw the component architecture in Mermaid:
+- All components involved (frontend, backend, jobs, storage, external APIs)
+- Boundaries between components
+- Data flow directions
+
+```mermaid
+graph LR
+    ...
+```
+
+## Step 3: Core Flow — Sequence Diagram
+
+Draw the happy path as a sequence diagram:
+- Which components call which, in what order
+- What data passes at each step
+- Where async handoffs happen
+
+```mermaid
+sequenceDiagram
+    ...
+```
+
+## Step 4: State Machine
+
+Draw the state machine for the core domain object:
+- All valid states
+- All transitions and their triggers
+- Terminal states (success AND failure)
+
+```mermaid
+stateDiagram-v2
+    ...
+```
+
+## Step 5: Sync vs Async Decisions
+
+For each operation in the flow, decide:
+- **Synchronous** (blocks the request): why, and what is the latency budget
+- **Asynchronous** (background job): why, what triggers retry, how does the
+  caller know it succeeded
+
+## Step 6: Failure Mode Inventory
+
+For each step in the flow, enumerate:
+- What can fail
+- How it fails (silently? loudly? partial success?)
+- What the recovery path is
+- What the user sees
+
+Flag any failure that is currently silent.
+
+## Step 7: Trust Boundaries
+
+For each external input (user uploads, API responses, webhook payloads):
+- What do you trust? What do you validate?
+- Where could malicious input cause harm?
+- Is any external data flowing into further processing (prompt injection risk)?
+
+## Step 8: Test Matrix
+
+| Layer | What to test | Why |
+|-------|-------------|-----|
+| Unit | ... | ... |
+| Integration | ... | ... |
+| E2E | ... | ... |
+
+Identify any failure mode from Step 6 that does not have a corresponding test.
+
+## Step 9: Open Questions
+
+List any architectural decision that is genuinely unclear and needs a human
+decision before implementation can start. Not a comprehensive list — only
+blockers.
+```
+
+---
+
+## Example
+
+**Feature**: Smart listing creation from photo (post-`/plan-ceo-review`)
+
+**Output excerpt**:
+```mermaid
+graph LR
+    Upload[Photo Upload] --> Storage[Object Storage]
+    Storage --> Classify[Vision Classification Job]
+    Classify --> Enrich[Web Enrichment Job]
+    Enrich --> DraftGen[Draft Generation]
+    DraftGen --> DB[(Listings DB)]
+    DraftGen --> UI[Listing Editor UI]
+```
+
+State machine:
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> classifying
+    classifying --> enriching
+    classifying --> classification_failed
+    enriching --> draft_ready
+    enriching --> enrichment_partial
+    enrichment_partial --> draft_ready
+    draft_ready --> published
+    draft_ready --> discarded
+```
+
+Failure modes:
+- Classification fails → degrade to manual listing (not silent failure)
+- Enrichment partially fails → use what succeeded, flag missing fields
+- Upload succeeds, classification job never starts → orphaned file, cleanup job required
+- Web data in draft generation → prompt injection vector, sanitize before passing to LLM
+
+---
+
+## Integration with Other Commands
+
+```
+/plan-ceo-review    → product direction locked
+/plan-eng-review    → architecture locked  ← you are here
+[implement]
+/review             → paranoid pre-merge check
+/ship               → release
+```
+
+## See Also
+
+- [Cognitive Mode Switching](../../guide/workflows/gstack-workflow.md) — full workflow context
+- [plan-ceo-review](./plan-ceo-review.md) — previous step
+- [Plan Pipeline](../../guide/workflows/plan-pipeline.md) — more automated orchestration with ADR memory
--- a/guide/ecosystem/third-party-tools.md
+++ b/guide/ecosystem/third-party-tools.md
@ -1,12 +1,12 @@
 ---
 title: "Third-Party Tools for Claude Code"
-description: "Community tools for token tracking, session management, configuration, and alternative UIs"
+description: "Community tools for token tracking, session management, configuration, hook utilities, and alternative UIs"
 tags: [reference, integration, plugin]
 ---

 # Third-Party Tools for Claude Code

-> Community tools for token tracking, session management, configuration, and alternative UIs.
+> Community tools for token tracking, session management, configuration, hook utilities, and alternative UIs.
 >
 > **Last verified**: March 2026

@ -16,11 +16,12 @@ tags: [reference, integration, plugin]
 2. [Token & Cost Tracking](#token--cost-tracking)
 3. [Session Management](#session-management)
 4. [Configuration Management](#configuration-management)
-5. [Alternative UIs](#alternative-uis)
-6. [Multi-Agent Orchestration](#multi-agent-orchestration)
-7. [Plugin Ecosystem](#plugin-ecosystem)
-8. [Known Gaps](#known-gaps)
-9. [Recommendations by Persona](#recommendations-by-persona)
+5. [Hook Utilities](#hook-utilities)
+6. [Alternative UIs](#alternative-uis)
+7. [Multi-Agent Orchestration](#multi-agent-orchestration)
+8. [Plugin Ecosystem](#plugin-ecosystem)
+9. [Known Gaps](#known-gaps)
+10. [Recommendations by Persona](#recommendations-by-persona)

 ---

@ -327,6 +328,85 @@ A CLI that scaffolds pre-configured Claude Code setups with hooks, commands, sta

 ---

+## Hook Utilities
+
+Tools that extend Claude Code's hook system with additional logic, conditional execution, or automation patterns. For DIY hook examples, see [the hooks section in the ultimate guide](../ultimate-guide.md).
+
+### gitdiff-watcher
+
+A Stop hook utility that enforces quality gates before Claude hands back control. Runs shell commands (build, tests, linting) only when relevant files have changed, making CLAUDE.md quality rules deterministic.
+
+| Attribute | Details |
+|-----------|---------|
+| **Source** | [GitHub: fcamblor/gitdiff-watcher](https://github.com/fcamblor/gitdiff-watcher) |
+| **Install** | `npx @fcamblor/gitdiff-watcher@0.1.0` (no global install needed) |
+| **Language** | Node.js |
+| **Version** | 0.1.0 — work in progress, APIs may change |
+| **Author** | Florian Camblor |
+
+**The problem it solves**: CLAUDE.md rules like "tests must pass before handoff" are non-deterministic. As context grows, these rules compete with recent tool outputs for the model's attention and can be deprioritized — so Claude sometimes returns control with broken code even when the rule is explicit. A Stop hook runs outside the LLM context, making it structurally impossible to skip.
+
+**How it works**:
+
+1. Takes a glob pattern (`--on`) and one or more shell commands (`--exec`)
+2. On each Stop event, SHA-256 hashes all files matching the glob that appear in `git diff` (staged + unstaged)
+3. Compares against the previous snapshot stored in `.claude/gitdiff-watcher.state.local.json`
+4. If no relevant changes: exits 0 silently (no command runs)
+5. If changes detected: runs all `--exec` commands
+6. If any command fails (exit code 2): Claude receives the stderr and retries — the snapshot is NOT updated, so the check runs again next turn
+7. On full success: updates the snapshot
+
+**Example configuration** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx @fcamblor/gitdiff-watcher@0.1.0 --on 'src/**/*.{ts,tsx}' --exec 'npm run build'",
+            "timeout": 300,
+            "statusMessage": "Checking TypeScript build..."
+          },
+          {
+            "type": "command",
+            "command": "npx @fcamblor/gitdiff-watcher@0.1.0 --on 'src/**/*.{ts,tsx}' --exec 'npm test -- --passWithNoTests'",
+            "timeout": 300,
+            "statusMessage": "Checking tests..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Multiple hooks run in parallel (Claude Code spawns one subagent per hook entry).
+
+**Key behaviors**:
+
+- **Conditional**: only fires when matching files changed — no wasted CI time on unrelated edits
+- **Retry-safe**: failed runs preserve the snapshot, so the same check runs on the next attempt
+- **Parallel**: multiple `--exec` commands within one hook entry run sequentially; use separate hook entries for parallel execution
+- **Silent on no-op**: exits 0 without output when no relevant changes are detected
+
+**Limitations**:
+
+- v0.1.0 — explicitly "work in progress", CLI options and state file format may change
+- Uses `git diff (staged + unstaged)` for file detection — files not tracked by git are not visible to the watcher
+- Retry loops: a misconfigured check that always fails will cause Claude to retry indefinitely; add a `--exec-timeout` and ensure your commands have correct exit codes
+- Each Stop hook failure starts a new Claude turn, consuming context — near the 200K limit, repeated failures accelerate context consumption
+
+**When to use gitdiff-watcher vs a native Stop hook**:
+
+The same quality gate can be written in ~20 lines of bash without gitdiff-watcher. Use gitdiff-watcher when you want the file-change conditional logic and state persistence without writing it yourself, or when you need parallel checks across a polyglot codebase (e.g., TypeScript build + Kotlin tests simultaneously).
+
+> **Cross-ref**: Stop hook mechanics at [ultimate-guide.md hooks section](../ultimate-guide.md). For PostToolUse build checks (fires after every file edit, not at handoff), see the hooks section example at line ~8262.
+
+---
+
 ## Alternative UIs

 ### Claude Chic
@ -556,6 +636,9 @@ Claude Code's plugin system supports community-built extensions. For detailed do
 - **[claudemarketplaces.com](https://claudemarketplaces.com)** - Auto-scan GitHub for marketplace plugins
 - **[agentskills.io](https://agentskills.io)** - Open standard for agent skills (26+ platforms)

+**Notable skill packs**:
+- **[gstack](https://github.com/garrytan/gstack)** — 6-skill workflow suite covering the full ship cycle: strategic product gate (`/plan-ceo-review`), architecture review (`/plan-eng-review`), paranoid code review (`/review`), automated release (`/ship`), native browser QA (`/browse`), and retrospective (`/retro`). Created by Garry Tan (Y Combinator CEO). See [Cognitive Mode Switching](../workflows/gstack-workflow.md) for the workflow pattern and adoption guide.
+
 ---

 ## Known Gaps
--- a/guide/workflows/README.md
+++ b/guide/workflows/README.md
@ -71,6 +71,24 @@ Scale CLAUDE.md across a multi-developer, multi-tool team with profile-based mod

 **When to use**: Team 5+ devs, multiple AI tools (Claude Code + Cursor/Windsurf), mixed OS

+### [Changelog Fragments](./changelog-fragments.md) ⭐ NEW
+
+**Enforce per-PR documentation with a 3-layer system: CLAUDE.md rule + UserPromptSubmit hook + CI gate**
+
+Eliminates merge conflicts on `CHANGELOG.md`, captures context at implementation time, and ensures DB migrations are never silently deployed. Includes a reusable `UserPromptSubmit` hook pattern for enforcing any mandatory workflow step.
+
+**Key Topics**:
+- CLAUDE.md workflow rule for autonomous fragment creation
+- `UserPromptSubmit` hook with 3-tier priority (enforcement, discovery, contextual)
+- Conditional suggestion pattern: "if PR-intent without fragment-mention"
+- CI enforcement with independent migration check job
+
+### [Cognitive Mode Switching](./gstack-workflow.md) ⭐ NEW
+
+Switch between specialist roles across your ship cycle: strategic product gate, architecture review, paranoid code review, automated release, native browser QA, and retrospective.
+
+**When to use**: Ship cycles where you want explicit separation between product direction, engineering rigor, review, and release — rather than one generic assistant handling all phases
+
 ---

 ## 🎨 Design & Content
@ -171,6 +189,7 @@ Multi-session task tracking with TodoWrite, tasks API, and context persistence a
 | **Code quality** | [Iterative Refinement](./iterative-refinement.md) |
 | **New project from template** | [Skeleton Projects](./skeleton-projects.md) |
 | **Team AI instructions** | [Team AI Instructions](./team-ai-instructions.md) |
+| **Enforce mandatory workflow steps** | [Changelog Fragments](./changelog-fragments.md) |
 | **Documentation** | [PDF Generation](./pdf-generation.md) |
 | **Social previews** | [OG Image Generation](./og-image-generation.md) |
 | **Conference talk from raw material** | [Talk Preparation Pipeline](./talk-pipeline.md) |
@ -181,6 +200,8 @@ Multi-session task tracking with TodoWrite, tasks API, and context persistence a
 | **Hook-driven automation** | [Event-Driven Agents](./event-driven-agents.md) |
 | **Full plan workflow** | [Plan Pipeline](./plan-pipeline.md) |
 | **Multi-session tracking** | [Task Management](./task-management.md) |
+| **Strategic gate before coding** | [Cognitive Mode Switching](./gstack-workflow.md) |
+| **Non-MCP browser automation** | [Cognitive Mode Switching](./gstack-workflow.md) |

 ---

--- a/guide/workflows/gstack-workflow.md
+++ b/guide/workflows/gstack-workflow.md
@ -0,0 +1,218 @@
+---
+title: "Cognitive Mode Switching"
+description: "Switch between specialist roles across your ship cycle — strategic gate, architecture, paranoid review, release, browser QA, retrospective"
+tags: [workflow, skills, planning, review, shipping, browser-automation]
+---
+
+# Cognitive Mode Switching
+
+> **Confidence**: Tier 2 — Reference implementation: [gstack](https://github.com/garrytan/gstack) by Garry Tan (Y Combinator CEO), 1,100+ stars in 24h of launch (March 2026).
+
+**Reading time**: ~10 min
+**Prerequisites**: Claude Code skills basics, plan mode
+**Related**: [Plan Pipeline](./plan-pipeline.md), [Plan-Driven Development](./plan-driven.md)
+
+---
+
+## TL;DR
+
+One generic assistant blurs all phases together. This pattern gives each phase a distinct cognitive mode: you summon the right brain for the job, then switch when the work changes.
+
+```
+/plan-ceo-review  → "Are we building the right thing?"
+/plan-eng-review  → "How do we make this buildable?"
+/review           → "What will blow up in production?"
+/ship             → Execute the release, no debate
+/browse           → Does it actually work in the browser?
+/retro            → How well did we ship this week?
+```
+
+The insight is that planning, reviewing, and shipping require fundamentally different cognitive postures — and a single assistant left in generic mode will blend them badly.
+
+---
+
+## The 6 Gears
+
+| Command | Role | Core question | When to switch |
+|---------|------|---------------|----------------|
+| `/plan-ceo-review` | Founder / CEO | "Are we building the right thing?" | Before writing any code |
+| `/plan-eng-review` | Eng manager / tech lead | "How do we make this buildable?" | After direction is locked |
+| `/review` | Paranoid staff engineer | "What can still break in prod?" | Before merging |
+| `/ship` | Release engineer | "Get the plane landed" | Branch is ready, no more debate |
+| `/browse` | QA engineer | "Does it actually work?" | After deploy, against staging or prod |
+| `/retro` | Engineering manager | "How well did we ship?" | Weekly or post-launch |
+
+---
+
+## The Gap This Fills: Pre-Implementation Strategic Gate
+
+The hardest thing to get right with an AI coding assistant is not the implementation. It is the question that comes before: **are we building the right thing?**
+
+Claude Code is optimized to build what you ask. If you say "add photo upload", it will add photo upload. It will not ask whether photo upload is actually the product. That is the problem `/plan-ceo-review` solves.
+
+**Example**: You are building a Craigslist-style listing app.
+
+- Request: "Let sellers upload a photo for their item"
+- Literal implementation: file picker + image save
+- What the real product is: helping sellers create listings that actually sell
+
+If you run `/plan-ceo-review` first, the assistant is explicitly asked to challenge the literal request and find the product hiding inside it. The output becomes a different brief entirely: auto-identify the product from the photo, pull specs and pricing comps, draft title and description, suggest the hero image, detect low-quality photos before they go live.
+
+That is a different feature. A better one. And you only get it by inserting an explicit gate before implementation starts.
+
+**The three modes inside `/plan-ceo-review`**:
+- **SCOPE EXPANSION** — find the 10-star product, ask "what would make this 10x better for 2x the effort?"
+- **HOLD SCOPE** — accept the direction, make the plan bulletproof
+- **SCOPE REDUCTION** — strip to the minimum viable version ruthlessly
+
+The user selects the mode. The assistant commits to it and does not drift.
+
+---
+
+## /plan-eng-review: Making the Idea Buildable
+
+Once direction is locked, the cognitive mode shifts from product intuition to engineering rigor. `/plan-eng-review` is where ideation stops and architecture starts.
+
+What it should produce:
+- Architecture diagram (components, boundaries, data flow)
+- State machine for the core flow
+- Sync vs async boundary decisions
+- Failure modes and retry logic
+- Trust boundaries (where do you accept external input?)
+- Test matrix
+
+The key unlock is **forcing diagram generation**. Diagrams surface hidden assumptions that prose conceals. A sequence diagram makes you specify who calls what. A state machine makes you enumerate every failure mode. Without them, "the system will handle it" stays vague indefinitely.
+
+---
+
+## /review: Paranoid Staff Engineer Mode
+
+Passing tests do not mean the branch is safe. `/review` exists for the class of bugs that survive CI and hit production anyway.
+
+What it checks:
+- N+1 queries
+- Race conditions (two tabs overwriting the same state)
+- Trust boundary violations (accepting client-provided metadata without validation)
+- Orphaned data on failure paths
+- Missing indexes
+- Bad retry logic
+- Tests that pass while missing the real failure mode
+- Prompt injection when LLM output flows into further processing
+
+The posture is deliberate: imagine the production incident before it happens.
+
+---
+
+## /browse: Non-MCP Native Browser Automation
+
+`/browse` is the most technically distinct piece of gstack. It is not a MCP server. It is a compiled native binary (TypeScript + Bun) that runs a persistent headless Chromium daemon.
+
+**Why the architecture matters**:
+
+| Approach | Cold start | Subsequent calls | State persistence |
+|----------|-----------|-----------------|-------------------|
+| MCP browser server | New connection per session | ~500ms+ | Lost between sessions |
+| `/browse` native daemon | ~3s (once) | ~100-200ms | Cookies, tabs, auth persist |
+
+This matters for QA workflows: logging into a staging environment once and then running a full navigation sequence stays fast because the daemon never restarts. No MCP socket overhead, no session reset.
+
+**Available operations**: navigate, read page text, take screenshots, snapshot accessibility tree with refs, click/fill by ref, run JavaScript, inspect console logs, capture network requests.
+
+**When to prefer this over MCP browser tools**:
+- Latency-sensitive QA loops (10+ page checks in sequence)
+- Environments where MCP server connections are restricted
+- When you need browser state (auth, cookies) to persist across multiple commands in one session
+
+**When to stick with MCP**: single-page checks, simpler environments, or when MCP browser tooling is already in place.
+
+---
+
+## Full Cycle Demo
+
+```
+# 1. Strategic gate — challenge the brief
+[plan mode]
+You: I want to add seller photo upload to the listing app.
+     Sellers should be able to upload a photo and we create the listing from it.
+
+You: /plan-ceo-review   (select SCOPE EXPANSION mode)
+
+Claude: "Photo upload" is not the feature. The real job is helping sellers
+        create listings that actually sell. Here's the 10-star version:
+        auto-identify the product, pull specs and pricing comps from the web,
+        draft title and description, suggest the best hero image...
+
+# 2. Engineering gate — lock the architecture
+You: /plan-eng-review
+
+Claude: [Architecture diagram, async job boundaries, state machine for
+        upload → classify → enrich → draft pipeline, failure modes,
+        trust boundaries, test matrix]
+
+# 3. Implement the plan
+[exit plan mode, write code]
+
+# 4. Paranoid review — find what tests missed
+You: /review
+
+Claude: Race condition: two tabs can overwrite cover-photo selection.
+        Trust boundary: pulling web data into draft generation creates
+        a prompt injection vector.
+        Missing: orphan cleanup for failed uploads.
+
+You: [fix the issues]
+
+# 5. Ship
+You: /ship
+
+Claude: [Syncs main, runs tests, pushes branch, opens PR — done]
+
+# 6. Browser QA against staging
+You: /browse staging.myapp.com — test the listing flow
+
+Claude: [Navigates routes, fills upload form, verifies enrichment renders,
+        checks console for errors, screenshots each step]
+        All pages load correctly. Listing flow works end to end.
+```
+
+---
+
+## Install
+
+```bash
+# Install globally (~/.claude/skills/)
+git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup
+```
+
+Or paste this directly into Claude Code and it handles the rest:
+
+> Install gstack: run `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`
+
+For team installs (committed to repo so `git clone` just works for teammates), see the [gstack README](https://github.com/garrytan/gstack).
+
+> **Note (March 2026)**: gstack was released March 11, 2026. The patterns are solid; the implementation is new. Verify the repository is actively maintained before adopting in a production workflow.
+
+---
+
+## When to Use This vs. Other Workflows
+
+| Situation | This workflow | Alternative |
+|-----------|---------------|-------------|
+| Complex feature, direction uncertain | `/plan-ceo-review` first | [Spec-First](./spec-first.md) |
+| Direction clear, architecture complex | `/plan-eng-review` | [Plan Pipeline](./plan-pipeline.md) |
+| Need independent validation of plan | [Plan Pipeline](./plan-pipeline.md) `/plan-validate` | — |
+| Browser automation, single page check | Any MCP browser tool | `/browse` (overkill) |
+| Browser automation, multi-step QA loop | `/browse` | MCP tools (slower) |
+| Want structured ADR learning loop | [Plan Pipeline](./plan-pipeline.md) | — |
+
+The main differentiator from [Plan Pipeline](./plan-pipeline.md): gstack is a linear gear sequence you control manually. Plan Pipeline is a more automated orchestration with ADR memory and parallel agent teams. For solo developers who want explicit control over each phase, gstack is faster to adopt.
+
+---
+
+## See Also
+
+- [Plan Pipeline](./plan-pipeline.md) — Automated 3-command workflow with ADR learning loop
+- [Plan-Driven Development](./plan-driven.md) — Fundamentals of planning before coding
+- [Iterative Refinement](./iterative-refinement.md) — Quality improvement cycles
+- [gstack on GitHub](https://github.com/garrytan/gstack) — Source, install instructions, full skill prompts
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -330,6 +330,10 @@ deep_dive:
  third_party_tools_rtk: "guide/ecosystem/third-party-tools.md:7"
  third_party_tools_session_mgmt: "guide/ecosystem/third-party-tools.md:126"
  third_party_tools_config_mgmt: "guide/ecosystem/third-party-tools.md:214"
+  third_party_tools_hook_utilities: "guide/ecosystem/third-party-tools.md:331"
+  third_party_gitdiff_watcher: "guide/ecosystem/third-party-tools.md:335"
+  third_party_gitdiff_watcher_upstream: "https://github.com/fcamblor/gitdiff-watcher"
+  third_party_gitdiff_watcher_purpose: "Stop hook utility — enforces build/test quality gates before handoff, fires only when matching files changed"
  third_party_tools_alternative_uis: "guide/ecosystem/third-party-tools.md:259"
  third_party_tools_known_gaps: "guide/ecosystem/third-party-tools.md:375"
  third_party_tools_recommendations: "guide/ecosystem/third-party-tools.md:391"