@aslomon/effectum 0.1.0

package/system/commands/ralph-loop.md

@@ -0,0 +1,163 @@
+# /ralph-loop -- Self-Referential Agentic Loop for Autonomous Implementation
+
+You enter an autonomous iteration loop. Each iteration: assess state, implement the next step, run quality gates, repeat -- until all criteria are met or max-iterations is reached.
+
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for these components:
+
+1. **Prompt text**: The complete work order (everything that is not a flag).
+2. **`--max-iterations N`**: Maximum number of iterations (required, default 30).
+3. **`--completion-promise "PHRASE"`**: The exact phrase to output when done (required).
+
+If either `--max-iterations` or `--completion-promise` is missing, ask the user to provide them and wait.
+
+## Step 2: Initialize State
+
+Create the state file at `.claude/ralph-loop.local.md`:
+
+```yaml
+---
+active: true
+iteration: 0
+max_iterations: [N]
+completion_promise: "[PHRASE]"
+started_at: [ISO 8601 timestamp]
+errors_consecutive: 0
+last_error: ""
+---
+
+## Original Prompt
+
+[FULL PROMPT TEXT FROM $ARGUMENTS]
+
+## Progress Log
+
+[Empty -- will be updated each iteration]
+```
+
+Read `CLAUDE.md` for the project's build, test, lint, and type-check commands.
+
+## Step 3: Execute Iteration Loop
+
+For each iteration (1 through max_iterations):
+
+### 3a. Read State
+
+1. Read `.claude/ralph-loop.local.md` for current iteration count, progress log, and error state.
+2. Check current project state: `git diff --stat`, existing files, latest test results.
+3. If a PRD is referenced in the prompt, re-read the acceptance criteria.
+
+### 3b. Determine Next Step
+
+Based on the prompt, progress log, and current project state, determine the single next logical step to implement. Follow this general sequence:
+
+1. Data layer: migrations, schemas, types, validation.
+2. Backend: services, API routes, business logic.
+3. Frontend: components, pages, hooks.
+4. Tests: unit tests, integration tests (follow TDD where practical).
+5. E2E tests: critical user journeys.
+6. Polish: code review, cleanup, final verification.
+
+If an `<iteration_plan>` was provided in the prompt, follow it as a roadmap.
+
+### 3c. Implement
+
+Execute the next step. Write code, tests, configurations -- whatever the step requires. Follow project conventions from CLAUDE.md.
+
+### 3d. Run Quality Gates
+
+After every significant change, run the project's quality gates:
+
+1. Build command.
+2. Type-check command.
+3. Test command.
+4. Lint command.
+
+Record the results.
+
+### 3e. Update State
+
+Update `.claude/ralph-loop.local.md`:
+
+- Increment `iteration` counter.
+- Add a progress log entry: what was done, what passed/failed.
+- Update `errors_consecutive` (reset to 0 on success, increment on failure).
+- Update `last_error` with the most recent error message (if any).
+
+### 3f. Check Completion
+
+Evaluate whether ALL of these conditions are met:
+
+1. Every acceptance criterion from the PRD/prompt is implemented and verified.
+2. All quality gates pass (build, types, tests, lint).
+3. The completion promise statement is 100% TRUE.
+
+**If all conditions are met:**
+Output the completion promise: `<promise>[COMPLETION PROMISE TEXT]</promise>`
+Set `active: false` in the state file.
+Write a final status report to `.claude/ralph-status.md`.
+**STOP.**
+
+**If conditions are NOT yet met:**
+Continue to the next iteration.
+
+## Step 4: Error Recovery
+
+Apply these escalation rules:
+
+### Build/Test Error
+
+- Next iteration sees the error output and fixes it. This is normal -- continue.
+
+### Same Error 3 Consecutive Times
+
+- The current approach is not working. Try a fundamentally different approach:
+  - Different algorithm or data structure.
+  - Different library or API.
+  - Simpler implementation that still satisfies the criteria.
+- Document what was tried and why it failed in the progress log.
+
+### Same Error 5 Consecutive Times
+
+- This is a blocker. Document it in `.claude/ralph-blockers.md`:
+  - What the error is.
+  - What approaches were tried.
+  - Why none worked.
+  - Suggested investigation paths.
+- Move to the next task/acceptance criterion. Do not keep retrying.
+
+### 80% of Iterations Consumed
+
+- Write a comprehensive status report to `.claude/ralph-status.md`:
+  - What is done (with test results).
+  - What remains.
+  - Active blockers.
+  - Suggested next steps.
+  - Estimated remaining work.
+- Continue implementing, but prioritize the most impactful remaining work.
+
+### Flaky Test
+
+- Investigate the root cause: stateful dependency, timing issue, test isolation problem.
+- Do NOT retry blindly. Fix the underlying cause.
+- If the root cause cannot be fixed in one iteration: document it as a known issue and skip to the next task.
+
+### Max Iterations Reached
+
+- Set `active: false` in the state file.
+- Write a final status report to `.claude/ralph-status.md`.
+- Do NOT output the completion promise -- it would be dishonest.
+- Report what was accomplished and what remains.
+
+## CRITICAL RULES
+
+1. **Honesty above all**: The completion promise may ONLY be output when the statement is 100% TRUE. Do NOT output false promises to escape the loop. If the build is broken, tests fail, or criteria are unmet, the promise MUST NOT be output.
+2. **One step per iteration**: Each iteration should accomplish one meaningful piece of work. Do not try to implement the entire feature in a single iteration.
+3. **Always run quality gates**: After every significant change, verify the build and tests. Do not accumulate changes without verification.
+4. **Self-awareness**: Read your own progress log to avoid repeating failed approaches. Learn from previous iterations.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All code, state files, progress logs, and technical content in English.

