From aegis
Enforces design-first process before coding: explores intent, clarifies requirements, proposes approaches with trade-offs, drafts specs, and secures approval.
npx claudepluginhub ganyuanran/aegis --plugin aegisThis skill uses the workspace's default tool permissions.
→ Creative work (feature, component, behavior change)? → **Design first. No code until design approved.**
Guides collaborative brainstorming to refine ideas into approved designs and specs before implementation. Use prior to building features, components, or modifying behavior.
Refines ideas into approved designs and specs via structured collaboration: explores context, asks questions, proposes approaches, writes docs before implementation.
Turns ideas into approved designs and specs via structured dialogue: context exploration, questions, proposals, reviews. Enforces before any feature, component, or change implementation.
Share bugs, ideas, or general feedback.
→ Creative work (feature, component, behavior change)? → Design first. No code until design approved.
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 design and get user approval.
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.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 design 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:
TaskIntentDraft, BaselineReadSetHint, ImpactStatementDraftdocs/aegis/specs/YYYY-MM-DD-<topic>-design.md and commitThe terminal state is invoking writing-plans. Do NOT invoke any other implementation skill.
Understanding the idea:
Working artifacts: Keep three drafts: TaskIntentDraft (outcome, scope, risks), BaselineReadSetHint (candidate docs, authority gaps), ImpactStatementDraft (affected layers, owners, invariants, compat, non-goals). Refresh when scope changes.
Exploring approaches: Propose 2-3 approaches with trade-offs and recommendation. Make scope boundary explicit: what's in, what's deferred, what belongs elsewhere.
Presenting the design: Scale sections to complexity. Cover: architecture, components, data flow, error handling, testing, compatibility boundary. Get approval after each section.
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.
Documentation:
Aegis Project Workspace initialization (first creation only):
If docs/aegis/ does not exist and scripts/aegis-workspace.py is
available in the active method-pack checkout, initialize the target project:
python scripts/aegis-workspace.py init --root <target-project-root>.
If the helper 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.
Write the validated design (spec):
Save to docs/aegis/specs/YYYY-MM-DD-<topic>-design.md.
Spec always goes to specs/ — never to work/.
Update INDEX.md:
Prefer the helper: python scripts/aegis-workspace.py append-index --root <target-project-root> --path docs/aegis/specs/<filename>.md --kind spec --title "<title>". If the helper is unavailable, append the new spec entry
to docs/aegis/INDEX.md manually.
After the append, run python scripts/aegis-workspace.py check --root <target-project-root> when the helper is available. This validates
structure and index coverage only; it does not grant completion authority.
Commit the design document to git.
Include the latest TaskIntentDraft, BaselineReadSetHint, and ImpactStatementDraft inline or in an appendix when they materially shaped the design.
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:
Fix any issues inline. No need to re-review — just fix and move on.
User Review Gate: After the spec review loop passes, ask the user to review the written spec before proceeding:
"Spec written and committed to
<path>. 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. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
Implementation:
A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
Offering the companion: When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
This offer MUST be its own message. Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
Per-question decision: Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: would the user understand this better by seeing it than reading it?
A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
If they agree to the companion, read the detailed guide before proceeding:
skills/brainstorming/visual-companion.md
When creating docs/aegis/BASELINE-GOVERNANCE.md for the first time, use this template:
# Baseline Governance
## 1. Architecture Defect
A confirmed error, gap, or contradiction IN the baseline itself.
- Fix baseline first, then align implementation to corrected baseline.
- Do NOT patch implementation around a defective baseline.
## 2. Architecture Drift
Implementation has deviated from a confirmed, correct baseline.
- Return to baseline via the simplest path.
- Do NOT "update baseline to match drift" without explicit review.
## 3. Baseline Check Protocol
Before non-trivial changes:
1. Read the latest baseline snapshot in `baseline/`
2. Compare current code structure against ownership map
3. Compare current contracts against contract inventory
4. Check for new anti-patterns not recorded in known list
5. Report: aligned / minor drift (self-correctable) / material drift (needs review)
## 4. Architecture Review — 7 Dimensions
After each non-trivial change:
1. **Ownership integrity** — every component has exactly one canonical owner
2. **Module boundaries** — no unauthorized cross-module coupling
3. **Contract changes** — all API/signature/behavior contract changes documented
4. **Cascade proliferation** — no new cascading dependency chains
5. **Dependency direction** — dependencies flow toward stability
6. **Retirement completeness** — old owners/fallbacks/paths removed or scheduled
7. **Entropy flow** — net complexity decreased or stayed; no unjustified new entities
## 5. Hard Boundaries
- BASELINE-GOVERNANCE.md is the constitution for THIS project's Aegis workspace
- Baseline snapshots in `baseline/` are evidence, not authority
- ADRs in `adr/` record decisions; they do not replace baseline governance
- This file is NEVER auto-updated — changes require explicit user review
When creating the first docs/aegis/baseline/YYYY-MM-DD-initial-baseline.md: