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>
This commit is contained in:
Florian BRUNIAUX
parent
ded3a9858d
commit
1728b6de39
6 changed files with 665 additions and 7 deletions
137
examples/commands/plan-ceo-review.md
Normal file
137
examples/commands/plan-ceo-review.md
Normal file
|
|
@ -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
|
||||
195
examples/commands/plan-eng-review.md
Normal file
195
examples/commands/plan-eng-review.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue