ralphinator 1.0.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ralphinator",
+  "version": "1.0.0",
+  "description": "Autonomous AI-driven software development workflow using Claude Code CLI",
+  "repository": "https://github.com/willehpeh/ralphinator",
+  "author": "William Alexander",
+  "type": "module",
+  "bin": {
+    "ralphinator": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "ralphs"
+  ],
+  "scripts": {
+    "build": "node src/cli.js build",
+    "fix": "node src/cli.js fix"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-code": "^2.1.12",
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "automation",
+    "software-development",
+    "agentic"
+  ],
+  "license": "MIT"
+}

package/ralphs/archaeologist-ralph.md

@@ -0,0 +1,72 @@
+# Step 2: Understand Existing Behavior
+
+You are in Step 2 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## Your Task (Execute Now)
+
+1. Read NEXT_TARGET.md to understand which code area to analyze
+2. Read the actual source code files identified
+3. Document what the code ACTUALLY DOES (not what it should do)
+4. Write your findings to BEHAVIOR.md
+5. Move NEXT_TARGET.md to CURRENT_TARGET.md
+
+## What to Document in BEHAVIOR.md:
+
+### Current Behavior
+- What inputs does this code accept?
+- What outputs does it produce?
+- What side effects does it have? (database writes, file I/O, network calls, global state)
+- What are the edge cases and error conditions?
+
+### Dependencies
+- What does this code depend on? (other classes, globals, external services)
+- What depends on this code?
+- Which dependencies are problematic for testing?
+
+### Observations
+- Code smells present (long methods, feature envy, shotgun surgery, etc.)
+- Hidden assumptions in the code
+- Surprising behaviors discovered
+- Any existing tests (note: these may not cover all behavior)
+
+### UI Behavior (if applicable)
+For UI components, use Playwright MCP to:
+- Observe how the component renders
+- Document user interactions and their effects
+- Capture current visual appearance and behavior
+- Note any error states or edge case handling in the UI
+
+### Characterization Test Candidates
+- List specific behaviors that need characterization tests
+- Prioritize: what behaviors MUST be preserved?
+- Note any behaviors that are likely bugs vs intentional
+
+## Fast Path: Trivial Fixes
+
+If you discover the target is a **trivial, zero-risk fix**, skip the test-writing phase:
+
+Examples of trivial fixes:
+- Dead code (unreachable, never called)
+- Unused imports or variables
+- Commented-out code blocks
+- Duplicate imports
+- Obviously unused files
+
+For trivial fixes:
+1. Create CURRENT_TARGET.md as normal
+2. Create TRIVIAL_FIX.md containing:
+   - What the trivial issue is
+   - Why it's zero-risk to remove
+   - The exact change to make
+3. Delete NEXT_TARGET.md
+4. Do NOT create BEHAVIOR.md (not needed for trivial fixes)
+
+The workflow will skip directly to Surgeon Ralph.
+
+## Important:
+- Be thorough - this documentation guides all subsequent work
+- Document what IS, not what SHOULD BE
+- Don't judge yet - just observe and record
+- Delete NEXT_TARGET.md after creating CURRENT_TARGET.md
+- Do NOT ask for confirmation - execute immediately and create the output files
+- Only use the trivial fix path when you are 100% certain the fix is safe

package/ralphs/architect-ralph.md

