You MUST use this before any creative work - refines rough ideas into executable specifications through collaborative questioning, alternative exploration, and incremental validation. Use this skill when called from a command.
From spexnpx claudepluginhub rhuss/cc-spex --plugin spexThis skill uses the workspace's default tool permissions.
Help turn rough ideas into formal, executable specifications through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the specification and get user approval.
Key Difference from Standard Brainstorming:
These commands DO NOT EXIST. They will fail with "Unknown skill". When proposing next steps:
/speckit.specify (NOT /spex:specify)/speckit.plan (NOT /spex:plan)/speckit.tasks (NOT /spex:tasks)/speckit.implement (NOT /spex:implement)spex namespace only has: brainstorm, review-*, evolve, traits, init, help.
All spec workflow commands live in the speckit.* namespace.
</HARD-GATE>
Every project goes through this process. A todo list, a single-function utility, a config change: all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The spec can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
You MUST create a task for each of these items and complete them in order:
brainstorm/ for existing docs on similar topics, offer to update or create new/speckit.specify (or create manually), validate and commitspex:review-spec for formal validation; fix and re-review until approved (max 3 iterations, then surface to human)/speckit.plan or /speckit.implementbrainstorm/NN-topic-slug.mdbrainstorm/00-overview.md with index, open threads, parked ideasdigraph brainstorming {
"Initialize spec-kit" [shape=box];
"Explore project context" [shape=box];
"Related brainstorm exists?" [shape=diamond];
"Ask clarifying questions" [shape=box];
"Propose 2-3 approaches" [shape=box];
"Present spec sections" [shape=box];
"User approves spec?" [shape=diamond];
"Create specification file" [shape=box];
"Spec review loop\n(spex:review-spec)" [shape=box];
"Spec review passed?" [shape=diamond];
"User reviews spec?" [shape=diamond];
"Validate & commit spec" [shape=box];
"Offer /speckit.plan or /speckit.implement" [shape=box];
"Write brainstorm document" [shape=box];
"Update overview" [shape=box];
"Done" [shape=doublecircle];
"Initialize spec-kit" -> "Explore project context";
"Explore project context" -> "Related brainstorm exists?";
"Related brainstorm exists?" -> "Ask clarifying questions" [label="no, or user chooses new"];
"Related brainstorm exists?" -> "Ask clarifying questions" [label="yes, user chooses update"];
"Ask clarifying questions" -> "Propose 2-3 approaches";
"Propose 2-3 approaches" -> "Present spec sections";
"Present spec sections" -> "User approves spec?";
"User approves spec?" -> "Present spec sections" [label="no, revise"];
"User approves spec?" -> "Create specification file" [label="yes"];
"Create specification file" -> "Spec review loop\n(spex:review-spec)";
"Spec review loop\n(spex:review-spec)" -> "Spec review passed?";
"Spec review passed?" -> "Spec review loop\n(spex:review-spec)" [label="issues found,\nfix and re-review"];
"Spec review passed?" -> "User reviews spec?" [label="approved"];
"User reviews spec?" -> "Create specification file" [label="changes requested"];
"User reviews spec?" -> "Validate & commit spec" [label="approved"];
"Validate & commit spec" -> "Offer /speckit.plan or /speckit.implement";
"Offer /speckit.plan or /speckit.implement" -> "Write brainstorm document";
"Write brainstorm document" -> "Update overview";
"Update overview" -> "Done";
}
The terminal state is "Done" (after writing brainstorm document and updating overview). Do NOT invoke any implementation skill directly. After brainstorming, the ONLY next steps are spec-driven: planning or implementing from the approved spec.
Before starting the brainstorming workflow, ensure spec-kit is initialized:
{Skill: spec-kit}
If spec-kit prompts for restart, pause this workflow and resume after restart.
Claude MUST use /speckit.specify to create specs. Claude MUST NOT:
/speckit.specify for any reasonIf /speckit.* commands are not available, tell the user to run /spex:init first. Do NOT fall back to manual spec creation.
Check context first:
specs/ directory.specify/memory/constitution.md)brainstorm/ directory for existing brainstorm documents (triggers revisit detection, see step 3 in checklist)Assess scope before deep-diving:
Ask questions to refine:
Remember: You're building a SPEC, so focus on WHAT needs to happen, not HOW it will be implemented.
Propose 2-3 different approaches:
Questions to explore:
Once you believe you understand what you're building, present the spec:
Design for isolation and clarity:
Working in existing codebases:
Once the user approves the presented spec:
<HARD-GATE> You MUST invoke `/speckit.specify` to create the spec file. Do NOT create spec files manually using Write or Edit tools. Do NOT create the spec directory with mkdir. Do NOT write spec.md directly. The `/speckit.specify` command handles file creation, directory structure, numbering, and template formatting. Bypassing it is a process violation. </HARD-GATE>Announce spec creation:
"Based on our discussion, I'm creating the specification using /speckit.specify..."
Create spec file by invoking /speckit.specify:
This creates the spec at specs/[NNNN]-[feature-name]/spec.md using the spec-kit template.
Pass the approved spec content to /speckit.specify so it populates the template correctly.
If /speckit.specify is not available (commands not installed): Stop and tell the user
to run /spex:init first. Do NOT fall back to manual file creation.
Run clarification check (RECOMMENDED):
After creating the spec, invoke /speckit.clarify to identify any underspecified areas.
Present clarification results to user for review. If gaps are identified, update the spec before proceeding.
IMPORTANT: Capture implementation insights separately
If technical details emerged during brainstorming (technology choices, architecture decisions, trade-off discussions), create implementation-notes.md to capture them:
specs/features/[feature-name]/implementation-notes.mdWhy separate from spec:
Example content:
# Implementation Notes: User Authentication
## Design Decisions
### Decision: OAuth vs. Magic Links
- Chose OAuth (Google + GitHub)
- Rationale: User preference for familiar login flow
- Rejected magic links: Email deliverability concerns
### Decision: JWT in httpOnly cookies
- Prevents XSS attacks
- Refresh token rotation for security
- Trade-off: Slightly more complex than localStorage
Spec structure (spec-kit template provides this, but reference for review):
# Feature: [Feature Name]
## Purpose
[Why this feature exists - the problem it solves]
## Requirements
### Functional Requirements
- [What the feature must do]
- [Behavior in specific scenarios]
- [Integration points]
### Non-Functional Requirements
- [Performance constraints]
- [Security requirements]
- [Accessibility needs]
## Success Criteria
- [How we know it works]
- [Measurable outcomes]
## Error Handling
- [What can go wrong]
- [How errors should be handled]
## Edge Cases
- [Boundary conditions]
- [Unusual scenarios]
## Dependencies
- [Other features/systems required]
- [External services]
## Out of Scope
- [What this feature explicitly does NOT do]
- [Future considerations]
## Open Questions
- [Anything still unclear]
- [Decisions deferred to implementation]
.specify/memory/constitution.mdSpec Self-Review (quick inline check before formal review):
Before dispatching the formal review, do a quick inline pass:
Fix any issues inline before proceeding to the formal review.
Spec Review Loop:
After the self-review pass, run the formal review loop:
spex:review-spec to validate the spec for soundness and completenessspex:review-spec, repeat until approvedUser Review Gate:
After the spec review loop passes, ask the user to review the written spec before proceeding:
"Spec written and reviewed at
<path>. Please review it and let me know if you want to make any changes before we proceed to planning."
Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
Record spec path for brainstorm document:
Note the spec path (specs/[NNNN]-[feature-name]/) so the brainstorm document (step 12) can reference it with status spec-created.
Run consistency check (RECOMMENDED):
If /speckit.analyze is available, invoke it to check for cross-artifact consistency.
Generate review_brief.md:
After spec is validated, generate a brief for reviewers. Read the spec and synthesize:
Write to specs/[feature-name]/review_brief.md using the template:
# Review Brief: [Feature Name]
**Spec:** specs/[feature-name]/spec.md
**Generated:** YYYY-MM-DD
> Reviewer's guide to scope and key decisions. See full spec for details.
---
## Feature Overview
[3-5 sentences on purpose, scope, and key outcomes]
## Scope Boundaries
- **In scope:** [What this includes]
- **Out of scope:** [What this explicitly excludes]
- **Why these boundaries:** [Brief justification]
## Critical Decisions
### [Decision Title]
- **Choice:** [What was decided]
- **Trade-off:** [Key trade-off made]
- **Feedback:** [Specific question for reviewer]
## Areas of Potential Disagreement
> Decisions or approaches where reasonable reviewers might push back.
### [Topic]
- **Decision:** [What was decided]
- **Why this might be controversial:** [Reason]
- **Alternative view:** [What someone might prefer]
- **Seeking input on:** [Specific question]
## Naming Decisions
| Item | Name | Context |
|------|------|---------|
| ... | ... | ... |
## Open Questions
- [ ] [Question needing stakeholder input]
## Risk Areas
| Risk | Impact | Mitigation |
|------|--------|------------|
| ... | High/Med/Low | ... |
---
*Share with reviewers before implementation.*
Constraints:
Check if spex is initialized:
If .specify/ directory does not exist or .claude/commands/speckit.specify.md does not exist, warn the user:
/speckit.plan or /speckit.implement, you need to initialize the project with /spex:init. This sets up spec-kit templates, commands, and trait configuration."Offer next steps (use EXACTLY these command names):
/speckit.specify" (NOT /spex:specify, which does not exist)/speckit.plan or implement with /speckit.implement/spex:specify, /spex:plan, /spex:implement, or /spex:tasksCommit the spec:
git add specs/[NNNN]-[feature-name]/
git commit -m "Add spec for [feature name]
Includes:
- spec.md (requirements)
- review_brief.md (reviewer guide)
Assisted-By: 🤖 Claude Code"
Each brainstorm session produces a structured summary document. The document uses this format:
# Brainstorm: [Topic]
**Date:** YYYY-MM-DD
**Status:** active | parked | abandoned | spec-created
**Spec:** specs/NNNN-feature-name/ (only if status is spec-created)
## Problem Framing
[What problem is being explored and why it matters]
## Approaches Considered
### A: [Approach Name]
- Pros: ...
- Cons: ...
### B: [Approach Name]
- Pros: ...
- Cons: ...
## Decision
[What was chosen and why, or "Parked: [reason]" if no decision was reached]
## Open Threads
- [Unresolved question or idea that needs further exploration]
Status values:
active - session completed, idea is being pursuedparked - session stopped intentionally, idea may be revisitedabandoned - session stopped, idea is not being pursuedspec-created - session led to a spec (include spec path)The brainstorm/00-overview.md file provides a navigable index of all brainstorm sessions:
# Brainstorm Overview
Last updated: YYYY-MM-DD
## Sessions
| # | Date | Topic | Status | Spec |
|---|------|-------|--------|------|
| 01 | YYYY-MM-DD | topic-slug | spec-created | 0003 |
| 02 | YYYY-MM-DD | topic-slug | active | - |
| 03 | YYYY-MM-DD | topic-slug | parked | - |
## Open Threads
- [Thread description] (from #NN)
- [Thread description] (from #NN)
## Parked Ideas
- [Idea description] (#NN)
Reason: [why parked]
When: During step 3 of the checklist (after exploring project context).
How:
brainstorm/ directory exists. If not, skip (no prior brainstorms).NN-*.md files in brainstorm/ (excluding 00-overview.md).If "Update existing" is chosen: At session end, instead of creating a new file, append a new section to the existing document:
---
## Revisit: YYYY-MM-DD
### Updated Problem Framing
[How understanding has evolved]
### New Approaches Considered
...
### Updated Decision
...
### Open Threads
- [New or updated threads]
Then update the overview to reflect any status or thread changes.
When: Step 12 of the checklist (after transition, at session end).
You MUST write the brainstorm document at session end. This step is NOT optional.
Procedure:
Create directory if it does not exist:
mkdir -p brainstorm/
Detect next number by scanning existing files:
# List existing brainstorm docs, extract numbers, find max
ls brainstorm/[0-9][0-9]-*.md 2>/dev/null
Use max_existing_number + 1. If no files exist, start at 01. Do NOT gap-fill (if 01 and 03 exist, next is 04).
Generate topic slug: Derive from the brainstorm topic. Lowercase, hyphens, 2-4 words.
Example: "user authentication system" becomes auth-system
Determine status:
spec-created (include spec path)parkedabandonedactiveWrite the document using the Brainstorm Document Structure defined above.
Commit the brainstorm document:
git add brainstorm/NN-topic-slug.md
git commit -m "Add brainstorm: [topic]
Assisted-By: 🤖 Claude Code"
When: Step 13 of the checklist (immediately after writing the brainstorm document).
You MUST update the overview after every brainstorm document write or update. This step is NOT optional.
Procedure:
If brainstorm/00-overview.md does not exist, create it.
If brainstorm/ exists but 00-overview.md is missing, regenerate it from all existing documents.
Always regenerate by scanning all documents (idempotent full rebuild):
NN-*.md files in brainstorm/ (excluding 00-overview.md)## Open Threadsparked, collect the idea and reasonBuild the overview using the Overview Document Structure defined above:
(from #NN)parked documentsWrite brainstorm/00-overview.md with the rebuilt content.
Commit the overview update:
git add brainstorm/00-overview.md
git commit -m "Update brainstorm overview
Assisted-By: 🤖 Claude Code"
When: The user stops the brainstorm before creating a spec.
Zero-interaction guard: If the session had no meaningful interaction (no approaches explored, no clarifying questions answered beyond the initial topic), do NOT prompt to save. Simply end the session without creating any artifacts.
For sessions with meaningful interaction (approaches were discussed, questions were answered):
Use AskUserQuestion to ask: "Save this brainstorm session?"
parked, update overviewabandoned, update overviewIf the user chooses to save, follow the "Writing the Brainstorm Document" and "Updating the Overview" procedures above.
If no constitution exists and this seems to be early in project:
After first spec created:
/speckit.constitutionDon't be pushy: Constitution is optional but recommended.
User: I want to add a comment system to the blog
You: I'm using spex:brainstorm to refine this idea into a spec.
Let me understand the context first...
[Reviews existing code and specs]
For the comment system, what level of features do you want?
A) Basic - Name, email, comment text only
B) Standard - Above + threading/replies
C) Advanced - Above + reactions, editing, moderation
D) Full - Above + notifications, mentions, markdown
User: B - Standard with threading
You: Great. For threading, should replies be:
A) Unlimited depth (comments on comments on comments...)
B) One level only (reply to top-level comments)
C) Two levels (reply and one nested level)
[... conversation continues ...]
You: Based on our discussion, here's the spec:
## Purpose
Enable readers to discuss blog posts through threaded comments,
fostering community engagement and feedback.
## Requirements
### Functional Requirements
- Readers can submit comments on published blog posts
- Comments require: name, email, comment text
- Comments support one level of replies (threading)
- Comments display in chronological order, newest first
- Replies display under parent comment
...
Does this look right so far?
User: Yes
[... continues through all sections, getting approval ...]
You: Spec approved! Creating the specification file...
[Creates spec via /speckit.specify]
[Runs spex:review-spec]
[Asks user to review spec before proceeding]
Spec is sound and implementable.
Committed to git.
Ready to move forward? Next steps:
- Plan first: `/speckit.plan`
- Implement directly: `/speckit.implement`
Don't:
Do:
The spec you create here becomes the source of truth. Implementation will flow from it. Code reviews will validate against it. Make it clear, complete, and correct.
Good specs enable good implementation. Take the time to get it right.