@every-env/compound-plugin 2.37.1 → 2.39.0

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.