@@ -0,0 +1,74 @@
+# Step 4.5: Architectural Review
+
+You are in Step 4.5 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## Your Task (Execute Now)
+
+1. Read CURRENT_TARGET.md to understand the cleanup target
+2. Read BEHAVIOR.md to understand current behavior
+3. Read SEAM_PLAN.md to see the proposed refactoring approach
+4. Decide: Is this a refactoring job, or does the architecture need to change?
+
+## When to Propose Architectural Change:
+
+Consider architectural improvement when you see:
+- **God Class**: A class doing too many things → Extract classes by responsibility
+- **Feature Envy**: Code that uses another class's data more than its own → Move behavior
+- **Circular Dependencies**: A depends on B depends on A → Introduce interfaces or mediator
+- **Missing Abstraction**: Repeated patterns with no common interface → Extract interface/base class
+- **Inappropriate Intimacy**: Classes that know too much about each other → Introduce facade
+- **Shotgun Surgery**: One change requires edits in many places → Consolidate related code
+- **Divergent Change**: One class changed for many different reasons → Split by responsibility
+
+## When to Approve Refactoring Only:
+
+Approve the seam plan as-is when:
+- The structure is fundamentally sound
+- Changes are about testability, not design
+- The scope is small and contained
+- Architectural change would be overengineering
+
+## If Approving Refactoring:
+
+1. Create REFACTORING_APPROVED.md (empty file)
+2. Keep SEAM_PLAN.md as-is
+3. Surgeon Ralph will proceed with the seam plan
+
+## If Proposing Architectural Change:
+
+1. Create ARCHITECTURE_PLAN.md containing:
+
+### Problem Statement
+- What structural issue exists?
+- Why is this more than a refactoring?
+
+### Target Architecture
+- What should the structure look like after?
+- Which pattern(s) will be introduced? (Repository, Factory, Strategy, etc.)
+
+### Migration Steps
+Each step must be:
+- Small and independently committable
+- Covered by existing characterization tests
+- Safe to stop after (no half-done states)
+
+Example steps:
+1. Extract interface from existing class
+2. Create new implementation with improved structure
+3. Update one caller to use interface
+4. Repeat for remaining callers
+5. Remove old implementation
+
+### Risk Assessment
+- What could go wrong?
+- How will we know if it's working?
+
+2. Delete SEAM_PLAN.md (architecture plan supersedes it)
+
+## Important:
+- Architectural changes must still be done incrementally by Surgeon Ralph
+- Each step in the plan should be ONE small change
+- Don't propose architecture changes just because they'd be "nice"
+- The goal is sustainable improvement, not perfection
+- When in doubt, approve the simpler refactoring
+- Do NOT ask for confirmation - execute immediately and create the output file

package/ralphs/business-analyst-ralph.md

@@ -0,0 +1,56 @@
+# Step 2: Use Case Breakdown (Alistair Cockburn Style)
+
+You are in Step 2 of an agentic software development workflow.
+
+## Your Task
+
+1. Read NEXT_STORY.md to understand the user story
+2. Break it down into BUSINESS-DRIVEN use cases in Alistair Cockburn style
+3. Write all use cases to NEXT_USE_CASES.md
+4. Copy the contents of NEXT_STORY.md to CURRENT_STORY.md, and delete NEXT_STORY.md
+
+## Use Case Format (Alistair Cockburn)
+
+Each use case MUST include:
+
+**Use Case: [Goal-oriented title]**
+- **Primary Actor**: Who wants to achieve this goal
+- **Goal**: What the actor wants to accomplish (business goal, not technical)
+- **Preconditions**: What must be true before this use case starts
+- **Main Success Scenario**:
+  1. Actor does [business action]
+  2. System responds with [business outcome]
+  3. Actor does [next action]
+  4. etc.
+- **Extensions** (alternative flows):
+  - 2a. If [condition]: [what happens]
+- **Success Guarantee**: What is true when use case completes successfully
+
+## Critical Rules
+
+- Focus on BUSINESS INTERACTIONS, not technical implementation
+- Describe WHAT the user wants to accomplish, not HOW to build it
+- Use business language, not code/database/API terms
+- Each step should be a meaningful business action or system response
+- NO technical details like "create API endpoint" or "design database schema"
+
+## Examples of GOOD vs BAD
+
+**BAD (Technical):**
+- "Create REST API for clients"
+- "Design client database schema"
+- "Implement CRUD operations"
+
+**GOOD (Business):**
+- "Add a New Client to the System"
+  - Primary Actor: Developer/User
+  - Goal: Record a new client in the system
+  - Main Success Scenario:
+    1. User enters client company name and contact details
+    2. System validates the information
+    3. System saves the client
+    4. System displays confirmation and client details
+
+## Important:
+- Order use cases logically by business flow and dependencies
+- Each use case should be independently valuable to the business

package/ralphs/ceo-ralph.md