package/system/commands/refactor-clean.md

@@ -0,0 +1,104 @@
+# /refactor-clean -- Remove Dead Code and Improve Quality
+
+You clean up the codebase by removing dead code and improving quality, without changing any observable behavior. Every change is validated by the test suite.
+
+## Step 1: Establish a Passing Baseline
+
+1. Read `CLAUDE.md` for the project's test command, build command, and lint command.
+2. Run the full test suite.
+3. **If any tests fail: STOP immediately.** Do not refactor a codebase with failing tests. Report the failures and suggest running `/build-fix` or `/tdd` first.
+4. Record the test count and pass rate as the baseline.
+
+## Step 2: Analyze the Codebase
+
+Scan for refactoring opportunities across these categories:
+
+### Dead Code
+
+- **Unused imports**: Imports that are not referenced anywhere in the file.
+- **Unused variables and functions**: Declared but never called or read.
+- **Unused files**: Files that are not imported by any other file.
+- **Commented-out code blocks**: Old code left in comments (not explanatory comments).
+- **Unreachable code**: Code after return/throw statements, never-true conditions.
+
+### Oversized Files
+
+- Files exceeding 300 lines. Identify natural split points (separate concerns, distinct feature areas).
+
+### Duplicated Logic
+
+- Functions or code blocks that appear in multiple places with minor variations. Identify candidates for extraction into shared utilities.
+
+### Overly Complex Functions
+
+- Functions exceeding 40 lines. Identify extraction points (helper functions, early returns, guard clauses).
+
+### Inconsistent Naming
+
+- Variables, functions, or files that don't follow the project's naming conventions (as defined in CLAUDE.md).
+
+## Step 3: Create a Refactoring Plan
+
+Present the findings as a prioritized list:
+
+```
+| # | Category       | Location                    | Description                          | Risk |
+| - | -------------- | --------------------------- | ------------------------------------ | ---- |
+| 1 | Dead code      | src/lib/utils/old-helper.ts | File not imported anywhere           | Low  |
+| 2 | Oversized file | src/lib/auth/service.ts     | 412 lines, split auth + session      | Med  |
+| 3 | Duplication    | src/components/form/*.tsx    | Validation logic duplicated 3 times  | Low  |
+| 4 | Complex fn     | src/lib/billing/calc.ts     | calculateTotal: 67 lines             | Med  |
+```
+
+**Wait for user approval before proceeding.** The user may exclude specific items or reprioritize.
+
+## Step 4: Refactor One Thing at a Time
+
+For each approved refactoring item:
+
+1. **Make the change**: Apply the refactoring (delete dead code, extract function, rename, split file).
+2. **Run the full test suite**: Verify all tests still pass.
+3. **If tests pass**: Move to the next item.
+4. **If tests fail**: Revert the change immediately. Investigate why the "dead" code or refactoring broke something. Report the finding -- it may indicate a test gap or hidden dependency.
+
+### Refactoring Patterns
+
+- **Remove dead code**: Delete the unused import, variable, function, or file. If a file is deleted, check for any remaining references.
+- **Split oversized file**: Extract related functions/classes into a new file. Update all import paths. Ensure the public API surface remains identical.
+- **Extract duplicated logic**: Create a shared utility function. Replace all instances with calls to the shared function. Verify behavior is identical.
+- **Simplify complex functions**: Extract helper functions, use early returns to reduce nesting, separate concerns into distinct functions.
+- **Fix naming**: Rename using the IDE/tool's rename capability or update all references manually. Verify no references are missed.
+
+## Step 5: Final Verification
+
+After all refactoring is complete:
+
+1. Run the full test suite -- verify all tests pass (same count as baseline, no new failures).
+2. Run the build command -- verify it passes.
+3. Run the lint command -- verify it passes.
+4. Compare the codebase metrics:
+   - Total lines of code (before vs. after).
+   - Number of files (before vs. after).
+   - Largest file size (before vs. after).
+
+## Step 6: Report
+
+Present a summary:
+
+```
+| Metric                | Before | After  |
+| --------------------- | ------ | ------ |
+| Total source files    | 87     | 84     |
+| Total lines of code   | 12,450 | 11,200 |
+| Largest file (lines)  | 412    | 245    |
+| Tests passing         | 142    | 142    |
+| Build status          | PASS   | PASS   |
+| Lint status           | PASS   | PASS   |
+```
+
+List each refactoring that was applied and its impact. Suggest running `/verify` for a full quality gate check.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All code, file paths, and technical content in English.

