Skip to content

Commit 1728b6d

Browse files
FlorianBruniauxclaude
FlorianBruniaux
and
claude
committed
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>
1 parent ded3a98 commit 1728b6d

File tree

6 files changed

+665
-7
lines changed

6 files changed

+665
-7
lines changed

‎examples/commands/plan-ceo-review.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: plan-ceo-review
3+
description: Strategic product gate — challenge the brief, find the 10-star product hiding inside the request, before writing any code
4+
version: 1.0.0
5+
inspired-by: https://github.com/garrytan/gstack
6+
---
7+
8+
# /plan-ceo-review — Strategic Product Gate
9+
10+
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.
11+
12+
**Use in plan mode, before any implementation.**
13+
14+
---
15+
16+
## The Problem This Solves
17+
18+
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.
19+
20+
---
21+
22+
## When to Use
23+
24+
- Before implementing any significant feature request
25+
- Especially when the request is specific ("add photo upload") — specificity often signals the requester has already collapsed the solution space
26+
- When you want to pressure-test a direction before committing engineering time
27+
28+
---
29+
30+
## Three Modes
31+
32+
The command asks the user to choose one before proceeding:
33+
34+
| Mode | Posture | Use when |
35+
|------|---------|----------|
36+
| **SCOPE EXPANSION** | Find the 10-star product, push scope up | Direction is fuzzy, want to dream |
37+
| **HOLD SCOPE** | Accept direction, make the plan bulletproof | Direction is locked, want rigor |
38+
| **SCOPE REDUCTION** | Strip to minimum viable, cut ruthlessly | Overloaded backlog, need to ship fast |
39+
40+
The assistant commits to the selected mode and does not drift mid-review.
41+
42+
---
43+
44+
## Prompt Template
45+
46+
```markdown
47+
# /plan-ceo-review
48+
49+
You are in CEO / founder review mode. Your job is NOT to implement anything.
50+
Your job is to review the plan or feature request with product-level thinking
51+
and return a better brief.
52+
53+
## Step 0: Choose Mode
54+
55+
Ask the user which mode to use (if not specified):
56+
- SCOPE EXPANSION: Find the 10-star product. Push scope up. What's the version
57+
that feels inevitable and delightful?
58+
- HOLD SCOPE: Accept the direction. Make this plan bulletproof. Catch every
59+
failure mode and unstated assumption.
60+
- SCOPE REDUCTION: Find the minimum viable version that achieves the core
61+
outcome. Cut everything else.
62+
63+
Once the user selects, commit to that mode for the entire review.
64+
65+
## Step 1: Restate the Request
66+
67+
Summarize the literal request in 1-2 sentences. Be precise — not editorialized.
68+
69+
## Step 2: Challenge the Premise
70+
71+
Ask the more important question: what is this product actually FOR?
72+
73+
- What is the user's real job-to-be-done?
74+
- Is the literal request the best way to solve it?
75+
- What assumption is the request making that might be wrong?
76+
77+
## Step 3: The Real Product (EXPANSION) / Bulletproof Plan (HOLD) / MVP (REDUCTION)
78+
79+
**SCOPE EXPANSION**: Describe the 10-star version of this product.
80+
- What would make this 10x better for 2x the effort?
81+
- What do users actually want, not what they asked for?
82+
- List 5-8 specific features or design decisions that would make this feel
83+
inevitable.
84+
85+
**HOLD SCOPE**: Accept the direction. Now find everything that can go wrong.
86+
- Unstated assumptions in the request
87+
- Edge cases that are not covered
88+
- Missing error states
89+
- UX gaps
90+
- Security or trust boundary issues
91+
- Operational concerns (monitoring, rollback, data migration)
92+
93+
**SCOPE REDUCTION**: What is the smallest version that proves the core value?
94+
- What is the one thing this must do?
95+
- What can be cut without losing the point?
96+
- What can be deferred to v2?
97+
98+
## Step 4: Recommendation
99+
100+
Return one of:
101+
- **Proceed as stated** — the original request is the right product
102+
- **Reframe** — here is the better brief (with specifics)
103+
- **Reject** — here is why this is the wrong direction, and what to build instead
104+
105+
Do NOT make any code changes. This is a review, not an implementation.
106+
```
107+
108+
---
109+
110+
## Example
111+
112+
**Input**: "Let sellers upload a photo for their listing"
113+
114+
**Output (SCOPE EXPANSION)**:
115+
> "Photo upload" is not the feature. The real job is helping sellers create listings that actually sell.
116+
>
117+
> 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.
118+
>
119+
> **Recommendation**: Reframe. The brief should be "smart listing creation from photo" not "photo upload".
120+
121+
---
122+
123+
## Integration with Other Commands
124+
125+
```
126+
/plan-ceo-review → lock product direction
127+
/plan-eng-review → lock technical architecture
128+
[implement]
129+
/review → paranoid pre-merge check
130+
/ship → release
131+
```
132+
133+
## See Also
134+
135+
- [Cognitive Mode Switching](../../guide/workflows/gstack-workflow.md) — full workflow context
136+
- [plan-eng-review](./plan-eng-review.md) — next step after direction is locked
137+
- [plan-start](./plan-start.md) — native plan mode command

