@aslomon/effectum 0.1.0

package/system/templates/CLAUDE.md.tmpl

@@ -0,0 +1,141 @@
+# {{PROJECT_NAME}} — Claude Code Configuration
+
+## Communication
+
+- {{LANGUAGE}}
+- Be direct. Act autonomously. No unnecessary confirmations.
+- Think step-by-step for complex problems. Use plan mode for multi-file changes.
+- Use subagents (Task tool) for parallel and independent work.
+
+## Tech Stack
+
+{{TECH_STACK}}
+
+## Architecture Principles
+
+{{ARCHITECTURE_PRINCIPLES}}
+
+## Project Structure
+
+{{PROJECT_STRUCTURE}}
+
+## Code Quality Rules
+
+- Functions: max 40 lines, single responsibility
+- Files: max 300 lines, split if larger
+- Naming: descriptive, no abbreviations, no Hungarian notation
+- Error handling: use Result pattern (`{ data, error }`) for operations that can fail. Never swallow errors.
+- No console.log in production code (use structured logger)
+- No hardcoded strings for config/env values
+- Prefer `const` and immutable patterns
+- Prefer named exports over default exports
+- Prefer composition over inheritance
+
+## Quality Gates
+
+{{QUALITY_GATES}}
+
+## Design System — MANDATORY
+
+- ALWAYS use the `frontend-design` skill for ANY design-related work: UI components, pages, layouts, styling, visual polish, landing pages, dashboards, posters, artifacts — everything visual.
+- Every project MUST have a `DESIGN.md` file in the project root. This is non-negotiable.
+  - If it does not exist, create it before doing any design work.
+  - If it exists, read and study it thoroughly before making any design decisions.
+  - Update it when new design decisions are made (colors, typography, spacing, patterns, components).
+- `DESIGN.md` must document: color palette, typography (fonts, sizes, weights), spacing system, border radii, shadows, animation conventions, component patterns, brand guidelines, tone/mood, and any project-specific visual rules.
+- Never make visual/design decisions that contradict `DESIGN.md`. When in doubt, consult the document first.
+- This applies across ALL projects — web, mobile, CLI, docs, presentations, artifacts.
+
+## Development Workflow
+
+- SPEC-DRIVEN: define requirements and acceptance criteria before coding
+- TEST-FIRST: write failing tests, then implement (use /tdd)
+- DONE = compiles + tests pass + linter clean (use /verify)
+- Plan complex features before implementing (use /plan)
+- Review changes before committing (use /code-review)
+- Fix build errors incrementally (use /build-fix)
+- Clean dead code periodically (use /refactor-clean)
+- Only commit when explicitly asked. Prefer specific file staging over `git add .`
+
+## Available Commands
+
+| Command           | Phase          | Function                                 |
+| ----------------- | -------------- | ---------------------------------------- |
+| `/plan`           | Start          | Analysis + plan + **waits for approval** |
+| `/tdd`            | Implementation | Tests first -> code -> refactor          |
+| `/verify`         | QA             | Build + types + lint + tests             |
+| `/e2e`            | QA             | E2E tests (Playwright / XCTest UI)       |
+| `/code-review`    | Review         | Security + quality audit                 |
+| `/build-fix`      | Debugging      | Incremental error resolution             |
+| `/refactor-clean` | Cleanup        | Remove dead code                         |
+| `/checkpoint`     | Safety         | Create a restore point                   |
+| `/ralph-loop`     | Full Auto      | Iterative autonomous implementation      |
+| `/orchestrate`    | Teams          | Parallel multi-agent implementation      |
+
+## Context7 — Always Use for Research
+
+- Always use Context7 MCP (`resolve_library_id` -> `get_library_docs`) when:
+  - Planning features that involve libraries, frameworks, or APIs
+  - Exploring documentation for setup, configuration, or integration
+  - Generating code that uses external dependencies
+  - Checking current API signatures, options, or best practices
+  - Comparing approaches or evaluating library capabilities
+- This applies to ALL stacks
+- Fetch docs proactively — do not rely on training data for library-specific details
+
+## Active Hooks — Be Aware
+
+The following hooks run automatically. Do NOT duplicate their behavior:
+
+- **Auto-Format**: {{FORMATTER}} runs after every Edit/Write. Do not manually run the formatter.
+- **CHANGELOG**: A Stop hook auto-updates CHANGELOG.md with [Unreleased] entries after meaningful changes. Do not manually update CHANGELOG.md unless the user explicitly asks.
+- **Commit Message Gate**: Commit messages must be >= 10 characters and descriptive. The hook blocks short messages.
+- **Stop Quality Gate**: A prompt hook verifies all tasks are completed before stopping. If it returns `ok: false`, continue working on what's missing.
+- **Subagent Quality Gate**: Subagent output is verified. Ensure subagents complete their tasks fully, not just report findings.
+- **Error Learning**: Tool failures are logged to `.claude/logs/tool-failures.jsonl`. Check this file at session start to learn from past mistakes and avoid repeating them.
+- **Guardrails Injection**: At session start and after compaction, `~/.claude/guardrails.md` (global) and `$PROJECT/.claude/guardrails.md` (project) are loaded. Follow them strictly.
+- **Transcript Backup**: Transcripts are backed up before context compaction to `.claude/backups/`.
+- **Protected Files**: `.env`, `.env.local`, `.env.production`, `secrets/`, `.git/`, lock files cannot be written to. Use Bash for env file operations if absolutely needed.
+- **Destructive Command Blocker**: `rm -rf /`, `DROP TABLE`, `--force push`, `reset --hard` are blocked.
+- **Desktop Notifications**: User gets OS notifications on permission prompts and task completion.
+
+## Stack-Specific Rules
+
+{{STACK_SPECIFIC_GUARDRAILS}}
+
+## Agent Teams — Opt-In
+
+Agent Teams are DISABLED by default. Enable in settings.json:
+`"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }`
+
+Three execution tiers exist — use the simplest that fits:
+
+| Tier                 | Mechanism                           | When                                           |
+| -------------------- | ----------------------------------- | ---------------------------------------------- |
+| Single-Agent         | Main session alone                  | Simple tasks, bugfixes, single-file changes    |
+| Subagents (default)  | Task Tool spawns specialized agents | Parallel research, code reviews, focused tasks |
+| Agent Teams (opt-in) | Independent Claude instances        | Complex features with 3+ parallel workstreams  |
+
+## Shell Commands — Non-Interactive Only
+
+- ALWAYS use non-interactive flags for shell commands. AI agents cannot interact with stdin prompts.
+- Examples: `{{PACKAGE_MANAGER}} install --yes`, `rm -rf`, `apt install -y`
+- Never use interactive commands: `git rebase -i`, `git add -i`, `less`, `vim`, `nano`, `top`
+- If a command might prompt for input, find and use its non-interactive equivalent or pass defaults via flags/env vars.
+
+## Tool Usage
+
+- Use dedicated tools (Read, Grep, Glob) over Bash equivalents
+- Use Context7 MCP for up-to-date library/framework documentation
+- Use git worktrees for risky or exploratory changes
+- Parallelize independent tool calls
+- When blocked, investigate root cause. Never brute-force or retry blindly.
+- Never use destructive git operations as shortcuts
+
+## Commit Conventions
+
+- Conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
+- Include scope when applicable: `feat(auth): add login flow`
+- Commit messages must be >= 10 characters and descriptive
+- Prefer specific file staging over `git add .`
+- Only commit when explicitly asked

