@aslomon/effectum 0.1.0

package/system/README.md

@@ -0,0 +1,118 @@
+# system/ — Autonomous Development System
+
+Configuration templates, stack presets, and workflow definitions for the Claude Code autonomous development system.
+
+## Directory Structure
+
+```
+system/
+  templates/                    # Parameterized config templates
+    CLAUDE.md.tmpl              # Project CLAUDE.md ({{PLACEHOLDER}} syntax)
+    settings.json.tmpl          # Claude Code settings with hooks
+    guardrails.md.tmpl          # Guardrails with stack-specific sections
+    AUTONOMOUS-WORKFLOW.md      # Full workflow reference (not a template)
+  stacks/                       # Stack presets (inject into templates)
+    nextjs-supabase.md          # Next.js + TypeScript + Supabase
+    python-fastapi.md           # Python + FastAPI + SQLAlchemy
+    swift-ios.md                # Swift + SwiftUI + SwiftData
+    generic.md                  # Stack-agnostic baseline
+  commands/                     # Slash command definitions (future)
+```
+
+## How It Works
+
+### 1. Templates
+
+Files in `templates/` use `{{PLACEHOLDER}}` syntax for values that vary per project. During `/setup`, placeholders are substituted with values from the selected stack preset and user input.
+
+**Template placeholders:**
+
+| Placeholder                     | Source       | Example Value                           |
+| ------------------------------- | ------------ | --------------------------------------- |
+| `{{PROJECT_NAME}}`              | User input   | `TaskFlow SaaS`                         |
+| `{{LANGUAGE}}`                  | User input   | `English` or `German (du/informal)`     |
+| `{{TECH_STACK}}`                | Stack preset | Full tech stack description             |
+| `{{ARCHITECTURE_PRINCIPLES}}`   | Stack preset | Architecture rules for the stack        |
+| `{{PROJECT_STRUCTURE}}`         | Stack preset | Directory layout                        |
+| `{{QUALITY_GATES}}`             | Stack preset | Build/test/lint commands                |
+| `{{PACKAGE_MANAGER}}`           | Stack preset | `pnpm`, `uv`, `swift package`, etc.     |
+| `{{FORMATTER}}`                 | Stack preset | `npx prettier --write`, `ruff format`   |
+| `{{FORMATTER_COMMAND}}`         | Stack preset | Shell command for the formatter         |
+| `{{FORMATTER_GLOB}}`            | Stack preset | File extensions to auto-format          |
+| `{{STACK_SPECIFIC_GUARDRAILS}}` | Stack preset | Stack-specific rules                    |
+| `{{TOOL_SPECIFIC_GUARDRAILS}}`  | Stack preset | Tool-specific rules                     |
+| `{{AUTONOMY_PERMISSIONS}}`      | User input   | `bypassPermissions` or `askPermissions` |
+
+### 2. Stack Presets
+
+Files in `stacks/` define all stack-specific values as named sections. Each section corresponds to a template placeholder. The `/setup` command reads the selected preset and injects its values into the templates.
+
+**Available presets:**
+
+| Preset             | File                 | Use Case                            |
+| ------------------ | -------------------- | ----------------------------------- |
+| Next.js + Supabase | `nextjs-supabase.md` | Full-stack web apps                 |
+| Python + FastAPI   | `python-fastapi.md`  | Backend services and APIs           |
+| Swift + iOS        | `swift-ios.md`       | Native Apple platform apps          |
+| Generic            | `generic.md`         | Any stack (user fills in specifics) |
+
+**Adding a new preset:**
+
+1. Copy `generic.md` as a starting point
+2. Fill in all sections (TECH_STACK, ARCHITECTURE_PRINCIPLES, etc.)
+3. Save as `stacks/{name}.md`
+4. The preset is automatically available during `/setup`
+
+### 3. Setup Flow
+
+When `/setup` runs in a target project:
+
+1. User selects a stack preset (or `generic`)
+2. User provides project name and preferences
+3. Templates are rendered with preset values + user input
+4. Generated files are written to the target project:
+   - `.claude/CLAUDE.md` (from `CLAUDE.md.tmpl`)
+   - `.claude/settings.json` (from `settings.json.tmpl`)
+   - `.claude/guardrails.md` (from `guardrails.md.tmpl`)
+5. `AUTONOMOUS-WORKFLOW.md` is copied as-is (reference doc, no substitution)
+
+### 4. Fixed vs. Templated Content
+
+**Fixed (same in every project):**
+
+- Code Quality Rules (40-line functions, 300-line files, naming conventions)
+- Development Workflow (/plan, /tdd, /verify, /code-review)
+- Available Commands table
+- Context7 usage instructions
+- Design System (DESIGN.md requirement)
+- Agent Teams section
+- Shell command rules (non-interactive only)
+- Tool usage guidelines
+- Commit conventions
+- All hooks in settings.json (SessionStart, PreToolUse, PostToolUse, Stop, etc.)
+- All error patterns and workflow lessons in guardrails
+
+**Templated (varies per stack):**
+
+- Tech stack description
+- Architecture principles
+- Project structure
+- Quality gate commands
+- Package manager
+- Formatter command and file glob
+- Stack-specific and tool-specific guardrails
+
+## Relationship to AUTONOMOUS-WORKFLOW.md
+
+The `AUTONOMOUS-WORKFLOW.md` file is a comprehensive reference document covering:
+
+- PRD template and best practices
+- Prompt templates (Standard, Express, Full-Auto, Ralph Loop)
+- Workflow phases (Planning, DB, Backend, Frontend, E2E, Verification)
+- Command chains by feature type
+- Quality gates
+- Agent Teams usage
+- Ralph Loop configuration
+- Lessons learned from real sessions
+
+It is NOT a template — it is copied as-is into target projects as a workflow reference.