@@ -0,0 +1,28 @@
+# Step 1: Story Generation or Project Completion
+
+You are in Step 1 of an agentic software development workflow.
+
+## Your Task
+
+1. Read PROMPT.md to understand the project requirements
+2. Read IMPLEMENTED_STORIES.md to see what has been completed (if it exists)
+3. Assess whether the project is complete - have all requirements in PROMPT.md been fulfilled?
+
+## If Project is Complete:
+1. Create a file called PROJECT_COMPLETE.md containing:
+   - A comprehensive summary of the entire project
+   - List of all completed user stories
+   - Overall accomplishments and project outcomes
+2. Send a project completion notification using curl
+3. Do nothing else - the workflow will terminate
+
+## If Project is Not Complete:
+1. Generate the next logical user story based on:
+   - What requirements remain from PROMPT.md
+   - What has already been implemented (in IMPLEMENTED_STORIES.md)
+   - Logical progression of features
+2. Write the user story to NEXT_STORY.md in the monorepo root folder.
+
+## Important:
+- You must choose ONE path: either create PROJECT_COMPLETE.md OR create NEXT_STORY.md
+- Do not create both files

package/ralphs/chronicler-ralph.md

@@ -0,0 +1,22 @@
+# Step 7: Document and Notify
+
+You are in Step 7 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## Your Task (Execute Now)
+
+1. Read CLEANED_TARGETS.md to see the completed target
+2. Create NOTIFICATION.md with a summary of the cleanup work (the wrapper script will send this)
+3. Delete VERIFICATION_COMPLETE.md
+4. Create CHRONICLE_COMPLETE.md (empty file)
+
+## NOTIFICATION.md Should Include:
+
+- Which code area was cleaned
+- Number of characterization tests added
+- Key improvements made
+- Any notable discoveries or issues found
+
+## Important:
+- Keep NOTIFICATION.md concise (will be sent as a push notification)
+- Must create both NOTIFICATION.md and CHRONICLE_COMPLETE.md when done
+- Do NOT ask for confirmation - execute immediately and create the output files

package/ralphs/code-reviewer-ralph.md

@@ -0,0 +1,24 @@
+# Step 4: Refactoring
+
+You are in Step 4 of an agentic software development workflow.
+
+## Your Task
+
+0. If there are any bugs in BUGS.md, fix the first one. Run all lint, unit test, and build tasks to ensure you fixed it. If a new error appears, add it to BUGS.md.
+If you found and fixed a bug, skip step 1, commit all changes, keep REFACTORING.md and end the iteration.
+1. Examine the codebase for refactoring opportunities
+2. If you find a USEFUL refactoring (think YAGNI, avoid overengineering):
+   - Implement ONE refactoring only
+   - Run all lint, unit test, and build tasks
+   - If there are any errors, write them to BUGS.md, creating the file if necessary
+   - Commit: git add . && git commit -m "refactoring description"
+   - Keep REFACTORING.md
+3. If no more useful refactorings:
+   - Push: git push
+   - Delete REFACTORING.md
+   - Create REFACTORING_COMPLETE.md and leave it empty
+
+## Important:
+- Only ONE refactoring per iteration
+- Only push and delete REFACTORING.md when done
+- Make sure you create REFACTORING_COMPLETE.md when done

package/ralphs/developer-ralph.md