package/system/templates/guardrails.md.tmpl

@@ -0,0 +1,39 @@
+# Project Guardrails
+
+Curated lessons from past development sessions. These are injected at every session start.
+Follow these strictly — each exists because ignoring it caused real problems.
+
+## Error Patterns
+
+- **Test env != dev env**: Never assume test and dev environments behave identically. Validate integration points early with the actual environment.
+- **Read diagnostics before fixing**: Always read the full error message/stack trace before attempting a fix. Guessing wastes iterations.
+- **Manual != automated**: Code that works when run manually may fail in automated contexts (CI, hooks, subagents). Test automation paths explicitly.
+- **Stateful deps cause flaky tests**: External state (DB, files, network) makes tests non-deterministic. Mock or isolate stateful dependencies.
+- **Use precise identifiers**: When searching/replacing code, use unique identifiers. Ambiguous patterns cause wrong matches.
+
+## Workflow Lessons
+
+- **Validate integration points early**: Don't build the full feature before testing that the integration (API, DB, auth) actually works.
+- **Non-interactive commands only**: AI agents cannot handle stdin prompts. Always use `-y`, `--yes`, `--non-interactive` flags.
+- **Check DESIGN.md first**: Before any UI/design work, read DESIGN.md. Making design decisions without it causes inconsistencies that are expensive to fix.
+
+## Code Quality
+
+- Functions: max 40 lines. Split immediately if exceeded.
+- Files: max 300 lines. Split into logical modules if exceeded.
+- No hardcoded strings for configuration values — use environment variables.
+- Error handling: always use Result pattern `{ data, error }` for operations that can fail. Never swallow errors.
+
+## Safety
+
+- Never modify protected files (.env, .env.local, .env.production, secrets/, .git/, lock files) directly.
+- Never run destructive commands (rm -rf /, DROP TABLE, --force push, reset --hard).
+- Only commit when explicitly asked. Prefer specific file staging over `git add .`.
+
+## Stack-Specific
+
+{{STACK_SPECIFIC_GUARDRAILS}}
+
+## Tool-Specific
+
+{{TOOL_SPECIFIC_GUARDRAILS}}

