forgecraft-mcp 0.1.0

package/templates/web-react/review.yaml

@@ -0,0 +1,94 @@
+tag: WEB-REACT
+section: review
+blocks:
+  - id: react-architecture-review
+    tier: recommended
+    dimension: architecture
+    title: "React Architecture Review"
+    description: |
+      Evaluate component hierarchy, state management, and rendering patterns.
+    checklist:
+      - id: component-hierarchy
+        description: "Atomic Design followed: atoms → molecules → organisms → templates → pages."
+        severity: important
+      - id: component-purity
+        description: "Components are pure UI. No API calls or business logic inside components."
+        severity: critical
+      - id: state-management
+        description: "State management follows hierarchy: local → context → global store. No prop drilling > 2 levels."
+        severity: important
+      - id: route-structure
+        description: "Routes organized by feature. Lazy loading for non-critical routes."
+        severity: nice-to-have
+
+  - id: react-code-quality-review
+    tier: recommended
+    dimension: code-quality
+    title: "React Code Quality Review"
+    description: |
+      Evaluate component patterns, hooks usage, and i18n compliance.
+    checklist:
+      - id: i18n-compliance
+        description: "Every user-facing string goes through the i18n system. No hardcoded text in JSX."
+        severity: critical
+      - id: accessibility
+        description: "WCAG 2.1 AA compliance: semantic HTML, ARIA labels, keyboard navigation, focus management."
+        severity: critical
+      - id: hooks-patterns
+        description: "Custom hooks extract reusable logic. No complex useEffect chains. Dependencies arrays are correct."
+        severity: important
+      - id: key-props
+        description: "List renderings use stable, unique keys. No array index as key for dynamic lists."
+        severity: important
+      - id: error-boundaries
+        description: "Feature areas wrapped in Error Boundaries. Crash in one widget doesn’t take down the page."
+        severity: critical
+      - id: suspense-loading
+        description: "Every async operation has loading, success, and error states. No blank screens. Skeleton loaders for layout stability."
+        severity: important
+
+  - id: react-performance-review
+    tier: recommended
+    dimension: performance
+    title: "React Performance Review"
+    description: |
+      Evaluate rendering efficiency, bundle size, and lazy loading.
+    checklist:
+      - id: unnecessary-rerenders
+        description: "No unnecessary re-renders. React.memo, useMemo, useCallback used where measurably impactful."
+        severity: important
+      - id: bundle-size
+        description: "Bundle size monitored. No full-library imports (use tree-shakeable named imports)."
+        severity: important
+      - id: image-optimization
+        description: "Images optimized: lazy loading, responsive srcset, modern formats (WebP/AVIF)."
+        severity: nice-to-have
+      - id: core-web-vitals
+        description: "Core Web Vitals tracked: LCP < 2.5s, FID < 100ms, CLS < 0.1."
+        severity: important
+      - id: bundle-budget
+        description: "JavaScript bundle within budget. Initial load under 200 KB compressed. Lighthouse CI enforced in pipeline."
+        severity: important
+      - id: preview-deployments
+        description: "PR preview deployments enabled. URL posted in PR comments for stakeholder review."
+        severity: nice-to-have
+      - id: cache-headers
+        description: "Hashed assets use immutable cache headers. HTML uses short-lived cache with stale-while-revalidate."
+        severity: important
+
+  - id: react-test-review
+    tier: recommended
+    dimension: tests
+    title: "React Test Review"
+    description: |
+      Evaluate React-specific testing patterns.
+    checklist:
+      - id: error-boundary-coverage
+        description: "Error boundaries tested: verify fallback UI renders on component errors. Error reporting verified."
+        severity: important
+      - id: loading-error-states
+        description: "All async operations tested in three states: loading, success, error. No untested blank screens."
+        severity: critical
+      - id: user-interaction-tests
+        description: "Key user flows tested via integration tests (Testing Library). Tests interact as a user would, not via implementation details."
+        severity: critical

package/templates/web-react/structure.yaml

