@iceinvein/agent-skills 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@iceinvein/agent-skills",
+  "version": "0.1.0",
+  "description": "Install agent skills into AI coding tools",
+  "author": "iceinvein",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agent-skills": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "bun build src/cli/index.ts --outdir dist/cli --target node",
+    "test": "bun test",
+    "dev": "bun run src/cli/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iceinvein/agent-skills"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.11"
+  }
+}

package/skills/code-intelligence/skill.json

@@ -0,0 +1,31 @@
+{
+  "name": "code-intelligence",
+  "version": "1.0.0",
+  "description": "Semantic code search, call hierarchy, dependency graphs, and impact analysis via MCP",
+  "author": "iceinvein",
+  "type": "code",
+  "tools": ["claude", "cursor"],
+  "mcp": {
+    "package": "@iceinvein/code-intelligence-mcp",
+    "command": "npx",
+    "args": ["-y", "@iceinvein/code-intelligence-mcp"]
+  },
+  "install": {
+    "claude": {
+      "mcpServers": {
+        "code-intelligence": {
+          "command": "npx",
+          "args": ["-y", "@iceinvein/code-intelligence-mcp"]
+        }
+      }
+    },
+    "cursor": {
+      "mcpServers": {
+        "code-intelligence": {
+          "command": "npx",
+          "args": ["-y", "@iceinvein/code-intelligence-mcp"]
+        }
+      }
+    }
+  }
+}

