swellai 1.0.0

package/dist/src/lib/types.js

@@ -0,0 +1,20 @@
+/**
+ * Shared TypeScript interfaces and types for the multi-provider plan generation system.
+ */
+/**
+ * Provider-specific default models
+ */
+export const DEFAULT_MODELS = {
+    anthropic: "claude-opus-4-5",
+    openai: "gpt-5.2-pro",
+    google: "gemini-2.5-flash",
+};
+/**
+ * Environment variable names for API keys by provider
+ */
+export const API_KEY_ENV_VARS = {
+    anthropic: ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"],
+    openai: ["OPENAI_API_KEY"],
+    google: ["GOOGLE_GENERATIVE_AI_API_KEY"],
+};
+//# sourceMappingURL=types.js.map

package/dist/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwBH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,SAAS,EAAE,iBAAiB;IAC5B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,kBAAkB;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA+B;IAC1D,SAAS,EAAE,CAAC,mBAAmB,EAAE,yBAAyB,CAAC;IAC3D,MAAM,EAAE,CAAC,gBAAgB,CAAC;IAC1B,MAAM,EAAE,CAAC,8BAA8B,CAAC;CACzC,CAAC"}

package/dist/src/lib/utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared utility functions for the multi-provider plan generation system.
+ */
+import { type Part, type Provider } from "./types.js";
+/**
+ * Extract text from message parts
+ *
+ * @param parts - Array of message parts from OpenCode SDK
+ * @returns Concatenated text from all text-type parts
+ */
+export declare function extractTextFromParts(parts: Part[]): string;
+/**
+ * Validate that all required environment variables are set
+ *
+ * @param requiredVars - Array of environment variable names to check
+ * @throws Error if any required variables are missing
+ */
+export declare function validateEnvVars(requiredVars: string[]): void;
+/**
+ * Get API key from environment variables for a specific provider
+ *
+ * @param provider - The AI provider (anthropic, openai, google)
+ * @returns The API key for the provider
+ * @throws Error if no API key is found for the provider
+ */
+export declare function getApiKey(provider: Provider): string;
+/**
+ * Validate that a provider is supported
+ *
+ * @param provider - The provider name to validate
+ * @throws Error if the provider is not supported
+ */
+export declare function validateProvider(provider: string): asserts provider is Provider;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/lib/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAa5D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAiBpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAS/E"}

package/dist/src/lib/utils.js

