forgecraft-mcp 0.1.0

package/templates/universal/nfr.yaml

@@ -0,0 +1,197 @@
+tag: UNIVERSAL
+section: nfr
+blocks:
+  - id: security
+    tier: core
+    title: "Security"
+    content: |
+      ## NFR: Security
+
+      ### Authentication & Authorization
+      - Authentication mechanism: {{auth_mechanism}}
+      - Authorization model: {{auth_model}}
+      - Secret management: environment variables minimum, secrets manager preferred (AWS SSM, Vault)
+      - No secrets in code, config files, or git history. Ever.
+
+      ### Input Validation
+      - Validate and sanitize ALL external input at system boundary.
+      - Use allowlists, not denylists.
+      - Parameterized queries only — no string concatenation for SQL/commands.
+
+      ### Dependencies
+      - Automated dependency vulnerability scanning (Dependabot, Snyk, or equivalent).
+      - No dependencies with known critical CVEs.
+      - Lock file committed (package-lock.json, poetry.lock, Cargo.lock).
+
+      ### Transport
+      - TLS 1.2+ for all network communication.
+      - HSTS headers on all web responses.
+      - CORS configured to minimum necessary origins.
+
+  - id: observability
+    tier: recommended
+    title: "Observability"
+    content: |
+      ## NFR: Observability
+
+      ### Structured Logging
+      - JSON-formatted structured logs (structlog for Python, pino for Node).
+      - Every log entry includes: timestamp, level, service, trace_id, operation, context.
+      - Log levels used correctly: DEBUG for development, INFO for operations, WARN for degraded
+        state, ERROR for failures requiring attention.
+      - NO sensitive data in logs (PHI, PII, credentials, tokens).
+
+      ### Metrics
+      - RED metrics on all service boundaries: Rate, Errors, Duration.
+      - Business metrics for key operations.
+      - Alerting thresholds defined for all critical metrics.
+
+      ### Health Checks
+      - /health endpoint returning: status, version, uptime, dependency health.
+      - Readiness vs liveness probes (Kubernetes) or equivalent.
+
+  - id: reliability
+    tier: recommended
+    title: "Reliability"
+    content: |
+      ## NFR: Reliability
+
+      ### Graceful Degradation
+      - Circuit breakers on all external service calls.
+      - Timeout configured on every external call (no indefinite waits).
+      - Fallback behavior defined for each dependency failure.
+
+      ### Disaster Recovery
+      - Backup strategy: automated, tested, documented.
+      - Runbook for common failure scenarios.
+      - **RPO** (Recovery Point Objective): maximum acceptable data loss = {{rpo | default: 1 hour}}.
+      - **RTO** (Recovery Time Objective): maximum acceptable downtime = {{rto | default: 4 hours}}.
+      - Failover tested at least quarterly. Document time-to-recovery in post-mortems.
+      - Database point-in-time recovery enabled. Retention: {{backup_retention | default: 30 days}}.
+
+      ### Availability Targets
+      - Target uptime: {{uptime_target | default: 99.9%}} (≈ 8.7 hours downtime/year).
+      - Define SLIs (error rate, latency p99, availability) and SLOs per service.
+      - Error budget policy: when budget is exhausted, freeze feature releases until reliability improves.
+      - Maintenance windows communicated 48h in advance. Prefer zero-downtime deployments.
+
+  - id: scalability
+    tier: optional
+    title: "Scalability"
+    content: |
+      ## NFR: Scalability
+
+      ### Horizontal Scaling
+      - Application designed for horizontal scaling — no in-process state that can't be lost.
+      - Session/cache state externalized to Redis, Memcached, or equivalent.
+      - Connection pooling configured per environment. Pool exhaustion triggers alerts, not failures.
+
+      ### Data Layer
+      - Database queries support the expected data volume. Test with 10x expected load.
+      - Pagination on all list operations. No unbounded queries.
+      - Read replicas for read-heavy workloads. Write/read split documented.
+      - Index strategy reviewed quarterly. Slow query log monitored.
+
+      ### Queue & Async Processing
+      - CPU-intensive or long-running work offloaded to background queues.
+      - Queue depth monitored. Auto-scale workers based on queue backlog.
+      - Dead letter queues for failed messages. Alert and review DLQ weekly.
+
+  - id: compliance
+    tier: optional
+    title: "Compliance & Data Governance"
+    content: |
+      ## NFR: Compliance & Data Governance
+
+      ### Data Classification
+      - All data fields classified: Public, Internal, Confidential, Restricted.
+      - Restricted data (PII, PHI, financial) encrypted at rest and in transit.
+      - Access to restricted data logged and auditable.
+
+      ### GDPR / Privacy
+      - Data processing purposes documented. No collection beyond stated purpose.
+      - Right to access: user can export their data in machine-readable format.
+      - Right to erasure: user data deletable within {{deletion_sla | default: 30 days}} of request.
+      - Data retention schedules defined per data type. Auto-delete expired data.
+      - Cookie consent where required. No tracking before consent.
+
+      ### Audit Trail
+      - Security-relevant actions logged: authentication events, permission changes,
+        data access, admin operations.
+      - Audit logs immutable, retained for {{audit_retention | default: 1 year}}.
+      - Logs stored separately from application data.
+
+  - id: accessibility
+    tier: optional
+    title: "Accessibility"
+    content: |
+      ## NFR: Accessibility
+
+      ### Standards
+      - Target: WCAG 2.1 AA compliance minimum for all user-facing interfaces.
+      - Semantic HTML. Proper heading hierarchy. ARIA attributes where HTML semantics aren't sufficient.
+      - All interactive elements keyboard-accessible. Visible focus indicators.
+      - Color contrast: minimum 4.5:1 for normal text, 3:1 for large text.
+
+      ### Testing
+      - Automated accessibility audit in CI (axe-core, Lighthouse accessibility).
+      - Screen reader testing for critical user journeys (at least quarterly).
+      - No images without alt text. No videos without captions.
+
+      ### Universal Design
+      - Support reduced motion (`prefers-reduced-motion`).
+      - Support high contrast mode.
+      - Touch targets minimum 44x44px on mobile interfaces.
+
+  - id: internationalization
+    tier: optional
+    title: "Internationalization"
+    content: |
+      ## NFR: Internationalization (i18n)
+
+      ### Text & Content
+      - All user-facing text externalized to translation files from day one.
+      - No hardcoded strings in UI code. No string concatenation for translatable sentences.
+      - Translation keys namespaced by feature: `module.component.label`.
+
+      ### Formatting
+      - Dates, numbers, currencies formatted via `Intl` API or equivalent — never manual formatting.
+      - Time zones handled correctly. Store UTC, display in user's local zone.
+      - Support RTL layouts if right-to-left languages are in scope.
+
+      ### Workflow
+      - New strings automatically flagged for translation in CI.
+      - Missing translations fall back to default locale, never show raw keys to users.
+
+  - id: maintainability
+    tier: recommended
+    title: "Maintainability & Developer Experience"
+    content: |
+      ## NFR: Maintainability & Developer Experience
+
+      ### Onboarding
+      - New developer productive within 1 day: clone → install → run → make a change → test → commit.
+      - README.md with step-by-step local setup.
+      - .env.example with every variable documented.
+
+      ### Code Quality Metrics
+      - Cyclomatic complexity: flag functions > 10, block > 15.
+      - Dead code detection.
+      - Documentation coverage: all public APIs have docstrings/JSDoc.
+
+      ### Technical Debt Tracking
+      - Tech debt items logged in Status.md.
+      - No "we'll fix it later" without a tracked item.
+
+  - id: cost-management
+    tier: optional
+    title: "Cost Management"
+    content: |
+      ## NFR: Cost Management
+
+      ### Resource Budgets
+      - Monthly cloud spend budget defined and alerted at 80% threshold.
+      - Cost per user/transaction tracked as a business KPI.
+
+      ### Optimization Cadence
+      - Monthly: review top 5 cost drivers, identify optimization opportunities.

