forgecraft-mcp 1.2.0 → 1.3.2

package/templates/web-react/review.yaml

@@ -1,94 +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
+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

@@ -1,46 +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"
+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-react/verification.yaml

@@ -1,126 +1,126 @@
-tag: WEB-REACT
-section: verification
-title: "Behavioral Navigation Verification"
-description: >
-  UI behavior cannot be verified by type checks or unit tests alone. Correct
-  behavior means: the right elements are visible at the right URLs, interactions
-  produce the right state transitions, and the UI matches the design spec visually.
-  This strategy uses Playwright for navigational path execution and Claude Vision
-  for visual contract assertion — closing the behavioral uncertainty dimension.
-uncertainty_levels:
-  - behavioral
-completeness_ceiling: 0.85
-
-phases:
-
-  - id: contract-definition
-    title: "Define Navigation Contracts and Visual Expectations"
-    rationale: >
-      A behavioral contract is a precise description of: which URL renders which component,
-      which user actions trigger which state transitions, and what the page looks like at
-      each checkpoint. Without explicit contracts, visual regressions and interaction bugs
-      are invisible to the automated verify loop.
-    steps:
-      - id: define-use-case-paths
-        instruction: >
-          For every user-facing feature, write a use-case navigational path as a numbered list:
-          1. Starting URL and initial state
-          2. Each user action (click, fill, submit, navigate) in order
-          3. Expected URL and visible DOM elements after each action
-          4. Terminal state (e.g., "success toast visible, redirect to /dashboard")
-          Store in docs/use-cases/{feature}.md. Minimum one path per route group.
-        contract: >
-          docs/use-cases/ directory exists with one file per feature.
-          Each file has a numbered step list with URL, action, and assertion per step.
-        tools: ["filesystem"]
-        expected_output: "docs/use-cases/auth.md, docs/use-cases/articles.md, etc."
-        pass_criterion: "File count in docs/use-cases/ ≥ number of route groups"
-
-      - id: define-visual-snapshots
-        instruction: >
-          For every major page state (empty state, loaded state, error state), define a
-          visual expectation in plain English that Claude Vision can assert against a screenshot:
-          e.g., "The navbar shows the user avatar. The feed contains at least one article card.
-          The sidebar is absent on mobile viewport."
-          Store expectations in docs/visual-contracts/{page}.md.
-        contract: >
-          docs/visual-contracts/ exists. Each file lists named states with prose
-          visual expectations that are unambiguous.
-        tools: ["filesystem"]
-        expected_output: "docs/visual-contracts/feed.md with 'loaded_state', 'empty_state', 'error_state' sections"
-        pass_criterion: "File count in docs/visual-contracts/ ≥ number of pages"
-
-  - id: execution
-    title: "Run Playwright Paths + Claude Vision Assertions"
-    rationale: >
-      Playwright drives the browser headlessly and captures screenshots at each checkpoint.
-      Claude Vision asserts the screenshot against the visual contract — this is the only
-      technique that catches layout breakage, missing elements, and wrong copy in one pass.
-    steps:
-      - id: run-playwright-navigation
-        instruction: >
-          For each use-case path in docs/use-cases/, write a Playwright test that:
-          1. Navigates to the starting URL
-          2. Executes each action in the numbered list
-          3. Takes a screenshot after every state transition
-          4. Asserts on DOM elements cited in the contract (getByRole, getByText, toBeVisible)
-          Run with `npx playwright test` in headless mode.
-        contract: >
-          Playwright test file exists per use-case. All DOM assertions in the contract
-          are expressed as Playwright locators. Test run exits 0.
-        tools: ["npx playwright test", "npx playwright codegen"]
-        expected_output: "Playwright HTML report + screenshots in test-results/playwright/"
-        pass_criterion: "playwright test exits 0; 0 failing tests"
-
-      - id: assert-screenshots-with-vision
-        instruction: >
-          For each screenshot taken by Playwright, call Claude Vision with:
-          - The screenshot file path
-          - The visual contract from docs/visual-contracts/{page}.md for that state
-          - The prompt: "Assert this screenshot against the following visual contract.
-            List every contract item that FAILS. If all items pass, respond: PASS."
-          Record the response. Any response other than PASS is a failure.
-        contract: >
-          Every screenshot has a corresponding vision assertion result.
-          All results are PASS for the final verify loop iteration.
-        tools: ["claude --vision", "anthropic vision API", "openai vision API"]
-        expected_output: "vision-assertions.json: [{screenshot, contract_state, result: PASS|FAIL, failures: [...]}]"
-        pass_criterion: "All vision assertion results = PASS"
-        requires_human_review: true
-
-      - id: run-accessibility-check
-        instruction: >
-          Run axe-core or @axe-core/playwright on every page visited.
-          Zero critical or serious violations are allowed.
-          Document all moderate violations for backlog.
-        contract: "0 critical or serious axe violations on any page"
-        tools: ["@axe-core/playwright", "axe-core"]
-        expected_output: "axe-report.json per page with violations array"
-        pass_criterion: "critical + serious violation count = 0 across all pages"
-
-  - id: evidence
-    title: "Persist Screenshots, Vision Results, and Traces"
-    rationale: >
-      Screenshots and vision assertion results are the ground truth for behavioral
-      verification. They must be persisted so regressions are detectable across
-      Playwright test runs, CI runs, and GS loop passes.
-    steps:
-      - id: persist-playwright-report
-        instruction: >
-          Save Playwright HTML report to test-results/playwright/index.html.
-          Save all screenshots to test-results/playwright/screenshots/{test-name}/{step}.png.
-          On failure, save the Playwright trace zip for each failing test.
-        contract: "test-results/playwright/ exists with report and screenshots"
-        tools: ["playwright --reporter=html"]
-        expected_output: "HTML report + PNG per checkpoint + trace.zip on failure"
-        pass_criterion: "test-results/playwright/index.html exists"
-
-      - id: persist-vision-assertions
-        instruction: >
-          Save vision-assertions.json to test-results/vision-assertions.json.
-          Summary: total assertions, pass count, fail count, list of failed contracts.
-          If any assertion fails, the FAIL details become the fix prompt input for next pass.
-        contract: "vision-assertions.json exists with integer pass and fail counts"
-        tools: ["jq", "node"]
-        expected_output: '{"total": 12, "passed": 11, "failed": 1, "failures": [...]}'
-        pass_criterion: "File parses; failed count = 0 for strategy to be complete"
+tag: WEB-REACT
+section: verification
+title: "Behavioral Navigation Verification"
+description: >
+  UI behavior cannot be verified by type checks or unit tests alone. Correct
+  behavior means: the right elements are visible at the right URLs, interactions
+  produce the right state transitions, and the UI matches the design spec visually.
+  This strategy uses Playwright for navigational path execution and Claude Vision
+  for visual contract assertion — closing the behavioral uncertainty dimension.
+uncertainty_levels:
+  - behavioral
+completeness_ceiling: 0.85
+
+phases:
+
+  - id: contract-definition
+    title: "Define Navigation Contracts and Visual Expectations"
+    rationale: >
+      A behavioral contract is a precise description of: which URL renders which component,
+      which user actions trigger which state transitions, and what the page looks like at
+      each checkpoint. Without explicit contracts, visual regressions and interaction bugs
+      are invisible to the automated verify loop.
+    steps:
+      - id: define-use-case-paths
+        instruction: >
+          For every user-facing feature, write a use-case navigational path as a numbered list:
+          1. Starting URL and initial state
+          2. Each user action (click, fill, submit, navigate) in order
+          3. Expected URL and visible DOM elements after each action
+          4. Terminal state (e.g., "success toast visible, redirect to /dashboard")
+          Store in docs/use-cases/{feature}.md. Minimum one path per route group.
+        contract: >
+          docs/use-cases/ directory exists with one file per feature.
+          Each file has a numbered step list with URL, action, and assertion per step.
+        tools: ["filesystem"]
+        expected_output: "docs/use-cases/auth.md, docs/use-cases/articles.md, etc."
+        pass_criterion: "File count in docs/use-cases/ ≥ number of route groups"
+
+      - id: define-visual-snapshots
+        instruction: >
+          For every major page state (empty state, loaded state, error state), define a
+          visual expectation in plain English that Claude Vision can assert against a screenshot:
+          e.g., "The navbar shows the user avatar. The feed contains at least one article card.
+          The sidebar is absent on mobile viewport."
+          Store expectations in docs/visual-contracts/{page}.md.
+        contract: >
+          docs/visual-contracts/ exists. Each file lists named states with prose
+          visual expectations that are unambiguous.
+        tools: ["filesystem"]
+        expected_output: "docs/visual-contracts/feed.md with 'loaded_state', 'empty_state', 'error_state' sections"
+        pass_criterion: "File count in docs/visual-contracts/ ≥ number of pages"
+
+  - id: execution
+    title: "Run Playwright Paths + Claude Vision Assertions"
+    rationale: >
+      Playwright drives the browser headlessly and captures screenshots at each checkpoint.
+      Claude Vision asserts the screenshot against the visual contract — this is the only
+      technique that catches layout breakage, missing elements, and wrong copy in one pass.
+    steps:
+      - id: run-playwright-navigation
+        instruction: >
+          For each use-case path in docs/use-cases/, write a Playwright test that:
+          1. Navigates to the starting URL
+          2. Executes each action in the numbered list
+          3. Takes a screenshot after every state transition
+          4. Asserts on DOM elements cited in the contract (getByRole, getByText, toBeVisible)
+          Run with `npx playwright test` in headless mode.
+        contract: >
+          Playwright test file exists per use-case. All DOM assertions in the contract
+          are expressed as Playwright locators. Test run exits 0.
+        tools: ["npx playwright test", "npx playwright codegen"]
+        expected_output: "Playwright HTML report + screenshots in test-results/playwright/"
+        pass_criterion: "playwright test exits 0; 0 failing tests"
+
+      - id: assert-screenshots-with-vision
+        instruction: >
+          For each screenshot taken by Playwright, call Claude Vision with:
+          - The screenshot file path
+          - The visual contract from docs/visual-contracts/{page}.md for that state
+          - The prompt: "Assert this screenshot against the following visual contract.
+            List every contract item that FAILS. If all items pass, respond: PASS."
+          Record the response. Any response other than PASS is a failure.
+        contract: >
+          Every screenshot has a corresponding vision assertion result.
+          All results are PASS for the final verify loop iteration.
+        tools: ["claude --vision", "anthropic vision API", "openai vision API"]
+        expected_output: "vision-assertions.json: [{screenshot, contract_state, result: PASS|FAIL, failures: [...]}]"
+        pass_criterion: "All vision assertion results = PASS"
+        requires_human_review: true
+
+      - id: run-accessibility-check
+        instruction: >
+          Run axe-core or @axe-core/playwright on every page visited.
+          Zero critical or serious violations are allowed.
+          Document all moderate violations for backlog.
+        contract: "0 critical or serious axe violations on any page"
+        tools: ["@axe-core/playwright", "axe-core"]
+        expected_output: "axe-report.json per page with violations array"
+        pass_criterion: "critical + serious violation count = 0 across all pages"
+
+  - id: evidence
+    title: "Persist Screenshots, Vision Results, and Traces"
+    rationale: >
+      Screenshots and vision assertion results are the ground truth for behavioral
+      verification. They must be persisted so regressions are detectable across
+      Playwright test runs, CI runs, and GS loop passes.
+    steps:
+      - id: persist-playwright-report
+        instruction: >
+          Save Playwright HTML report to test-results/playwright/index.html.
+          Save all screenshots to test-results/playwright/screenshots/{test-name}/{step}.png.
+          On failure, save the Playwright trace zip for each failing test.
+        contract: "test-results/playwright/ exists with report and screenshots"
+        tools: ["playwright --reporter=html"]
+        expected_output: "HTML report + PNG per checkpoint + trace.zip on failure"
+        pass_criterion: "test-results/playwright/index.html exists"
+
+      - id: persist-vision-assertions
+        instruction: >
+          Save vision-assertions.json to test-results/vision-assertions.json.
+          Summary: total assertions, pass count, fail count, list of failed contracts.
+          If any assertion fails, the FAIL details become the fix prompt input for next pass.
+        contract: "vision-assertions.json exists with integer pass and fail counts"
+        tools: ["jq", "node"]
+        expected_output: '{"total": 12, "passed": 11, "failed": 1, "failures": [...]}'
+        pass_criterion: "File parses; failed count = 0 for strategy to be complete"