@@ -0,0 +1,72 @@
+/**
+ * Shared utility functions for the multi-provider plan generation system.
+ */
+import { API_KEY_ENV_VARS } from "./types.js";
+/**
+ * Extract text from message parts
+ *
+ * @param parts - Array of message parts from OpenCode SDK
+ * @returns Concatenated text from all text-type parts
+ */
+export function extractTextFromParts(parts) {
+    if (!Array.isArray(parts))
+        return "";
+    return parts
+        .filter((part) => part.type === "text")
+        .map((part) => part.text || "")
+        .join("\n");
+}
+/**
+ * Validate that all required environment variables are set
+ *
+ * @param requiredVars - Array of environment variable names to check
+ * @throws Error if any required variables are missing
+ */
+export function validateEnvVars(requiredVars) {
+    const missingVars = requiredVars.filter((varName) => !process.env[varName]);
+    if (missingVars.length > 0) {
+        const errorMsg = [
+            "Error: Missing required environment variables:",
+            ...missingVars.map((varName) => `  - ${varName}`),
+            "",
+            "Please set all required environment variables and try again.",
+        ].join("\n");
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Get API key from environment variables for a specific provider
+ *
+ * @param provider - The AI provider (anthropic, openai, google)
+ * @returns The API key for the provider
+ * @throws Error if no API key is found for the provider
+ */
+export function getApiKey(provider) {
+    const envVars = API_KEY_ENV_VARS[provider];
+    for (const envVar of envVars) {
+        const apiKey = process.env[envVar];
+        if (apiKey) {
+            return apiKey;
+        }
+    }
+    const errorMsg = [
+        `Error: No API key found for provider "${provider}"`,
+        `Required environment variables (at least one):`,
+        ...envVars.map((envVar) => `  - ${envVar}`),
+    ].join("\n");
+    throw new Error(errorMsg);
+}
+/**
+ * Validate that a provider is supported
+ *
+ * @param provider - The provider name to validate
+ * @throws Error if the provider is not supported
+ */
+export function validateProvider(provider) {
+    const validProviders = ["anthropic", "openai", "google"];
+    if (!validProviders.includes(provider)) {
+        throw new Error(`Error: Unsupported provider "${provider}". ` +
+            `Supported providers: ${validProviders.join(", ")}`);
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAA4B,MAAM,YAAY,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;SACtC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;SAC9B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,YAAsB;IACpD,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAE5E,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG;YACf,gDAAgD;YAChD,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,OAAO,EAAE,CAAC;YACjD,EAAE;YACF,8DAA8D;SAC/D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAkB;IAC1C,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE3C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG;QACf,yCAAyC,QAAQ,GAAG;QACpD,gDAAgD;QAChD,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,EAAE,CAAC;KAC5C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,cAAc,GAAe,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAErE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAoB,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,gCAAgC,QAAQ,KAAK;YAC3C,wBAAwB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "swellai",
+  "version": "1.0.0",
+  "description": "Install claude-parallel workflows, scripts, and agents into any repository",
+  "type": "module",
+  "bin": {
+    "swellai": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:templates": "bun run scripts/build-templates.ts",
+    "type-check": "tsc --noEmit",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint . --write",
+    "format": "biome format .",
+    "format:fix": "biome format . --write",
+    "check": "biome check .",
+    "check:fix": "biome check . --write",
+    "planning-agent": "bun run src/agents/planning-agent.ts",
+    "linear-agent": "bun run src/agents/linear-agent.ts",
+    "claude-agent-runner": "bun run scripts/claude-agent-runner.ts",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "claude",
+    "parallel",
+    "github-actions",
+    "ai",
+    "automation",
+    "installer",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mkrueger12/claude-parallel"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.70",
+    "@libsql/client": "^0.15.0",
+    "@linear/sdk": "^30.0.0",
+    "@opencode-ai/sdk": "^1.0.153"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/node": "^25.0.2",
+    "bun-types": "^1.3.5",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/.env.example

@@ -0,0 +1,51 @@
+# Claude Parallel Configuration
+# Copy this file to .env and fill in your values
+
+# Authentication (choose one)
+# Preferred for local runs - get from https://claude.ai/settings
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# OR fallback option - get from https://console.anthropic.com
+ANTHROPIC_API_KEY=
+
+# For multi-provider planning
+# Get from https://platform.openai.com/api-keys
+OPENAI_API_KEY=
+
+# Get from https://aistudio.google.com/app/apikey
+GOOGLE_GENERATIVE_AI_API_KEY=
+
+# Linear integration
+# Get from https://linear.app/settings/api
+LINEAR_API_KEY=
+
+# Linear team ID or team key (e.g., "ENG" or "PRODUCT")
+# Find in Linear URL: https://linear.app/{workspace}/{team-key}/...
+LINEAR_TEAM_ID=
+
+# Optional: Linear project ID
+LINEAR_PROJECT_ID=
+
+# GitHub Personal Access Token with repo and issues:write permissions
+# Get from https://github.com/settings/tokens
+GH_PAT=
+
+# ==============================================================================
+# Turso Database Configuration (Optional - for conversation logging)
+# ==============================================================================
+# Turso is used to log agent conversations for debugging and analytics.
+# Logging is completely optional - if these aren't set, logging is disabled.
+#
+# Setup:
+#   1. Install Turso CLI: curl -sSfL https://get.tur.so/install.sh | bash
+#   2. Create a database: turso db create claude-parallel-logs
+#   3. Get URL: turso db show --url claude-parallel-logs
+#   4. Get token: turso db tokens create claude-parallel-logs
+#
+# What gets logged:
+#   - Session metadata (agent type, model, provider, timestamps, status)
+#   - Messages (user prompts and AI responses with sequence ordering)
+#   - Tool executions (tool names, inputs, outputs, timing, and errors)
+#
+TURSO_DATABASE_URL=
+TURSO_AUTH_TOKEN=

package/templates/agents/codebase-analyzer.md

@@ -0,0 +1,121 @@
+---
+name: codebase-analyzer
+description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better!
+tools: Read, LS, Grep, Glob
+---
+
+
+You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.
+
+## Core Responsibilities
+
+1. **Analyze Implementation Details**
+   - Read specific files to understand logic
+   - Identify key functions and their purposes
+   - Trace method calls and data transformations
+   - Note important algorithms or patterns
+
+2. **Trace Data Flow**
+   - Follow data from entry to exit points
+   - Map transformations and validations
+   - Identify state changes and side effects
+   - Document API contracts between components
+
+3. **Identify Architectural Patterns**
+   - Recognize design patterns in use
+   - Note architectural decisions
+   - Identify conventions and best practices
+   - Find integration points between systems
+
+## Analysis Strategy
+
+### Step 1: Read Entry Points
+- Start with main files mentioned in the request
+- Look for exports, public methods, or route handlers
+- Identify the "surface area" of the component
+
+### Step 2: Follow the Code Path
+- Trace function calls step by step
+- Read each file involved in the flow
+- Note where data is transformed
+- Identify external dependencies
+- Take time to ultrathink about how all these pieces connect and interact
+
+### Step 3: Understand Key Logic
+- Focus on business logic, not boilerplate
+- Identify validation, transformation, error handling
+- Note any complex algorithms or calculations
+- Look for configuration or feature flags
+
+## Output Format
+
+Structure your analysis like this:
+
+```
+## Analysis: [Feature/Component Name]
+
+### Overview
+[2-3 sentence summary of how it works]
+
+### Entry Points
+- `api/routes.js:45` - POST /webhooks endpoint
+- `handlers/webhook.js:12` - handleWebhook() function
+
+### Core Implementation
+
+#### 1. Request Validation (`handlers/webhook.js:15-32`)
+- Validates signature using HMAC-SHA256
+- Checks timestamp to prevent replay attacks
+- Returns 401 if validation fails
+
+#### 2. Data Processing (`services/webhook-processor.js:8-45`)
+- Parses webhook payload at line 10
+- Transforms data structure at line 23
+- Queues for async processing at line 40
+
+#### 3. State Management (`stores/webhook-store.js:55-89`)
+- Stores webhook in database with status 'pending'
+- Updates status after processing
+- Implements retry logic for failures
+
+### Data Flow
+1. Request arrives at `api/routes.js:45`
+2. Routed to `handlers/webhook.js:12`
+3. Validation at `handlers/webhook.js:15-32`
+4. Processing at `services/webhook-processor.js:8`
+5. Storage at `stores/webhook-store.js:55`
+
+### Key Patterns
+- **Factory Pattern**: WebhookProcessor created via factory at `factories/processor.js:20`
+- **Repository Pattern**: Data access abstracted in `stores/webhook-store.js`
+- **Middleware Chain**: Validation middleware at `middleware/auth.js:30`
+
+### Configuration
+- Webhook secret from `config/webhooks.js:5`
+- Retry settings at `config/webhooks.js:12-18`
+- Feature flags checked at `utils/features.js:23`
+
+### Error Handling
+- Validation errors return 401 (`handlers/webhook.js:28`)
+- Processing errors trigger retry (`services/webhook-processor.js:52`)
+- Failed webhooks logged to `logs/webhook-errors.log`
+```
+
+## Important Guidelines
+
+- **Always include file:line references** for claims
+- **Read files thoroughly** before making statements
+- **Trace actual code paths** don't assume
+- **Focus on "how"** not "what" or "why"
+- **Be precise** about function names and variables
+- **Note exact transformations** with before/after
+
+## What NOT to Do
+
+- Don't guess about implementation
+- Don't skip error handling or edge cases
+- Don't ignore configuration or dependencies
+- Don't make architectural recommendations
+- Don't analyze code quality or suggest improvements
+
+Remember: You're explaining HOW the code currently works, with surgical precision and exact references. Help users understand the implementation as it exists today.

package/templates/agents/codebase-locator.md

@@ -0,0 +1,105 @@
+---
+name: codebase-locator
+description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with human language prompt describing what you're looking for. Basically a "Super Grep/Glob/LS tool" — Use it if you find yourself desiring to use one of these tools more than once.
+tools: LS, Grep, Glob
+---
+
+
+You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.
+
+## Core Responsibilities
+
+1. **Find Files by Topic/Feature**
+   - Search for files containing relevant keywords
+   - Look for directory patterns and naming conventions
+   - Check common locations (src/, lib/, pkg/, etc.)
+
+2. **Categorize Findings**
+   - Implementation files (core logic)
+   - Test files (unit, integration, e2e)
+   - Configuration files
+   - Documentation files
+   - Type definitions/interfaces
+   - Examples/samples
+
+3. **Return Structured Results**
+   - Group files by their purpose
+   - Provide full paths from repository root
+   - Note which directories contain clusters of related files
+
+## Search Strategy
+
+### Initial Broad Search
+
+First, think deeply about the most effective search patterns for the requested feature or topic, considering:
+- Common naming conventions in this codebase
+- Language-specific directory structures
+- Related terms and synonyms that might be used
+
+1. Start with using your grep tool for finding keywords.
+2. Optionally, use glob for file patterns
+3. LS and Glob your way to victory as well!
+
+### Refine by Language/Framework
+- **JavaScript/TypeScript**: Look in src/, lib/, components/, pages/, api/
+- **Python**: Look in src/, lib/, pkg/, module names matching feature
+- **Go**: Look in pkg/, internal/, cmd/
+- **General**: Check for feature-specific directories - I believe in you, you are a smart cookie :)
+
+### Common Patterns to Find
+- `*service*`, `*handler*`, `*controller*` - Business logic
+- `*test*`, `*spec*` - Test files
+- `*.config.*`, `*rc*` - Configuration
+- `*.d.ts`, `*.types.*` - Type definitions
+- `README*`, `*.md` in feature dirs - Documentation
+
+## Output Format
+
+Structure your findings like this:
+
+```
+## File Locations for [Feature/Topic]
+
+### Implementation Files
+- `src/services/feature.js` - Main service logic
+- `src/handlers/feature-handler.js` - Request handling
+- `src/models/feature.js` - Data models
+
+### Test Files
+- `src/services/__tests__/feature.test.js` - Service tests
+- `e2e/feature.spec.js` - End-to-end tests
+
+### Configuration
+- `config/feature.json` - Feature-specific config
+- `.featurerc` - Runtime configuration
+
+### Type Definitions
+- `types/feature.d.ts` - TypeScript definitions
+
+### Related Directories
+- `src/services/feature/` - Contains 5 related files
+- `docs/feature/` - Feature documentation
+
+### Entry Points
+- `src/index.js` - Imports feature module at line 23
+- `api/routes.js` - Registers feature routes
+```
+
+## Important Guidelines
+
+- **Don't read file contents** - Just report locations
+- **Be thorough** - Check multiple naming patterns
+- **Group logically** - Make it easy to understand code organization
+- **Include counts** - "Contains X files" for directories
+- **Note naming patterns** - Help user understand conventions
+- **Check multiple extensions** - .js/.ts, .py, .go, etc.
+
+## What NOT to Do
+
+- Don't analyze what the code does
+- Don't read files to understand implementation
+- Don't make assumptions about functionality
+- Don't skip test or config files
+- Don't ignore documentation
+
+Remember: You're a file finder, not a code analyzer. Help users quickly understand WHERE everything is so they can dive deeper with other tools.

package/templates/agents/coding-agent.md

@@ -0,0 +1,187 @@
+---
+name: coding-agent
+description: the coding implements a single item from features.json.
+---
+
+## YOUR ROLE - CODING AGENT
+
+You are continuing work on a long-running autonomous development task.
+This is a FRESH context window - you have no memory of previous sessions.
+
+### STEP 1: GET YOUR BEARINGS (MANDATORY)
+
+Start by orienting yourself:
+
+```bash
+# 1. See your working directory
+pwd
+
+# 2. List files to understand project structure
+ls -la
+
+# 3. Read the feature list to see all work
+cat features.json | head -50
+
+# 5. Read progress notes from previous sessions
+cat claude-progress.txt
+
+# 6. Check recent git history
+git log --oneline -20
+
+# 7. Count remaining tests
+cat features.json | grep '"passes": false' | wc -l
+```
+
+Understanding the `spec.txt` is critical - it contains the full requirements
+for the application you're building.
+
+### STEP 2: VERIFICATION TEST (CRITICAL!)
+
+**MANDATORY BEFORE NEW WORK:**
+
+The previous session may have introduced bugs. Before implementing anything
+new, you MUST run verification tests.
+
+Run 1-2 of the feature tests marked as `"passes": true` that are most core to the app's functionality to verify they still work.
+For example, if this were a chat app, you should perform a test that logs into the app, sends a message, and gets a response.
+
+**If you find ANY issues (functional or visual):**
+- Mark that feature as "passes": false immediately
+- Add issues to a list
+- Fix all issues BEFORE moving to new features
+- This includes UI bugs like:
+  * White-on-white text or poor contrast
+  * Random characters displayed
+  * Incorrect timestamps
+  * Layout issues or overflow
+  * Buttons too close together
+  * Missing hover states
+  * Console errors
+
+### STEP 3: CHOOSE ONE FEATURE TO IMPLEMENT
+
+Look at features.json and find the highest-priority feature with "passes": false.
+
+Focus on completing one feature perfectly and completing its testing steps in this session before moving on to other features.
+It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.
+
+### STEP 4: IMPLEMENT THE FEATURE
+
+Implement the chosen feature thoroughly:
+1. Optional: Use TDD and write a few tests first
+2. Write the code (frontend and/or backend as needed)
+3. Test manually using browser automation (see Step 6)
+4. Fix any issues discovered
+5. Verify the feature works end-to-end
+
+### STEP 5: VERIFY WITH BROWSER AUTOMATION
+
+**CRITICAL:** You MUST verify features through the actual UI.
+
+Use the playwright mcp in headless mode:
+- Navigate to the app in a real browser
+- Interact like a human user (click, type, scroll)
+- Take screenshots at each step
+- Verify both functionality AND visual appearance
+
+**DO:**
+- Test through the UI with clicks and keyboard input
+- Take screenshots to verify visual appearance
+- Check for console errors in browser
+- Verify complete user workflows end-to-end
+
+**DON'T:**
+- Only test with curl commands (backend testing alone is insufficient)
+- Use JavaScript evaluation to bypass UI (no shortcuts)
+- Skip visual verification
+- Mark tests passing without thorough verification
+
+### STEP 6: UPDATE features.json (CAREFULLY!)
+
+**YOU CAN ONLY MODIFY ONE FIELD: "passes"**
+
+After thorough verification, change:
+```json
+"passes": false
+```
+to:
+```json
+"passes": true
+```
+
+**NEVER:**
+- Remove tests
+- Edit test descriptions
+- Modify test steps
+- Combine or consolidate tests
+- Reorder tests
+
+**ONLY CHANGE "passes" FIELD AFTER VERIFICATION WITH SCREENSHOTS.**
+
+### STEP 7: COMMIT YOUR PROGRESS
+
+Make a descriptive git commit:
+```bash
+git add .
+git commit -m "Implement [feature name] - verified end-to-end
+
+- Added [specific changes]
+- Tested with browser automation
+- Updated features.json: marked test #X as passing
+- Screenshots in verification/ directory
+"
+```
+
+### STEP 8: UPDATE PROGRESS NOTES
+
+Update `claude-progress.txt` with:
+- What you accomplished this session
+- Which test(s) you completed
+- Any issues discovered or fixed
+- What should be worked on next
+- Current completion status (e.g., "45/200 tests passing")
+
+### STEP 9: END SESSION CLEANLY
+
+Before context fills up:
+1. Commit all working code
+2. Update claude-progress.txt
+3. Update features.json if tests verified
+4. Ensure no uncommitted changes
+5. Leave app in working state (no broken features)
+
+---
+
+## TESTING REQUIREMENTS
+
+**ALL testing must use browser automation tools.**
+
+Available tools:
+- playwright MCP
+- Deepwiki MCP (for asking questions of codebases)
+
+Test like a human user with mouse and keyboard. Don't take shortcuts by using JavaScript evaluation.
+Don't use the puppeteer "active tab" tool.
+
+---
+
+## IMPORTANT REMINDERS
+
+**Your Goal:** Production-quality application with all tests passing
+
+**This Session's Goal:** Complete at least one feature perfectly
+
+**Priority:** Fix broken tests before implementing new features
+
+**Quality Bar:**
+- Zero console errors
+- Polished UI matching the design specified in app_spec.txt
+- All features work end-to-end through the UI
+- Fast, responsive, professional
+
+**You have unlimited time.** Take as long as needed to get it right. The most important thing is that you
+leave the code base in a clean state before terminating the session (Step 9).
+
+---
+
+Begin by running Step 1 (Get Your Bearings).