package/templates/universal/review.yaml

@@ -0,0 +1,164 @@
+tag: UNIVERSAL
+section: review
+blocks:
+  - id: architecture-review
+    tier: core
+    dimension: architecture
+    title: "Architecture Review"
+    description: |
+      Evaluate the system's structural integrity, coupling, and scalability.
+      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)."
+        severity: critical
+      - id: dependency-graph
+        description: "Dependency graph is acyclic. No circular imports between modules."
+        severity: critical
+      - id: layer-violations
+        description: "No layer violations — dependencies point downward only. Handlers never import from infrastructure."
+        severity: critical
+      - id: coupling-concerns
+        description: "Modules communicate through interfaces, not concrete implementations."
+        severity: important
+      - id: data-flow
+        description: "Data flow patterns are clear and documented. No hidden side channels."
+        severity: important
+      - id: single-point-of-failure
+        description: "No single points of failure in critical paths. External calls have timeouts and fallbacks."
+        severity: important
+      - id: security-boundaries
+        description: "Auth, data access, and API boundaries are explicitly defined and enforced."
+        severity: critical
+      - id: hexagonal-ports
+        description: "Port interfaces (Repository, Gateway) defined in the domain layer, implemented by adapters. Adapters are swappable."
+        severity: important
+      - id: dto-boundaries
+        description: "DTOs used at layer boundaries. Domain entities never leaked to API responses or persisted directly."
+        severity: important
+      - id: bounded-contexts
+        description: "If multiple domains exist, each has its own bounded context with separate models. No shared DB tables across contexts."
+        severity: important
+      - id: domain-events-decoupling
+        description: "Cross-module communication uses domain events or defined interfaces — no direct imports between unrelated modules."
+        severity: nice-to-have
+
+  - id: code-quality-review
+    tier: core
+    dimension: code-quality
+    title: "Code Quality Review"
+    description: |
+      Evaluate code organization, DRY compliance, error handling, and technical debt.
+      Flag repetition aggressively. Call out missing edge cases explicitly.
+    checklist:
+      - id: module-structure
+        description: "Code is organized by feature, not by layer. Each module owns its models, service, and types."
+        severity: critical
+      - id: dry-violations
+        description: "No duplicated logic across modules. Shared utilities extracted to shared/."
+        severity: important
+      - id: error-handling-patterns
+        description: "Custom error hierarchy used consistently. No bare Error throws. Errors carry context (IDs, timestamps, operation)."
+        severity: critical
+      - id: missing-edge-cases
+        description: "Edge cases handled: empty inputs, null/undefined, boundary values, concurrent access."
+        severity: important
+      - id: technical-debt
+        description: "No TODO/FIXME without a tracked item. No commented-out code."
+        severity: important
+      - id: naming-quality
+        description: "All names are intention-revealing. No abbreviations except universally understood ones (id, url, http)."
+        severity: nice-to-have
+      - id: over-under-engineering
+        description: "Code is 'engineered enough' — no premature abstractions, no fragile shortcuts."
+        severity: important
+      - id: cqs-compliance
+        description: "Functions either change state (command) or return data (query), not both. Exceptions are documented."
+        severity: important
+      - id: guard-clauses
+        description: "No deep nesting. Invalid cases handled first with early returns. Happy path runs at shallowest indentation."
+        severity: important
+      - id: composition-over-inheritance
+        description: "Prefer composition via interfaces and delegation. Class inheritance used only for genuine is-a relationships."
+        severity: important
+      - id: law-of-demeter
+        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."
+        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."
+        severity: important
+      - id: primitive-obsession
+        description: "Domain concepts wrapped in typed Value Objects (EmailAddress, Money) instead of raw strings/numbers."
+        severity: nice-to-have
+
+  - id: test-review
+    tier: recommended
+    dimension: tests
+    title: "Test Review"
+    description: |
+      Evaluate test coverage, assertion quality, and edge case thoroughness.
+      Well-tested code is non-negotiable. Rather too many tests than too few.
+    checklist:
+      - id: coverage-gaps
+        description: "Minimum 80% line coverage overall. 90% on new/changed code. 95% on critical paths."
+        severity: critical
+      - id: test-pyramid
+        description: "Test distribution follows pyramid: 60-75% unit, 20-30% integration, 5-10% E2E."
+        severity: important
+      - id: assertion-strength
+        description: "Assertions are specific and meaningful. No assert(true), no empty catch blocks, no tests that can't fail."
+        severity: critical
+      - id: edge-case-coverage
+        description: "Tests cover edge cases: empty collections, boundary values, error paths, concurrent scenarios."
+        severity: important
+      - id: test-naming
+        description: "Every test name is a specification: 'rejects_unknown_tag' not 'test_validation'."
+        severity: nice-to-have
+      - id: failure-modes
+        description: "Failure modes and error paths are tested, not just happy paths."
+        severity: critical
+      - id: test-isolation
+        description: "Tests are independent — no shared mutable state, no order dependencies. Each test sets up its own data."
+        severity: important
+      - id: test-data-builders
+        description: "Test data constructed via factories/builders, not copy-pasted literals. Shared fixtures for common objects."
+        severity: nice-to-have
+
+  - id: performance-review
+    tier: recommended
+    dimension: performance
+    title: "Performance Review"
+    description: |
+      Evaluate query patterns, memory usage, caching opportunities, and algorithmic complexity.
+      Focus on measurable bottlenecks, not micro-optimizations.
+    checklist:
+      - id: n-plus-one
+        description: "No N+1 query or I/O patterns. Batch operations where possible."
+        severity: critical
+      - id: memory-usage
+        description: "No unbounded collections or memory leaks. Large data sets streamed, not loaded in full."
+        severity: important
+      - id: caching
+        description: "Repeated expensive operations have caching. Cache invalidation strategy documented."
+        severity: nice-to-have
+      - id: algorithmic-complexity
+        description: "No O(n²) or worse algorithms on unbounded data. Complexity documented for non-obvious paths."
+        severity: important
+      - id: startup-time
+        description: "Application startup is fast. Heavy initialization is lazy or async."
+        severity: nice-to-have
+      - id: graceful-shutdown
+        description: "Application handles SIGTERM/SIGINT gracefully: drains connections, finishes in-flight work, then exits."
+        severity: important
+      - id: ci-pipeline
+        description: "CI pipeline runs lint, type-check, tests, and build on every push. Failures block merge."
+        severity: critical
+      - id: deployment-automation
+        description: "Deploy is one command or one button. No multi-step manual runbooks. Rollback is equally simple."
+        severity: important
+      - id: environment-parity
+        description: "Staging mirrors production: same provider, same DB engine, same services. No 'works on staging' surprises."
+        severity: important