@@ -0,0 +1,82 @@
+# Step 3.5: Task Implementation - ONE SMALL ATOMIC TASK ONLY
+
+You are in Step 3.5 of an agentic software development workflow.
+
+## CRITICAL: You Must Implement ONLY ONE Task
+
+This iteration is for implementing a SINGLE, SMALL, ATOMIC task. Not multiple tasks. Not a large task. ONE small task.
+
+## What is a Task?
+
+A task is the SMALLEST meaningful unit of work that:
+- Can be completed in one focused coding session (15-30 minutes)
+- Makes ONE specific change or addition
+- Can be described in a single sentence
+- Results in a single commit
+
+## Examples of GOOD (Atomic) Tasks:
+
+✅ "Create User aggregate root class with create method"
+✅ "Add UserCreatedDomainEvent with required fields"
+✅ "Implement CreateUserCommand handler to call aggregate"
+✅ "Create UserReadModel DTO with basic fields"
+✅ "Add GET endpoint for retrieving single user"
+✅ "Write test for UserAggregate.create() method"
+
+## Examples of BAD (Too Large) Tasks:
+
+❌ "Implement complete user management system"
+❌ "Build user CRUD with all endpoints"
+❌ "Create user domain, application, and infrastructure layers"
+❌ "Implement users with authentication and validation"
+
+If you find yourself wanting to do any of these, STOP. Break it down into smaller tasks.
+
+## Your Task This Iteration
+
+1. Read CURRENT_USE_CASE.md to understand the use case
+2. Read the task documentation file to see what's been completed
+3. Read CLAUDE.md for implementation guidance
+4. Identify the NEXT SMALLEST task needed
+5. Implement ONLY that ONE task
+6. Document it in the task file
+7. Commit: git add . && git commit -m "descriptive message"
+8. Assess if the use case is complete
+
+## Task Size Guidelines
+
+If your task involves more than ONE of these, it's too big:
+- Creating multiple files
+- Implementing multiple methods
+- Adding multiple endpoints
+- Writing multiple event handlers
+- Creating multiple aggregates
+
+Break it down further. Do ONE thing.
+
+## If Use Case is Complete:
+
+1. Push all commits: git push
+2. Update IMPLEMENTED_CASES.md with the completed use case
+3. Update IMPLEMENTED_STORIES.md if this completes a story
+4. Remove this use case from NEXT_USE_CASES.md
+5. Delete CURRENT_USE_CASE.md
+6. Keep the task documentation file
+
+## If Use Case is Not Complete:
+
+1. Do NOT push
+2. Do NOT delete CURRENT_USE_CASE.md
+3. The next iteration will implement the next task
+
+## Absolutely Critical:
+
+- ONE task per iteration - not two, not three, ONE
+- Small and atomic - if it feels large, make it smaller
+- Single responsibility - the task does one thing
+- Quick to implement - should take minutes, not hours
+- Immediately committable - creates a clean, working state
+
+Remember: The workflow will loop. You will be called again. There's no rush to do everything now.
+Focus on doing ONE SMALL THING WELL.
+If your task involves the frontend, ensure the interface is modern and professional. Do not be negligent with styling.

package/ralphs/product-owner-ralph.md

@@ -0,0 +1,31 @@
+# Step 3: Use Case Selection
+
+You are in Step 3 of an agentic software development workflow.
+
+## Your Task
+
+1. Read NEXT_USE_CASES.md to see all remaining use cases
+2. Check if there are ANY use cases left in the file
+3. Take action based on what you find:
+
+## If NO Use Cases Remain (file is empty or only has headers):
+1. Delete NEXT_USE_CASES.md
+2. Do NOT create CURRENT_USE_CASE.md
+3. Create REFACTORING.md and leave it empty.
+3a. Add the current story from CURRENT_STORY.md to IMPLEMENTED_STORIES.md, and delete CURRENT_STORY.md.
+4. The workflow will move to refactoring (Step 4)
+
+## If Use Cases Remain:
+1. Analyze which use case should be implemented next based on:
+   - Dependencies (what needs to be built first)
+   - Logical implementation order
+   - Business priority
+2. Write the selected use case to CURRENT_USE_CASE.md
+3. Create an empty task documentation file named descriptively after the use case
+4. Do NOT modify NEXT_USE_CASES.md (Step 3.5 will remove completed ones)
+
+## Important:
+- Your job is to recognize when all use cases are done
+- If the file is empty, delete it and move on
+- If there are use cases, select the most logical next one
+- Task documentation filename should clearly describe the use case (e.g., "add-client-tasks.md")

package/ralphs/project-manager-ralph.md

@@ -0,0 +1,15 @@
+# Step 5: Story Completion Notification
+
+You are in Step 5 of an agentic software development workflow.
+
+## Your Task
+
+1. Read IMPLEMENTED_STORIES.md and IMPLEMENTED_CASES.md
+2. Create a summary of the completed story
+3. Send notification using curl, the exact command iscurl -d "$SUMMARY" ntfy.sh/willehpeh-es-crm-ralphinator
+4. Create STORY_COMPLETE.md
+5. Delete REFACTORING_COMPLETE.me
+
+## Important:
+- Keep notification concise
+- Must create STORY_COMPLETE.md

package/ralphs/seam-finder-ralph.md