package/system/templates/settings.json.tmpl

@@ -0,0 +1,201 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Read(*)",
+      "Write(*)",
+      "Edit(*)",
+      "Glob(*)",
+      "Grep(*)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "Task(*)",
+      "NotebookEdit(*)",
+      "mcp__playwright",
+      "mcp__sequential-thinking"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf .)"
+    ],
+    "defaultMode": "{{AUTONOMY_PERMISSIONS}}"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'echo \"Git: branch=$(git branch --show-current 2>/dev/null || echo none) | uncommitted=$(git status --short 2>/dev/null | wc -l | tr -d \" \") files | recent: $(git log --oneline -3 2>/dev/null || echo none)\"; GLOBAL_GR=\"$HOME/.claude/guardrails.md\"; PROJECT_GR=\"${CLAUDE_PROJECT_DIR:-.}/.claude/guardrails.md\"; if [ -f \"$GLOBAL_GR\" ]; then echo \"=== GLOBAL GUARDRAILS ===\"; cat \"$GLOBAL_GR\"; echo \"=== END GUARDRAILS ===\"; fi; if [ -f \"$PROJECT_GR\" ] && [ \"$PROJECT_GR\" != \"$GLOBAL_GR\" ]; then echo \"=== PROJECT GUARDRAILS ===\"; cat \"$PROJECT_GR\"; echo \"=== END PROJECT GUARDRAILS ===\"; fi'",
+            "statusMessage": "Loading git context & guardrails..."
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; echo \"=== POST-COMPACTION CONTEXT ===\"; echo \"Branch: $(git branch --show-current 2>/dev/null)\"; echo \"Modified: $(git diff --name-only 2>/dev/null | tr \"\\n\" \", \")\"; echo \"Staged: $(git diff --cached --name-only 2>/dev/null | tr \"\\n\" \", \")\"; echo \"Last 5 commits: $(git log --oneline -5 2>/dev/null)\"; echo \"Rules: {{PACKAGE_MANAGER}} (not others). Check DESIGN.md before UI work.\"; if [ -f DESIGN.md ]; then echo \"DESIGN.md exists — follow it.\"; fi; if [ -f .claude/logs/tool-failures.jsonl ]; then echo \"Recent errors:\"; tail -3 .claude/logs/tool-failures.jsonl 2>/dev/null; fi; GLOBAL_GR=\"$HOME/.claude/guardrails.md\"; PROJECT_GR=\"${CLAUDE_PROJECT_DIR:-.}/.claude/guardrails.md\"; if [ -f \"$GLOBAL_GR\" ]; then echo \"=== GUARDRAILS ===\"; head -50 \"$GLOBAL_GR\"; echo \"=== END ===\"; fi; if [ -f \"$PROJECT_GR\" ] && [ \"$PROJECT_GR\" != \"$GLOBAL_GR\" ]; then echo \"=== PROJECT GUARDRAILS ===\"; head -30 \"$PROJECT_GR\"; echo \"=== END ===\"; fi; echo \"=== END CONTEXT ===\"'",
+            "statusMessage": "Re-injecting context..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); for p in \".env\" \".env.local\" \".env.production\" \"secrets/\" \".git/\" \"package-lock.json\" \"pnpm-lock.yaml\" \"Pipfile.lock\" \"poetry.lock\" \"Package.resolved\" \"Cargo.lock\"; do if [[ \"$FILE\" == *\"$p\"* ]]; then echo \"Blocked: protected file pattern \\\"$p\\\"\" >&2; exit 2; fi; done; exit 0'",
+            "statusMessage": "Checking file protection..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'CMD=$(jq -r \".tool_input.command\" <<< \"$(cat)\"); for p in \"rm -rf /\" \"rm -rf ~\" \"drop table\" \"DROP TABLE\" \"truncate table\" \"TRUNCATE TABLE\" \"push.*--force\" \"--force.*push\" \"reset --hard origin\"; do if echo \"$CMD\" | grep -qiE \"$p\"; then echo \"Blocked: destructive pattern \\\"$p\\\" detected\" >&2; exit 2; fi; done; exit 0'",
+            "statusMessage": "Checking command safety..."
+          },
+          {
+            "type": "command",
+            "command": "bash -c 'CMD=$(jq -r \".tool_input.command\" <<< \"$(cat)\"); if echo \"$CMD\" | grep -qE \"^git commit\"; then MSG=$(echo \"$CMD\" | grep -oP \"(?<=-m \\\")[^\\\"]+|(?<=-m \\x27)[^\\x27]+\" || echo \"\"); if [ -n \"$MSG\" ] && [ ${#MSG} -lt 10 ]; then echo \"Commit message too short (min 10 chars). Be descriptive.\" >&2; exit 2; fi; fi; exit 0'",
+            "statusMessage": "Checking commit message..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path\" <<< \"$(cat)\"); EXT=\"${FILE##*.}\"; case \"$EXT\" in {{FORMATTER_GLOB}}) {{FORMATTER_COMMAND}} \"$FILE\" 2>/dev/null;; esac; exit 0'",
+            "timeout": 15,
+            "statusMessage": "Auto-formatting..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'jq -r \".tool_input.command\" <<< \"$(cat)\" | while IFS= read -r cmd; do echo \"$(date +%Y-%m-%dT%H:%M:%S) [$(pwd)] $cmd\" >> ~/.claude/command-audit.log; done; exit 0'",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'INPUT=$(cat); TOOL=$(echo \"$INPUT\" | jq -r \".tool_name\"); ERROR=$(echo \"$INPUT\" | jq -r \".error // empty\" | head -3); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command // .tool_input.file_path // empty\" | head -1); mkdir -p \"${CLAUDE_PROJECT_DIR:-.}/.claude/logs\"; echo \"{\\\"ts\\\":\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\",\\\"tool\\\":\\\"$TOOL\\\",\\\"input\\\":\\\"$(echo $CMD | tr '\"' \"'\" | cut -c1-100)\\\",\\\"error\\\":\\\"$(echo $ERROR | tr '\"' \"'\" | tr \"\\n\" \" \" | cut -c1-200)\\\"}\" >> \"${CLAUDE_PROJECT_DIR:-.}/.claude/logs/tool-failures.jsonl\"; exit 0'",
+            "statusMessage": "Logging error pattern...",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'INPUT=$(cat); TRANSCRIPT=$(echo \"$INPUT\" | jq -r \".transcript_path // empty\"); if [ -n \"$TRANSCRIPT\" ] && [ -f \"$TRANSCRIPT\" ]; then BACKUP_DIR=\"${CLAUDE_PROJECT_DIR:-.}/.claude/backups\"; mkdir -p \"$BACKUP_DIR\"; cp \"$TRANSCRIPT\" \"$BACKUP_DIR/transcript_$(date +%Y%m%d_%H%M%S).jsonl\"; ls -t \"$BACKUP_DIR\"/transcript_*.jsonl 2>/dev/null | tail -n +6 | xargs rm -f 2>/dev/null; fi; exit 0'",
+            "statusMessage": "Backing up transcript..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Evaluate if Claude should stop. Context: $ARGUMENTS\n\nCheck:\n1. Were ALL user-requested tasks completed (not just attempted)?\n2. Any unresolved errors or failed operations?\n3. If code was changed, was it verified (no obvious type errors, no broken imports)?\n4. Any TODO/FIXME comments added but not resolved?\n\nIMPORTANT: If stop_hook_active is true in the input, this is a second pass — be lenient and only block for critical unfinished work. Never block twice in a row for the same reason.\n\nRespond {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"what remains\"} to continue.",
+            "timeout": 30,
+            "statusMessage": "Verifying work completion..."
+          },
+          {
+            "type": "agent",
+            "prompt": "Check if meaningful code changes were made in this session by running: git diff --stat HEAD 2>/dev/null\n\nIf there are staged or unstaged changes to source code files (not just config/formatting):\n1. Read the current CHANGELOG.md if it exists\n2. Add entries under [Unreleased] following Keep a Changelog format (Added/Changed/Fixed/Removed)\n3. If CHANGELOG.md doesn't exist, create it with a proper header and the current changes\n\nIf changes are trivial (only formatting, only comments, only config), skip and respond {\"ok\": true}.\nIf stop_hook_active is true, respond {\"ok\": true} immediately — do not update CHANGELOG on second pass.\n\nContext: $ARGUMENTS",
+            "timeout": 60,
+            "statusMessage": "Updating CHANGELOG..."
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A subagent just finished its work. Review the output in $ARGUMENTS.\n\nCheck the last_assistant_message field:\n1. Did the subagent actually complete its assigned task (not just describe findings)?\n2. Did it leave placeholder code, TODO comments, or incomplete implementations?\n3. If it was supposed to write/edit files, did it actually do so?\n\nIf complete, respond {\"ok\": true}.\nIf incomplete, respond {\"ok\": false, \"reason\": \"specific description of what the subagent still needs to do\"}.",
+            "timeout": 30,
+            "statusMessage": "Verifying subagent work..."
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A teammate just became idle. Context: $ARGUMENTS\n\nCheck:\n1. Are all their assigned tasks completed?\n2. Are there unclaimed tasks in the shared task list they could pick up?\n3. Should they assist another teammate who is blocked?\n\nRespond {\"ok\": true} to let them stop, or {\"ok\": false, \"reason\": \"description of remaining work\"} to assign more.",
+            "timeout": 30,
+            "statusMessage": "Checking teammate workload..."
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'INPUT=$(cat); TASK=$(echo \"$INPUT\" | jq -r \".task_id // empty\"); AGENT=$(echo \"$INPUT\" | jq -r \".agent_name // empty\"); mkdir -p \"${CLAUDE_PROJECT_DIR:-.}/.claude/logs\"; echo \"$(date +%Y-%m-%dT%H:%M:%S) TASK_DONE: $TASK by $AGENT\" >> \"${CLAUDE_PROJECT_DIR:-.}/.claude/logs/team-activity.log\"; exit 0'",
+            "statusMessage": "Logging task completion...",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "permission_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\" sound name \"Ping\"'"
+          }
+        ]
+      },
+      {
+        "matcher": "idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\" sound name \"Glass\"'"
+          }
+        ]
+      }
+    ]
+  },
+  "skipDangerousModePermissionPrompt": true,
+  "effortLevel": "high"
+}