package/templates/universal/structure.yaml

@@ -0,0 +1,52 @@
+tag: UNIVERSAL
+section: structure
+language: both
+entries:
+  - path: CLAUDE.md
+    type: file
+    description: "CC persistent instruction set"
+  - path: Status.md
+    type: file
+    description: "Session bridge — updated every session"
+  - path: .env.example
+    type: file
+    description: "All required env vars documented"
+  - path: .claude/hooks
+    type: directory
+    description: "Git quality gate scripts"
+  - path: docs
+    type: directory
+    description: "PRD, Tech Spec, ADRs"
+  - path: docs/PRD.md
+    type: file
+    description: "Product requirements document"
+  - path: docs/TechSpec.md
+    type: file
+    description: "Technical specification"
+  - path: docs/adr
+    type: directory
+    description: "Architecture Decision Records"
+  - path: scripts
+    type: directory
+    description: "Project utility scripts"
+  - path: src
+    type: directory
+    description: "Application source code"
+  - path: src/shared/config
+    type: directory
+    description: "Env validation, fail-fast on startup"
+  - path: src/shared/exceptions
+    type: directory
+    description: "Base exception hierarchy"
+  - path: src/shared/logging
+    type: directory
+    description: "Structured logging setup"
+  - path: tests
+    type: directory
+    description: "Test suites"
+  - path: tests/unit
+    type: directory
+    description: "Unit tests"
+  - path: tests/integration
+    type: directory
+    description: "Integration tests"

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

