forgecraft-mcp 0.2.1 → 0.4.0

package/templates/universal/instructions.yaml

@@ -18,10 +18,11 @@ blocks:
     title: "Code Standards"
     content: |
       ## Code Standards
-      - Maximum function/method length: {{max_function_length | default: 50}} lines. If longer, decompose.
-      - Maximum file length: {{max_file_length | default: 300}} lines. If longer, split by responsibility.
+      - Maximum function/method length: {{max_function_length | default: 50}} lines (hook-enforced).
+      - Maximum file length: {{max_file_length | default: 300}} lines (hook-enforced).
       - Maximum function parameters: {{max_function_params | default: 5}}. If more, use a parameter object.
-      - Every public function/method must have a docstring/JSDoc with typed params and returns.
+      - No circular imports — module dependency graph must be acyclic (hook-enforced).
+      - Every public function/method must have {{#if language_is_typescript}}a JSDoc comment{{/if}}{{#if language_is_python}}a docstring (Google or NumPy style){{/if}} with typed params and returns.
       - Delete orphaned code. Do not comment it out. Git has history.
       - Before creating a new utility, search the entire codebase for existing ones.
       - Reuse existing patterns — check shared modules before writing new.
@@ -81,7 +82,7 @@ blocks:
       ### Modular from Day One
       - Feature-based modules over layer-based. Each feature owns its models, service, repository, routes.
       - Module dependency graph must be acyclic.
-      - Every module has a clear public API via __init__.py / index.ts exports.
+      - Every module has a clear public API via {{#if language_is_typescript}}index.ts{{/if}}{{#if language_is_python}}__init__.py{{/if}} exports.
 
   - id: layered-architecture
     tier: recommended
@@ -124,7 +125,7 @@ blocks:
 
       ### Data Transfer Objects (DTOs)
       - Use DTOs at layer boundaries — never pass domain entities to/from the API layer.
-      - **Request DTOs**: validated at the API boundary (Zod schema → typed object).
+      - **Request DTOs**: validated at the API boundary ({{#if language_is_typescript}}Zod schema{{/if}}{{#if language_is_python}}Pydantic model{{/if}} → typed object).
       - **Response DTOs**: shaped for the consumer, not mirroring the domain model.
       - **Domain ↔ Persistence mapping**: repositories map between domain entities and DB rows/documents.
       - DTOs are plain data objects — no methods, no behavior, no framework decorators.
@@ -178,8 +179,9 @@ blocks:
       - Instead: `order.getShippingCity()` or pass the needed data directly.
 
       ### Immutability by Default
-      - Use `const` over `let`. Use `readonly` on properties and parameters.
-      - Prefer `ReadonlyArray<T>`, `Readonly<T>`, `ReadonlyMap`, `ReadonlySet`.
+      {{#if language_is_typescript}}- Use `const` over `let`. Use `readonly` on properties and parameters.
+      - Prefer `ReadonlyArray<T>`, `Readonly<T>`, `ReadonlyMap`, `ReadonlySet`.{{/if}}{{#if language_is_python}}- Use `Final` for constants. Use `frozen=True` on dataclasses.
+      - Prefer `tuple` over `list` for immutable sequences. Use `MappingProxyType` for immutable dicts.{{/if}}
       - When you need to "modify" data, create a new copy with the change.
       - Mutable state is the #1 source of bugs. Restrict it to the smallest possible scope.
 
@@ -196,117 +198,7 @@ blocks:
       - Factories are the natural companion to dependency injection — the DI container
         IS the top-level factory.
 
-  - id: domain-driven-design
-    tier: optional
-    title: "Domain-Driven Design Essentials"
-    content: |
-      ## Domain-Driven Design (DDD) Essentials
-
-      ### Entities vs. Value Objects
-      - **Entity**: has identity (ID) that persists across state changes. Two users with the
-        same name are NOT the same user. Compared by ID.
-      - **Value Object**: defined by its attributes, not identity. Two `Money(100, "USD")` are
-        the same. Immutable. Compared by value.
-      - When in doubt, make it a Value Object — they're simpler and safer.
-
-      ### Eliminate Primitive Obsession
-      - Don't use raw `string` for email, `number` for currency, `string` for phone.
-      - Wrap domain concepts in typed Value Objects: `EmailAddress`, `Money`, `PhoneNumber`.
-      - Value Objects enforce validation at construction — an invalid email can never exist.
-      - This moves validation FROM every call site TO the constructor — DRY + safe.
-
-      ### Aggregates
-      - An aggregate is a cluster of domain objects treated as a single unit for data changes.
-      - One entity is the **aggregate root** — all external access goes through it.
-      - Aggregates enforce invariants: `Order` ensures its `OrderLines` don't exceed the limit.
-      - Reference other aggregates by ID, not by direct object reference.
-
-      ### Bounded Contexts
-      - A bounded context is a boundary within which a domain model has a specific meaning.
-      - The word "Account" means different things in Billing vs. Auth vs. Social.
-      - Each context owns its models, language, and persistence — no shared database tables.
-      - Contexts communicate via well-defined interfaces, events, or an **Anti-Corruption Layer**
-        that translates between contexts.
-
-      ### Domain Events
-      - When something important happens in the domain, publish an event: `OrderPlaced`,
-        `MemberDeactivated`, `PaymentFailed`.
-      - Events decouple modules: the Order module publishes `OrderPlaced`, the Notification
-        module subscribes — neither imports the other.
-      - Events are past-tense named facts. They carry the data needed by subscribers.
-      - In-process event bus for monoliths; message broker (SQS, Kafka, NATS) for distributed.
-
-  - id: cqrs-event-patterns
-    tier: optional
-    title: "CQRS & Event Patterns"
-    content: |
-      ## CQRS & Event-Driven Patterns
-
-      ### CQRS (Command Query Responsibility Segregation)
-      When read and write patterns diverge significantly:
-      - **Command side**: validates, enforces business rules, writes to the canonical store.
-      - **Query side**: reads from optimized read models (denormalized views, search indices).
-      - Start simple: same database, separate service methods. Optimize to separate stores
-        only when read/write scaling demands it.
-      - CQRS is not mandatory everywhere — use it where read/write asymmetry is real.
-
-      ### Event Sourcing (when appropriate)
-      - Store the sequence of events, not just current state.
-      - Useful for: audit trails, temporal queries, debugging, undo/redo.
-      - NOT appropriate for: simple CRUD, low-value data, early-stage features.
-      - If you use event sourcing, you MUST also maintain a read-projection.
-
-      ### Pub/Sub & Message Patterns
-      - **Fire and forget**: publish event, don't wait for subscribers.
-      - **Request/Reply**: send command, wait for response.
-      - In-process: use an event emitter or mediator.
-      - Distributed: use durable message queues with at-least-once delivery.
-
-  - id: design-patterns-reference
-    tier: optional
-    title: "Design Patterns Quick Reference"
-    content: |
-      ## Design Patterns — When to Reach for What
-
-      ### Creational
-      - **Factory Method / Abstract Factory**: Use when instantiation logic is complex or varies by context.
-        Prefer over `new` in business logic — keep constructors for DI only.
-      - **Builder**: Use when constructing objects with many optional parameters. Fluent API preferred.
-      - **Singleton**: Almost never in application code. Use DI to manage lifecycle instead.
-        Acceptable only for: loggers, config singletons in composition root.
-
-      ### Structural
-      - **Adapter**: Wrap third-party APIs to match your port interfaces. Isolates vendor lock-in.
-      - **Facade**: Simplify complex subsystem interactions behind a unified interface.
-        Every module's `index.ts` exports are a facade.
-      - **Decorator**: Add behavior (logging, caching, retry, auth) without modifying the original.
-        Middleware pipelines are decorator chains.
-      - **Proxy**: Lazy loading, access control, or caching in front of expensive resources.
-
-      ### Behavioral
-      - **Strategy**: Extract interchangeable algorithms behind an interface. Inject the right one.
-        Examples: pricing calculators, render strategies, sort algorithms.
-      - **Observer / Pub-Sub**: Decouple event producers from consumers. Use for: domain events,
-        UI state changes, webhook fan-out. See CQRS & Event Patterns section.
-      - **Chain of Responsibility**: Middleware pipelines (Express, Koa). Each handler decides
-        to process or pass to the next. Order matters.
-      - **Command**: Encapsulate actions as objects. Enables: undo/redo, queuing, audit trail.
-
-      ### Enterprise
-      - **Repository**: Encapsulate data access behind a collection-like interface. Defined in the
-        domain layer, implemented in the infrastructure layer as adapters.
-      - **Unit of Work**: Track changes within a transaction boundary. Commit or roll back atomically.
-        Pair with Repository for database operations.
-      - **Saga**: Coordinate multi-step distributed operations. Each step has a compensating action
-        for rollback. Use for: order processing, payment flows, multi-service workflows.
-      - **Outbox**: Write events to a local outbox table in the same transaction as the state change.
-        A separate process reliably publishes them. Guarantees at-least-once event delivery.
-
-      ### Anti-Patterns to Avoid
-      - **God Object**: One class that knows/does everything. Split by responsibility.
-      - **Service Locator**: Global registry looked up at runtime. Use constructor injection instead.
-      - **Anemic Domain Model**: Entities with only getters/setters, logic in services.
-        Push behavior into domain objects.
+      > **Design reference patterns** (DDD, CQRS, GoF) available on demand via `get_design_reference` tool.
 
   - id: twelve-factor-ops
     tier: optional
@@ -416,6 +308,37 @@ blocks:
       - Define invariants, not examples: "sorting is idempotent", "encode then decode = identity".
       - Property tests complement, not replace, example-based tests.
 
+  - id: tdd-methodology
+    tier: core
+    title: "Test-Driven Development"
+    content: |
+      ## Test-Driven Development (TDD)
+
+      ### Red-Green-Refactor — The Only Cycle
+      1. **RED**: Write a failing test that describes the desired behavior. Run it. It MUST fail.
+         If it passes, the test is wrong — it's not testing what you think.
+      2. **GREEN**: Write the minimum code to make the test pass. No more.
+      3. **REFACTOR**: Clean up while all tests stay green. No new behavior in this step.
+      Repeat. Every feature, every function, every bug fix follows this cycle.
+
+      ### Tests Are Specifications, Not Confirmations
+      - Write tests against **expected behavior**, never against current implementation.
+      - A test that passes on broken code is worse than no test — it provides false confidence.
+      - Never weaken an assertion to match what the code currently does. If the code disagrees
+        with the spec, the code is wrong.
+      - Never write a test suite after the fact that just "locks in" existing behavior without
+        verifying it's correct.
+
+      ### Bug Fix Protocol
+      - **Every bug fix starts with a failing test** that reproduces the bug.
+      - The test must fail before the fix and pass after. No exceptions.
+      - If you can't write a reproducing test, you don't understand the bug well enough to fix it.
+
+      ### One Behavior Per Test
+      - Each test verifies exactly one behavior or rule.
+      - A test with multiple unrelated assertions is testing multiple things — split it.
+      - Test name = the specification: `rejects_expired_tokens`, not `test_auth`.
+
   - id: data-guardrails
     tier: core
     title: "Data Guardrails"

package/templates/universal/mcp-servers.yaml

@@ -7,6 +7,7 @@ servers:
     args: ["-y", "forgecraft-mcp"]
     tags: [UNIVERSAL]
     category: scaffolding
+    tier: core
     url: "https://github.com/jghiringhelli/forgecraft-mcp"
 
   - name: context7
@@ -15,6 +16,7 @@ servers:
     args: ["-y", "@upstash/context7-mcp@latest"]
     tags: [UNIVERSAL]
     category: documentation
+    tier: recommended
     url: "https://github.com/upstash/context7"
 
   - name: sequential-thinking
@@ -23,4 +25,14 @@ servers:
     args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
     tags: [UNIVERSAL]
     category: general
+    tier: optional
     url: "https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking"
+
+  - name: spec-workflow
+    description: "Spec-driven TDD workflow with structured requirements, design docs, and red-green-refactor quality gates"
+    command: npx
+    args: ["-y", "spec-workflow-mcp"]
+    tags: [UNIVERSAL]
+    category: testing
+    tier: optional
+    url: "https://github.com/Pimzino/spec-workflow-mcp"

package/templates/universal/nfr.yaml

@@ -177,7 +177,7 @@ blocks:
       ### Code Quality Metrics
       - Cyclomatic complexity: flag functions > 10, block > 15.
       - Dead code detection.
-      - Documentation coverage: all public APIs have docstrings/JSDoc.
+      - Documentation coverage: all public APIs have {{#if language_is_typescript}}JSDoc{{/if}}{{#if language_is_python}}docstrings{{/if}}.
 
       ### Technical Debt Tracking
       - Tech debt items logged in Status.md.

package/templates/universal/reference.yaml

@@ -0,0 +1,111 @@
+tag: UNIVERSAL
+section: reference
+blocks:
+  - id: domain-driven-design
+    title: "Domain-Driven Design Essentials"
+    content: |
+      ## Domain-Driven Design (DDD) Essentials
+
+      ### Entities vs. Value Objects
+      - **Entity**: has identity (ID) that persists across state changes. Two users with the
+        same name are NOT the same user. Compared by ID.
+      - **Value Object**: defined by its attributes, not identity. Two `Money(100, "USD")` are
+        the same. Immutable. Compared by value.
+      - When in doubt, make it a Value Object — they're simpler and safer.
+
+      ### Eliminate Primitive Obsession
+      - Don't use raw `string` for email, `number` for currency, `string` for phone.
+      - Wrap domain concepts in typed Value Objects: `EmailAddress`, `Money`, `PhoneNumber`.
+      - Value Objects enforce validation at construction — an invalid email can never exist.
+      - This moves validation FROM every call site TO the constructor — DRY + safe.
+
+      ### Aggregates
+      - An aggregate is a cluster of domain objects treated as a single unit for data changes.
+      - One entity is the **aggregate root** — all external access goes through it.
+      - Aggregates enforce invariants: `Order` ensures its `OrderLines` don't exceed the limit.
+      - Reference other aggregates by ID, not by direct object reference.
+
+      ### Bounded Contexts
+      - A bounded context is a boundary within which a domain model has a specific meaning.
+      - The word "Account" means different things in Billing vs. Auth vs. Social.
+      - Each context owns its models, language, and persistence — no shared database tables.
+      - Contexts communicate via well-defined interfaces, events, or an **Anti-Corruption Layer**
+        that translates between contexts.
+
+      ### Domain Events
+      - When something important happens in the domain, publish an event: `OrderPlaced`,
+        `MemberDeactivated`, `PaymentFailed`.
+      - Events decouple modules: the Order module publishes `OrderPlaced`, the Notification
+        module subscribes — neither imports the other.
+      - Events are past-tense named facts. They carry the data needed by subscribers.
+      - In-process event bus for monoliths; message broker (SQS, Kafka, NATS) for distributed.
+
+  - id: cqrs-event-patterns
+    title: "CQRS & Event Patterns"
+    content: |
+      ## CQRS & Event-Driven Patterns
+
+      ### CQRS (Command Query Responsibility Segregation)
+      When read and write patterns diverge significantly:
+      - **Command side**: validates, enforces business rules, writes to the canonical store.
+      - **Query side**: reads from optimized read models (denormalized views, search indices).
+      - Start simple: same database, separate service methods. Optimize to separate stores
+        only when read/write scaling demands it.
+      - CQRS is not mandatory everywhere — use it where read/write asymmetry is real.
+
+      ### Event Sourcing (when appropriate)
+      - Store the sequence of events, not just current state.
+      - Useful for: audit trails, temporal queries, debugging, undo/redo.
+      - NOT appropriate for: simple CRUD, low-value data, early-stage features.
+      - If you use event sourcing, you MUST also maintain a read-projection.
+
+      ### Pub/Sub & Message Patterns
+      - **Fire and forget**: publish event, don't wait for subscribers.
+      - **Request/Reply**: send command, wait for response.
+      - In-process: use an event emitter or mediator.
+      - Distributed: use durable message queues with at-least-once delivery.
+
+  - id: design-patterns-reference
+    title: "Design Patterns Quick Reference"
+    content: |
+      ## Design Patterns — When to Reach for What
+
+      ### Creational
+      - **Factory Method / Abstract Factory**: Use when instantiation logic is complex or varies by context.
+        Prefer over `new` in business logic — keep constructors for DI only.
+      - **Builder**: Use when constructing objects with many optional parameters. Fluent API preferred.
+      - **Singleton**: Almost never in application code. Use DI to manage lifecycle instead.
+        Acceptable only for: loggers, config singletons in composition root.
+
+      ### Structural
+      - **Adapter**: Wrap third-party APIs to match your port interfaces. Isolates vendor lock-in.
+      - **Facade**: Simplify complex subsystem interactions behind a unified interface.
+        Every module's public exports are a facade.
+      - **Decorator**: Add behavior (logging, caching, retry, auth) without modifying the original.
+        Middleware pipelines are decorator chains.
+      - **Proxy**: Lazy loading, access control, or caching in front of expensive resources.
+
+      ### Behavioral
+      - **Strategy**: Extract interchangeable algorithms behind an interface. Inject the right one.
+        Examples: pricing calculators, render strategies, sort algorithms.
+      - **Observer / Pub-Sub**: Decouple event producers from consumers. Use for: domain events,
+        UI state changes, webhook fan-out. See CQRS & Event Patterns section.
+      - **Chain of Responsibility**: Middleware pipelines (Express, Koa). Each handler decides
+        to process or pass to the next. Order matters.
+      - **Command**: Encapsulate actions as objects. Enables: undo/redo, queuing, audit trail.
+
+      ### Enterprise
+      - **Repository**: Encapsulate data access behind a collection-like interface. Defined in the
+        domain layer, implemented in the infrastructure layer as adapters.
+      - **Unit of Work**: Track changes within a transaction boundary. Commit or roll back atomically.
+        Pair with Repository for database operations.
+      - **Saga**: Coordinate multi-step distributed operations. Each step has a compensating action
+        for rollback. Use for: order processing, payment flows, multi-service workflows.
+      - **Outbox**: Write events to a local outbox table in the same transaction as the state change.
+        A separate process reliably publishes them. Guarantees at-least-once event delivery.
+
+      ### Anti-Patterns to Avoid
+      - **God Object**: One class that knows/does everything. Split by responsibility.
+      - **Service Locator**: Global registry looked up at runtime. Use constructor injection instead.
+      - **Anemic Domain Model**: Entities with only getters/setters, logic in services.
+        Push behavior into domain objects.

package/templates/universal/review.yaml

@@ -10,7 +10,7 @@ blocks:
       Focus on component boundaries, dependency flow, and failure modes.
     checklist:
       - id: component-boundaries
-        description: "Component boundaries are well-defined with clear public APIs (index.ts exports)."
+        description: "Component boundaries are well-defined with clear public APIs (module exports)."
         severity: critical
       - id: dependency-graph
         description: "Dependency graph is acyclic. No circular imports between modules."
@@ -85,7 +85,7 @@ blocks:
         description: "No long method chains through objects (a.b().c().d()). Objects expose only the information their callers need."
         severity: nice-to-have
       - id: immutability
-        description: "const over let, readonly on properties. Mutable state restricted to smallest possible scope."
+        description: "Immutable by default — prefer constants and frozen structures. Mutable state restricted to smallest possible scope."
         severity: important
       - id: pure-functions
         description: "Domain logic, validation, and transformations are pure (same input → same output, no side effects). Side effects pushed to adapters."

package/templates/universal/skills.yaml

@@ -0,0 +1,106 @@
+tag: UNIVERSAL
+section: skills
+skills:
+  - id: code-review
+    name: Code Review
+    filename: code-review.md
+    description: "Structured code review with checklist and severity ratings"
+    tier: core
+    content: |
+      Review the code changes in this project. For each file changed:
+
+      1. **Read** the file and understand the context
+      2. **Check** against these criteria:
+         - Correctness: Does the logic do what it claims?
+         - Security: Any injection, auth bypass, or data leak risks?
+         - Performance: Any N+1 queries, unbounded loops, or memory leaks?
+         - Readability: Are names intention-revealing? Is complexity justified?
+         - Tests: Are edge cases covered? Can tests fail?
+
+      3. **Output** findings in this format:
+         - **File**: path/to/file
+         - **Line**: number
+         - **Severity**: CRITICAL | IMPORTANT | SUGGESTION
+         - **Issue**: description
+         - **Fix**: recommended change
+
+      If $ARGUMENTS is provided, focus the review on those specific files or concerns.
+      Otherwise, review all staged or recently changed files (use `git diff --name-only`).
+
+  - id: run-tests
+    name: Run Tests
+    filename: run-tests.md
+    description: "Run test suite and analyze failures"
+    tier: core
+    content: |
+      Run the project's test suite and analyze the results.
+
+      Steps:
+      {{#if language_is_typescript}}
+      1. Run `npm test` or `npx vitest run`
+      2. If tests fail, read the failing test files and the source code they test
+      3. Identify root cause — is it a test bug or a source bug?
+      4. Propose a fix with explanation
+      {{/if}}
+      {{#if language_is_python}}
+      1. Run `pytest -v` or `python -m pytest`
+      2. If tests fail, read the failing test files and the source code they test
+      3. Identify root cause — is it a test bug or a source bug?
+      4. Propose a fix with explanation
+      {{/if}}
+
+      If $ARGUMENTS is provided, run only matching tests (e.g., a specific file or pattern).
+
+      Always report:
+      - Total tests: passed / failed / skipped
+      - Coverage summary if available
+      - Any flaky test patterns detected
+
+  - id: debug-error
+    name: Debug Error
+    filename: debug-error.md
+    description: "Investigate and fix an error from logs or stack trace"
+    tier: recommended
+    content: |
+      Debug the following error. $ARGUMENTS should contain the error message or stack trace.
+
+      Investigation steps:
+      1. Parse the error message and stack trace
+      2. Identify the source file and line number
+      3. Read the relevant source code
+      4. Trace the data flow backward to find the root cause
+      5. Check for similar patterns elsewhere in the codebase
+      6. Propose a fix with:
+         - **Root cause**: why this happened
+         - **Fix**: the code change
+         - **Prevention**: how to prevent recurrence (test, type guard, validation)
+
+      Do NOT guess. Read the actual code before proposing solutions.
+
+  - id: refactor-file
+    name: Refactor File
+    filename: refactor-file.md
+    description: "Refactor a file following SOLID principles and project conventions"
+    tier: recommended
+    content: |
+      Refactor the file specified in $ARGUMENTS following project conventions.
+
+      Analysis steps:
+      1. Read the file completely
+      2. Check against SOLID principles:
+         - **S**: Does each function/class have one responsibility?
+         - **O**: Can behavior be extended without modifying existing code?
+         - **L**: Are subtypes substitutable?
+         - **I**: Are interfaces focused?
+         - **D**: Are dependencies injected?
+      3. Check project conventions:
+         - Max function length: 50 lines
+         - Max file length: 300 lines
+         - Max parameters: 5 (use parameter object if more)
+         - Intention-revealing names, no abbreviations
+      4. Propose changes grouped by priority:
+         - MUST: Violations of project standards
+         - SHOULD: Improvements to readability/maintainability
+         - COULD: Optional enhancements
+
+      Make changes incrementally. Run tests after each change to verify nothing breaks.

package/templates/web-react/mcp-servers.yaml

@@ -7,6 +7,7 @@ servers:
     args: ["-y", "@anthropic/chrome-devtools-mcp@latest"]
     tags: [WEB-REACT, WEB-STATIC, ANALYTICS]
     category: devtools
+    tier: recommended
     url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp"
 
   - name: playwright
@@ -15,4 +16,5 @@ servers:
     args: ["-y", "@anthropic/mcp-server-playwright"]
     tags: [WEB-REACT, WEB-STATIC]
     category: testing
+    tier: recommended
     url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-playwright"

package/templates/web-react/skills.yaml

@@ -0,0 +1,56 @@
+tag: WEB-REACT
+section: skills
+skills:
+  - id: react-add-component
+    name: Add React Component
+    filename: react-add-component.md
+    description: "Scaffold a new React component following project patterns"
+    tier: core
+    content: |
+      Create a new React component. $ARGUMENTS should contain the component name and description.
+
+      Steps:
+      1. Analyze existing component patterns:
+         - File naming convention (PascalCase, kebab-case, index.tsx barrel)
+         - Component style (function components, arrow functions)
+         - Styling approach (CSS modules, Tailwind, styled-components, etc.)
+         - State management pattern (hooks, context, store)
+         - Props pattern (inline types, separate interface, shared types)
+      2. Create the component matching discovered patterns:
+         - Component file with proper TypeScript props interface
+         - Styles file if the project uses co-located styles
+         - Index barrel export if the project uses them
+      3. Add tests:
+         - Renders without crashing
+         - Displays expected content with given props
+         - Handles user interaction (click, input) if applicable
+      4. Export from the nearest index file
+
+      Follow existing patterns. Do NOT introduce new styling or state management approaches.
+
+  - id: react-optimize-performance
+    name: Optimize React Performance
+    filename: react-optimize-performance.md
+    description: "Find and fix React performance issues"
+    tier: recommended
+    content: |
+      Analyze React components for performance issues. If $ARGUMENTS specifies a component, focus there. Otherwise, scan the project.
+
+      Check for:
+      1. **Unnecessary re-renders**:
+         - Components missing `React.memo` where props rarely change
+         - Inline object/array/function creation in JSX props
+         - Missing `useCallback` / `useMemo` for expensive operations
+      2. **State management**:
+         - State stored too high in the tree causing cascading renders
+         - Derived state that should be computed (not stored)
+         - Missing state colocation
+      3. **Data fetching**:
+         - Missing loading/error states
+         - No request deduplication or caching
+         - Waterfalls (sequential fetches that could be parallel)
+      4. **Bundle size**:
+         - Large imports that could be lazy-loaded
+         - Missing code splitting at route boundaries
+
+      For each issue found, provide the file, line, problem, and fix with code.

package/templates/web-static/mcp-servers.yaml

@@ -7,6 +7,7 @@ servers:
     args: ["-y", "@anthropic/chrome-devtools-mcp@latest"]
     tags: [WEB-REACT, WEB-STATIC, ANALYTICS]
     category: devtools
+    tier: recommended
     url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp"
 
   - name: playwright
@@ -15,4 +16,5 @@ servers:
     args: ["-y", "@anthropic/mcp-server-playwright"]
     tags: [WEB-REACT, WEB-STATIC]
     category: testing
+    tier: recommended
     url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-playwright"

package/templates/web3/mcp-servers.yaml

@@ -7,4 +7,5 @@ servers:
     args: ["-y", "mcp-server-solidity"]
     tags: [WEB3]
     category: devtools
+    tier: recommended
     url: "https://github.com/AIMONGmbH/solidity-mcp-server"

package/templates/zero-trust/mcp-servers.yaml

@@ -7,6 +7,7 @@ servers:
     args: ["-y", "mcp-server-aws"]
     tags: [ZERO-TRUST, INFRA]
     category: security
+    tier: recommended
     env:
       AWS_REGION: ""
       AWS_ACCESS_KEY_ID: ""