forgecraft-mcp 0.1.0

package/templates/universal/claude-md.yaml

@@ -0,0 +1,477 @@
+tag: UNIVERSAL
+section: claude-md
+blocks:
+  - id: project-identity
+    tier: core
+    title: "Project Identity"
+    content: |
+      ## Project Identity
+      - **Repo**: {{repo_url}}
+      - **Primary Language**: {{language}}
+      - **Framework**: {{framework}}
+      - **Domain**: {{domain}}
+      - **Sensitive Data**: {{sensitive_data}}
+      - **Project Tags**: {{tags}}
+
+  - id: code-standards
+    tier: core
+    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 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.
+      - 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.
+      - No abbreviations in names except universally understood ones (id, url, http, db, api).
+      - All names must be intention-revealing. If you need a comment to explain what a variable
+        holds, the name is wrong.
+
+  - id: production-code-standards
+    tier: core
+    title: "Production Code Standards"
+    content: |
+      ## Production Code Standards — NON-NEGOTIABLE
+
+      These apply to ALL code including prototypes. "It's just a prototype" is never a valid
+      exception. Prototypes become production code within days at CC development speed.
+
+      ### SOLID Principles
+      - **Single Responsibility**: One module = one reason to change. Use "and" to describe it? Split it.
+      - **Open/Closed**: Extend via interfaces and composition. Never modify working code for new behavior.
+      - **Liskov Substitution**: Any interface implementation must be fully swappable. No isinstance checks.
+      - **Interface Segregation**: Small focused interfaces. No god-interfaces.
+      - **Dependency Inversion**: Depend on abstractions. Concrete classes are injected, never instantiated
+        inside business logic.
+
+      ### Zero Hardcoded Values
+      - ALL configuration through environment variables or config files. No exceptions.
+      - ALL external URLs, ports, credentials, thresholds, feature flags must be configurable.
+      - ALL magic numbers must be named constants with documentation.
+      - Config is validated at startup — fail fast if required values are missing.
+
+      ### Zero Mocks in Application Code
+      - No mock objects, fake data, or stub responses in source code. Ever.
+      - Mocks belong ONLY in test files.
+      - For local dev: create proper interface implementations selected via config.
+      - No `if DEBUG: return fake_data` patterns. Use dependency injection to swap implementations.
+      - No TODO/FIXME stubs returning hardcoded values. Use NotImplementedError with a description.
+
+      ### Interfaces First
+      Before writing any implementation:
+      1. Define the interface/protocol/abstract class
+      2. Define the data contracts (input/output DTOs)
+      3. Write the consuming code against the interface
+      4. Write tests against the interface
+      5. THEN implement the concrete class
+
+      ### Dependency Injection
+      - Every service receives dependencies through its constructor.
+      - A composition root (main.py / app.ts / container) wires everything.
+      - No service locator pattern. No global singletons. No module-level instances.
+
+      ### Error Handling
+      - Custom exception hierarchy per module. No bare Exception raises.
+      - Errors carry context: IDs, timestamps, operation names.
+      - Fail fast, fail loud. No silent swallowing of exceptions.
+      - Domain code never returns HTTP status codes — that's the API layer's job.
+
+      ### 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.
+
+  - id: layered-architecture
+    tier: recommended
+    title: "Layered Architecture"
+    content: |
+      ## Layered Architecture (Ports & Adapters / Hexagonal)
+
+      ```
+      ┌─────────────────────────────┐
+      │  API / CLI / Event Handlers │  ← Thin. Validation + delegation only. No logic.
+      ├─────────────────────────────┤     These are DRIVING ADAPTERS (primary).
+      │  Services (Business Logic)  │  ← Orchestration. Depends on PORT INTERFACES only.
+      ├─────────────────────────────┤
+      │  Domain Models              │  ← Pure data + behavior. No I/O. No framework imports.
+      │  (Entities, Value Objects)  │     The inner hexagon. Zero external dependencies.
+      ├─────────────────────────────┤
+      │  Port Interfaces            │  ← Abstract contracts (Repository, Gateway, Notifier).
+      │                             │     Defined by the domain, implemented by adapters.
+      ├─────────────────────────────┤
+      │  Repositories / Adapters    │  ← DRIVEN ADAPTERS (secondary). All external I/O
+      │                             │     (DB, APIs, files, queues, email, caches).
+      ├─────────────────────────────┤
+      │  Infrastructure / Config    │  ← DI container, env config, connection factories
+      └─────────────────────────────┘
+      ```
+
+      ### Ports (Interfaces owned by the domain)
+      - **Repository ports**: `UserRepository`, `OrderRepository` — data persistence contracts.
+      - **Gateway ports**: `PaymentGateway`, `EmailSender` — external service contracts.
+      - Ports are defined in the domain/service layer, never in the adapter layer.
+      - Port interfaces specify WHAT, never HOW.
+
+      ### Adapters (Implementations of ports)
+      - **Driving adapters** (primary): HTTP controllers, CLI handlers, message consumers
+        — they CALL the application through port interfaces.
+      - **Driven adapters** (secondary): PostgresUserRepository, StripePaymentGateway,
+        SESEmailSender — they ARE CALLED BY the application through port interfaces.
+      - Adapters are interchangeable. Swap `PostgresUserRepository` for `InMemoryUserRepository`
+        in tests without changing a single line of business logic.
+
+      ### 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).
+      - **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.
+
+      ### Layer Rules
+      - Never skip layers. API handlers do not call repositories directly.
+      - Dependencies point INWARD only. Inner layers never import from outer layers.
+      - Domain models have ZERO external dependencies.
+      - The domain layer does not know HTTP, SQL, or any framework exists.
+
+  - id: clean-code-principles
+    tier: recommended
+    title: "Clean Code Principles"
+    content: |
+      ## Clean Code Principles
+
+      ### Command-Query Separation (CQS)
+      - **Commands** change state but return nothing (void).
+      - **Queries** return data but change nothing (no side effects).
+      - A function should do one or the other, never both.
+      - Exception: stack.pop() style operations where separation is impractical — document why.
+
+      ### Guard Clauses & Early Return
+      - Eliminate deep nesting. Handle invalid cases first, return early.
+      - The happy path runs at the shallowest indentation level.
+      - Before:
+        ```
+        if (user) {
+          if (user.isActive) {
+            if (user.hasPermission) {
+              // actual logic buried 3 levels deep
+        ```
+      - After:
+        ```
+        if (!user) throw new NotFoundError(...);
+        if (!user.isActive) throw new InactiveError(...);
+        if (!user.hasPermission) throw new ForbiddenError(...);
+        // actual logic at top level
+        ```
+
+      ### Composition over Inheritance
+      - Prefer composing objects via interfaces and delegation over class inheritance.
+      - Inheritance creates tight coupling and fragile hierarchies.
+      - Use inheritance ONLY for genuine "is-a" relationships (rare).
+      - When in doubt, compose: inject a collaborator, don't extend a base class.
+
+      ### Law of Demeter (Principle of Least Knowledge)
+      - A method should only call methods on: its own object, its parameters, objects it creates,
+        its direct dependencies.
+      - Do NOT chain through objects: `order.getCustomer().getAddress().getCity()` — BAD.
+      - 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`.
+      - 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.
+
+      ### Pure Functions
+      - A pure function: same inputs → same outputs, no side effects.
+      - Domain logic, validation, transformation, and calculation should be pure.
+      - Side effects (I/O, logging, database) are pushed to the edges (adapters).
+      - Pure functions are trivially testable — no mocks needed.
+
+      ### Factory Pattern
+      - Use factories to encapsulate complex object construction.
+      - Factory methods on the class itself for simple cases: `User.create(dto)`.
+      - Factory classes/functions when construction involves dependencies or conditional logic.
+      - 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.
+
+  - id: twelve-factor-ops
+    tier: optional
+    title: "12-Factor & Operational Readiness"
+    content: |
+      ## 12-Factor App & Operational Readiness
+
+      ### Configuration
+      - ALL config comes from environment variables or external config services. Zero config in code.
+      - Config is validated at startup — fail fast with a clear error if required values are missing.
+      - `.env.example` committed with every variable documented. `.env` is gitignored.
+
+      ### Stateless Processes
+      - Application processes are stateless. Session data lives in external stores (Redis, DB).
+      - Any process can be killed and restarted without data loss.
+      - File uploads go to object storage (S3, GCS), not local disk.
+
+      ### Port Binding
+      - The application is self-contained and exports services via port binding.
+      - No runtime injection of a web server — the app embeds its own (Express, Uvicorn, etc.).
+
+      ### Disposability
+      - Processes start fast (< 5 seconds) and shut down gracefully.
+      - SIGTERM triggers: stop accepting new work → finish in-flight requests → close connections → exit.
+      - Workers use robust job queues so interrupted work is retried, not lost.
+
+      ### Dev/Prod Parity
+      - Minimize gaps between development and production environments.
+      - Use the same backing services in dev as prod (same DB engine, same cache).
+      - Docker / containers recommended for environment parity.
+
+      ### Logs as Event Streams
+      - The app writes logs to stdout/stderr — never to local files.
+      - Log aggregation is an ops concern (ELK, Datadog, CloudWatch), not an application concern.
+      - Structured JSON logs with correlation IDs for tracing across services.
+
+      ### Build, Release, Run
+      - Strict separation: build (compile + assets), release (build + config), run (execute).
+      - Every release is immutable and tagged. Rollback = deploy a previous release.
+      - CI/CD pipeline automates: lint → test → build → deploy with gates at each stage.
+
+  - id: cicd-deployment
+    tier: recommended
+    title: "CI/CD & Deployment"
+    content: |
+      ## CI/CD & Deployment
+
+      ### Pipeline
+      - Every push triggers: lint → type-check → unit tests → build → integration tests.
+      - Merges to main additionally run: security scan → deploy to staging → smoke tests → promote.
+      - Pipeline must complete in under 10 minutes. Parallelize test suites, cache dependencies.
+      - Failed pipelines block merge. No exceptions.
+
+      ### Environments
+      - Minimum three environments: **development** (local), **staging** (mirrors prod), **production**.
+      - Environment config is injected — same artifact runs everywhere with different env vars.
+      - Staging is a faithful replica of production (same provider, same DB engine, same services).
+
+      ### Deployment Strategy
+      - Default: **rolling deployment** with health checks (zero downtime).
+      - For critical services: **blue-green** or **canary** with automated rollback on error rate spike.
+      - Every deploy is tagged with git SHA. Rollback = redeploy a previous SHA.
+      - Deployment must be one command or one button. No multi-step manual runbooks.
+
+      ### Preview Environments
+      - Pull requests get ephemeral preview deployments where feasible (Vercel, Netlify, Railway).
+      - Preview URLs in PR comments for stakeholder review before merge.
+
+  - id: testing-pyramid
+    tier: core
+    title: "Testing Pyramid"
+    content: |
+      ## Testing Pyramid
+
+      ```
+               /  E2E  \          ← 5-10% of tests. Core journeys only.
+              / Integration \      ← 20-30%. Real dependencies at boundaries.
+             /    Unit Tests   \   ← 60-75%. Fast, isolated, every public function.
+      ```
+
+      ### Coverage Targets
+      - Overall minimum: {{coverage_minimum | default: 80}}% line coverage (blocks commit)
+      - New/changed code: {{coverage_new_code_min | default: 90}}% minimum (measured on diff)
+      - Critical paths: 95%+ (data pipelines, auth, PHI handling, financial calculations)
+
+      ### Test Rules
+      - Every test name is a specification: `test_rejects_duplicate_member_ids` not `test_validation`
+      - No empty catch blocks. No `assert True`. No tests that can't fail.
+      - Test files colocated: `[module].test.[ext]` or in `tests/` mirroring src structure.
+      - Flaky tests are bugs — fix or quarantine, never ignore.
+
+      ### Test Doubles Taxonomy
+      Use the correct double for the job:
+      - **Stub**: Returns canned data. No assertions on calls. Use when you need to control input.
+      - **Spy**: Records calls. Assert after the fact. Use to verify side effects.
+      - **Fake**: Working implementation with shortcuts (in-memory DB). Use for integration-speed tests.
+      - **Mock**: Pre-programmed expectations. Assert call patterns. Use sparingly — they couple to implementation.
+      Prefer stubs and fakes over mocks. Tests that mock everything test nothing.
+
+      ### Test Data Builders
+      - Use Builder or Factory pattern for test data: `UserBuilder.anAdmin().withName('Alice').build()`.
+      - One builder per domain entity. Builders provide sensible defaults so tests only specify what matters.
+      - No raw object literals scattered across tests. Centralize in `tests/fixtures/` or `tests/builders/`.
+
+      ### Property-Based Testing
+      - For pure functions with wide input ranges, add property tests (fast-check, Hypothesis, QuickCheck).
+      - Define invariants, not examples: "sorting is idempotent", "encode then decode = identity".
+      - Property tests complement, not replace, example-based tests.
+
+  - id: data-guardrails
+    tier: core
+    title: "Data Guardrails"
+    content: |
+      ## Data Guardrails ⚠️
+      - NEVER sample, truncate, or subset data unless explicitly instructed.
+      - NEVER make simplifying assumptions about distributions, scales, or schemas.
+      - State exact row counts, column sets, and filters for every data operation.
+      - If data is too large for in-memory, say so — don't silently downsample.
+
+  - id: commit-protocol
+    tier: core
+    title: "Commit Protocol"
+    content: |
+      ## Commit Protocol
+      - Conventional commits: feat|fix|refactor|docs|test|chore(scope): description
+      - Commits must pass: compilation, lint, tests, coverage gate, anti-pattern scan.
+      - Keep commits atomic — one logical change per commit.
+      - Commit BEFORE any risky refactor. Tag stable states.
+      - Update Status.md at the end of every session.
+
+  - id: mcp-tooling
+    tier: recommended
+    title: "MCP-Powered Tooling"
+    content: |
+      ## MCP-Powered Tooling
+      ### CodeSeeker — Graph-Powered Code Intelligence
+      CodeSeeker builds a knowledge graph of the codebase with hybrid search
+      (vector + text + path, fused with RRF). Use it for:
+      - **Semantic search**: "find code that handles errors like this" — not just grep.
+      - **Graph traversal**: imports, calls, extends — follow dependency chains.
+      - **Coding standards**: auto-detected validation, error handling, and state patterns.
+      - **Contextual reads**: `get_file_context` returns a file with its related code.
+      Indexing is automatic on first search (~30s–5min depending on codebase size).
+      Most valuable on mid-to-large projects (10K+ files) with established patterns.
+      Install: `npx codeseeker install --vscode` or see https://github.com/jghiringhelli/codeseeker
+
+  - id: engineering-preferences
+    tier: recommended
+    title: "Engineering Preferences"
+    content: |
+      ## Engineering Preferences
+      These calibrate Claude Code's judgment on subjective trade-offs.
+      - **DRY is important** — flag repetition aggressively.
+      - **Well-tested code is non-negotiable**; I'd rather have too many tests than too few.
+      - **"Engineered enough"** — not under-engineered (fragile, hacky) and not over-engineered
+        (premature abstraction, unnecessary complexity).
+      - **Handle more edge cases**, not fewer; thoughtfulness > speed.
+      - **Bias toward explicit over clever** — readability wins over brevity.
+      - When in doubt, ask rather than assume.
+
+  - id: corrections-log
+    tier: core
+    title: "Corrections Log"
+    content: |
+      ## Corrections Log
+      When I correct your output, record the correction pattern here so you don't repeat it.
+      ### Learned Corrections
+      - [CC appends corrections here with date and description]

package/templates/universal/hooks.yaml

@@ -0,0 +1,196 @@
+tag: UNIVERSAL
+section: hooks
+hooks:
+  - name: branch-protection
+    trigger: pre-commit
+    description: "Block direct commits to main/master branches"
+    filename: pre-commit-branch-check.sh
+    script: |
+      #!/bin/bash
+      BRANCH=$(git rev-parse --abbrev-ref HEAD)
+      if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+        echo "❌ Direct commits to $BRANCH are blocked. Create a feature branch."
+        exit 1
+      fi
+
+  - name: dangerous-commands
+    trigger: pre-exec
+    description: "Block destructive commands (rm -rf /, DROP DATABASE, force push)"
+    filename: pre-exec-safety.sh
+    script: |
+      #!/bin/bash
+      DANGEROUS_PATTERNS=(
+        "rm -rf /"
+        "DROP DATABASE"
+        "DROP TABLE"
+        "TRUNCATE"
+        "force push"
+        "git push.*--force"
+        "kubectl delete namespace"
+      )
+      for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+        if echo "$1" | grep -iqE "$pattern"; then
+          echo "❌ Blocked dangerous command matching: $pattern"
+          exit 1
+        fi
+      done
+
+  - name: auto-format
+    trigger: pre-commit
+    description: "Run language-appropriate formatter on staged files"
+    filename: pre-commit-format.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      # Python
+      echo "$STAGED" | grep '\.py$' | xargs -r black --quiet 2>/dev/null
+      echo "$STAGED" | grep '\.py$' | xargs -r isort --quiet 2>/dev/null
+      # TypeScript/JavaScript
+      echo "$STAGED" | grep '\.\(ts\|tsx\|js\|jsx\)$' | xargs -r npx prettier --write 2>/dev/null
+      # Re-stage formatted files
+      echo "$STAGED" | xargs -r git add
+
+  - name: secrets-scanner
+    trigger: pre-commit
+    description: "Scan for accidentally committed secrets (AWS keys, API keys, passwords)"
+    filename: pre-commit-secrets.sh
+    script: |
+      #!/bin/bash
+      PATTERNS=(
+        'AKIA[0-9A-Z]{16}'
+        'password\s*=\s*["\x27][^"\x27]+'
+        'BEGIN RSA PRIVATE KEY'
+        'sk-[a-zA-Z0-9]{48}'
+        'ghp_[a-zA-Z0-9]{36}'
+      )
+      STAGED=$(git diff --cached --name-only)
+      for file in $STAGED; do
+        for pattern in "${PATTERNS[@]}"; do
+          if grep -qE "$pattern" "$file" 2>/dev/null; then
+            echo "❌ Potential secret found in $file matching pattern"
+            exit 1
+          fi
+        done
+      done
+
+  - name: compile-check
+    trigger: pre-commit
+    description: "Detect project type and run appropriate compile/build check"
+    filename: pre-commit-compile.sh
+    script: |
+      #!/bin/bash
+      echo "🔨 Running build check..."
+      if [ -f "pyproject.toml" ] || [ -f "setup.py" ] || [ -f "requirements.txt" ]; then
+        STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')
+        if [ -n "$STAGED_PY" ]; then
+          for file in $STAGED_PY; do
+            python -m py_compile "$file" 2>&1
+            if [ $? -ne 0 ]; then
+              echo "❌ Syntax error in $file"
+              exit 1
+            fi
+          done
+          echo "  ✅ Python syntax OK"
+        fi
+      fi
+      if [ -f "tsconfig.json" ]; then
+        npx tsc --noEmit 2>&1
+        if [ $? -ne 0 ]; then
+          echo "❌ TypeScript compilation failed."
+          exit 1
+        fi
+        echo "  ✅ TypeScript compilation OK"
+      fi
+      echo "🔨 Build check passed"
+
+  - name: test-coverage
+    trigger: pre-commit
+    description: "Run tests with coverage and enforce minimum thresholds"
+    filename: pre-commit-test.sh
+    script: |
+      #!/bin/bash
+      COVERAGE_MIN={{coverage_minimum | default: 80}}
+      echo "🧪 Running tests with coverage..."
+      if [ -f "package.json" ]; then
+        if grep -q '"vitest"' package.json 2>/dev/null; then
+          npx vitest run --reporter=verbose 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Tests failed."
+            exit 1
+          fi
+          echo "  ✅ Tests passed"
+        elif grep -q '"jest"' package.json 2>/dev/null; then
+          npx jest --passWithNoTests --coverage \
+            --coverageThreshold="{\"global\":{\"lines\":$COVERAGE_MIN}}" \
+            --silent 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Jest tests failed or coverage below ${COVERAGE_MIN}%."
+            exit 1
+          fi
+          echo "  ✅ Jest tests passed"
+        fi
+      fi
+      if [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+        if command -v pytest &> /dev/null; then
+          pytest --tb=short --quiet --cov=src --cov-fail-under=$COVERAGE_MIN 2>&1
+          if [ $? -ne 0 ]; then
+            echo "❌ Tests failed or coverage below ${COVERAGE_MIN}%."
+            exit 1
+          fi
+          echo "  ✅ Python tests passed"
+        fi
+      fi
+      echo "🧪 All tests passed"
+
+  - name: anti-pattern-detector
+    trigger: pre-commit
+    description: "Scan source files for production code anti-patterns"
+    filename: pre-commit-prod-quality.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+      SOURCE_FILES=$(echo "$STAGED" | grep -E '\.(py|ts|tsx|js|jsx)$' | grep -vE '(test_|\.test\.|\.spec\.|__tests__|tests/|fixtures/|mock|conftest)')
+      if [ -z "$SOURCE_FILES" ]; then exit 0; fi
+      VIOLATIONS=0
+      WARNINGS=0
+      echo "🔍 Scanning for production code anti-patterns..."
+      for file in $SOURCE_FILES; do
+        if echo "$file" | grep -vqE '(config|settings|\.env)'; then
+          if grep -nE '(localhost|127\.0\.0\.1|0\.0\.0\.0)' "$file" | grep -vE '(#|//|""")' > /tmp/violations 2>/dev/null; then
+            if [ -s /tmp/violations ]; then
+              echo "  ❌ $file — hardcoded URL/host"
+              VIOLATIONS=$((VIOLATIONS + 1))
+            fi
+          fi
+        fi
+        if grep -nEi '\b(mock_data|fake_data|dummy_data|stub_response)' "$file" > /tmp/violations 2>/dev/null; then
+          if [ -s /tmp/violations ]; then
+            echo "  ❌ $file — mock/stub data in production code"
+            VIOLATIONS=$((VIOLATIONS + 1))
+          fi
+        fi
+        LINE_COUNT=$(wc -l < "$file")
+        if [ "$LINE_COUNT" -gt {{max_file_length | default: 300}} ]; then
+          echo "  ⚠️  $file — $LINE_COUNT lines (max {{max_file_length | default: 300}})"
+          WARNINGS=$((WARNINGS + 1))
+        fi
+      done
+      rm -f /tmp/violations
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo "❌ $VIOLATIONS violation(s) found — commit blocked."
+        exit 1
+      fi
+      echo "🔍 Production quality scan passed"
+
+  - name: code-review
+    trigger: pre-commit
+    description: "Claude Code reviews diff against project standards"
+    filename: pre-commit-review.sh
+    script: |
+      #!/bin/bash
+      DIFF=$(git diff --cached)
+      if [ -z "$DIFF" ]; then exit 0; fi
+      echo "📝 Staged changes ready for review"
+      # Full auto-review requires claude CLI integration
+      # This hook validates the diff is non-empty and staged
+      exit 0