package/system/commands/build-fix.md

@@ -0,0 +1,89 @@
+# /build-fix -- Incrementally Fix Build and Type Errors
+
+You fix build and type errors one at a time, re-running the build after each fix. You never suppress errors or skip warnings to force a passing build.
+
+## Step 1: Run the Build
+
+1. Read `CLAUDE.md` to identify the project's build command and type-check command.
+2. Run the build command.
+3. If the build succeeds with zero errors: report success and stop.
+
+## Step 2: Analyze Build Output
+
+If the build fails:
+
+1. Read the **complete** error output -- every error, every warning.
+2. Count the total number of errors.
+3. Categorize the errors:
+   - **Type errors**: Missing types, incompatible types, missing properties.
+   - **Import errors**: Missing modules, wrong paths, circular dependencies.
+   - **Syntax errors**: Malformed code, missing brackets, invalid expressions.
+   - **Configuration errors**: Missing environment variables, wrong settings.
+   - **Dependency errors**: Missing packages, version conflicts.
+
+## Step 3: Fix One Error at a Time
+
+Pick the **first** error in the output (errors often cascade -- fixing the first frequently resolves downstream errors).
+
+1. Read the source file referenced in the error.
+2. Understand the error: what is expected vs. what exists.
+3. Apply a **targeted fix** -- change only what is necessary to resolve this specific error.
+   - For type errors: add correct types, fix interfaces, use type guards. Never use `any` or unsafe casts.
+   - For import errors: fix the import path, add the missing export, or install the missing package.
+   - For syntax errors: fix the syntax.
+   - For configuration errors: check CLAUDE.md and project config files for the correct values.
+   - For dependency errors: install the missing package using the project's package manager (as specified in CLAUDE.md).
+
+4. **Do NOT**:
+   - Add `// @ts-ignore`, `// @ts-expect-error`, or equivalent suppressions.
+   - Change `strict` mode settings or compiler options to be more permissive.
+   - Delete code to make errors disappear.
+   - Add `any` types to bypass type checking.
+
+## Step 4: Re-Run the Build
+
+1. Run the build command again after the fix.
+2. Compare the error count to the previous run:
+   - Fewer errors: good -- the fix worked and may have resolved cascading errors.
+   - Same number: the fix resolved one error but uncovered another.
+   - More errors: the fix introduced new problems -- revert it and try a different approach.
+
+## Step 5: Repeat
+
+Go back to Step 3 with the next error. Continue until:
+
+- **Build passes**: Report success. List the fixes applied.
+- **10 fix attempts reached**: Stop and report the current state:
+  - How many errors were fixed.
+  - How many errors remain.
+  - The remaining error messages with file paths and line numbers.
+  - Ask the user for guidance on the remaining errors.
+
+## Step 6: Also Run Type Check (if separate)
+
+If the project has a separate type-check command (distinct from the build command):
+
+1. Run the type-check command after the build passes.
+2. If type errors exist: repeat Steps 3-5 for type errors.
+
+## Step 7: Report
+
+Present a summary:
+
+```
+| Metric             | Value                    |
+| ------------------ | ------------------------ |
+| Initial errors     | 12                       |
+| Errors fixed       | 12                       |
+| Remaining errors   | 0                        |
+| Fix attempts       | 8 (some fixes cascaded)  |
+| Build status       | PASS                     |
+| Type check status  | PASS                     |
+```
+
+If errors remain, list each one with file, line, error message, and what was attempted.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All error messages and technical content in English.