‎examples/commands/plan-eng-review.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
name: plan-eng-review
3+
description: Engineering architecture gate — lock architecture, diagrams, edge cases, and test matrix before writing implementation code
4+
version: 1.0.0
5+
inspired-by: https://github.com/garrytan/gstack
6+
---
7+
8+
# /plan-eng-review — Engineering Architecture Gate
9+
10+
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.
11+
12+
**Use after `/plan-ceo-review` has locked direction. Still in plan mode.**
13+
14+
---
15+
16+
## The Problem This Solves
17+
18+
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.
19+
20+
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.
21+
22+
---
23+
24+
## When to Use
25+
26+
- After product direction is validated (post `/plan-ceo-review` or equivalent)
27+
- Before any implementation work starts on a non-trivial feature
28+
- When the feature has async components, external dependencies, or multi-step flows
29+
- Any time "the architecture is clear" needs to be proven, not assumed
30+
31+
---
32+
33+
## What It Should Produce
34+
35+
| Output | Why it matters |
36+
|--------|----------------|
37+
| Architecture diagram (Mermaid) | Makes component boundaries explicit |
38+
| Data flow diagram | Shows where data transforms and who owns what |
39+
| State machine for core flow | Forces enumeration of all states including failures |
40+
| Sync vs async boundary decisions | Prevents "just make it async" without reasoning |
41+
| Failure mode inventory | Every failure path, not just happy path |
42+
| Trust boundary map | Where do you accept external input? What do you validate? |
43+
| Test matrix | What needs to be tested and at which layer |
44+
45+
---
46+
47+
## Prompt Template
48+
49+
```markdown
50+
# /plan-eng-review
51+
52+
You are in engineering manager / tech lead mode. Direction is locked.
53+
Your job is to make it buildable — turn the product direction into a
54+
technical spec that an engineer can implement without making architecture
55+
decisions on the fly.
56+
57+
Do NOT question the product direction. Do NOT suggest scope changes.
58+
Do NOT implement anything. Return a technical spec.
59+
60+
## Step 1: Restate the Feature
61+
62+
1-2 sentences: what is being built. Confirm you are working from the
63+
correct brief.
64+
65+
## Step 2: Architecture Diagram
66+
67+
Draw the component architecture in Mermaid:
68+
- All components involved (frontend, backend, jobs, storage, external APIs)
69+
- Boundaries between components
70+
- Data flow directions
71+
72+
```mermaid
73+
graph LR
74+
...
75+
```
76+
77+
## Step 3: Core Flow — Sequence Diagram
78+
79+
Draw the happy path as a sequence diagram:
80+
- Which components call which, in what order
81+
- What data passes at each step
82+
- Where async handoffs happen
83+
84+
```mermaid
85+
sequenceDiagram
86+
...
87+
```
88+
89+
## Step 4: State Machine
90+
91+
Draw the state machine for the core domain object:
92+
- All valid states
93+
- All transitions and their triggers
94+
- Terminal states (success AND failure)
95+
96+
```mermaid
97+
stateDiagram-v2
98+
...
99+
```
100+
101+
## Step 5: Sync vs Async Decisions
102+
103+
For each operation in the flow, decide:
104+
- **Synchronous** (blocks the request): why, and what is the latency budget
105+
- **Asynchronous** (background job): why, what triggers retry, how does the
106+
caller know it succeeded
107+
108+
## Step 6: Failure Mode Inventory
109+
110+
For each step in the flow, enumerate:
111+
- What can fail
112+
- How it fails (silently? loudly? partial success?)
113+
- What the recovery path is
114+
- What the user sees
115+
116+
Flag any failure that is currently silent.
117+
118+
## Step 7: Trust Boundaries
119+
120+
For each external input (user uploads, API responses, webhook payloads):
121+
- What do you trust? What do you validate?
122+
- Where could malicious input cause harm?
123+
- Is any external data flowing into further processing (prompt injection risk)?
124+
125+
## Step 8: Test Matrix
126+
127+
| Layer | What to test | Why |
128+
|-------|-------------|-----|
129+
| Unit | ... | ... |
130+
| Integration | ... | ... |
131+
| E2E | ... | ... |
132+
133+
Identify any failure mode from Step 6 that does not have a corresponding test.
134+
135+
## Step 9: Open Questions
136+
137+
List any architectural decision that is genuinely unclear and needs a human
138+
decision before implementation can start. Not a comprehensive list — only
139+
blockers.
140+
```
141+
142+
---
143+
144+
## Example
145+
146+
**Feature**: Smart listing creation from photo (post-`/plan-ceo-review`)
147+
148+
**Output excerpt**:
149+
```mermaid
150+
graph LR
151+
Upload[Photo Upload] --> Storage[Object Storage]
152+
Storage --> Classify[Vision Classification Job]
153+
Classify --> Enrich[Web Enrichment Job]
154+
Enrich --> DraftGen[Draft Generation]
155+
DraftGen --> DB[(Listings DB)]
156+
DraftGen --> UI[Listing Editor UI]
157+
```
158+
159+
State machine:
160+
```mermaid
161+
stateDiagram-v2
162+
[*] --> pending
163+
pending --> classifying
164+
classifying --> enriching
165+
classifying --> classification_failed
166+
enriching --> draft_ready
167+
enriching --> enrichment_partial
168+
enrichment_partial --> draft_ready
169+
draft_ready --> published
170+
draft_ready --> discarded
171+
```
172+
173+
Failure modes:
174+
- Classification fails → degrade to manual listing (not silent failure)
175+
- Enrichment partially fails → use what succeeded, flag missing fields
176+
- Upload succeeds, classification job never starts → orphaned file, cleanup job required
177+
- Web data in draft generation → prompt injection vector, sanitize before passing to LLM
178+
179+
---
180+
181+
## Integration with Other Commands
182+
183+
```
184+
/plan-ceo-review → product direction locked
185+
/plan-eng-review → architecture locked ← you are here
186+
[implement]
187+
/review → paranoid pre-merge check
188+
/ship → release
189+
```
190+
191+
## See Also
192+
193+
- [Cognitive Mode Switching](../../guide/workflows/gstack-workflow.md) — full workflow context
194+
- [plan-ceo-review](./plan-ceo-review.md) — previous step
195+
- [Plan Pipeline](../../guide/workflows/plan-pipeline.md) — more automated orchestration with ADR memory

0 commit comments

Comments
 (0)