forgecraft-mcp 0.2.1 → 0.3.0

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: ""