package/system/commands/cancel-ralph.md

@@ -0,0 +1,90 @@
+# /cancel-ralph -- Cancel an Active Ralph Loop
+
+You gracefully cancel a running Ralph Loop, preserve progress, and report the current state.
+
+## Step 1: Check for Active Loop
+
+Check if `.claude/ralph-loop.local.md` exists.
+
+- **If it does not exist**: Inform the user: "No active Ralph Loop found. There is nothing to cancel."
+  **STOP.**
+
+- **If it exists**: Read the file completely. Check the `active` field:
+  - If `active: false`: Inform the user: "The Ralph Loop has already completed or been cancelled. See `.claude/ralph-status.md` for the final status."
+    **STOP.**
+  - If `active: true`: Continue to Step 2.
+
+## Step 2: Capture Current State
+
+Gather the current project state:
+
+1. Read the progress log from `.claude/ralph-loop.local.md` (iterations completed, what was done).
+2. Read the original prompt and completion promise.
+3. Run `git diff --stat` to see uncommitted changes.
+4. Run the project's test command to get current test status.
+5. Run the project's build command to get current build status.
+6. Check for any blocker files at `.claude/ralph-blockers.md`.
+
+## Step 3: Write Status Report
+
+Write a comprehensive status report to `.claude/ralph-status.md`:
+
+```markdown
+# Ralph Loop Status Report
+
+## Summary
+
+- **Started**: [ISO timestamp from state file]
+- **Cancelled**: [current ISO timestamp]
+- **Iterations completed**: [N] of [max_iterations]
+- **Completion promise**: "[PHRASE]"
+- **Promise fulfilled**: No (cancelled)
+
+## What Was Implemented
+
+[List each piece of functionality that was implemented, based on the progress log]
+
+## What Remains
+
+[List acceptance criteria or tasks that were not completed]
+
+## Current Quality Gate Status
+
+| Gate  | Status                     |
+| ----- | -------------------------- |
+| Build | [PASS/FAIL]                |
+| Types | [PASS/FAIL]                |
+| Tests | [PASS/FAIL -- N/M passing] |
+| Lint  | [PASS/FAIL]                |
+
+## Blockers (if any)
+
+[Content from .claude/ralph-blockers.md, or "None"]
+
+## Uncommitted Changes
+
+[Summary of git diff --stat output]
+
+## Recommended Next Steps
+
+[Concrete suggestions for how to continue: specific fixes, remaining tasks, approach changes]
+```
+
+## Step 4: Update State File
+
+Set `active: false` in `.claude/ralph-loop.local.md`. Do not delete the file -- it serves as a record.
+
+## Step 5: Inform the User
+
+Report to the user:
+
+1. The Ralph Loop has been cancelled.
+2. How many iterations were completed out of the maximum.
+3. Brief summary of what was accomplished.
+4. Where to find the full status report (`.claude/ralph-status.md`).
+5. Suggested next steps: continue manually, restart with a modified prompt, or run `/verify` to assess the current state.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All status report content and technical details in English.