package/system/commands/tdd.md

@@ -0,0 +1,84 @@
+# /tdd -- Test-Driven Development: RED -> GREEN -> REFACTOR
+
+You implement features using strict Test-Driven Development. Every piece of functionality starts with a failing test.
+
+## Step 1: Establish Context
+
+1. Read `CLAUDE.md` for the project's test framework, test conventions, and file organization.
+2. Read `$ARGUMENTS` for the feature context: PRD reference, specific functionality, or conversation context.
+3. If a PRD is referenced, read it to understand the acceptance criteria.
+4. Read existing test files to understand patterns: test structure, naming, helpers, fixtures, mocking approach.
+
+## Step 2: Identify the Next Unit of Work
+
+Break the feature into small, independently testable pieces of functionality. Pick the next piece that:
+
+- Has no unmet dependencies on other unimplemented pieces.
+- Represents a single, clearly defined behavior.
+- Can be expressed as one or more test assertions.
+
+If all pieces are implemented, skip to Step 6.
+
+## Step 3: RED -- Write a Failing Test
+
+1. Create or open the test file following project conventions (colocated with source or in a tests directory).
+2. Write a test that describes the expected behavior of the next piece of functionality.
+   - Use descriptive test names that explain WHAT is being tested and WHAT the expected outcome is.
+   - Test one behavior per test case.
+   - Use the project's test framework and assertion style as specified in CLAUDE.md.
+3. Run the test using the project's test command (as specified in CLAUDE.md).
+4. **Verify it fails for the RIGHT reason:**
+   - The test should fail because the functionality does not exist yet (e.g., missing function, missing module, wrong return value).
+   - If it fails for the WRONG reason (import error, syntax error, misconfigured test), fix the test setup first.
+   - If it passes unexpectedly, the behavior already exists -- move to the next piece.
+
+## Step 4: GREEN -- Write Minimum Code to Pass
+
+1. Write the simplest implementation that makes the failing test pass.
+   - Follow project conventions, patterns, and architectural rules from CLAUDE.md.
+   - Use existing utilities, components, and services where applicable.
+   - Do NOT add functionality beyond what the test requires.
+2. Run the test using the project's test command.
+3. **Verify it passes.** If it still fails:
+   - Read the error output completely before attempting a fix.
+   - Apply a targeted fix (one change at a time).
+   - Re-run the test.
+
+## Step 5: REFACTOR -- Improve While Green
+
+With the test passing, improve the code quality:
+
+1. Extract common patterns into shared utilities or helpers.
+2. Improve naming for clarity.
+3. Reduce duplication (DRY) -- within the current feature and against existing code.
+4. Ensure functions stay under 40 lines and files under 300 lines.
+5. Ensure error handling follows project conventions (e.g., Result pattern).
+6. Run the full test suite (not just the current test) to verify nothing is broken.
+7. If any test breaks during refactoring: revert the refactoring change and investigate.
+
+## Step 6: Repeat
+
+Go back to Step 2 and pick the next piece of functionality. Continue until all acceptance criteria from the PRD or feature description are covered by passing tests.
+
+## Step 7: Final Verification
+
+When the feature is fully implemented:
+
+1. Run the complete test suite to confirm all tests pass.
+2. Run the project's build command to confirm compilation succeeds.
+3. Run the project's type-check command (if separate from build) to confirm type safety.
+4. Run the project's linter to confirm code style compliance.
+5. Report results: what was implemented, how many tests were written, and the pass/fail status of each quality gate.
+6. Suggest running `/verify` for the full quality gate check or `/e2e` for end-to-end tests.
+
+## Error Recovery
+
+- **Import/module errors**: Check if the module path, export name, or package installation is correct.
+- **Type errors**: Use type guards or validation schemas instead of type assertions.
+- **Flaky tests**: Investigate the root cause (stateful dependency, timing, test isolation) -- do not retry blindly.
+- **Same error 3 times**: Try a fundamentally different approach. Document what was tried and why it failed.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All code, test names, and technical content in English.