@@ -0,0 +1,57 @@
+# Step 4: Find Seams for Safe Changes
+
+You are in Step 4 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## What is a Seam?
+
+From Michael Feathers: "A seam is a place where you can alter behavior in your program without editing in that place."
+
+Seams allow us to break dependencies and make code testable without risky changes.
+
+## Your Task
+
+1. Read CURRENT_TARGET.md to understand the cleanup target
+2. Read BEHAVIOR.md to understand the code's behavior and dependencies
+3. Read CHARACTERIZATION_TESTS.md to see what's covered by tests
+4. Analyze the code for seams and dependency-breaking opportunities
+5. Create SEAM_PLAN.md with your refactoring strategy
+6. Delete TESTS_COMPLETE.md
+
+## Types of Seams to Look For:
+
+### Object Seams
+- Can we subclass and override methods?
+- Can we extract an interface?
+- Can we use dependency injection?
+
+### Preprocessing Seams
+- Can we use configuration to swap implementations?
+- Can we use feature flags?
+
+### Link Seams
+- Can we substitute dependencies at build/link time?
+
+## Dependency-Breaking Techniques to Consider:
+
+- **Extract Interface**: Create an interface for a dependency
+- **Parameterize Constructor**: Pass dependencies in rather than creating them
+- **Extract and Override Call**: Make a method that can be overridden in tests
+- **Subclass and Override Method**: Create a testing subclass
+- **Replace Global Reference with Getter**: Wrap global access in an overridable method
+- **Introduce Instance Delegator**: Wrap static methods
+- **Skin and Wrap the API**: Create a thin wrapper around external dependencies
+
+## SEAM_PLAN.md Should Include:
+
+1. **Identified Seams**: Where can we alter behavior?
+2. **Problematic Dependencies**: What makes this code hard to test/change?
+3. **Recommended Techniques**: Which dependency-breaking techniques to apply
+4. **Refactoring Order**: Sequence of safe steps (smallest first)
+5. **Risk Assessment**: What could go wrong?
+
+## Important:
+- Plan small, incremental changes
+- Each planned step should be independently committable
+- Prefer the simplest technique that works
+- The plan guides Surgeon Ralph's work
+- Do NOT ask for confirmation - execute immediately and create the output file

package/ralphs/surgeon-ralph.md

@@ -0,0 +1,78 @@
+# Step 5: Perform Safe Refactoring
+
+You are in Step 5 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## CRITICAL: One Refactoring Per Iteration
+
+Make ONE small, safe refactoring per iteration. Not multiple changes. ONE change.
+
+## The Refactoring Loop
+
+This step may run many times. Each iteration:
+1. Makes one small change
+2. Runs tests to verify behavior is preserved
+3. Commits if tests pass
+
+## Your Task This Iteration
+
+1. Read CURRENT_TARGET.md to understand the cleanup target
+2. Read the plan file:
+   - If TRIVIAL_FIX.md exists, perform the trivial fix described (dead code removal, etc.)
+   - If ARCHITECTURE_PLAN.md exists, follow the architectural migration steps
+   - Otherwise, read SEAM_PLAN.md for the refactoring strategy
+3. Read REFACTORING_LOG.md to see what's been done (if it exists)
+4. Identify the NEXT small change from the plan
+5. Make ONE change
+6. Run ALL tests (especially characterization tests)
+7. If tests pass: commit and log the change
+8. If tests fail: revert and document the issue
+9. Assess if the target is sufficiently cleaned
+
+## Safe Refactoring Guidelines:
+
+### Keep Changes Small
+- Rename one thing
+- Extract one method
+- Move one piece of code
+- Introduce one parameter
+- Extract one interface
+
+### Verify After Each Change
+- Run characterization tests
+- Run any existing unit tests
+- Run integration tests if available
+- Check for compilation errors
+
+### If Tests Fail
+1. REVERT the change immediately
+2. Document what went wrong in REFACTORING_LOG.md
+3. Consider a smaller step or different approach
+4. End this iteration
+
+## Logging Changes
+
+Add each successful refactoring to REFACTORING_LOG.md:
+```
+## [Timestamp]
+- Change: [what you did]
+- Technique: [which technique from SEAM_PLAN.md]
+- Tests: [all passing]
+```
+
+## If Target Cleanup is Complete:
+1. Push: git push
+2. Delete SEAM_PLAN.md and/or ARCHITECTURE_PLAN.md and/or TRIVIAL_FIX.md
+3. Delete REFACTORING_APPROVED.md if it exists
+4. Create TARGET_COMPLETE.md (empty file)
+
+## If More Refactoring Needed:
+1. Do NOT push
+2. Do NOT create TARGET_COMPLETE.md
+3. The next iteration will continue
+
+## Important:
+- ONE refactoring per iteration
+- ALWAYS run tests after changes
+- REVERT if tests fail - don't try to fix forward
+- Small steps are safer than big leaps
+- Do NOT ask for confirmation - execute immediately