package/workshop/knowledge/01-prd-template.md

@@ -0,0 +1,275 @@
+# PRD Template — Agent-Ready
+
+This template produces PRDs that can be handed directly to Claude Code, GSD, or any AI coding agent for autonomous implementation.
+
+---
+
+## Standard PRD Template
+
+````markdown
+# PRD: [Feature Name]
+
+## Problem
+
+What is the problem? Why does it need to be solved? Include business context and who is affected.
+
+[2-4 sentences. Be specific about the pain point and its impact.]
+
+## Goal
+
+What should work when this is done? Measurable outcome.
+
+[1-3 sentences. Include success metrics if possible.]
+
+## User Stories
+
+- As a [role], I want to [action], so that [benefit]
+- As a [role], I want to [action], so that [benefit]
+- As a [role], I want to [action], so that [benefit]
+
+[Use Jobs-to-be-Done framing: focus on the motivation behind the action, not just the action itself.]
+
+## Acceptance Criteria
+
+Each criterion must be independently testable. Use Given/When/Then format for complex criteria.
+
+- [ ] AC1: [Concrete, testable criterion]
+- [ ] AC2: [Concrete, testable criterion]
+- [ ] AC3: Given [precondition], When [action], Then [expected result]
+- [ ] AC4: Given [precondition], When [action], Then [expected result]
+
+[Every criterion must map to at least one automated test. If you cannot write a test for it, it is not concrete enough.]
+
+## Scope
+
+### In Scope
+
+- Feature X
+- Screen Y
+- API Endpoint Z
+- [List everything that IS being built]
+
+### Out of Scope
+
+- What should NOT be built (explicit boundaries)
+- Future features that are intentionally deferred
+- Related functionality that belongs to a different PRD
+- [Be explicit — vague boundaries cause scope creep]
+
+## Data Model
+
+### Tables
+
+#### [table_name]
+
+| Column     | Type        | Constraints                     | Description           |
+| ---------- | ----------- | ------------------------------- | --------------------- |
+| id         | uuid        | PK, default gen_random_uuid()   | Primary key           |
+| org_id     | uuid        | FK → organizations.id, NOT NULL | Tenant isolation      |
+| [field]    | [type]      | [constraints]                   | [description]         |
+| created_at | timestamptz | NOT NULL, default now()         | Creation timestamp    |
+| updated_at | timestamptz | NOT NULL, default now()         | Last update timestamp |
+
+### Relations
+
+- [table_a] belongs to [table_b] via [foreign_key]
+- [table_a] has many [table_c] via [foreign_key]
+
+### RLS Policies
+
+- [table_name]: Users can only [SELECT/INSERT/UPDATE/DELETE] rows where org_id matches their organization
+- [table_name]: Only admins can [specific operation]
+
+### Indexes
+
+- [table_name]: unique index on [columns]
+- [table_name]: index on [columns] (query pattern: [describe])
+
+## API Design
+
+### [HTTP_METHOD] /api/[resource]
+
+**Purpose:** [What this endpoint does]
+
+**Authentication:** Required / Public
+
+**Request:**
+
+```json
+{
+  "field": "type — description"
+}
+```
+````
+
+**Response (200):**
+
+```json
+{
+  "data": {
+    "id": "uuid",
+    "field": "value"
+  }
+}
+```
+
+**Error Responses:**
+
+- 400: [When and why]
+- 401: [When and why]
+- 403: [When and why]
+- 404: [When and why]
+- 429: [Rate limit details]
+
+[Repeat for each endpoint]
+
+## UI/UX
+
+- [Layout description or Figma link]
+- [Responsive requirements and breakpoints]
+- [Key interaction patterns]
+- [Empty states, loading states, error states]
+
+## Constraints
+
+- Performance: [latency, throughput requirements]
+- Dependencies: [external services, existing features]
+- Security: [specific security requirements beyond standard]
+- Timeline: [if applicable]
+
+````
+
+---
+
+## Agent-Ready Extension
+
+For autonomous implementation (Ralph Loop, GSD, or full-auto Claude Code), add these three sections to the PRD:
+
+```markdown
+## Quality Gates
+
+Automated checks that MUST pass before the feature is considered done:
+
+- Build: `pnpm build` — 0 errors
+- Types: `tsc --noEmit` — 0 errors
+- Tests: `pnpm vitest run` — all pass, 80%+ coverage on new code
+- Lint: `pnpm lint` — 0 errors, 0 warnings
+- E2E: `npx playwright test` — all pass (if applicable)
+- Security: `/code-review` — no OWASP vulnerabilities
+- RLS: Supabase security advisor — no warnings (if DB changes)
+- No Debug Logs: 0 `console.log` in production code
+- Type Safety: no `any`, no `as` casts in new code
+- File Size: no file exceeds 300 lines
+- Custom: [project-specific checks]
+
+## Autonomy Rules
+
+Where the AI agent can make its own decisions vs. where it must follow strict guidelines:
+
+- Design decisions: [Follow DESIGN.md / use best judgment / ask]
+- Library choices: [use existing dependencies only / free to add / predefined list]
+- Architecture: [follow existing patterns in src/lib/ / free to decide]
+- File structure: [follow project conventions / free to organize]
+- Error messages: [follow i18n patterns / English only / free to decide]
+- On ambiguity: [decide autonomously and document / stop and ask]
+
+## Completion Promise
+
+The exact phrase that must be 100% true before the agent may declare the feature done:
+
+"[All acceptance criteria met, build passes, all tests pass, 0 lint errors, no console.log in production code]"
+
+[This phrase is used as the --completion-promise for Ralph Loop or as the exit criterion for GSD execute-phase.]
+````
+
+---
+
+## Prompt Templates for Handoff
+
+### Standard Prompt (for Claude Code)
+
+```
+Implement the following feature autonomously from database to frontend.
+
+<workflow>
+1. /plan — Create implementation plan, wait for approval
+2. After approval: /tdd (tests first, then code)
+3. /verify after each phase
+4. /e2e for critical user journeys
+5. /code-review at the end
+6. Do NOT commit — show the final git diff
+</workflow>
+
+<prd>
+[INSERT COMPLETE PRD HERE]
+</prd>
+
+<context>
+- Project: [project name/path]
+- Supabase Project ID: [ID] (if applicable)
+- Follow existing patterns in: [relevant files/directories]
+</context>
+```
+
+### Ralph Loop Prompt (for full autonomy)
+
+```
+/ralph-loop Implement [feature name] per the PRD below.
+
+<workflow>
+Each iteration:
+1. Check current state (git diff, test results)
+2. Implement the next logical step
+3. Run quality gates after every significant change
+4. When ALL criteria pass: output <promise>[COMPLETION PROMISE]</promise>
+</workflow>
+
+<quality_gates>
+[INSERT Quality Gates from PRD]
+</quality_gates>
+
+<autonomy_rules>
+[INSERT Autonomy Rules from PRD]
+</autonomy_rules>
+
+<prd>
+[INSERT COMPLETE PRD]
+</prd>
+
+--max-iterations [N] --completion-promise '[COMPLETION PROMISE]'
+```
+
+### GSD Prompt (for GSD framework)
+
+```
+/gsd:new-project
+
+[Paste the PRD when GSD asks for project description.
+GSD will handle the rest: research, planning, execution, verification.]
+```
+
+---
+
+## Max-Iterations Guide
+
+| PRD Complexity    | Suggested Max-Iterations | Rationale                       |
+| ----------------- | ------------------------ | ------------------------------- |
+| Bugfix            | 10                       | Find + Fix + Test               |
+| Small (1-3 AC)    | 20                       | Single endpoint, simple UI      |
+| Standard (4-8 AC) | 30                       | DB + API + Frontend + Tests     |
+| Large (9+ AC)     | 50                       | Multi-domain, complex UI, E2E   |
+| Refactoring       | 15                       | Scoped changes, little new code |
+
+---
+
+## Completion Promise Examples
+
+| Feature Type  | Promise                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| Standard      | "All tests pass, build succeeds, 0 lint errors, no console.log in production code"        |
+| With E2E      | "All unit tests pass, all e2e tests pass, build succeeds, 0 lint errors"                  |
+| Bugfix        | "Bug is fixed, regression test added and passing, build succeeds"                         |
+| With Supabase | "Migration applied, RLS policies active, all tests pass, build succeeds, types generated" |
+| Refactoring   | "All tests pass, no dead code, build succeeds, 0 lint errors"                             |
+
+> **Note:** Any PRD that includes DB changes (new tables, schema modifications) should include "types generated" in the completion promise. This ensures the type-safety chain (DB schema → generated types → Zod schemas → API → frontend) remains intact. See the "With Supabase" row above for an example.