package/system/commands/verify.md

@@ -0,0 +1,71 @@
+# /verify -- Run All Quality Gates and Report Results
+
+You run every quality gate for the project and report a clear pass/fail summary. You do NOT fix failures automatically.
+
+## Step 1: Determine Verification Scope
+
+Parse `$ARGUMENTS` to determine the scope:
+
+- **No arguments** (`/verify`): Standard verification -- build + types + lint + tests.
+- **`quick`** (`/verify quick`): Minimal verification -- build + types only.
+- **`full`** (`/verify full`): Complete verification -- all gates including E2E, debug checks, and file size analysis.
+
+## Step 2: Read Project Configuration
+
+Read `CLAUDE.md` to identify the project's specific commands for each quality gate:
+
+- Build command (e.g., compile, transpile, bundle).
+- Type-check command (if separate from build).
+- Lint command.
+- Test command (unit + integration).
+- E2E test command (for `full` scope only).
+
+If CLAUDE.md does not specify a command for a gate, attempt to detect it from project configuration files (package.json, pyproject.toml, Makefile, Cargo.toml, etc.). If a gate cannot be detected, mark it as SKIPPED with a note.
+
+## Step 3: Run Quality Gates
+
+Run each gate sequentially. Collect the output and determine pass/fail for each.
+
+### Standard Gates (always run)
+
+1. **Build**: Run the project's build command. PASS = zero errors, zero exit code.
+2. **Type Check**: Run the project's type-check command (if separate from build). PASS = zero type errors.
+3. **Lint**: Run the project's lint command. PASS = zero errors (warnings are acceptable unless the project treats them as errors).
+4. **Tests**: Run the project's test suite (unit + integration). PASS = all tests pass, zero exit code.
+
+### Full Gates (only with `full` or `e2e` argument)
+
+5. **E2E Tests**: Run the project's E2E test command. PASS = all tests pass.
+6. **Debug Statements**: Search production source code for debug statements:
+   - JavaScript/TypeScript: `console.log`, `console.debug`, `console.warn` (not in test files), `debugger`
+   - Python: `print(`, `breakpoint()`, `pdb.set_trace()`
+   - Other languages: adapt to common debug patterns.
+   - PASS = zero debug statements found in production code.
+7. **File Size**: Check all source files for length. Flag any file exceeding 300 lines. PASS = no oversized files.
+
+## Step 4: Present Results
+
+Present results as a clear table:
+
+```
+| Gate            | Status  | Details                          |
+| --------------- | ------- | -------------------------------- |
+| Build           | PASS    | Completed in 12s                 |
+| Type Check      | PASS    | 0 errors                         |
+| Lint            | FAIL    | 3 errors in src/lib/auth.ts      |
+| Tests           | PASS    | 47/47 passed                     |
+| E2E Tests       | SKIPPED | Not requested (use /verify full) |
+| Debug Statements| PASS    | 0 found                          |
+| File Size       | WARNING | 2 files exceed 300 lines         |
+```
+
+## Step 5: Summary
+
+- **All gates PASS**: Report success. The project is in a clean state.
+- **Any gate FAIL**: Report which gates failed with the specific error details (file, line, error message). List the failures in priority order (build errors first, then types, then lint, then tests).
+- **Do NOT attempt to fix failures automatically.** Present the findings and ask the user what to do. Suggest `/build-fix` for build/type errors, or specific actions for other failures.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All technical output (error messages, file paths, gate names) in English.

package/system/stacks/generic.md