package/skills/codebase-architecture/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: codebase-architecture
+description: Use when designing architecture for a new project, reviewing an existing codebase for structural health, identifying design patterns and anti-patterns, or when asked to refactor module boundaries, dependency direction, or component organization
+---
+
+# Codebase Architecture
+
+Design architecture for new projects or review existing codebases. Covers both macro (architectural patterns, module boundaries, dependency direction) and micro (design patterns within components) levels. Language-agnostic.
+
+**Core principle:** Evidence before opinion. Read code before diagnosing. Name every pattern explicitly. Cite specific files and lines.
+
+## When to Use
+
+- "Review the architecture of this codebase"
+- "How should I structure this new project?"
+- "What design patterns are we using?"
+- "Help me refactor these module boundaries"
+- "Map the dependencies in this project"
+- Codebase feels tangled, coupled, or inconsistent
+
+**Not for:** Reviewing design documents (use `design-integrity-review`), bug hunting (use `find-bugs`), performance optimization.
+
+## Mode Selection
+
+```dot
+digraph mode {
+    "Skill invoked" [shape=doublecircle];
+    "Mode explicit?" [shape=diamond];
+    "Codebase has substantial code?" [shape=diamond];
+    "Ask user: new design or review?" [shape=box];
+    "New-Project Mode" [shape=doublecircle];
+    "Review Mode" [shape=doublecircle];
+
+    "Skill invoked" -> "Mode explicit?";
+    "Mode explicit?" -> "New-Project Mode" [label="user said design/new"];
+    "Mode explicit?" -> "Review Mode" [label="user said review/audit/refactor"];
+    "Mode explicit?" -> "Codebase has substantial code?" [label="ambiguous"];
+    "Codebase has substantial code?" -> "Ask user: new design or review?" [label="yes"];
+    "Codebase has substantial code?" -> "New-Project Mode" [label="no/empty"];
+    "Ask user: new design or review?" -> "New-Project Mode" [label="new"];
+    "Ask user: new design or review?" -> "Review Mode" [label="review"];
+}
+```
+
+---
+
+## New-Project Mode
+
+Structured dialogue that produces an architecture spec. **Do NOT design in silence** — ask questions, wait for answers.
+
+### Phase 1: Understand the Domain
+
+Before patterns or layers — understand what's being built:
+- What does this system do? (one sentence)
+- Who are the actors? (users, services, external systems)
+- What are the 3-5 key operations?
+- What are the hard constraints? (performance, team size, deployment, compliance)
+
+**One question at a time.** Do not dump all questions at once.
+
+### Phase 2: Identify Architectural Drivers
+
+Surface forces that should *shape* the architecture:
+- **Scale axis** — single user CLI vs multi-tenant SaaS vs embedded
+- **Change axis** — what changes frequently vs remains stable?
+- **Integration axis** — what external systems must this talk to?
+- **Team axis** — how many people/teams? (Conway's Law)
+
+These drivers determine which patterns are appropriate. A 500-line CLI does not need hexagonal architecture.
+
+### Phase 3: Select Architectural Patterns
+
+Using Phase 2 drivers, recommend macro-level patterns from `patterns-reference.md`:
+- Overall structure (layered, hexagonal, event-driven, etc.)
+- Communication style (sync, async, event sourcing)
+- Data strategy (single DB, CQRS, shared-nothing)
+
+**MUST present 2-3 options with trade-offs.** Recommend one with rationale tied explicitly to the drivers from Phase 2. Do not present a single approach as inevitable.
+
+### Phase 4: Define Boundaries & Interfaces
+
+The most important phase:
+- Each module gets a clear responsibility (one sentence)
+- Define interfaces between modules
+- **Establish dependency direction** — which modules know about which? Dependencies should point toward stable abstractions, not toward volatile details.
+- **Name the design patterns** that apply within each module (e.g., "plugin system uses Strategy", "event bus uses Observer"). Refer to `patterns-reference.md`.
+
+### Phase 5: Produce Architecture Spec
+
+Write structured document to `docs/architecture/architecture-spec.md` (or user's preference):
+- System overview (one paragraph)
+- Architectural drivers & constraints
+- Module map with responsibilities
+- Interface definitions
+- Dependency graph (text-based, showing direction)
+- Pattern decisions with rationale
+- Risk areas & open questions
+
+Ask user how they want to proceed — their planning workflow, direct implementation, or keep as reference.
+
+---
+
+## Review Mode
+
+Scan-first, dialogue-second. **Read code before forming opinions.**
+
+### Phase 1: Codebase Scan
+
+Use available tools (code-intelligence MCP, grep, glob, file reads):
+- **Dependency mapping** — trace imports/requires to build module dependency graph. Note direction and cycles.
+- **Structure mapping** — directory layout, module boundaries, entry points
+- **Size analysis** — identify oversized files/modules (signal of unclear responsibilities)
+- **Pattern detection** — recognize patterns in use (repository classes, factory functions, event emitters, middleware chains)
+
+**Do not skip this phase.** Do not rely on CLAUDE.md or README alone. Read actual source files.
+
+### Phase 2: Architectural Health Assessment
+
+Evaluate findings against these dimensions:
+
+| Dimension | Check | Rating |
+|-----------|-------|--------|
+| **Dependency direction** | Do deps point toward abstractions or toward details? Circular deps? | strong / adequate / weak |
+| **Module cohesion** | Single clear responsibility per module? | strong / adequate / weak |
+| **Coupling** | Can you change one module without rippling? | strong / adequate / weak |
+| **Boundary clarity** | Explicit interfaces, or modules reach into internals? | strong / adequate / weak |
+| **Pattern consistency** | Same problem solved the same way everywhere? | strong / adequate / weak |
+| **Abstraction quality** | Abstractions earn their keep? Leaky or unnecessary? | strong / adequate / weak |
+
+**Distinguish intentional from accidental.** A codebase using 3 patterns for the same problem might be evolving. Flag inconsistency but ask before assuming it's a mistake.
+
+### Phase 3: Health Report
+
+Save to `docs/architecture/architecture-review-YYYY-MM-DD.md`:
+- **Architecture overview** — what the structure actually is
+- **Dependency graph** — text-based, showing direction and cycles
+- **Pattern inventory** — each pattern named, where it's used, file:line references, consistency assessment
+- **Smell inventory** — specific issues with severity (critical / warning / info)
+- **Strengths** — what's working well and why. This section is mandatory.
+- **Health score** — per-dimension rating table from Phase 2
+- **Priority ordering** — what to fix first based on impact-to-effort
+
+### Phase 4: Prescriptions
+
+For each smell or weakness:
+- What to change and why
+- Which pattern to apply (reference `patterns-reference.md`)
+- Impact estimate (how much code changes, risk of breakage)
+- Priority (high / medium / low) with rationale
+
+### Phase 5: Transition to Action
+
+Present prescriptions and ask:
+- Which fixes to pursue
+- How they want to proceed (their planning skill, start executing, or keep the report)
+
+---
+
+## Guard Rails
+
+**Evidence before opinion.** Read code before diagnosing. Use code-intelligence MCP tools, grep, glob — whatever is available.
+
+**Name the pattern, cite the location.** "Strategy pattern in `src/providers/types.ts:24`" — not "you seem to use a strategy-like approach."
+
+**Strengths matter as much as weaknesses.** A review that only lists problems is misleading. Call out what's well-structured.
+
+**Don't prescribe patterns for their own sake.** Every recommendation answers: "What problem does this solve in this codebase?" If the answer is "best practice," that's not good enough.
+
+**Scale to codebase size.** 500-line CLI? Don't recommend hexagonal architecture. 50-file project? Don't recommend CQRS. Actively resist over-engineering.
+
+**Don't assume before asking.** In new-project mode, do not state 10 assumptions and build a full design. Ask, listen, then design.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Designing without understanding domain constraints | Complete Phase 1-2 before Phase 3 |
+| Presenting one architecture as inevitable | Always present 2-3 options with trade-offs |
+| Using patterns but not naming them | Explicitly name every pattern by its standard name |
+| Tracing module layout but not dependency direction | Map which modules import which and assess direction |
+| Listing only problems in a review | Strengths section is mandatory |
+| Over-engineering for a small codebase | Match pattern complexity to actual codebase scale |
+| Assuming inconsistency is accidental | Ask before diagnosing — it might be intentional evolution |

package/skills/codebase-architecture/patterns-reference.md

@@ -0,0 +1,168 @@
+# Architecture & Design Patterns Reference
+
+Decision-aid for the `codebase-architecture` skill. Concise per entry — enough to make a decision, not a textbook.
+
+---
+
+## Architectural Patterns (Macro)
+
+### Layered (N-Tier)
+Horizontal layers where each depends only on the layer below.
+- **Use when:** Clear separation of concerns is needed; team members work on different layers; standard business applications.
+- **Avoid when:** Heavy cross-cutting concerns; performance-critical paths that suffer from layer traversal.
+- **Trade-off:** Simple to understand vs rigid boundaries that can lead to "pass-through" layers with no logic.
+
+### Hexagonal (Ports & Adapters)
+Core domain logic has no external dependencies. External systems connect through ports (interfaces) and adapters (implementations).
+- **Use when:** Domain logic is complex and must be testable in isolation; multiple external integrations (DBs, APIs, queues).
+- **Avoid when:** Simple CRUD apps where the indirection adds no value; small scripts or CLIs.
+- **Trade-off:** Excellent testability and replaceability vs more files and indirection.
+
+### Event-Driven
+Components communicate through events. Producers don't know about consumers.
+- **Use when:** Loose coupling between subsystems; async workflows; audit trails; multiple consumers for the same event.
+- **Avoid when:** Simple request-response flows; you need synchronous consistency; small teams where the indirection isn't justified.
+- **Trade-off:** Extreme decoupling vs harder debugging and eventual consistency challenges.
+
+### CQRS (Command Query Responsibility Segregation)
+Separate models for reading and writing data.
+- **Use when:** Read and write patterns differ significantly; high-read/low-write or vice versa; complex domain with simple queries.
+- **Avoid when:** Read and write models are nearly identical; adds complexity without benefit for simple domains.
+- **Trade-off:** Optimized read/write paths vs maintaining two models and their synchronization.
+
+### Pipe-and-Filter
+Data flows through a sequence of processing steps, each transforming the input.
+- **Use when:** Data transformation pipelines; compiler stages; ETL processes; middleware chains.
+- **Avoid when:** Complex branching logic; interactive applications.
+- **Trade-off:** Composable and reusable stages vs limited to sequential data flow.
+
+### Microkernel (Plugin)
+Minimal core with extensible functionality via plugins.
+- **Use when:** Product must support customization; IDE-like extensibility; varying feature sets per deployment.
+- **Avoid when:** All features are always needed; plugin overhead isn't justified.
+- **Trade-off:** Maximum extensibility vs plugin API design is hard to get right and hard to change.
+
+### Monolith-First
+Single deployable unit. Extract services only when proven necessary.
+- **Use when:** Starting a new project; small team; unclear domain boundaries; rapid prototyping.
+- **Avoid when:** Domain boundaries are well-understood AND team scale demands independent deployment.
+- **Trade-off:** Simple deployment and debugging vs harder to scale individual components independently.
+
+---
+
+## Design Patterns (Micro)
+
+### Creating Things
+
+**Factory** — Encapsulates object creation logic. Use when: construction is complex, multiple variants exist, or you want to decouple creation from usage.
+- Detect: Functions named `createX()`, `buildX()`, or `XFactory` classes.
+- Misuse: Factory for objects with trivial constructors (just use `new`).
+
+**Builder** — Step-by-step construction of complex objects. Use when: objects have many optional parameters or construction requires validation.
+- Detect: Method chaining patterns (`.setX().setY().build()`).
+- Misuse: Builder for objects with 2-3 parameters (use constructor or options object).
+
+**Singleton** — Single instance shared globally. Use when: truly global resources (DB connection pool, logger). **Use sparingly** — often a sign of hidden global state.
+- Detect: `getInstance()`, module-level `export const instance = new X()`.
+- Misuse: Using singleton when dependency injection would be cleaner and more testable.
+
+### Structuring Relationships
+
+**Adapter** — Translates one interface to another. Use when: integrating with external APIs or libraries whose interface doesn't match yours.
+- Detect: Classes wrapping third-party libraries; `XAdapter`, `XWrapper` names.
+- Misuse: Adapting internal code to internal code (just change the interface).
+
+**Facade** — Simplified interface over a complex subsystem. Use when: callers need a simple API but the underlying system is complex.
+- Detect: Classes that delegate to multiple subsystem objects; `XService`, `XManager` names.
+- Misuse: Facade that just passes through to one class (unnecessary indirection).
+
+**Decorator** — Wraps an object to add behavior without modifying it. Use when: cross-cutting concerns (logging, caching, auth); composable behavior layers.
+- Detect: Classes/functions that wrap another and add behavior; middleware patterns.
+- Misuse: Decorator chains so deep that debugging becomes impossible.
+
+**Composite** — Tree structure where individual objects and compositions share the same interface. Use when: hierarchical data (file systems, UI component trees, org charts).
+- Detect: Recursive structures where a node can contain children of the same type.
+
+### Managing Behavior
+
+**Strategy** — Swappable algorithms behind a common interface. Use when: multiple approaches to the same operation; user-selectable behavior; provider abstraction.
+- Detect: Interface + multiple implementations; `XStrategy`, `XProvider` names; config-driven selection.
+- Misuse: Strategy for a single implementation with no planned alternatives.
+
+**Observer / EventEmitter** — Objects subscribe to notifications from a subject. Use when: one-to-many notifications; decoupled event handling.
+- Detect: `.on()`, `.subscribe()`, `.addEventListener()`; `EventEmitter` usage; pub/sub patterns.
+- Misuse: Observer between two tightly-coupled objects (just call a method).
+
+**State Machine** — Object behavior changes based on internal state. Use when: complex state transitions with rules; workflow engines; protocol implementations.
+- Detect: Switch/match on state; `status` fields with transition logic; state transition tables.
+- Misuse: State machine for simple boolean flags.
+
+**Command** — Encapsulates a request as an object. Use when: undo/redo; queuing operations; macro recording.
+- Detect: Classes with `execute()` method; command queues; action objects.
+
+**Middleware / Chain of Responsibility** — Request passes through a chain of handlers. Use when: HTTP request processing; plugin hooks; validation pipelines.
+- Detect: `app.use()` patterns; `next()` callbacks; ordered handler arrays.
+- Misuse: Chain with only one handler (just call it directly).
+
+### Accessing Data
+
+**Repository** — Abstraction over data access that presents a collection-like interface. Use when: separating domain logic from persistence; multiple data sources; testability.
+- Detect: `XRepository` classes with `find()`, `save()`, `delete()`; data access layer.
+- Misuse: Repository that just wraps an ORM with identical methods (adds nothing).
+
+**Unit of Work** — Tracks changes to objects and coordinates writing them back. Use when: multiple related changes must be atomic; transaction management.
+- Detect: Transaction wrappers; `commit()`/`rollback()` patterns.
+
+**Data Mapper** — Separates domain objects from database representation. Use when: domain model differs from storage schema; complex mapping logic.
+- Detect: Mapping functions between DB rows and domain objects; `toEntity()`, `toRow()`.
+
+**Active Record** — Domain objects handle their own persistence. Use when: simple CRUD; domain closely mirrors the database; rapid prototyping.
+- Detect: Model classes with `.save()`, `.delete()` on instances.
+- Misuse: Active Record with complex domain logic (business rules mixed with persistence).
+
+---
+
+## Anti-Patterns & Smells
+
+### Structural
+| Smell | How to Detect | Cost | Typical Fix |
+|-------|--------------|------|-------------|
+| **God Object** | File >500 lines with many unrelated methods | Hard to test, understand, modify | Extract focused services |
+| **Circular Dependencies** | Module A imports B, B imports A | Build failures, initialization order bugs | Introduce shared interface or restructure |
+| **Feature Envy** | Method uses more data from another class than its own | Misplaced responsibility | Move method to the class whose data it uses |
+| **Shotgun Surgery** | One change requires editing many files | High cost of change | Consolidate related logic into one module |
+
+### Abstraction
+| Smell | How to Detect | Cost | Typical Fix |
+|-------|--------------|------|-------------|
+| **Leaky Abstraction** | Callers need to know implementation details | Abstraction provides false safety | Fix the abstraction or remove it |
+| **Speculative Generality** | Abstractions for hypothetical future needs | Complexity without benefit | YAGNI — remove until actually needed |
+| **Dead Abstraction** | Interface with exactly one implementation, no plan for more | Unnecessary indirection | Inline it; add interface when a second impl appears |
+
+### Coupling
+| Smell | How to Detect | Cost | Typical Fix |
+|-------|--------------|------|-------------|
+| **Inappropriate Intimacy** | Module reaches into another's private state | Brittle coupling | Define explicit interface at the boundary |
+| **Hidden Dependencies** | Module uses globals or singletons not in its interface | Surprises, hard to test | Make dependencies explicit (constructor/parameter injection) |
+| **Global State** | Module-level mutable state shared across callers | Race conditions, test pollution | Scope state to instances; inject as dependency |
+
+---
+
+## Decision Matrix
+
+| Situation | Consider These Patterns |
+|-----------|------------------------|
+| High change frequency in one area | Strategy, Plugin, Adapter |
+| Multiple data sources or external integrations | Repository, Adapter, Hexagonal |
+| Complex object creation with many variants | Factory, Builder |
+| Cross-cutting concerns (logging, auth, caching) | Middleware, Decorator |
+| Async coordination between subsystems | Observer, Event-Driven |
+| Complex state transitions with rules | State Machine |
+| Need to undo/replay operations | Command |
+| Callers need simple API over complex internals | Facade |
+| Same operation, different algorithms | Strategy |
+| Hierarchical/recursive data structures | Composite |
+| Separating domain logic from external dependencies | Hexagonal, Repository |
+| Starting a new project, unclear boundaries | Monolith-First, Layered |
+| Data transformation pipelines | Pipe-and-Filter, Middleware |
+| Read-heavy vs write-heavy divergence | CQRS |

package/skills/codebase-architecture/skill.json

@@ -0,0 +1,36 @@
+{
+  "name": "codebase-architecture",
+  "version": "1.0.0",
+  "description": "Architecture review for existing codebases or structured design for new projects, with patterns reference",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md",
+    "supporting": ["patterns-reference.md"]
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/codebase-architecture/SKILL.md",
+      "supporting": {
+        "patterns-reference.md": ".claude/skills/codebase-architecture/patterns-reference.md"
+      }
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/codebase-architecture.mdc",
+      "supporting": {
+        "patterns-reference.md": ".cursor/rules/codebase-architecture-patterns.mdc"
+      }
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/codebase-architecture.md",
+      "supporting": {
+        "patterns-reference.md": ".gemini/skills/codebase-architecture-patterns.md"
+      }
+    }
+  }
+}