@@ -0,0 +1,46 @@
+tag: WEB-REACT
+section: structure
+language: typescript
+entries:
+  - path: src/app
+    type: directory
+    description: "App shell, providers, router config"
+  - path: src/app/App.tsx
+    type: file
+    description: "Root component with providers"
+  - path: src/app/router.tsx
+    type: file
+    description: "ALL routes defined here as config"
+  - path: src/app/providers
+    type: directory
+    description: "Context providers (auth, theme, i18n)"
+  - path: src/app/layouts
+    type: directory
+    description: "Layout components (sidebar, header, etc.)"
+  - path: src/features
+    type: directory
+    description: "Feature modules (self-contained)"
+  - path: src/shared/api
+    type: directory
+    description: "Centralized API client"
+  - path: src/shared/components
+    type: directory
+    description: "Reusable UI components (atoms, molecules)"
+  - path: src/shared/hooks
+    type: directory
+    description: "Shared hooks (useDebounce, useMediaQuery, etc.)"
+  - path: src/shared/config
+    type: directory
+    description: "Nav config, env access, constants"
+  - path: src/locales
+    type: directory
+    description: "i18n translation files"
+  - path: src/locales/en
+    type: directory
+    description: "English translations"
+  - path: src/styles
+    type: directory
+    description: "Global styles, theme, tokens"
+  - path: tests/e2e
+    type: directory
+    description: "Playwright tests"

package/templates/web-static/claude-md.yaml

