# Brainstorming > Use when defining new features, product behavior, UI/component design, architecture choices, contract changes, or ambiguous medium/high-complexity work before implementation. - **Type:** Skill - **Install:** `agentstack add skill-ganyuanran-aegis-brainstorming` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [GanyuanRan](https://agentstack.voostack.com/s/ganyuanran) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [GanyuanRan](https://github.com/GanyuanRan) - **Source:** https://github.com/GanyuanRan/Aegis/tree/main/skills/brainstorming ## Install ```sh agentstack add skill-ganyuanran-aegis-brainstorming ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Execute → New feature, product behavior, UI/component design, architecture/contract change, or ambiguous medium/high-complexity work? → **Design first. No implementation until the needed design/spec is approved.** 1. Explore project context → read authority docs, check for existing patterns 2. Ask clarifying questions one at a time (prefer multiple choice) 3. Propose 2-3 approaches with trade-offs and your recommendation 4. Present design sections → get user approval after each 5. Write spec → self-review → user review → transition to writing-plans → HARD GATE: For tasks that match this skill, do NOT write code, scaffold projects, or invoke implementation skills until design/spec approval is satisfied. # Brainstorming Ideas Into Designs Help turn ideas into fully formed designs and specs through natural collaborative dialogue. Start by understanding the current project context and authority boundary, then ask questions one at a time to refine the idea. Once you understand what you're building, present the smallest design artifact that stabilizes the work and get the required approval. Do NOT invoke any implementation skill, write any code, scaffold any project, or take implementation action for work that matches this skill until you have presented the required design/spec and the user has approved it where this workflow requires approval. ## Route Away When It Is Small Do not force this workflow onto low-complexity work. A tiny wording edit, single-owner bug fix, simple config/status question, or local utility change can proceed through concise intent, baseline check, TDD/debugging, and verification. If uncertainty or impact grows, escalate back here and write the smallest stabilizing spec. ## Checklist You MUST create a task for each of these items and complete them in order: 1. **Explore project context** — check files, docs, recent commits, authority docs, CONTEXT.md 2. **Choose the path and scope** — real design? diagnosis? route accordingly or decompose first 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 4. **Draft working artifacts** — `TaskIntentDraft`, `BaselineReadSetHint`, `BaselineUsageDraft`, `ImpactStatementDraft` 5. **Run existence check when adding new surfaces** — only if an approach adds a new owner, skill, artifact, adapter, fallback, workflow step, or benchmark metric 6. **Propose 2-3 approaches** — with trade-offs and your recommendation 7. **Present design** — in sections scaled to complexity, get user approval where required 8. **Write spec artifact** — save a Spec Brief or Design Spec under `docs/aegis/specs/` when persistent requirements are needed 9. **Spec self-review** — check for placeholders, contradictions, ambiguity, scope, boundary 10. **User reviews written spec** — ask user to review before proceeding 11. **Transition to implementation** — invoke writing-plans skill (terminal state) **The terminal state is invoking writing-plans.** Do NOT invoke any other implementation skill. ## The Process **Understanding the idea:** - Check current project state first (files, docs, recent commits) - Read relevant authority docs before asking deep questions - If the request is diagnosis/root-cause/follow-up to an approved plan → route to correct workflow - If the request spans multiple independent subsystems → flag and decompose first - Ask clarifying questions one at a time, prefer multiple choice - Separate facts, assumptions, unknowns while exploring **Working artifacts:** Keep four drafts: `TaskIntentDraft` (outcome, goal, success evidence, stop condition, non-goals, scope, risks), `BaselineReadSetHint` (candidate docs, authority gaps), `BaselineUsageDraft` (required refs, optionally delivered context refs, acknowledged-before-plan refs, cited refs, missing refs, advisory decision), and `ImpactStatementDraft` (affected layers, owners, invariants, compat, non-goals). Refresh when scope changes. **Compact output contract:** `TaskIntentDraft`, `BaselineReadSetHint`, `BaselineUsageDraft`, `Requirement Ready Check`, `ImpactStatementDraft`, `Existence Check`, `Product Risk Lens`, `Architecture Integrity Lens`, `Baseline Role Alignment`, `Plan-Time Complexity Check`, `Options`, and `Decision Needed`. Use this compact shape before expanding into a full design structure. Use a compact `BaselineUsageDraft` whenever the design direction depends on specific baseline docs or current-authority refs: ```text BaselineUsageDraft: - Required baseline refs: - Delivered context refs: - Acknowledged before plan refs: - Cited in design refs: - Missing refs: - Decision: continue | needs-baseline-readback | needs-verification | pause-for-user | blocked ``` `Delivered context refs` is optional host-projected bookkeeping only. It is not authoritative proof that a host injected or the model internally consumed a context payload. The artifact exists to make baseline/context attention drift visible before the design is recommended or approved. Use a compact `Requirement Ready Check` before recommending a design when the requirement is not already confirmed and complete: ```text Requirement Ready Check: - Requirement source refs: - Goals and scope refs: - User / scenario refs: - Requirement item refs: - Acceptance / verification criteria refs: - Open blocker questions: - Decision: ready | needs-source | needs-goal-alignment | needs-scenario | needs-acceptance-criteria | needs-clarification | needs-user-decision | blocked ``` Treat task intent, conversation, source documents, and agent inference as candidate requirement sources until project authority confirms them. If the decision is not `ready`, keep the design at proposal/spec clarification level; do not turn the gap into implementation tasks. **Existence Check:** Before recommending an approach that adds a new owner, skill, artifact, host adapter, fallback, compatibility path, workflow step, or benchmark metric, check whether it needs to exist. Use `docs/current/AEGIS_MINIMALITY_REFERENCE.md` as the reference. Do not force this onto ordinary feature design that reuses existing owners and artifacts. ```text Existence Check: - Proposed new surface: - Existing owner / reuse candidate: - Why existing surface is insufficient: - Creation proof: - Entropy / retirement impact: - Decision: reuse-existing | add-with-proof | defer | reject | needs-first-principles-review ``` If the decision is `reuse-existing`, recommend the reuse path instead of a new surface. If the decision is `add-with-proof`, carry the proof, verification signal, and any retirement trigger into the design/spec. **Product Risk Lens:** For ambiguous product, feature, UI, workflow, or architecture choices, add a compact review lens, not persona roleplay: ```text Product Risk Lens: - Value: - Non-goals: - Trade-offs: - Decision needed: ``` This is a review lens, not persona output. It does not override baseline evidence, approved requirements, or current authority docs; it only makes the product risk and decision point visible before implementation. **Plan-Time Complexity Check:** Before choosing an implementation direction for medium/high work, inspect the likely owner files and current shape. This is an advisory design pressure check, not a gate and not completion authority. Do not force it onto tiny low-risk edits. Use `using-aegis/references/complexity-governance.md` for the shared artifact classes, pressure-signal interpretation, and over-budget handling. ```text Complexity Budget: - Artifact class: - Target files / artifacts: - Current pressure: - Projected post-change pressure: - Budget result: within-budget | at-risk | over-budget - Planned governance: Plan-Time Complexity Check: - Better file boundary: - Recommendation: edit-in-place | extract helper | add owner file | split task | defer refactor ``` **Exploring approaches:** Propose 2-3 approaches with trade-offs and recommendation. Make scope boundary explicit: what's in, what's deferred, what belongs elsewhere. Before approach selection, use `Existence Check` for any proposed new surface. Escalate to `first-principles-review` and its `Decision Hygiene Review` when the candidate direction still introduces a new owner, duplicate owner, fallback, adapter, compat-only carrier, delete-first question, unverified assumption, or "long-term stable" claim after the existence check. Do not make either check a universal design ceremony; return to this workflow once the decision surface is clean. When the central decision is internal retirement vs compat retention vs persistent-state confirmation, compose `anti-entropy-governance`. It classifies the deletion target, chooses `delete-first | compat-exception | confirmation-first`, and keeps destructive authority outside the design skill. Use the narrower `Architecture Integrity Lens` when the main risk is not broad strategy but architecture coherence: unclear canonical owner, responsibility overlap, caller-side fallback, stale path carrying real logic, or a possible higher-level owner / contract / source-of-truth simplification. The lens should answer invariant, canonical owner / contract, responsibility overlap, higher-level simplification, retirement / falsifier, and verdict before the approach is recommended. **Baseline Role Alignment:** When a question may involve both "what should be built" and "where it should live", keep requirement truth separate from architecture truth: ```text Baseline Role Alignment: - Product / Requirement Baseline: - Architecture / Runtime Boundary Baseline: - Result: aligned | Design Defect | Implementation Drift | missing-authority | needs-clarification - scope: requirements | architecture | both - Next action: ``` Use `Design Defect` when the relevant requirement, design, or baseline is wrong. Use `Implementation Drift` when the work deviates from a correct unchanged baseline. `Architecture Defect` and `Architecture Drift` remain compatibility aliases for architecture-scoped `Design Defect` and architecture-scoped `Implementation Drift`. This is a review lens, not a runtime gate or completion authority. **Presenting the design:** Scale sections to complexity. Cover only the surfaces that matter: architecture, components, data flow, error handling, testing, compatibility boundary. Get approval for the design before implementation when behavior, contract, architecture, or user-facing flow is being decided. **ADR signals:** When the design/spec touches durable architecture surfaces (owner, public contract, artifact shape, dependency direction, source-of-truth, host compatibility, runtime-ready boundary, fallback, adapter, or retirement schedule), mark the ADR signal, source refs, real alternatives, and expected baseline-sync question for later completion. Do not create accepted architecture memory from unexecuted ideas. **Design for isolation:** Each unit = one clear purpose, well-defined interface, testable independently. Can someone understand it without reading internals? Can you change internals without breaking consumers? **Existing codebases:** Follow existing patterns. Include targeted improvements only when they serve the current goal. If the design touches contracts, compat, fallbacks, or duplicated owners → call it out directly. ## After the Design **Documentation:** 1. **Aegis Project Workspace initialization (first creation only):** If `docs/aegis/` does not exist and configured Aegis workspace support is available, initialize the target project: `python init --root `. If installed Aegis workspace support is unavailable, create it manually: a. Create `docs/aegis/README.md` — describes workspace purpose and structure b. Create `docs/aegis/INDEX.md` — empty index, will be appended below c. Create `docs/aegis/BASELINE-GOVERNANCE.md` from the template in "BASELINE-GOVERNANCE.md Template" section below d. If the project has existing code, create an initial baseline snapshot: `docs/aegis/baseline/YYYY-MM-DD-initial-baseline.md` using the "Initial Baseline Snapshot Template" below If `docs/aegis/` already exists, use it — do not recreate. 2. **Write the validated spec artifact when needed:** Use the smallest artifact that stabilizes the task: - Spec Brief: `docs/aegis/specs/YYYY-MM-DD--brief.md` for medium tasks that need what/why/acceptance pinned before planning. - Design Spec: `docs/aegis/specs/YYYY-MM-DD--design.md` for high complexity, architecture, contract, migration, cross-module, or ambiguous behavior requiring user review. Specs always go to `specs/` — never to `work/`. 3. **Update INDEX.md:** Prefer configured Aegis workspace support: `python append-index --root --path docs/aegis/specs/.md --kind spec --title ""`. If workspace support is unavailable, append the new spec entry to `docs/aegis/INDEX.md` manually. After the append, run `python check --root ` when configured workspace support is available. This validates structure and index coverage only; it does not grant completion authority. 4. Commit the design document to git. 5. Include the latest `TaskIntentDraft`, `BaselineReadSetHint`, `BaselineUsageDraft`, and `ImpactStatementDraft` inline or in an appendix when they materially shaped the design. 6. Record explicit non-goals and compatibility boundaries so the later implementation plan does not drift. **Spec Self-Review:** After writing the spec document, look at it with fresh eyes: 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them. 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions? 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition? 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit. 5. **Boundary check:** Did you clearly mark invariants, compatibility boundaries, owners, non-goals, and any ADR signals for later completion backfill? If the spec endorses a risky approach, confirm the `first-principles-review` `Decision Hygiene Review` or `Architecture Integrity Lens` result is reflected or explicitly marked unnecessary. Fix any issues inline. No need to re-review — just fix and move on. **User Review Gate:** After a Design Spec review loop passes, ask the user to review the written spec before proceeding: > "Spec written and committed to ``. Please review it and let me know if you want to make any changes before we start writing out the implementation plan." Wait for the user's response when this workflow requires review. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves. For a small Spec Brief created only to pin medium-task acceptance, user review may be concise unless project rules require a formal approval step. **Implementation:** - Invoke the writing-plans skill to create a detailed implementation plan - Do NOT invoke any other skill. writing-plans is the next step. ## Key Principles - **One question at a time** - Don't overwhelm with multiple questions - **Multiple choice preferred** - Easier to answer than open-ended when possible - **YAGNI ruthlessly** - Remove unnecessary features from all designs - **Explore alternatives** - Always propose 2-3 approaches before settling - **Incremental validation** - Present design, get approval before moving on - **Be flexible** - Go back and clarify when something doesn't make sense ## BASELINE-GOVERNANCE.md Template When creating `docs/aegis/BASELINE-GOVERNANCE.md` for the first time, use this template: ```markdown # Baseline Governance ## 1. Baseline Roles - Product / Requirement Baseline: confirmed requirement sources, target state, goals and scope, users / scenarios, requirement items, acceptance / verification criteria, non-goals, workflow constraints, open qu … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [GanyuanRan](https://github.com/GanyuanRan) - **Source:** [GanyuanRan/Aegis](https://github.com/GanyuanRan/Aegis) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-ganyuanran-aegis-brainstorming - Seller: https://agentstack.voostack.com/s/ganyuanran - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.