@every-env/compound-plugin 2.38.0 → 2.39.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Release numbering now follows the repository `v*` tag line. Starting at `v2.34.0`, the root CLI package and this changelog stay on that shared version stream. Older entries below retain the previous `0.x` CLI numbering.
 
+# [2.39.0](https://github.com/EveryInc/compound-engineering-plugin/compare/v2.38.0...v2.39.0) (2026-03-16)
+
+
+### Bug Fixes
+
+* drop 'CLI' suffix from Codex and Gemini platform names ([ec8d685](https://github.com/EveryInc/compound-engineering-plugin/commit/ec8d68580f3da65852e72c127cccc6e66326369b))
+* make brainstorm handoff auto-chain and cross-platform ([637653d](https://github.com/EveryInc/compound-engineering-plugin/commit/637653d2edf89c022b9e312ea02c0ac1a305d741))
+* restore 'wait for the user's reply' fallback language ([fca3a40](https://github.com/EveryInc/compound-engineering-plugin/commit/fca3a4019c55c76b9f1ad326cc3d284f5007b8f4))
+
+
+### Features
+
+* add leverage check to brainstorm skill ([0100245](https://github.com/EveryInc/compound-engineering-plugin/commit/01002450cd077b800a917625c5eb6d12da061d0b))
+* instruct brainstorm skill to use platform blocking question tools ([d2c4cee](https://github.com/EveryInc/compound-engineering-plugin/commit/d2c4cee6f9774a5fb2c8ca325c389dadb4a72b1c))
+* refactor brainstorm skill into requirements-first workflow ([4d80a59](https://github.com/EveryInc/compound-engineering-plugin/commit/4d80a59e51b4b2e99ff8c2443e2a1b039d7475c9))
+
 # [2.38.0](https://github.com/EveryInc/compound-engineering-plugin/compare/v2.37.1...v2.38.0) (2026-03-16)
 
 

package/README.md

@@ -194,7 +194,7 @@ Brainstorm → Plan → Work → Review → Compound → Repeat
 | `/ce:review` | Multi-agent code review before merging |
 | `/ce:compound` | Document learnings to make future work easier |
 
-The `brainstorming` skill supports `/ce:brainstorm` with collaborative dialogue to clarify requirements and compare approaches before committing to a plan.
+The `/ce:brainstorm` skill supports collaborative dialogue to clarify requirements and compare approaches before committing to a plan.
 
 Each cycle compounds: brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "type": "module",
   "private": false,
   "bin": {

package/plugins/compound-engineering/CLAUDE.md

@@ -76,10 +76,10 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 - [ ] Use imperative/infinitive form (verb-first instructions)
 - [ ] Avoid second person ("you should") - use objective language ("To accomplish X, do Y")
 
-### AskUserQuestion Usage
+### Cross-Platform User Interaction
 
-- [ ] If the skill uses `AskUserQuestion`, it must include an "Interaction Method" preamble explaining the numbered-list fallback for non-Claude environments
-- [ ] Prefer avoiding `AskUserQuestion` entirely (see `brainstorming/SKILL.md` pattern) for skills intended to run cross-platform
+- [ ] When a skill needs to ask the user a question, instruct use of the platform's blocking question tool and name the known equivalents (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini)
+- [ ] Include a fallback for environments without a question tool (e.g., present numbered options and wait for the user's reply before proceeding)
 
 ### Quick Validation Command
 

package/plugins/compound-engineering/README.md

@@ -131,7 +131,6 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou
 
 | Skill | Description |
 |-------|-------------|
-| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
 | `document-review` | Improve documents through structured self-review |
 | `every-style-editor` | Review copy for Every's style guide compliance |
 | `file-todos` | File-based todo tracking system |

package/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md

@@ -1,16 +1,38 @@
 ---
 name: ce:brainstorm
-description: Explore requirements and approaches through collaborative dialogue before planning implementation
+description: 'Explore requirements and approaches through collaborative dialogue before writing a right-sized requirements document and planning implementation. Use for feature ideas, problem framing, when the user says ''let''s brainstorm'', or when they want to think through options before deciding what to build. Also use when a user describes a vague or ambitious feature request, asks ''what should we build'', ''help me think through X'', presents a problem with multiple valid solutions, or seems unsure about scope or direction — even if they don''t explicitly ask to brainstorm.'
 argument-hint: "[feature idea or problem to explore]"
 ---
 
 # Brainstorm a Feature or Improvement
 
-**Note: The current year is 2026.** Use this when dating brainstorm documents.
+**Note: The current year is 2026.** Use this when dating requirements documents.
 
 Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/ce:plan`, which answers **HOW** to build it.
 
-**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
+The durable output of this workflow is a **requirements document**. In other workflows this might be called a lightweight PRD or feature brief. In compound engineering, keep the workflow name `brainstorm`, but make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria.
+
+This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution.
+
+## Core Principles
+
+1. **Assess scope first** - Match the amount of ceremony to the size and ambiguity of the work.
+2. **Be a thinking partner** - Suggest alternatives, challenge assumptions, and explore what-ifs instead of only extracting requirements.
+3. **Resolve product decisions here** - User-facing behavior, scope boundaries, and success criteria belong in this workflow. Detailed implementation belongs in planning.
+4. **Keep implementation out of the requirements doc by default** - Do not include libraries, schemas, endpoints, file layouts, or code-level design unless the brainstorm itself is inherently about a technical or architectural change.
+5. **Right-size the artifact** - Simple work gets a compact requirements document or brief alignment. Larger work gets a fuller document. Do not add ceremony that does not help planning.
+6. **Apply YAGNI to carrying cost, not coding effort** - Prefer the simplest approach that delivers meaningful value. Avoid speculative complexity and hypothetical future-proofing, but low-cost polish or delight is worth including when its ongoing cost is small and easy to maintain.
+
+## Interaction Rules
+
+1. **Ask one question at a time** - Do not batch several unrelated questions into one message.
+2. **Prefer single-select multiple choice** - Use single-select when choosing one direction, one priority, or one next step.
+3. **Use multi-select rarely and intentionally** - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
+4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+## Output Guidance
+
+- **Keep outputs concise** - Prefer short sections, brief bullets, and only enough detail to support the next decision.
 
 ## Feature Description
 
@@ -22,9 +44,16 @@ Do not proceed until you have a feature description from the user.
 
 ## Execution Flow
 
-### Phase 0: Assess Requirements Clarity
+### Phase 0: Resume, Assess, and Route
+
+#### 0.1 Resume Existing Work When Appropriate
 
-Evaluate whether brainstorming is needed based on the feature description.
+If the user references an existing brainstorm topic or document, or there is an obvious recent matching `*-requirements.md` file in `docs/brainstorms/`:
+- Read the document
+- Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?"
+- If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate
+
+#### 0.2 Assess Whether Brainstorming Is Needed
 
 **Clear requirements indicators:**
 - Specific acceptance criteria provided
@@ -33,71 +62,228 @@ Evaluate whether brainstorming is needed based on the feature description.
 - Constrained, well-defined scope
 
 **If requirements are already clear:**
-Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/ce:plan` instead, or would you like to explore the idea further?"
+Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Only write a short requirements document when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely — go straight to Phase 1.3 or Phase 3.
+
+#### 0.3 Assess Scope
+
+Use the feature description plus a light repo scan to classify the work:
+- **Lightweight** - small, well-bounded, low ambiguity
+- **Standard** - normal feature or bounded refactor with some decisions to make
+- **Deep** - cross-cutting, strategic, or highly ambiguous
+
+If the scope is unclear, ask one targeted question to disambiguate and then proceed.
 
 ### Phase 1: Understand the Idea
 
-#### 1.1 Repository Research (Lightweight)
+#### 1.1 Existing Context Scan
+
+Scan the repo before substantive brainstorming. Match depth to scope:
+
+**Lightweight** — Search for the topic, check if something similar already exists, and move on.
+
+**Standard and Deep** — Two passes:
 
-Run a quick repo scan to understand existing patterns:
+*Constraint Check* — Check project instruction files (`AGENTS.md`, `CLAUDE.md`) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.
 
-- Task compound-engineering:research:repo-research-analyst("Understand existing patterns related to: <feature_description>")
+*Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
 
-Focus on: similar features, established patterns, CLAUDE.md guidance.
+If nothing obvious appears after a short scan, say so and continue. Do not drift into technical planning — avoid inspecting tests, migrations, deployment, or low-level architecture unless the brainstorm is itself about a technical decision.
 
-#### 1.2 Collaborative Dialogue
+#### 1.2 Product Pressure Test
 
-Use the **AskUserQuestion tool** to ask questions **one at a time**.
+Before generating approaches, challenge the request to catch misframing. Match depth to scope:
 
-**Guidelines (see `brainstorming` skill for detailed techniques):**
+**Lightweight:**
+- Is this solving the real user problem?
+- Are we duplicating something that already covers this?
+- Is there a clearly better framing with near-zero extra cost?
+
+**Standard:**
+- Is this the right problem, or a proxy for a more important one?
+- What user or business outcome actually matters here?
+- What happens if we do nothing?
+- Is there a nearby framing that creates more user value without more carrying cost? If so, what complexity does it add?
+- Given the current project state, user goal, and constraints, what is the single highest-leverage move right now: the request as framed, a reframing, one adjacent addition, a simplification, or doing nothing?
+- Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling
+- Use the result to sharpen the conversation, not to bulldoze the user's intent
+
+**Deep** — Standard questions plus:
+- What durable capability should this create in 6-12 months?
+- Does this move the product toward that, or is it only a local patch?
+
+#### 1.3 Collaborative Dialogue
+
+Use the platform's blocking question tool when available (see Interaction Rules). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+**Guidelines:**
+- Ask questions **one at a time**
 - Prefer multiple choice when natural options exist
-- Start broad (purpose, users) then narrow (constraints, edge cases)
-- Validate assumptions explicitly
-- Ask about success criteria
+- Prefer **single-select** when choosing one direction, one priority, or one next step
+- Use **multi-select** only for compatible sets that can all coexist; if prioritization matters, ask which selected item is primary
+- Start broad (problem, users, value) then narrow (constraints, exclusions, edge cases)
+- Clarify the problem frame, validate assumptions, and ask about success criteria
+- Make requirements concrete enough that planning will not need to invent behavior
+- Surface dependencies or prerequisites only when they materially affect scope
+- Resolve product decisions here; leave technical implementation choices for planning
+- Bring ideas, alternatives, and challenges instead of only interviewing
 
-**Exit condition:** Continue until the idea is clear OR user says "proceed"
+**Exit condition:** Continue until the idea is clear OR the user explicitly wants to proceed.
 
 ### Phase 2: Explore Approaches
 
-Propose **2-3 concrete approaches** based on research and conversation.
+If multiple plausible directions remain, propose **2-3 concrete approaches** based on research and conversation. Otherwise state the recommended direction directly.
+
+When useful, include one deliberately higher-upside alternative:
+- Identify what adjacent addition or reframing would most increase usefulness, compounding value, or durability without disproportionate carrying cost. Present it as a challenger option alongside the baseline, not as the default. Omit it when the work is already obviously over-scoped or the baseline request is clearly the right move.
 
 For each approach, provide:
 - Brief description (2-3 sentences)
 - Pros and cons
+- Key risks or unknowns
 - When it's best suited
 
-Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
+Lead with your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.
+
+If one approach is clearly best and alternatives are not meaningful, skip the menu and state the recommendation directly.
+
+If relevant, call out whether the choice is:
+- Reuse an existing pattern
+- Extend an existing capability
+- Build something net new
+
+### Phase 3: Capture the Requirements
+
+Write or update a requirements document only when the conversation produced durable decisions worth preserving.
+
+This document should behave like a lightweight PRD without PRD ceremony. Include what planning needs to execute well, and skip sections that add no value for the scope.
+
+The requirements document is for product definition and scope control. Do **not** include implementation details such as libraries, schemas, endpoints, file layouts, or code structure unless the brainstorm is inherently technical and those details are themselves the subject of the decision.
+
+**Required content for non-trivial work:**
+- Problem frame
+- Concrete requirements or intended behavior with stable IDs
+- Scope boundaries
+- Success criteria
+
+**Include when materially useful:**
+- Key decisions and rationale
+- Dependencies or assumptions
+- Outstanding questions
+- Alternatives considered
+- High-level technical direction only when the work is inherently technical and the direction is part of the product/architecture decision
+
+**Document structure:** Use this template and omit clearly inapplicable optional sections:
 
-Use **AskUserQuestion tool** to ask which approach the user prefers.
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+
+# <Topic Title>
+
+## Problem Frame
+[Who is affected, what is changing, and why it matters]
+
+## Requirements
+- R1. [Concrete user-facing behavior or requirement]
+- R2. [Concrete user-facing behavior or requirement]
+
+## Success Criteria
+- [How we will know this solved the right problem]
+
+## Scope Boundaries
+- [Deliberate non-goal or exclusion]
+
+## Key Decisions
+- [Decision]: [Rationale]
+
+## Dependencies / Assumptions
+- [Only include if material]
+
+## Outstanding Questions
+
+### Resolve Before Planning
+- [Affects R1][User decision] [Question that must be answered before planning can proceed]
+
+### Deferred to Planning
+- [Affects R2][Technical] [Question that should be answered during planning or codebase exploration]
+- [Affects R2][Needs research] [Question that likely requires research during planning]
+
+## Next Steps
+[If `Resolve Before Planning` is empty: `→ /ce:plan` for structured implementation planning]
+[If `Resolve Before Planning` is not empty: `→ Resume /ce:brainstorm` to resolve blocking questions before planning]
+```
+
+For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
 
-### Phase 3: Capture the Design
+For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
 
-Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`.
+For very small requirements docs with only 1-3 simple requirements, plain bullet requirements are acceptable. For **Standard** and **Deep** requirements docs, use stable IDs like `R1`, `R2`, `R3` so planning and later review can refer to them unambiguously.
 
-**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
+When the work is simple, combine sections rather than padding them. A short requirements document is better than a bloated one.
+
+Before finalizing, check:
+- What would `ce:plan` still have to invent if this brainstorm ended now?
+- Do any requirements depend on something claimed to be out of scope?
+- Are any unresolved items actually product decisions rather than planning questions?
+- Did implementation details leak in when they shouldn't have?
+- Is there a low-cost change that would make this materially more useful?
+
+If planning would need to invent product behavior, scope boundaries, or success criteria, the brainstorm is not complete yet.
 
 Ensure `docs/brainstorms/` directory exists before writing.
 
-**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.
+If a document contains outstanding questions:
+- Use `Resolve Before Planning` only for questions that truly block planning
+- If `Resolve Before Planning` is non-empty, keep working those questions during the brainstorm by default
+- If the user explicitly wants to proceed anyway, convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question before proceeding
+- Do not force resolution of technical questions during brainstorming just to remove uncertainty
+- Put technical questions, or questions that require validation or research, under `Deferred to Planning` when they are better answered there
+- Use tags like `[Needs research]` when the planner should likely investigate the question rather than answer it from repo context alone
+- Carry deferred questions forward explicitly rather than treating them as a failure to finish the requirements doc
 
 ### Phase 4: Handoff
 
-Use **AskUserQuestion tool** to present next steps:
+#### 4.1 Present Next-Step Options
+
+Present next steps using the platform's blocking question tool when available (see Interaction Rules). Otherwise present numbered options in chat and end the turn.
+
+If `Resolve Before Planning` contains any items:
+- Ask the blocking questions now, one at a time, by default
+- If the user explicitly wants to proceed anyway, first convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question
+- If the user chooses to pause instead, present the handoff as paused or blocked rather than complete
+- Do not offer `Proceed to planning` or `Proceed directly to work` while `Resolve Before Planning` remains non-empty
+
+**Question when no blocking questions remain:** "Brainstorm complete. What would you like to do next?"
+
+**Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
+
+Present only the options that apply:
+- **Proceed to planning (Recommended)** - Run `/ce:plan` for structured implementation planning
+- **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
+- **Review and refine** - Offer this only when a requirements document exists and can be improved through structured review
+- **Ask more questions** - Continue clarifying scope, preferences, or edge cases
+- **Share to Proof** - Offer this only when a requirements document exists
+- **Done for now** - Return later
+
+If the direct-to-work gate is not satisfied, omit that option entirely.
 
-**Question:** "Brainstorm captured. What would you like to do next?"
+#### 4.2 Handle the Selected Option
 
-**Options:**
-1. **Review and refine** - Improve the document through structured self-review
-2. **Proceed to planning** - Run `/ce:plan` (will auto-detect this brainstorm)
-3. **Share to Proof** - Upload to Proof for collaborative review and sharing
-4. **Ask more questions** - I have more questions to clarify before moving on
-5. **Done for now** - Return later
+**If user selects "Proceed to planning (Recommended)":**
+
+Immediately run `/ce:plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
+
+**If user selects "Proceed directly to work":**
+
+Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
 
 **If user selects "Share to Proof":**
 
 ```bash
-CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md)
-TITLE="Brainstorm: <topic title>"
+CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md)
+TITLE="Requirements: <topic title>"
 RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
   -H "Content-Type: application/json" \
   -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
@@ -108,38 +294,42 @@ Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
 
 If the curl fails, skip silently. Then return to the Phase 4 options.
 
-**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4.
+**If user selects "Ask more questions":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user questions one at a time to further refine the design. Probe deeper into edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
 
 **If user selects "Review and refine":**
 
-Load the `document-review` skill and apply it to the brainstorm document.
+Load the `document-review` skill and apply it to the requirements document.
 
-When document-review returns "Review complete", present next steps:
+When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
 
-1. **Move to planning** - Continue to `/ce:plan` with this document
-2. **Done for now** - Brainstorming complete. To start planning later: `/ce:plan [document-path]`
+#### 4.3 Closing Summary
 
-## Output Summary
+Use the closing summary only when this run of the workflow is ending or handing off, not when returning to the Phase 4 options.
 
-When complete, display:
+When complete and ready for planning, display:
 
-```
+```text
 Brainstorm complete!
 
-Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
+Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if one was created
 
 Key decisions:
 - [Decision 1]
 - [Decision 2]
 
-Next: Run `/ce:plan` when ready to implement.
+Recommended next step: `/ce:plan`
 ```
 
-## Important Guidelines
+If the user pauses with `Resolve Before Planning` still populated, display:
 
-- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
-- **Ask one question at a time** - Don't overwhelm
-- **Apply YAGNI** - Prefer simpler approaches
-- **Keep outputs concise** - 200-300 words per section max
+```text
+Brainstorm paused.
 
-NEVER CODE! Just explore and document decisions.
+Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if one was created
+
+Planning is blocked by:
+- [Blocking question 1]
+- [Blocking question 2]
+
+Resume with `/ce:brainstorm` when ready to resolve these before planning.
+```

package/plugins/compound-engineering/skills/ce-plan/SKILL.md

@@ -22,38 +22,39 @@ Do not proceed until you have a clear feature description from the user.
 
 ### 0. Idea Refinement
 
-**Check for brainstorm output first:**
+**Check for requirements document first:**
 
-Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
+Before asking questions, look for recent requirements documents in `docs/brainstorms/` that match this feature:
 
 ```bash
-ls -la docs/brainstorms/*.md 2>/dev/null | head -10
+ls -la docs/brainstorms/*-requirements.md 2>/dev/null | head -10
 ```
 
-**Relevance criteria:** A brainstorm is relevant if:
+**Relevance criteria:** A requirements document is relevant if:
 - The topic (from filename or YAML frontmatter) semantically matches the feature description
 - Created within the last 14 days
 - If multiple candidates match, use the most recent one
 
-**If a relevant brainstorm exists:**
-1. Read the brainstorm document **thoroughly** — every section matters
-2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
+**If a relevant requirements document exists:**
+1. Read the source document **thoroughly** — every section matters
+2. Announce: "Found source document from [date]: [topic]. Using as foundation for planning."
 3. Extract and carry forward **ALL** of the following into the plan:
    - Key decisions and their rationale
    - Chosen approach and why alternatives were rejected
-   - Constraints and requirements discovered during brainstorming
-   - Open questions (flag these for resolution during planning)
+   - Problem framing, constraints, and requirements captured during brainstorming
+   - Outstanding questions, preserving whether they block planning or are intentionally deferred
    - Success criteria and scope boundaries
-   - Any specific technical choices or patterns discussed
-4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build
-5. Use brainstorm content as the **primary input** to research and planning phases
-6. **Critical: The brainstorm is the origin document.** Throughout the plan, reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
-7. **Do not omit brainstorm content** — if the brainstorm discussed it, the plan must address it (even if briefly). Scan each brainstorm section before finalizing the plan to verify nothing was dropped.
+   - Dependencies and assumptions, plus any high-level technical direction only when the origin document is inherently technical
+4. **Skip the idea refinement questions below** — the source document already answered WHAT to build
+5. Use source document content as the **primary input** to research and planning phases
+6. **Critical: The source document is the origin document.** Throughout the plan, reference specific decisions with `(see origin: <source-path>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
+7. **Do not omit source content** — if the source document discussed it, the plan must address it (even if briefly). Scan each section before finalizing the plan to verify nothing was dropped.
+8. **If `Resolve Before Planning` contains any items, stop.** Do not proceed with planning. Tell the user planning is blocked by unanswered brainstorm questions and direct them to resume `/ce:brainstorm` or answer those questions first.
 
-**If multiple brainstorms could match:**
-Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
+**If multiple source documents could match:**
+Use **AskUserQuestion tool** to ask which source document to use, or whether to proceed without one.
 
-**If no brainstorm found (or not relevant), run idea refinement:**
+**If no requirements document is found (or not relevant), run idea refinement:**
 
 Refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
 
@@ -191,7 +192,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
 ---
 
 # [Issue Title]
@@ -221,7 +222,7 @@ end
 
 ## Sources
 
-- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
+- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc
 - Related issue: #[issue_number]
 - Documentation: [relevant_docs_url]
 ````
@@ -246,7 +247,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
 ---
 
 # [Issue Title]
@@ -293,7 +294,7 @@ origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from
 
 ## Sources & References
 
-- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
+- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc
 - Similar implementations: [file_path:line_number]
 - Best practices: [documentation_url]
 - Related PRs: #[pr_number]
@@ -321,7 +322,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
-origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
 ---
 
 # [Issue Title]
@@ -436,7 +437,7 @@ origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from
 
 ### Origin
 
-- **Brainstorm document:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm. Key decisions carried forward: [list 2-3 major decisions from brainstorm]
+- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path) — include if plan originated from an upstream requirements doc. Key decisions carried forward: [list 2-3 major decisions from the origin]
 
 ### Internal References
 
@@ -515,15 +516,15 @@ end
 
 ### 6. Final Review & Submission
 
-**Brainstorm cross-check (if plan originated from a brainstorm):**
+**Origin document cross-check (if plan originated from a requirements doc):**
 
-Before finalizing, re-read the brainstorm document and verify:
-- [ ] Every key decision from the brainstorm is reflected in the plan
-- [ ] The chosen approach matches what was decided in the brainstorm
-- [ ] Constraints and requirements from the brainstorm are captured in acceptance criteria
-- [ ] Open questions from the brainstorm are either resolved or flagged
-- [ ] The `origin:` frontmatter field points to the brainstorm file
-- [ ] The Sources section includes the brainstorm with a summary of carried-forward decisions
+Before finalizing, re-read the origin document and verify:
+- [ ] Every key decision from the origin document is reflected in the plan
+- [ ] The chosen approach matches what was decided in the origin document
+- [ ] Constraints and requirements from the origin document are captured in acceptance criteria
+- [ ] Open questions from the origin document are either resolved or flagged
+- [ ] The `origin:` frontmatter field points to the correct source file
+- [ ] The Sources section includes the origin document with a summary of carried-forward decisions
 
 **Pre-submission Checklist:**
 

package/plugins/compound-engineering/skills/ce-review/SKILL.md

@@ -53,6 +53,7 @@ Ensure that the code is ready for analysis (either in worktree or on current bra
 <protected_artifacts>
 The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
 
+- `docs/brainstorms/*-requirements.md` — Requirements documents created by `/ce:brainstorm`. These are the product-definition artifacts that planning depends on.
 - `docs/plans/*.md` — Plan files created by `/ce:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/ce:work`).
 - `docs/solutions/*.md` — Solution documents created during the pipeline.
 
@@ -253,7 +254,7 @@ Remove duplicates, prioritize by severity and impact.
 
 - [ ] Collect findings from all parallel agents
 - [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
-- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
+- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` (see Protected Artifacts above)
 - [ ] Categorize by type: security, performance, architecture, quality, etc.
 - [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
 - [ ] Remove duplicate or overlapping findings

package/plugins/compound-engineering/skills/document-review/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: document-review
-description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
+description: This skill should be used to refine requirements or plan documents before proceeding to the next workflow step. It applies when a requirements document or plan document exists and the user wants to improve it.
 ---
 
 # Document Review
 
-Improve brainstorm or plan documents through structured review.
+Improve requirements or plan documents through structured review.
 
 ## Step 1: Get the Document
 
 **If a document path is provided:** Read it, then proceed to Step 2.
 
-**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
+**If no document is specified:** Ask which document to review, or look for the most recent requirements/plan in `docs/brainstorms/` or `docs/plans/`.
 
 ## Step 2: Assess
 
@@ -32,9 +32,10 @@ Score the document against these criteria:
 | Criterion | What to Check |
 |-----------|---------------|
 | **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") |
-| **Completeness** | Required sections present, constraints stated, open questions flagged |
-| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
-| **YAGNI** | No hypothetical features, simplest approach chosen |
+| **Completeness** | Required sections present, constraints stated, and outstanding questions clearly marked as blocking or deferred |
+| **Specificity** | Concrete enough for next step (requirements → can plan, plan → can implement) |
+| **Appropriate Level** | Requirements doc stays at behavior/scope level and does not drift into implementation unless the document is inherently technical |
+| **YAGNI** | Avoid speculative complexity whose carrying cost outweighs its value; keep low-cost, meaningful polish when it is easy to maintain |
 
 If invoked within a workflow (after `/ce:brainstorm` or `/ce:plan`), also check:
 - **User intent fidelity** — Document reflects what was discussed, assumptions validated
@@ -56,7 +57,7 @@ Present your findings, then:
 Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
 
 **Simplify when:**
-- Content serves hypothetical future needs, not current ones
+- Content serves hypothetical future needs without enough current value to justify its carrying cost
 - Sections repeat information already covered elsewhere
 - Detail exceeds what's needed to take the next step
 - Abstractions or structure add overhead without clarity
@@ -65,6 +66,10 @@ Simplification is purposeful removal of unnecessary complexity, not shortening f
 - Constraints or edge cases that affect implementation
 - Rationale that explains why alternatives were rejected
 - Open questions that need resolution
+- Deferred technical or research questions that are intentionally carried forward to the next stage
+
+**Also remove when inappropriate:**
+- Library choices, file structures, endpoints, schemas, or other implementation details that do not belong in a non-technical requirements document
 
 ## Step 6: Offer Next Action
 

package/plugins/compound-engineering/skills/resolve_todo_parallel/SKILL.md

@@ -12,7 +12,7 @@ Resolve all TODO comments using parallel processing.
 
 Get all unresolved TODOs from the /todos/\*.md directory
 
-If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
+If any todo recommends deleting, removing, or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
 
 ### 2. Plan
 

package/plugins/compound-engineering/skills/brainstorming/SKILL.md

@@ -1,190 +0,0 @@
----
-name: brainstorming
-description: This skill should be used before implementing features, building components, or making changes. It guides exploring user intent, approaches, and design decisions before planning. Triggers on "let's brainstorm", "help me think through", "what should we build", "explore approaches", ambiguous feature requests, or when the user's request has multiple valid interpretations that need clarification.
----
-
-# Brainstorming
-
-This skill provides detailed process knowledge for effective brainstorming sessions that clarify **WHAT** to build before diving into **HOW** to build it.
-
-## When to Use This Skill
-
-Brainstorming is valuable when:
-- Requirements are unclear or ambiguous
-- Multiple approaches could solve the problem
-- Trade-offs need to be explored with the user
-- The user hasn't fully articulated what they want
-- The feature scope needs refinement
-
-Brainstorming can be skipped when:
-- Requirements are explicit and detailed
-- The user knows exactly what they want
-- The task is a straightforward bug fix or well-defined change
-
-## Core Process
-
-### Phase 0: Assess Requirement Clarity
-
-Before diving into questions, assess whether brainstorming is needed.
-
-**Signals that requirements are clear:**
-- User provided specific acceptance criteria
-- User referenced existing patterns to follow
-- User described exact behavior expected
-- Scope is constrained and well-defined
-
-**Signals that brainstorming is needed:**
-- User used vague terms ("make it better", "add something like")
-- Multiple reasonable interpretations exist
-- Trade-offs haven't been discussed
-- User seems unsure about the approach
-
-If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."
-
-### Phase 1: Understand the Idea
-
-Ask questions **one at a time** to understand the user's intent. Avoid overwhelming with multiple questions.
-
-**Question Techniques:**
-
-1. **Prefer multiple choice when natural options exist**
-   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
-   - Avoid: "How should users be notified?"
-
-2. **Start broad, then narrow**
-   - First: What is the core purpose?
-   - Then: Who are the users?
-   - Finally: What constraints exist?
-
-3. **Validate assumptions explicitly**
-   - "I'm assuming users will be logged in. Is that correct?"
-
-4. **Ask about success criteria early**
-   - "How will you know this feature is working well?"
-
-**Key Topics to Explore:**
-
-| Topic | Example Questions |
-|-------|-------------------|
-| Purpose | What problem does this solve? What's the motivation? |
-| Users | Who uses this? What's their context? |
-| Constraints | Any technical limitations? Timeline? Dependencies? |
-| Success | How will you measure success? What's the happy path? |
-| Edge Cases | What shouldn't happen? Any error states to consider? |
-| Existing Patterns | Are there similar features in the codebase to follow? |
-
-**Exit Condition:** Continue until the idea is clear OR user says "proceed" or "let's move on"
-
-### Phase 2: Explore Approaches
-
-After understanding the idea, propose 2-3 concrete approaches.
-
-**Structure for Each Approach:**
-
-```markdown
-### Approach A: [Name]
-
-[2-3 sentence description]
-
-**Pros:**
-- [Benefit 1]
-- [Benefit 2]
-
-**Cons:**
-- [Drawback 1]
-- [Drawback 2]
-
-**Best when:** [Circumstances where this approach shines]
-```
-
-**Guidelines:**
-- Lead with a recommendation and explain why
-- Be honest about trade-offs
-- Consider YAGNI—simpler is usually better
-- Reference codebase patterns when relevant
-
-### Phase 3: Capture the Design
-
-Summarize key decisions in a structured format.
-
-**Design Doc Structure:**
-
-```markdown
----
-date: YYYY-MM-DD
-topic: <kebab-case-topic>
----
-
-# <Topic Title>
-
-## What We're Building
-[Concise description—1-2 paragraphs max]
-
-## Why This Approach
-[Brief explanation of approaches considered and why this one was chosen]
-
-## Key Decisions
-- [Decision 1]: [Rationale]
-- [Decision 2]: [Rationale]
-
-## Open Questions
-- [Any unresolved questions for the planning phase]
-
-## Next Steps
-→ `/ce:plan` for implementation details
-```
-
-**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
-
-### Phase 4: Handoff
-
-Present clear options for what to do next:
-
-1. **Proceed to planning** → Run `/ce:plan`
-2. **Refine further** → Continue exploring the design
-3. **Done for now** → User will return later
-
-## YAGNI Principles
-
-During brainstorming, actively resist complexity:
-
-- **Don't design for hypothetical future requirements**
-- **Choose the simplest approach that solves the stated problem**
-- **Prefer boring, proven patterns over clever solutions**
-- **Ask "Do we really need this?" when complexity emerges**
-- **Defer decisions that don't need to be made now**
-
-## Incremental Validation
-
-Keep sections short—200-300 words maximum. After each section of output, pause to validate understanding:
-
-- "Does this match what you had in mind?"
-- "Any adjustments before we continue?"
-- "Is this the direction you want to go?"
-
-This prevents wasted effort on misaligned designs.
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Better Approach |
-|--------------|-----------------|
-| Asking 5 questions at once | Ask one at a time |
-| Jumping to implementation details | Stay focused on WHAT, not HOW |
-| Proposing overly complex solutions | Start simple, add complexity only if needed |
-| Ignoring existing codebase patterns | Research what exists first |
-| Making assumptions without validating | State assumptions explicitly and confirm |
-| Creating lengthy design documents | Keep it concise—details go in the plan |
-
-## Integration with Planning
-
-Brainstorming answers **WHAT** to build:
-- Requirements and acceptance criteria
-- Chosen approach and rationale
-- Key decisions and trade-offs
-
-Planning answers **HOW** to build it:
-- Implementation steps and file changes
-- Technical details and code patterns
-- Testing strategy and verification
-
-When brainstorm output exists, `/ce:plan` should detect it and use it as input, skipping its own idea refinement phase.