@@ -0,0 +1,96 @@
+# Stack Preset: Generic
+
+> Stack-agnostic baseline. Use this when no specific stack preset matches, or as a starting point for custom stacks.
+
+## TECH_STACK
+
+```
+- Language: [SPECIFY — e.g., TypeScript, Python, Go, Rust, Java]
+- Framework: [SPECIFY — e.g., Express, Django, Gin, Actix, Spring Boot]
+- Database: [SPECIFY — e.g., PostgreSQL, MySQL, SQLite, MongoDB]
+- Testing: [SPECIFY — e.g., Jest, pytest, go test, cargo test]
+- Linting: [SPECIFY — e.g., ESLint, ruff, golangci-lint, clippy]
+- Package Manager: [SPECIFY — e.g., npm, pip, go mod, cargo]
+- Deployment: [SPECIFY — e.g., Docker, Kubernetes, serverless]
+```
+
+## ARCHITECTURE_PRINCIPLES
+
+```
+- Separation of concerns: keep data access, business logic, and presentation in distinct layers.
+- Dependency injection: pass dependencies explicitly. Avoid global state and singletons.
+- Type safety: use the strongest type system your language offers. Avoid escape hatches (any, Object, interface{}).
+- Validation at boundaries: validate all external input (API requests, env vars, file I/O) at the entry point.
+- Error handling: use explicit error types or Result patterns. Never swallow errors silently.
+- Configuration from environment: no hardcoded secrets or environment-specific values in source code.
+- Immutability by default: prefer const/final/readonly. Mutate only when necessary.
+- Tests are first-class: colocate tests with source code. Test behavior, not implementation.
+```
+
+## PROJECT_STRUCTURE
+
+````
+```
+src/                        # Application source code
+  [domain]/                 # Domain-specific modules
+    models/                 # Data models / entities
+    services/               # Business logic
+    handlers/               # Request handlers / controllers
+    repositories/           # Data access layer
+  shared/                   # Cross-cutting concerns
+    config/                 # Configuration loading and validation
+    errors/                 # Custom error types
+    middleware/             # Middleware / interceptors
+    utils/                  # Pure utility functions
+tests/                      # Test files (mirrors src/ structure)
+scripts/                    # Build, deploy, and maintenance scripts
+docs/                       # Documentation (if needed)
+```
+````
+
+## QUALITY_GATES
+
+```
+- Build: [BUILD_COMMAND] — 0 errors
+- Types: [TYPE_CHECK_COMMAND] — 0 errors (if applicable)
+- Tests: [TEST_COMMAND] — all pass, target 80%+ coverage
+- Lint: [LINT_COMMAND] — 0 errors
+- Format: [FORMAT_CHECK_COMMAND] — 0 differences
+- No Debug Logs: 0 debug print/log statements in production code
+- File Size: No file exceeds 300 lines
+```
+
+## FORMATTER
+
+```
+[SPECIFY — e.g., prettier, ruff format, gofmt, rustfmt, google-java-format]
+```
+
+## FORMATTER_GLOB
+
+```
+[SPECIFY — e.g., ts|tsx|js|jsx, py, go, rs, java]
+```
+
+## PACKAGE_MANAGER
+
+```
+[SPECIFY — e.g., pnpm, uv, go mod, cargo, maven]
+```
+
+## STACK_SPECIFIC_GUARDRAILS
+
+```
+- [Add project-specific guardrails here]
+- [e.g., "Use X package manager, not Y"]
+- [e.g., "Always validate input with Z library"]
+- [e.g., "Follow existing patterns in src/domain/"]
+```
+
+## TOOL_SPECIFIC_GUARDRAILS
+
+```
+- **Formatter runs automatically**: The PostToolUse hook auto-formats files. Don't run the formatter manually.
+- **CHANGELOG is auto-updated**: The Stop hook handles CHANGELOG.md. Don't update it manually unless explicitly asked.
+- **Lock files are protected**: Dependency lock files cannot be written to directly. Use package manager commands.
+```

package/system/stacks/nextjs-supabase.md