@@ -0,0 +1,110 @@
+tag: WEB-REACT
+section: claude-md
+blocks:
+  - id: react-component-architecture
+    tier: recommended
+    title: "React Component Architecture"
+    content: |
+      ## React & Frontend Standards
+
+      ### Component Architecture
+      - Atomic Design: atoms → molecules → organisms → templates → pages.
+      - Components are pure UI. No API calls, no business logic, no direct state management.
+      - Container/Presenter split: containers fetch data, presenters render UI.
+      - All components must have TypeScript props interfaces. No `any` types.
+      - No inline styles. Use CSS modules, Tailwind, or styled-components consistently.
+
+  - id: react-state-management
+    tier: recommended
+    title: "State Management"
+    content: |
+      ### State Management
+      - Local state (useState) for UI-only state (open/closed, hover, form inputs).
+      - Shared state via context or state library ONLY when 3+ components need the same data.
+      - Server state via React Query / TanStack Query / SWR — NEVER manually cache API responses.
+      - No prop drilling beyond 2 levels. Use composition (children) or context.
+
+  - id: react-i18n
+    tier: recommended
+    title: "Internationalization (i18n)"
+    content: |
+      ### Internationalization — From Day One
+      - EVERY user-facing string goes through the i18n system. No hardcoded display text.
+      - Use react-i18next or next-intl.
+      - Translation keys namespaced by feature: `members.table.header.name`.
+      - Date, number, currency formatting via Intl API — never manual formatting.
+
+  - id: react-forms
+    tier: recommended
+    title: "Forms"
+    content: |
+      ### Forms
+      - Use a form library (React Hook Form or Formik). No manual onChange handlers per field.
+      - Validation schema defined separately (Zod, Yup) and shared with backend if possible.
+      - All forms must handle: loading state, validation errors, submission errors, success feedback.
+
+  - id: react-api-integration
+    tier: recommended
+    title: "API Integration"
+    content: |
+      ### API Integration
+      - All API calls go through a centralized API client module.
+      - API client handles: auth headers, base URL from config, error transformation, retry logic.
+      - Use React Query for all server state.
+
+  - id: react-accessibility
+    tier: recommended
+    title: "Accessibility (a11y)"
+    content: |
+      ### Accessibility (a11y) — Non-Negotiable
+      - Semantic HTML elements (nav, main, section, article, button — not div for everything).
+      - All interactive elements keyboard-accessible. All images have alt text.
+      - ARIA labels on non-obvious interactive elements.
+      - Color contrast minimum AA (4.5:1 for text).
+
+  - id: react-error-boundaries
+    tier: recommended
+    title: "Error Handling & Suspense"
+    content: |
+      ### Error Boundaries
+      - Wrap feature areas in Error Boundaries — a crash in one widget must not take down the page.
+      - Error boundaries display user-friendly fallback UI with retry action.
+      - Log caught errors to monitoring service (Sentry, DataDog, etc.).
+      - Never catch errors silently — always report and show feedback.
+
+      ### Suspense & Loading States
+      - Use React Suspense for code-split components and async data.
+      - Every async operation has three states: loading, success, error. No blank screens.
+      - Skeleton loaders preferred over spinners for layout stability (reduces CLS).
+      - Optimistic updates for user-driven mutations (like/unlike, form submit).
+
+  - id: react-deployment
+    tier: recommended
+    title: "React Deployment & Hosting"
+    content: |
+      ## Frontend Deployment
+
+      ### Platform Selection
+      - **Vercel**: First choice for Next.js. Zero-config deploys, edge functions, image optimization built in.
+        ISR / on-demand revalidation works natively. Preview deployments on every PR.
+      - **Netlify**: Great for static + serverless. Form handling, edge functions, split testing built in.
+        Works well with Gatsby, Astro, plain React (via adapter).
+      - **Cloudflare Pages**: Unlimited bandwidth, global edge. Best for static or Pages Functions.
+      - **AWS Amplify / S3+CloudFront**: Full control, lower cost at scale. More ops overhead.
+      - Self-hosted Docker: only when platform restrictions require it.
+
+      ### Build & Deploy
+      - CI builds produce a static bundle (`dist/` or `.next/`). Same bundle deploys to staging then prod.
+      - Preview deployments for every PR — URL posted in PR comments for stakeholder review.
+      - Environment variables injected at build time (`NEXT_PUBLIC_*`, `VITE_*`). No secrets in client bundles.
+      - Build cache enabled (Turborepo, Nx, or platform-native). Target < 2 min builds.
+
+      ### Performance Budgets
+      - JavaScript budget: < {{js_budget_kb | default: 200}} KB compressed for initial load.
+      - Lighthouse CI in pipeline. Fail build if performance score drops below {{lighthouse_min | default: 90}}.
+      - Monitor Core Web Vitals in production (Vercel Analytics, web-vitals library, or RUM).
+
+      ### Edge & CDN
+      - Static assets served from CDN with immutable cache headers (content-hashed filenames).
+      - HTML entry point: short cache (5 min) or stale-while-revalidate.
+      - Use edge middleware for: redirects, A/B testing, geo-routing, auth checks (avoid full round-trip).