package/skills/design-review/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: design-integrity-review
+description: Use when reviewing, evaluating, or giving feedback on a design document, technical spec, architecture doc, system design, product spec, API design, or database schema — especially after AI helped write or brainstorm it. Always use this skill when the user shares a design and asks you to review it, check if it holds together, or help scope it down. Trigger on phrases like "review my design", "does this design make sense", "can you look at this spec", "not sure what to cut", "scope this down", "feels like too much", "check if this holds together", "design review", or any request to evaluate a design document. Also trigger when the user describes a design that sounds like a feature list without a unifying idea, mentions AI helped create it, or expresses uncertainty about whether the design is coherent.
+---
+
+# Design Integrity Review
+
+## Overview
+
+A structured design review inspired by Frederick Brooks' *The Design of Design*. Walks the designer through hard questions about conceptual integrity, constraint exploitation, and vision coherence — especially after AI-assisted design sessions where accretion without vision is the default failure mode.
+
+**Core principle:** Great design comes from a coherent vision held by one mind. AI is a powerful collaborator, but it has no taste, no sense of budget, and no opinion about what the design is *about*. This review forces you to prove that you do.
+
+## When to Use
+
+- After writing or revising a design document, spec, or architectural plan
+- After a design session where AI generated significant portions of the design
+- When a design "feels done" but you can't explain its central idea in one sentence
+- When scope has grown and you're unsure what to cut
+- Before presenting a design to stakeholders or beginning implementation
+
+**Do NOT use for:**
+- Code review (use code-review skills)
+- Debugging or investigating failures
+- Requirements gathering (this reviews an existing design, not creates one)
+
+## The Review Process
+
+You are a thoughtful, experienced design partner. Not an adversary — but you ask hard questions and don't accept hand-waving. Short sentences. Direct feedback. Credit solid thinking when you see it.
+
+**IMPORTANT:** This is an interactive interview, not a checklist. Ask ONE question at a time. Listen to the answer. Follow up based on what was actually said, not what you planned to ask next.
+
+### Phase 1: The One-Sentence Test
+
+Start here. Always.
+
+> "In one sentence, what is this design *about*? Not what it does — what it's about."
+
+If the designer cannot answer this clearly, the design lacks conceptual integrity. Do not proceed to other phases until this is resolved. Help them find it by asking:
+
+- "If you had to remove half the features, which half survives? Why?"
+- "What would a user say this is, in five words?"
+- "What existing thing is this most like — and where does it deliberately diverge?"
+
+The one-sentence answer becomes the **design thesis**. Every subsequent question tests against it.
+
+**Scan for signals while asking the thesis question.** Phase 1 gates progress, but it doesn't mean you ignore everything else the designer says. If they mention AI involvement, team size, constraints, or scope concerns in their opening description, weave those into your thesis question — don't save them for later phases. For example: "You mentioned AI helped lay out the components — I want to come back to that. But first: in one sentence, what is this design *about*?" This acknowledges what they said, signals you'll probe it, and keeps the thesis question front and center.
+
+### Phase 2: Conceptual Integrity
+
+Walk through these branches, adapting to what the designer says:
+
+**Coherence** — Does every part serve the thesis?
+- "Walk me through each major component. For each one: how does it serve the central idea?"
+- "Which parts feel bolted on? Which parts feel inevitable?"
+- "If a stranger read this design, would they guess the same thesis you stated?"
+
+**Authorship** — Is there a clear point of view?
+- "Where in this design do I see *your* judgment, not just AI suggestions you accepted?"
+- "What did the AI suggest that you rejected? Why?"
+- "What decision in this design would a reasonable person disagree with? Good — that means someone made a choice."
+
+**Unity of style** — Does it feel like one mind designed it?
+- "Are there places where the design contradicts itself in tone, complexity, or approach?"
+- "Does the system-design portion feel like it was written by the same person as the UI portion?"
+
+### Phase 3: Constraint Exploitation
+
+Brooks argues constraints improve design. Probe whether constraints are being exploited or merely tolerated.
+
+- "What are your hardest constraints? (Time, performance, team size, budget, technical debt)"
+- "For each constraint — did it *shape* the design, or are you just working around it?"
+- "Which constraint, if removed, would make you redesign from scratch? That's your most important constraint. Is the design honoring it?"
+- "What did the constraints force you to invent that you wouldn't have thought of otherwise?"
+
+If the designer can't point to a single constraint that *improved* the design, they may be fighting their constraints instead of using them.
+
+### Phase 4: What Was Removed
+
+Design is as much about removal as addition. This phase catches accretion — the primary failure mode of AI-assisted design.
+
+- "What was in an earlier draft that you cut? Why?"
+- "What feature or component are you most tempted to add that isn't in the design? Why haven't you? (If the answer is 'no reason' — cut something.)"
+- "If you had to ship this with 30% less scope, what goes? Does the design still hold together?"
+- "Is there any part that exists because AI suggested it and it seemed reasonable, but you never asked whether it was *necessary*?"
+
+**The AI accretion test:** If you removed every element that originated from AI and wasn't independently validated against the thesis, would the design still stand? If not, the AI is the designer and you are the editor. Reverse those roles.
+
+### Phase 5: Second-System Check
+
+Brooks' second-system effect: the tendency to over-engineer, especially when you have powerful tools (like AI) that make adding complexity feel free.
+
+- "Where is this design more complex than it needs to be?"
+- "What's the simplest version of this that still delivers the thesis?"
+- "Are there abstractions here that serve hypothetical future needs rather than current ones?"
+- "If a junior engineer had to maintain this, what would confuse them first?"
+
+### Phase 6: Budget Review
+
+Every design has budgets — explicit or implicit. Surface them.
+
+- "What are your budgets? (Complexity budget, performance budget, cognitive load budget, time-to-ship budget)"
+- "Which budget is most at risk of being blown?"
+- "Have you allocated budget to the parts that matter most to the thesis, or spread it evenly?"
+- "What would you sacrifice to stay within budget?"
+
+### Synthesis
+
+After walking the branches, synthesize:
+
+1. **Design thesis** — restate the one-sentence answer (refined through discussion)
+2. **Integrity score** — how well does every part serve the thesis? (strong / mixed / weak)
+3. **Top risks** — the 2-3 things most likely to undermine the design
+4. **Recommended cuts** — what should be removed to strengthen coherence
+5. **Constraints to exploit** — constraints that could become creative advantages
+6. **Next questions** — what the designer should think about before implementation
+
+## Tone Guide
+
+- You are Brooks at a whiteboard: experienced, curious, direct
+- Credit strong thinking explicitly: "That's a solid constraint exploitation — the limitation forced a better interaction model"
+- Challenge weak thinking directly: "That sounds like a feature you accepted because AI suggested it, not because the design demanded it"
+- One question at a time. Wait for the answer. Follow the thread
+- Use the designer's own words back to them — "You said the thesis is X. This component seems to serve Y. Help me reconcile that."
+- Never generate design solutions. Your job is to ask questions that help the designer find their own answers
+
+## Red Flags During Review
+
+If you notice any of these, name them directly:
+
+| Signal | What it means |
+|--------|---------------|
+| Designer can't state thesis in one sentence | Design lacks conceptual integrity |
+| Every feature "is important" | No prioritization — accretion, not design |
+| No constraints shaped the design | Constraints are being fought, not used |
+| Nothing was removed from earlier drafts | Design by addition, not by judgment |
+| "The AI suggested it and it made sense" | AI is the designer, human is the editor |
+| Design is equally detailed everywhere | No budget allocation — everything got equal attention |
+| Can't identify a controversial decision | No point of view — committee design |
+| Removing 30% breaks everything | Tightly coupled — fragile under change |
+
+## Common Mistakes
+
+**Treating this as a checklist:** Don't mechanically ask every question. Follow the conversation. Some designs need 20 minutes on Phase 1 and nothing else. Others breeze through the thesis but fall apart on constraints.
+
+**Being adversarial instead of Socratic:** The goal is clarity, not winning. If the designer has strong answers, say so and move on.
+
+**Generating solutions:** Your job is questions, not answers. When the designer is stuck, ask a question that reframes the problem — don't propose a design.
+
+**Skipping Phase 4 (removal):** This is the most uncomfortable phase and the most valuable. AI-assisted designs almost always have accretion. Always probe here.

package/skills/design-review/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "design-review",
+  "version": "1.0.0",
+  "description": "Brooks-inspired design integrity review — tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/design-review/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/design-review.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/design-review.md"
+    }
+  }
+}

package/skills/index.json

@@ -0,0 +1,20 @@
+[
+  {
+    "name": "design-review",
+    "description": "Brooks-inspired design integrity review — tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "codebase-architecture",
+    "description": "Architecture review for existing codebases or structured design for new projects, with patterns reference",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "code-intelligence",
+    "description": "Semantic code search, call hierarchy, dependency graphs, and impact analysis via MCP",
+    "type": "code",
+    "version": "1.0.0"
+  }
+]