marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
- 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>
This commit is contained in:
Florian BRUNIAUX 2026-03-13 10:34:51 +01:00
parent ded3a9858d
commit 1728b6de39
6 changed files with 665 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

97
guide/ecosystem/third-party-tools.md
View file

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

21
guide/workflows/README.md
View file

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

218
guide/workflows/gstack-workflow.md Normal file
View file

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