package/templates/web-react/hooks.yaml

@@ -0,0 +1,44 @@
+tag: WEB-REACT
+section: hooks
+hooks:
+  - name: i18n-enforcement
+    trigger: pre-commit
+    description: "Scan JSX/TSX for hardcoded user-facing strings not wrapped in t()"
+    filename: pre-commit-i18n.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Find string literals in JSX that aren't in t() calls, className, data-testid, etc.
+        if grep -nE '>\s*[A-Z][a-z]+(\s+[a-z]+)+\s*<' "$file" | grep -vE '(className|data-testid|aria-|console\.)' > /tmp/i18n_violations 2>/dev/null; then
+          if [ -s /tmp/i18n_violations ]; then
+            echo "  ⚠️  $file — possible untranslated string:"
+            cat /tmp/i18n_violations | head -3
+            VIOLATIONS=$((VIOLATIONS + 1))
+          fi
+        fi
+      done
+      rm -f /tmp/i18n_violations
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo "⚠️  $VIOLATIONS file(s) may have untranslated strings. Use t() wrapper."
+      fi
+
+  - name: a11y-lint
+    trigger: pre-commit
+    description: "Run accessibility checks on staged JSX/TSX files"
+    filename: pre-commit-a11y.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      # Check for div used as button without role
+      for file in $STAGED; do
+        if grep -nE '<div\s+onClick' "$file" | grep -v 'role=' > /tmp/a11y_violations 2>/dev/null; then
+          if [ -s /tmp/a11y_violations ]; then
+            echo "  ⚠️  $file — clickable div without role attribute. Use <button> or add role=\"button\""
+          fi
+        fi
+      done
+      rm -f /tmp/a11y_violations

package/templates/web-react/nfr.yaml

@@ -0,0 +1,27 @@
+tag: WEB-REACT
+section: nfr
+blocks:
+  - id: frontend-performance
+    tier: recommended
+    title: "Frontend Performance"
+    content: |
+      ## NFR: Frontend Performance
+
+      ### Core Web Vitals Targets
+      - LCP (Largest Contentful Paint): < 2.5s
+      - FID (First Input Delay): < 100ms
+      - CLS (Cumulative Layout Shift): < 0.1
+
+      ### Bundle
+      - Code splitting by route. No single bundle > 200KB gzipped.
+      - Tree shaking enabled. No unused exports.
+      - Bundle size tracked in CI — PRs that increase bundle > 10KB require justification.
+
+      ### Runtime
+      - Virtual/windowed lists for collections > 50 items.
+      - Debounce search inputs (300ms minimum).
+
+      ### Assets
+      - Images in modern formats (WebP/AVIF with fallback).
+      - Responsive images with srcset.
+      - Fonts preloaded, display:swap.