package/system/commands/checkpoint.md

@@ -0,0 +1,63 @@
+# /checkpoint -- Create a Git Restore Point
+
+You create a tagged git commit as a safe restore point. This allows easy rollback if subsequent changes need to be undone.
+
+## Step 1: Check Current State
+
+Run `git status` to assess the working tree.
+
+- **If there are no changes** (clean working tree, nothing to commit):
+  Inform the user: "Nothing to checkpoint -- the working tree is clean. The latest commit is already a valid restore point."
+  Show the current HEAD commit hash and message for reference.
+  **STOP.**
+
+- **If there are uncommitted changes** (tracked modifications, untracked files, or staged changes):
+  Continue to Step 2.
+
+## Step 2: Summarize Changes
+
+Briefly analyze what has changed:
+
+1. Run `git diff --stat` to see modified files.
+2. Run `git status` to see untracked and staged files.
+3. Generate a brief description of the current state (1 sentence), e.g.:
+   - "Added user invitation API routes and tests"
+   - "Partial implementation of dark mode toggle"
+   - "Build fixes for type errors in auth module"
+
+## Step 3: Create the Checkpoint
+
+1. Stage all changes:
+
+   ```
+   git add -A
+   ```
+
+2. Create the commit with a descriptive checkpoint message:
+
+   ```
+   git commit -m "checkpoint: [brief description of current state]"
+   ```
+
+3. Create a timestamp-based tag for easy identification:
+   ```
+   git tag checkpoint-[YYYY-MM-DD-HHMMSS]
+   ```
+   Use the current date and time in the format `YYYY-MM-DD-HHMMSS` (e.g., `checkpoint-2025-01-15-143022`).
+
+## Step 4: Report
+
+Show the user:
+
+1. The commit hash (short form).
+2. The tag name.
+3. Summary of what was included (files changed, insertions, deletions).
+4. Rollback instructions:
+   - **Soft rollback** (keep changes as uncommitted): `git reset --soft [commit-hash]`
+   - **View checkpoint**: `git show [tag-name]`
+   - **List all checkpoints**: `git tag -l "checkpoint-*"`
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All git messages, tag names, and technical content in English.

package/system/commands/code-review.md