@@ -0,0 +1,73 @@
+tag: WEB-STATIC
+section: claude-md
+blocks:
+  - id: static-site-architecture
+    tier: recommended
+    title: "Static Site Architecture"
+    content: |
+      ## Static Site & Jamstack Patterns
+
+      - Use Static Site Generation (SSG) as the default rendering strategy; reserve SSR or ISR only for pages requiring dynamic data at request time.
+      - Pre-render all content pages at build time. Ensure the build pipeline fails fast on broken links, missing assets, or template errors.
+      - Separate content from presentation: store structured content in Markdown, MDX, or a headless CMS, and consume it via build-time data fetching.
+      - Implement incremental builds where supported to keep build times under 60 seconds for content-heavy sites.
+      - Use content hashing for all emitted assets (JS, CSS, images) to enable aggressive, immutable caching (`Cache-Control: public, max-age=31536000, immutable`).
+      - Serve the site behind a CDN. Configure cache invalidation on deploy so users never see stale HTML entry points.
+      - Generate a `sitemap.xml` and `robots.txt` at build time. Include canonical URLs and Open Graph meta tags on every page.
+      - Keep JavaScript payload minimal. Audit bundle size on every PR; set a performance budget (e.g., < 100 KB compressed JS for the critical path).
+
+  - id: asset-optimization
+    tier: recommended
+    title: "Asset Optimization"
+    content: |
+      ## Asset Optimization & Performance
+
+      - Serve images in modern formats (WebP/AVIF) with `<picture>` fallbacks. Use responsive `srcset` and `sizes` attributes to deliver appropriately sized images.
+      - Inline critical CSS for above-the-fold content and defer non-critical stylesheets. Avoid render-blocking resources.
+      - Enable Brotli or gzip compression on the CDN/server for all text-based assets (HTML, CSS, JS, SVG, JSON).
+      - Lazy-load below-the-fold images and iframes using `loading="lazy"` or Intersection Observer.
+      - Preload key resources (`<link rel="preload">`) such as fonts and hero images. Use `font-display: swap` to prevent FOIT.
+      - Minimize third-party scripts. Load analytics and tracking asynchronously and after the main content is interactive.
+      - Run Lighthouse CI in the build pipeline; fail the build if performance score drops below the agreed threshold (e.g., 90).
+
+  - id: html-css-best-practices
+    tier: recommended
+    title: "HTML & CSS Best Practices"
+    content: |
+      ## HTML & CSS Quality Standards
+
+      - Write semantic HTML5 markup. Use `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, and `<footer>` to convey document structure.
+      - Ensure all pages pass WCAG 2.1 AA. Provide alt text for images, proper heading hierarchy, sufficient color contrast, and keyboard navigability.
+      - Use CSS custom properties (variables) for theming. Maintain a design-token file as the single source of truth for colors, spacing, and typography.
+      - Prefer utility-first or modular CSS methodologies (e.g., Tailwind, CSS Modules) to avoid specificity conflicts and dead CSS accumulation.
+      - Validate HTML output with the W3C validator in CI. Fix all errors; treat warnings as errors in new code.
+      - Support dark mode via `prefers-color-scheme` media query or a user-togglable theme that persists in `localStorage`.
+
+  - id: static-deployment
+    tier: recommended
+    title: "Static Site Deployment"
+    content: |
+      ## Static Site Deployment
+
+      ### Platforms
+      - **Netlify**: Git-push deploy, instant rollbacks, form handling, edge functions, split testing.
+        Free tier generous for static sites. Build plugins for Lighthouse, broken link detection.
+      - **Vercel**: Zero-config for Next.js/Astro/SvelteKit. Preview deployments per PR.
+      - **Cloudflare Pages**: Unlimited bandwidth, global edge network, Pages Functions for dynamic routes.
+      - **GitHub Pages**: Free for open-source. Limited (no server functions, no redirects file natively).
+        Suitable for docs sites and project landing pages only.
+      - **AWS S3 + CloudFront**: Maximum control, lowest cost at scale. Use `aws-cdk` or Terraform
+        to define the stack: S3 bucket (private) → CloudFront distribution → Route53 DNS → ACM cert.
+
+      ### Build Pipeline
+      - Build locally mirrors CI exactly (same Node version, same env vars). Use `.nvmrc` or `.node-version`.
+      - Build output is a static directory (`dist/`, `out/`, `public/`). No server process.
+      - Atomic deploys: new version fully uploaded before traffic switches. No partial states.
+      - Rollback = redeploy previous build artifact. Must complete in < 30 seconds.
+
+      ### Cache Strategy
+      - HTML: `Cache-Control: public, max-age=300, stale-while-revalidate=86400`.
+        Short-lived so deploys take effect quickly.
+      - Hashed assets (JS, CSS, images): `Cache-Control: public, max-age=31536000, immutable`.
+        Filename changes on content change — cache forever.
+      - Invalidate CDN cache on deploy (automatic on Netlify/Vercel/CF Pages; manual on CloudFront).

package/templates/web3/claude-md.yaml

@@ -0,0 +1,44 @@
+tag: WEB3
+section: claude-md
+blocks:
+  - id: smart-contract-patterns
+    tier: recommended
+    title: "Smart Contract Design"
+    content: |
+      ## Smart Contract Design Patterns
+
+      - Follow the Checks-Effects-Interactions pattern in every state-mutating function: validate inputs, update state, then make external calls. This prevents reentrancy attacks.
+      - Use the proxy pattern (UUPS or Transparent Proxy) for upgradeable contracts. Separate storage layout from logic, and never change the order of existing storage variables.
+      - Minimize on-chain storage. Store large data off-chain (IPFS, Arweave) and keep only content hashes on-chain for verification.
+      - Emit events for every significant state change. Events are the primary mechanism for off-chain indexers and UIs to track contract activity.
+      - Use OpenZeppelin's audited base contracts for standard functionality (ERC-20, ERC-721, ERC-1155, AccessControl, ReentrancyGuard) rather than writing from scratch.
+      - Implement access control with role-based patterns. Use multi-sig or timelocks for admin operations to prevent single points of compromise.
+      - Write comprehensive Solidity NatSpec comments for every public and external function, including `@param`, `@return`, and `@notice` tags.
+      - Target 100% branch coverage in contract tests. Test edge cases: zero values, max uint values, unauthorized callers, reentrancy attempts, and contract self-destruction scenarios.
+
+  - id: gas-optimization
+    tier: recommended
+    title: "Gas Optimization"
+    content: |
+      ## Gas Optimization Strategies
+
+      - Pack struct fields by size to minimize storage slots. Group `uint128` pairs, `bool` clusters, and `address` + smaller types into single 32-byte slots.
+      - Use `calldata` instead of `memory` for read-only function parameters in external functions to avoid unnecessary copying.
+      - Prefer mappings over arrays for lookups. If iteration is needed, maintain a separate array of keys alongside the mapping.
+      - Batch operations where possible: multi-transfer, batch minting, and batch approvals reduce per-transaction overhead.
+      - Use custom errors (`error InsufficientBalance(uint256 available, uint256 required)`) instead of `require` strings to save deployment and runtime gas.
+      - Cache storage variables in local `memory` or `stack` variables when accessed multiple times within a function.
+      - Profile gas usage in tests using Hardhat's gas reporter. Set gas budgets per function and fail CI if a change exceeds the budget.
+
+  - id: wallet-offchain
+    tier: recommended
+    title: "Wallet Integration & Off-Chain Patterns"
+    content: |
+      ## Wallet Integration & Off-Chain Architecture
+
+      - Support multiple wallet providers (MetaMask, WalletConnect, Coinbase Wallet) via a unified connector abstraction. Never hard-code a single provider.
+      - Handle chain switching and network mismatch gracefully. Prompt users to switch networks and display clear error messages for unsupported chains.
+      - Use EIP-712 typed structured data for off-chain signature requests so users can read and understand what they are signing.
+      - Implement an off-chain indexer (The Graph, custom) to serve query-heavy read operations. Never query the blockchain directly from the frontend for list or aggregate views.
+      - Design for L2 and multi-chain: abstract chain-specific logic behind an interface so the application can deploy to new chains without rewriting business logic.
+      - Validate all inputs on-chain even if they were validated off-chain. Off-chain validation is a UX convenience; on-chain validation is the security boundary.