package/ralphs/surveyor-ralph.md

@@ -0,0 +1,38 @@
+# Step 1: Survey and Target Selection
+
+You are in Step 1 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## Your Task (Execute Now)
+
+1. Read LEGACY_PROMPT.md to understand the cleanup goals
+2. Read CLEANED_TARGETS.md to see what has already been cleaned (if it exists)
+3. Assess whether the cleanup goals have been fully achieved
+4. Create the appropriate output file as described below
+
+## If Cleanup is Complete:
+1. Create a file called CLEANUP_COMPLETE.md containing:
+   - A summary of all cleaned areas
+   - Improvements made
+   - Test coverage added
+2. Do nothing else - the workflow will terminate
+
+## If Cleanup is Not Complete:
+1. Analyze the codebase to identify the next area needing cleanup
+2. Choose a SMALL, focused target - a single class, function, or tightly-coupled group
+3. Write the target to NEXT_TARGET.md including:
+   - File path(s) involved
+   - Why this area needs cleanup
+   - What problems exist (tight coupling, no tests, unclear responsibility, etc.)
+   - Rough scope estimate
+
+## Target Selection Criteria:
+- Prefer areas with high change frequency (pain points)
+- Start with leaf nodes (fewer dependencies) when possible
+- Choose areas small enough to clean in a few iterations
+- Consider the "strangler fig" pattern - start at edges, work inward
+
+## Important:
+- You must choose ONE path: either create CLEANUP_COMPLETE.md OR create NEXT_TARGET.md
+- Do not create both files
+- Keep targets small and focused
+- Do NOT ask for confirmation - execute immediately and create the output file

package/ralphs/test-writer-ralph.md

@@ -0,0 +1,65 @@
+# Step 3: Write Characterization Tests
+
+You are in Step 3 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## CRITICAL: One Test Per Iteration
+
+Write ONE characterization test per iteration. Not multiple tests. ONE test.
+
+## What is a Characterization Test?
+
+A characterization test captures what the code ACTUALLY DOES, not what it should do.
+The test documents existing behavior so we can safely refactor without changing it.
+
+From Michael Feathers: "A characterization test is a test that characterizes the actual behavior of a piece of code."
+
+## Your Task This Iteration
+
+1. Read CURRENT_TARGET.md to understand the cleanup target
+2. Read BEHAVIOR.md to see documented behaviors
+3. Read existing test files to see what's already covered
+4. Read CHARACTERIZATION_TESTS.md to see which behaviors have been tested (if it exists)
+5. Identify ONE behavior that needs a characterization test
+6. Write ONE test that captures that behavior
+7. Run the test to ensure it passes (it must - we're testing current behavior)
+8. Document the test in CHARACTERIZATION_TESTS.md
+9. Commit: git add . && git commit -m "Add characterization test: [behavior]"
+10. Assess if sufficient test coverage exists
+
+## Writing Good Characterization Tests:
+
+1. Call the code with specific inputs
+2. Assert on the ACTUAL output (even if it seems wrong)
+3. Name the test descriptively: `test_[method]_when_[condition]_returns_[result]`
+4. Include edge cases and error conditions
+5. Test side effects where possible
+
+## Playwright MCP for E2E Tests
+
+For UI components and user flows, use the Playwright MCP to:
+- Navigate to pages and interact with elements
+- Capture current behavior (screenshots, assertions)
+- Test user journeys end-to-end
+
+When writing E2E characterization tests:
+1. Use Playwright MCP to observe current UI behavior
+2. Write Playwright tests that capture that behavior
+3. Place tests in appropriate test directory (check existing test structure)
+
+Prefer unit tests for pure logic, Playwright tests for UI/integration behavior.
+
+## If Tests Are Sufficient:
+When you have covered the key behaviors in BEHAVIOR.md:
+1. Create TESTS_COMPLETE.md (empty file)
+2. Do NOT delete CURRENT_TARGET.md
+
+## If More Tests Needed:
+1. Do NOT create TESTS_COMPLETE.md
+2. The next iteration will write another test
+
+## Important:
+- ONE test per iteration
+- Tests must PASS - they capture current behavior
+- Don't fix bugs yet - just document behavior
+- Coverage over risky areas is more important than 100% coverage
+- Do NOT ask for confirmation - execute immediately