@@ -0,0 +1,120 @@
+# /code-review -- Security and Quality Review
+
+You perform a thorough security and code quality review of all changes. You report findings with severity levels and suggested fixes.
+
+## Step 1: Identify Changes to Review
+
+Determine the scope of the review:
+
+1. Run `git diff` to see all uncommitted changes (staged + unstaged).
+2. If on a feature branch: also run `git diff main...HEAD` (or the project's base branch) to see all branch changes.
+3. If `$ARGUMENTS` specifies files or directories: focus the review on those.
+4. List all changed files with their change type (added, modified, deleted).
+
+## Step 2: Read All Changed Files
+
+Read every changed file **completely** -- not just the diff hunks. Understanding the full file context is necessary for accurate review. Also read closely related files (imports, callers, types) when needed for context.
+
+## Step 3: Security Review (OWASP Top 10)
+
+Review all changes against these security criteria:
+
+1. **Injection (SQL, NoSQL, Command)**
+   - Are all database queries parameterized?
+   - Are user inputs sanitized before use in commands or queries?
+   - Are ORMs or query builders used correctly?
+
+2. **Broken Authentication**
+   - Are authentication checks present on all protected routes?
+   - Are session tokens handled securely?
+   - Are passwords hashed with a strong algorithm?
+
+3. **Sensitive Data Exposure**
+   - Are secrets, API keys, or credentials hardcoded in source code?
+   - Is sensitive data logged or exposed in error messages?
+   - Are environment variables used for configuration?
+
+4. **Broken Access Control**
+   - Are authorization checks present (role-based, ownership-based)?
+   - Are database-level access controls in place (RLS policies, row ownership)?
+   - Can users access resources that belong to other users or organizations?
+
+5. **Cross-Site Scripting (XSS)**
+   - Is user-generated content properly escaped/encoded before rendering?
+   - Are `dangerouslySetInnerHTML` or equivalent patterns justified and sanitized?
+
+6. **CSRF Protection**
+   - Are state-changing operations protected against CSRF?
+   - Are anti-CSRF tokens used where applicable?
+
+7. **Security Misconfiguration**
+   - Are CORS policies restrictive?
+   - Are security headers set (CSP, X-Frame-Options, etc.)?
+   - Are default credentials or debug modes disabled?
+
+## Step 4: Code Quality Review
+
+Review against these quality criteria:
+
+1. **Function Length**: Flag functions exceeding 40 lines. Suggest extraction points.
+2. **File Length**: Flag files exceeding 300 lines. Suggest splitting strategies.
+3. **Naming**: Check for descriptive names. Flag abbreviations, single-letter variables (outside loops), or Hungarian notation.
+4. **Error Handling**: Verify errors are handled explicitly (Result pattern, try-catch with meaningful handling). Flag swallowed errors (empty catch blocks, ignored return values).
+5. **Debug Statements**: Flag `console.log`, `console.debug`, `print()`, `debugger`, `breakpoint()` in production code (not test files).
+6. **Dead Code**: Flag unused imports, unreachable code, commented-out code blocks.
+7. **Duplication**: Flag duplicated logic that should be extracted into shared utilities.
+
+## Step 5: Type Safety Review
+
+Review type usage:
+
+1. **No `any` types**: Flag every use of `any` (or equivalent in the project's language). Suggest specific types, generics, or union types.
+2. **No unsafe type casts**: Flag `as` casts (TypeScript), forced unwraps (Swift), or equivalent. Suggest type guards, validation schemas, or runtime checks.
+3. **Null/undefined handling**: Verify proper handling of nullable values. Flag potential null dereferences.
+4. **Validation at boundaries**: Verify that external data (API inputs, form data, environment variables) is validated with schemas before use.
+
+## Step 6: Architecture Review
+
+Review against project conventions:
+
+1. Read `CLAUDE.md` for the project's architectural rules and patterns.
+2. **Separation of concerns**: Flag business logic in UI components, data access in presentation layers.
+3. **Convention compliance**: Verify file organization, naming patterns, import structure follow project conventions.
+4. **Dependency direction**: Verify imports flow in the correct direction (components -> services -> utilities, not the reverse).
+
+## Step 7: Present Findings
+
+Present each finding with:
+
+```
+### [SEVERITY] Description
+
+- **File**: path/to/file.ts
+- **Line**: 42
+- **Issue**: Detailed description of the problem.
+- **Risk**: What could go wrong if this is not fixed.
+- **Fix**: Specific, actionable suggestion for how to fix it.
+```
+
+Severity levels:
+
+| Severity     | Meaning                                                             |
+| ------------ | ------------------------------------------------------------------- |
+| **CRITICAL** | Security vulnerability, data loss risk, or production-breaking bug. |
+| **WARNING**  | Code quality issue, potential bug, or convention violation.         |
+| **INFO**     | Suggestion for improvement, minor style issue, or optimization.     |
+
+## Step 8: Summary
+
+Provide a summary:
+
+1. Total findings by severity: N CRITICAL, N WARNING, N INFO.
+2. Overall assessment: Is this code ready to merge/deploy?
+3. Priority actions: List the top 3 most important fixes.
+4. If zero CRITICAL findings: "No blocking issues found. Code is ready for deployment pending WARNING fixes."
+5. If CRITICAL findings exist: "Blocking issues found. These must be resolved before deployment."
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All technical findings (file paths, code snippets, issue descriptions) in English.

package/system/commands/e2e.md

@@ -0,0 +1,92 @@
+# /e2e -- Write and Run End-to-End Tests
+
+You write and execute end-to-end tests for critical user journeys. Focus on testing the application as a real user would interact with it.
+
+## Step 1: Determine Test Targets
+
+1. Read `CLAUDE.md` for the project's E2E framework, test directory, and conventions.
+2. Parse `$ARGUMENTS`:
+   - If specific test targets are provided (e.g., "login flow", "checkout"): focus on those.
+   - If acceptance criteria are provided: derive test cases from them.
+   - If empty: identify critical user journeys from the PRD, recent changes (`git diff`), or the application's core functionality.
+
+## Step 2: Study Existing Patterns
+
+1. Read existing E2E test files to understand:
+   - Test structure and organization.
+   - Helper functions, fixtures, and page objects.
+   - Authentication and setup patterns.
+   - Selector conventions (data-testid, roles, labels).
+   - Configuration (base URL, timeouts, browser settings).
+2. Read the E2E framework configuration file for project-specific settings.
+
+## Step 3: Plan Test Cases
+
+For each user journey, plan:
+
+1. **Happy path**: The primary success scenario the user is expected to follow.
+2. **Error cases**: Invalid inputs, permission denied, network errors, empty states.
+3. **Edge cases**: Boundary values, concurrent actions, rapid interactions.
+
+Each test must be independent -- no shared state between tests. Each test should set up its own preconditions and clean up after itself.
+
+## Step 4: Write E2E Tests
+
+Write tests using the project's E2E framework (as specified in CLAUDE.md). Follow these principles:
+
+1. **Selectors** (in priority order):
+   - Accessibility-tree-based: `getByRole`, `getByLabel`, `getByPlaceholder` -- most reliable, resilient to UI changes.
+   - `data-testid` attributes -- stable, explicit contract between test and implementation.
+   - Scoped queries -- search within a container element, not globally.
+   - Avoid: CSS classes, tag names, XPath, or text selectors that match multiple elements.
+
+2. **Test structure**:
+   - Descriptive test names that explain the user journey.
+   - Arrange (set up preconditions) -> Act (perform user actions) -> Assert (verify outcomes).
+   - Use the framework's built-in waiting mechanisms instead of hardcoded waits.
+   - Add `data-testid` attributes to source components when no suitable accessible selector exists.
+
+3. **Test isolation**:
+   - Each test starts from a known state (fresh session, seeded data).
+   - Tests do not depend on the execution order of other tests.
+   - Clean up any data or state created during the test.
+
+## Step 5: Run Tests
+
+1. Run the E2E tests using the project's E2E test command (as specified in CLAUDE.md).
+2. Collect the results: pass/fail per test, total duration, any screenshots or traces.
+
+## Step 6: Handle Failures
+
+On test failure, follow the diagnostic sequence **before** attempting any fix:
+
+1. **Read the error message and stack trace** completely.
+2. **Read framework-specific diagnostics**: screenshots, traces, video recordings, accessibility snapshots, HTML snapshots.
+3. **Check execution context**: Is the application running? Are environment variables set? Is the test database seeded?
+4. **Identify root cause**: Is this a test issue (wrong selector, timing) or an application bug?
+5. **Apply a targeted fix** (one change per attempt). Re-run the failing test.
+6. If the same test fails 3 times with different fixes: document the issue and move on. Report it as a blocker.
+
+## Step 7: Report Results
+
+Present results per test:
+
+```
+| Test                          | Status | Duration |
+| ----------------------------- | ------ | -------- |
+| User can sign up and log in   | PASS   | 3.2s     |
+| User sees error on invalid    | PASS   | 1.8s     |
+| Dashboard loads for new user  | FAIL   | 5.0s     |
+```
+
+For failures, include:
+
+- The exact error message.
+- The step that failed.
+- Any diagnostic artifacts (screenshot paths, trace paths).
+- Suggested root cause and fix.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All test names, code, and technical content in English.

package/system/commands/plan.md

@@ -0,0 +1,111 @@
+# /plan -- Analyze Requirements and Create Implementation Plan
+
+You create a detailed implementation plan for a feature, then STOP and wait for explicit approval before writing any code.
+
+## Step 1: Parse Input
+
+Read `$ARGUMENTS` for the feature description, PRD reference, or prompt.
+
+- If `$ARGUMENTS` references a PRD file path: read the entire PRD file.
+- If `$ARGUMENTS` contains inline requirements: use them directly.
+- If `$ARGUMENTS` is empty: ask the user what they want to implement and wait for a response.
+
+## Step 2: Explore the Codebase
+
+Systematically explore the project to build context:
+
+1. Read `CLAUDE.md` in the project root for stack, conventions, and project-specific rules.
+2. Read `DESIGN.md` if it exists for visual/design conventions.
+3. Glob for the project structure: `**/*.{ts,tsx,py,swift,go,rs}` (adapt to the project's language).
+4. Grep for patterns relevant to the feature (existing services, components, utilities, types).
+5. Read key files: entry points, existing similar features, shared utilities, configuration files.
+6. Check for existing tests to understand testing patterns and conventions.
+
+## Step 3: Identify Reusable Assets
+
+Document what already exists that the implementation can leverage:
+
+- Existing components, hooks, or utilities that can be reused or extended.
+- Established patterns for data fetching, error handling, state management, and validation.
+- Shared types, schemas, or interfaces relevant to the feature.
+- Test helpers, fixtures, or factories.
+
+## Step 4: Create the Implementation Plan
+
+Structure the plan in ordered phases with clear dependencies:
+
+### Phase 1: Data Layer (if applicable)
+
+- Database migrations, schema changes, type generation.
+- Validation schemas for new data structures.
+- Estimated complexity: [Low / Medium / High]
+
+### Phase 2: Backend / Services
+
+- API routes, server-side services, business logic.
+- Integration with existing services.
+- Estimated complexity: [Low / Medium / High]
+
+### Phase 3: Frontend / UI (if applicable)
+
+- Components, pages, layouts.
+- Client-side state and interactions.
+- Estimated complexity: [Low / Medium / High]
+
+### Phase 4: Testing
+
+- Unit tests for services and utilities.
+- Integration tests for API routes.
+- Component tests for UI.
+- Estimated complexity: [Low / Medium / High]
+
+### Phase 5: E2E Tests (if applicable)
+
+- Critical user journeys.
+- Edge cases and error scenarios.
+- Estimated complexity: [Low / Medium / High]
+
+### Phase 6: Verification
+
+- Build, type check, lint, full test suite.
+- Code review checklist items.
+
+For each phase, specify:
+
+- What will be created or modified (files, functions, components).
+- Dependencies on other phases.
+- Acceptance criteria that will be verified.
+
+## Step 5: Surface Risks and Open Questions
+
+List explicitly:
+
+- **Risks**: Potential complications, performance concerns, breaking changes.
+- **Open Questions**: Ambiguities in the requirements that need clarification.
+- **Assumptions**: Decisions you would make autonomously (and why).
+- **Dependencies**: External services, libraries, or features this depends on.
+
+## Step 6: Present the Plan
+
+Present the complete plan to the user in a clear, structured format. Include:
+
+1. Summary (1-2 sentences: what this implements and why).
+2. Phased plan with estimated complexity per phase.
+3. Reusable assets identified.
+4. Risks, open questions, and assumptions.
+5. Total estimated complexity.
+
+## Step 7: STOP and Wait
+
+**STOP HERE.** Do NOT write any code, create any files, or make any changes.
+
+Wait for explicit approval from the user:
+
+- **"OK"** or **"Go"** or **"Start"** -> Proceed with implementation (typically via `/tdd`).
+- **"Change X"** -> Revise the plan based on feedback, present again, wait again.
+- **"Start over"** -> Discard the plan and restart from Step 1.
+
+## Communication
+
+Follow the language settings defined in CLAUDE.md for user-facing communication.
+All technical content (code, file paths, plan details) in English.