@@ -0,0 +1,114 @@
+# Stack Preset: Next.js + Supabase
+
+> Full-stack web applications with Next.js, TypeScript, Tailwind CSS, and Supabase.
+
+## TECH_STACK
+
+```
+- Next.js >= 16, App Router ONLY (never Pages Router, never getServerSideProps/getStaticProps)
+- TypeScript strict mode, no `any`, no `as` casts (use type guards or Zod)
+- Tailwind CSS v4 + Shadcn UI components
+- Framer Motion for animations
+- Supabase: DB, Auth, Storage, Edge Functions, Realtime
+- Zod for ALL external data validation (API inputs, env vars, form data)
+- Vitest + Testing Library for unit/integration tests
+- Playwright for E2E tests
+- pnpm (never npm/yarn unless project explicitly uses them)
+- Vercel deployment, Docker Compose for local dev
+```
+
+## ARCHITECTURE_PRINCIPLES
+
+```
+- AGENT-NATIVE: every feature MUST expose clean REST/RPC APIs. Backend is modular, extensible, automatable.
+- MULTI-TENANT: include tenant_id/org_id from day one. Never assume single-tenant.
+- Supabase RLS policies on EVERY table, no exceptions. Run security advisors after DDL changes.
+- DB changes ONLY through migrations (apply_migration), never raw DDL.
+- Generate TypeScript types from Supabase schema. Never hand-write DB types.
+- End-to-end type safety: DB schema -> generated types -> Zod schemas -> API -> frontend.
+- Components -> Features -> Services separation. No business logic in components.
+- Server Components by default. Client Components only when needed (interactivity, hooks, browser APIs).
+- Colocate: keep tests, types, and utils next to the code they serve.
+- Zod validation on ALL external boundaries (API inputs, env vars, form data).
+- Result pattern { data, error } for all operations that can fail. Never throw for expected errors.
+```
+
+## PROJECT_STRUCTURE
+
+````
+```
+src/
+  app/                    # Next.js App Router (routes, layouts, pages)
+    (auth)/               # Route groups
+    api/                  # Route Handlers
+  components/
+    ui/                   # Shadcn/base components
+    [feature]/            # Feature-specific components
+  lib/
+    supabase/             # Client, server client, middleware, types
+    [domain]/             # Domain services (e.g., lib/billing/, lib/agents/)
+  hooks/                  # Custom React hooks
+  types/                  # Shared TypeScript types
+  utils/                  # Pure utility functions
+supabase/
+  migrations/             # SQL migrations (timestamped)
+  functions/              # Edge Functions (Deno)
+tests/
+  e2e/                    # Playwright tests
+```
+````
+
+## QUALITY_GATES
+
+```
+- Build: `pnpm build` — 0 errors
+- Types: `tsc --noEmit` — 0 errors
+- Tests: `pnpm vitest run` — all pass, 80%+ coverage
+- Lint: `pnpm lint` — 0 errors
+- E2E: `npx playwright test` — all pass (if applicable)
+- Code Review: `/code-review` — no security issues
+- RLS Check: Supabase security advisor — all tables have RLS policies
+- No Debug Logs: 0 console.log in production code (`grep -r "console.log" src/`)
+- Type Safety: No `any`, no `as` casts in source code
+- File Size: No file exceeds 300 lines
+```
+
+## FORMATTER
+
+```
+npx prettier --write
+```
+
+## FORMATTER_GLOB
+
+```
+ts|tsx|js|jsx|json|css|md
+```
+
+## PACKAGE_MANAGER
+
+```
+pnpm
+```
+
+## STACK_SPECIFIC_GUARDRAILS
+
+```
+- **pnpm, not npm**: This project ecosystem uses pnpm exclusively. npm commands will create conflicting lock files.
+- **Check DESIGN.md first**: Before any UI/design work, read DESIGN.md. Making design decisions without it causes inconsistencies.
+- **createServerClient in Server Components**: Always use `createServerClient` in Server Components and Route Handlers.
+- **createBrowserClient in Client Components**: Always use `createBrowserClient` in Client Components.
+- **Protect routes with middleware**: Use Supabase Auth middleware for all authenticated routes.
+- **Edge Functions validate with Zod**: All Edge Function inputs must be validated with Zod schemas.
+- **Realtime over polling**: Use Supabase Realtime subscriptions for live data, never polling.
+- **Migrations only**: DB changes ONLY through `apply_migration`. Never run raw DDL.
+- **Generated types only**: TypeScript types for DB schema MUST be generated via `generate_typescript_types`. Never hand-write DB types.
+```
+
+## TOOL_SPECIFIC_GUARDRAILS
+
+```
+- **Prettier runs automatically**: The PostToolUse hook auto-formats ts/tsx/js/jsx/json/css/md files. Don't run prettier manually — it wastes a tool call.
+- **CHANGELOG is auto-updated**: The Stop hook handles CHANGELOG.md. Don't update it manually unless explicitly asked.
+- **Lock files are protected**: pnpm-lock.yaml and package-lock.json cannot be written to directly. Use pnpm install/add commands.
+```