@bradtaylorsf/alpha-loop 1.0.0

package/dist/lib/verify.js

@@ -0,0 +1,235 @@
+/**
+ * Live Verification — start the app, use playwright-cli to test it like a real user.
+ *
+ * This is NOT running E2E test suites. This is an AI agent using playwright-cli
+ * to interactively verify that the implemented feature actually works by:
+ * 1. Starting the dev server
+ * 2. Opening the app in a browser via playwright-cli
+ * 3. Navigating, clicking, typing, taking screenshots
+ * 4. Reporting PASS or FAIL
+ */
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { exec } from './shell.js';
+import { log } from './logger.js';
+import { spawnAgent } from './agent.js';
+/** Max seconds to wait for app to become ready. */
+const APP_READY_TIMEOUT_S = 60;
+/**
+ * Run live verification using playwright-cli.
+ * Starts the app, sends agent to test it, returns result.
+ */
+export async function runVerify(options) {
+    const { worktree, logFile, issueNum, title, body, config, sessionDir } = options;
+    if (config.skipVerify) {
+        log.info('Verification skipped (skipVerify=true)');
+        return { passed: true, output: 'Verification skipped' };
+    }
+    if (config.dryRun) {
+        log.dry('Would run live verification');
+        return { passed: true, output: 'Verification skipped (dry run)' };
+    }
+    log.step(`Running live verification for issue #${issueNum}`);
+    // Check if playwright-cli is available
+    const whichResult = exec('which playwright-cli');
+    if (whichResult.exitCode !== 0) {
+        log.warn('playwright-cli not installed. Install with: npm install -g @anthropic-ai/claude-code');
+        log.info('Skipping live verification (no playwright-cli)');
+        return { passed: true, output: 'Verification skipped (playwright-cli not installed)' };
+    }
+    // Detect how to start the app
+    let devCmd = config.devCommand;
+    if (!devCmd) {
+        const pkgJsonPath = join(worktree, 'package.json');
+        if (existsSync(pkgJsonPath)) {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const scripts = pkg.scripts ?? {};
+            for (const name of ['dev', 'start', 'preview']) {
+                if (scripts[name]) {
+                    devCmd = `pnpm ${name}`;
+                    break;
+                }
+            }
+        }
+    }
+    if (!devCmd) {
+        log.info('No dev/start/preview command found, skipping verification');
+        return { passed: true, output: 'Verification skipped (no start command)' };
+    }
+    const port = config.port ?? 3000;
+    // Start the app in the background
+    log.info(`Starting app with '${devCmd}' on port ${port}...`);
+    const { spawn } = await import('node:child_process');
+    const appProcess = spawn('sh', ['-c', `PORT=${port} ${devCmd}`], {
+        cwd: worktree,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
+    });
+    const appPid = appProcess.pid;
+    // Wait for app to be ready
+    let ready = false;
+    for (let i = 0; i < APP_READY_TIMEOUT_S; i++) {
+        const check = exec(`curl -s -o /dev/null http://localhost:${port}`);
+        if (check.exitCode === 0) {
+            ready = true;
+            break;
+        }
+        // Check if process is still alive
+        try {
+            process.kill(appPid, 0);
+        }
+        catch {
+            log.error('App process exited before becoming ready');
+            return { passed: false, output: 'App failed to start' };
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    if (!ready) {
+        log.error(`App did not become ready on port ${port} within ${APP_READY_TIMEOUT_S}s`);
+        killProcess(appPid);
+        return { passed: false, output: `App failed to start on port ${port}` };
+    }
+    log.success(`App is ready on port ${port}`);
+    // Load saved auth state if it exists
+    const authStateDir = join(process.cwd(), '.alpha-loop', 'auth');
+    if (existsSync(join(authStateDir, 'state.json'))) {
+        log.info('Loading saved auth state...');
+        exec(`playwright-cli state-load "${authStateDir}/state.json"`);
+    }
+    // Save screenshots to session directory
+    const screenshotDir = join(sessionDir, 'screenshots', `issue-${issueNum}`);
+    mkdirSync(screenshotDir, { recursive: true });
+    // Get the diff to understand what changed
+    const diffStat = exec(`git diff --stat "origin/${config.baseBranch}...HEAD"`, { cwd: worktree });
+    // Get vision context
+    const visionFile = join(process.cwd(), '.alpha-loop', 'vision.md');
+    const visionContext = existsSync(visionFile) ? readFileSync(visionFile, 'utf-8') : '';
+    // Build the verification prompt
+    const verifyPrompt = `You are a QA tester verifying that issue #${issueNum} was implemented correctly.
+
+## Issue: ${title}
+
+${body}
+
+## What Changed
+${diffStat.stdout || 'No diff available'}
+
+${visionContext ? `## Product Vision\n${visionContext}\n` : ''}
+## Your Task
+
+The app is running at http://localhost:${port}. Use the playwright-cli to test it.
+
+### Playwright CLI Commands Available
+- \`playwright-cli open http://localhost:${port}\` — Open the app in a browser
+- \`playwright-cli goto <url>\` — Navigate to a page
+- \`playwright-cli snapshot\` — Get a snapshot of the current page with element refs
+- \`playwright-cli click <ref>\` — Click an element (use ref from snapshot, e.g. \`e15\`)
+- \`playwright-cli type <text>\` — Type text into the focused element
+- \`playwright-cli screenshot --path <file>\` — Take a screenshot and save to file
+- \`playwright-cli fill <ref> <text>\` — Fill a form field
+- \`playwright-cli select <ref> <value>\` — Select a dropdown option
+- \`playwright-cli wait <selector>\` — Wait for an element to appear
+- \`playwright-cli console\` — Check browser console for errors
+- \`playwright-cli network\` — Check network requests/responses
+
+### Testing Steps
+
+1. Open the app: \`playwright-cli open http://localhost:${port}\`
+2. Take a snapshot to see the page structure: \`playwright-cli snapshot\`
+3. Navigate to the feature that was changed
+4. Test the ACTUAL user flow described in the issue:
+   - Can you do what the issue says should work?
+   - Does the UI render correctly?
+   - Do form submissions work end-to-end?
+   - Check console for errors: \`playwright-cli console\`
+   - Check network for failed requests: \`playwright-cli network\`
+5. Take screenshots at key states (save to the screenshot directory below)
+6. Check for functional gaps:
+   - Is the backend wired to the frontend?
+   - Are there UI elements that don't respond?
+   - Does data persist after submission?
+
+### Auth / Login
+${existsSync(authStateDir) ? 'Auth state is pre-loaded. If you need to log in, use the credentials from the environment or .env file.' : 'No auth state saved.'}
+
+## Report
+
+After testing, output a verification report:
+
+### Status: PASS or FAIL
+
+### What Was Tested
+- (list each action you took with playwright-cli)
+
+### What Worked
+- (list what functioned correctly)
+
+### What Failed
+- (list what didn't work, with details and screenshots)
+
+### Console Errors
+- (any browser console errors found)
+
+### Network Issues
+- (any failed API calls or missing endpoints)
+
+### Gaps Found
+- (any disconnects between frontend and backend, missing pieces, etc.)
+
+### Screenshots
+Save screenshots to this directory: ${screenshotDir}
+Use descriptive filenames:
+- \`playwright-cli screenshot --path "${screenshotDir}/01-initial-load.png"\`
+- \`playwright-cli screenshot --path "${screenshotDir}/02-after-action.png"\`
+- \`playwright-cli screenshot --path "${screenshotDir}/03-final-state.png"\`
+
+IMPORTANT: Use playwright-cli commands to actually interact with the app.
+Navigate, click, type, submit forms. Verify the feature works as a real user would use it.`;
+    log.info(`Verification agent: claude + playwright-cli | Testing live at http://localhost:${port}`);
+    // Run the verification agent
+    const agentResult = await spawnAgent({
+        agent: 'claude',
+        model: config.model,
+        prompt: verifyPrompt,
+        cwd: worktree,
+        logFile,
+    });
+    const verifyOutput = agentResult.output;
+    // Kill the app process
+    log.info('Shutting down app...');
+    killProcess(appPid);
+    // Close playwright-cli browser sessions
+    exec('playwright-cli close-all');
+    // Check if verification passed based on agent output
+    if (/Status:.*FAIL/i.test(verifyOutput)) {
+        log.error('Live verification FAILED');
+        return { passed: false, output: verifyOutput };
+    }
+    else if (/Status:.*PASS/i.test(verifyOutput)) {
+        log.success('Live verification PASSED');
+        return { passed: true, output: verifyOutput };
+    }
+    else if (agentResult.exitCode === 0) {
+        log.success('Verification completed (agent exit 0)');
+        return { passed: true, output: verifyOutput };
+    }
+    else {
+        log.warn(`Verification unclear (agent exit ${agentResult.exitCode})`);
+        return { passed: false, output: verifyOutput };
+    }
+}
+function killProcess(pid) {
+    try {
+        // Kill process group (negative pid)
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            // Process already dead
+        }
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/lib/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/lib/verify.ts"],"names":[],"mappings":"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"}

package/dist/lib/vision.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Get vision context for prompt injection.
+ * Returns the contents of .alpha-loop/vision.md, or null if it doesn't exist.
+ */
+export declare function getVisionContext(projectDir?: string): string | null;
+/**
+ * Check if vision has been set up.
+ */
+export declare function hasVision(projectDir?: string): boolean;

package/dist/lib/vision.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const VISION_FILE = join('.alpha-loop', 'vision.md');
+/**
+ * Get vision context for prompt injection.
+ * Returns the contents of .alpha-loop/vision.md, or null if it doesn't exist.
+ */
+export function getVisionContext(projectDir = '.') {
+    const filePath = join(projectDir, VISION_FILE);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    return readFileSync(filePath, 'utf-8');
+}
+/**
+ * Check if vision has been set up.
+ */
+export function hasVision(projectDir = '.') {
+    return existsSync(join(projectDir, VISION_FILE));
+}
+//# sourceMappingURL=vision.js.map

package/dist/lib/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../src/lib/vision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAAqB,GAAG;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,aAAqB,GAAG;IAChD,OAAO,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/lib/worktree.d.ts

@@ -0,0 +1,29 @@
+export type WorktreeResult = {
+    path: string;
+    branch: string;
+};
+export type SetupWorktreeOptions = {
+    issueNum: number;
+    projectDir: string;
+    baseBranch: string;
+    sessionBranch?: string;
+    autoMerge?: boolean;
+    skipInstall?: boolean;
+    dryRun?: boolean;
+};
+export type CleanupWorktreeOptions = {
+    issueNum: number;
+    projectDir: string;
+    autoCleanup?: boolean;
+    dryRun?: boolean;
+};
+/**
+ * Create an isolated git worktree for processing an issue.
+ * When autoMerge is enabled and a session branch exists,
+ * branches from session branch so changes stack across issues.
+ */
+export declare function setupWorktree(options: SetupWorktreeOptions): Promise<WorktreeResult>;
+/**
+ * Remove a worktree. Keeps the branch (needed for PR).
+ */
+export declare function cleanupWorktree(options: CleanupWorktreeOptions): Promise<void>;

package/dist/lib/worktree.js

@@ -0,0 +1,153 @@
+/**
+ * Worktree Manager — create and clean up isolated git worktrees.
+ */
+import { existsSync, mkdirSync, symlinkSync, readlinkSync, unlinkSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { exec } from './shell.js';
+import { log } from './logger.js';
+const ENV_FILES = ['.env', '.env.local', '.env.development', '.env.development.local'];
+/**
+ * Create an isolated git worktree for processing an issue.
+ * When autoMerge is enabled and a session branch exists,
+ * branches from session branch so changes stack across issues.
+ */
+export async function setupWorktree(options) {
+    const { issueNum, projectDir, baseBranch, sessionBranch, autoMerge, skipInstall, dryRun } = options;
+    const branch = `agent/issue-${issueNum}`;
+    const worktreesDir = resolve(projectDir, '.worktrees');
+    mkdirSync(worktreesDir, { recursive: true });
+    const worktreePath = resolve(worktreesDir, `issue-${issueNum}`);
+    log.info(`Creating worktree at ${worktreePath} (branch: ${branch})`);
+    if (dryRun) {
+        log.dry(`Would create worktree: ${worktreePath}`);
+        return { path: worktreePath, branch };
+    }
+    // Clean up existing worktree if present
+    if (existsSync(worktreePath)) {
+        log.warn(`Worktree already exists at ${worktreePath}, removing...`);
+        exec(`git worktree remove "${worktreePath}" --force`, { cwd: projectDir });
+    }
+    // Delete local branch from previous runs (may exist even without worktree)
+    exec(`git branch -D "${branch}"`, { cwd: projectDir });
+    // Delete remote branch from previous failed runs
+    exec(`git push origin --delete "${branch}"`, { cwd: projectDir });
+    // Determine source branch: use session branch when auto-merging and it exists
+    let fromBranch = baseBranch;
+    if (autoMerge && sessionBranch && sessionBranch !== baseBranch) {
+        const remoteCheck = exec(`git rev-parse --verify "origin/${sessionBranch}"`, { cwd: projectDir });
+        const localCheck = exec(`git rev-parse --verify "${sessionBranch}"`, { cwd: projectDir });
+        if (remoteCheck.exitCode === 0 || localCheck.exitCode === 0) {
+            fromBranch = sessionBranch;
+        }
+    }
+    // Fetch latest
+    exec('git fetch origin', { cwd: projectDir });
+    // Create worktree from the appropriate branch (try origin/ first, fall back to local)
+    log.info(`Branching worktree from: ${fromBranch}`);
+    const remoteResult = exec(`git worktree add "${worktreePath}" -b "${branch}" "origin/${fromBranch}"`, { cwd: projectDir });
+    if (remoteResult.exitCode !== 0) {
+        const localResult = exec(`git worktree add "${worktreePath}" -b "${branch}" "${fromBranch}"`, { cwd: projectDir });
+        if (localResult.exitCode !== 0) {
+            throw new Error(`Failed to create worktree from ${fromBranch}: ${localResult.stderr}`);
+        }
+        log.info(`Created worktree from local ${fromBranch}`);
+    }
+    else {
+        log.info(`Created worktree from origin/${fromBranch}`);
+    }
+    // Symlink env files from main repo to worktree (gitignored files don't exist in worktrees)
+    for (const envFile of ENV_FILES) {
+        const src = join(projectDir, envFile);
+        const dest = join(worktreePath, envFile);
+        if (existsSync(src)) {
+            // Remove existing file/symlink if present
+            if (existsSync(dest)) {
+                try {
+                    unlinkSync(dest);
+                }
+                catch { /* ignore */ }
+            }
+            symlinkSync(src, dest);
+            log.info(`Symlinked ${envFile} to worktree`);
+        }
+    }
+    // Set COMPOSE_PROJECT_NAME so Docker doesn't use "issue-N" as project name
+    ensureComposeProjectName(worktreePath, projectDir);
+    // Install dependencies unless skipped
+    if (!skipInstall) {
+        log.info('Installing dependencies in worktree...');
+        const installResult = exec('pnpm install --frozen-lockfile', { cwd: worktreePath });
+        if (installResult.exitCode !== 0) {
+            // Fall back to regular install
+            const fallback = exec('pnpm install', { cwd: worktreePath });
+            if (fallback.exitCode !== 0) {
+                log.warn('pnpm install had issues, continuing anyway...');
+            }
+        }
+    }
+    log.info(`Worktree ready at ${worktreePath}`);
+    return { path: worktreePath, branch };
+}
+/**
+ * Remove a worktree. Keeps the branch (needed for PR).
+ */
+export async function cleanupWorktree(options) {
+    const { issueNum, projectDir, autoCleanup = true, dryRun } = options;
+    const worktreePath = resolve(projectDir, '.worktrees', `issue-${issueNum}`);
+    if (!autoCleanup) {
+        log.info('Skipping worktree cleanup (autoCleanup=false)');
+        return;
+    }
+    if (dryRun) {
+        log.dry(`Would clean up worktree: ${worktreePath}`);
+        return;
+    }
+    if (existsSync(worktreePath)) {
+        log.info(`Removing worktree: ${worktreePath}`);
+        const result = exec(`git worktree remove "${worktreePath}" --force`, { cwd: projectDir });
+        if (result.exitCode !== 0) {
+            log.warn('Could not remove worktree cleanly, forcing...');
+            exec(`rm -rf "${worktreePath}"`, { cwd: projectDir });
+            exec('git worktree prune', { cwd: projectDir });
+        }
+    }
+    log.info('Worktree cleaned up');
+}
+/**
+ * Ensure COMPOSE_PROJECT_NAME is set in the worktree's .env file
+ * so Docker Compose doesn't use the worktree directory name (e.g., "issue-2")
+ * as the project name for containers.
+ */
+function ensureComposeProjectName(worktreePath, projectDir) {
+    const repoName = basename(projectDir);
+    const envPath = join(worktreePath, '.env');
+    // Check if .env already has COMPOSE_PROJECT_NAME
+    if (existsSync(envPath)) {
+        // If it's a symlink, we can't modify it — check if the source has the var
+        try {
+            readlinkSync(envPath);
+            // It's a symlink — check if the source .env already has COMPOSE_PROJECT_NAME
+            const content = readFileSync(envPath, 'utf-8');
+            if (content.includes('COMPOSE_PROJECT_NAME'))
+                return;
+            // Source doesn't have it — create a .env.compose override instead
+            const composePath = join(worktreePath, '.env.compose');
+            writeFileSync(composePath, `COMPOSE_PROJECT_NAME=${repoName}\n`);
+            log.info(`Set COMPOSE_PROJECT_NAME=${repoName} in .env.compose`);
+            return;
+        }
+        catch {
+            // Not a symlink — safe to check/append
+            const content = readFileSync(envPath, 'utf-8') ?? '';
+            if (content.includes('COMPOSE_PROJECT_NAME'))
+                return;
+            appendFileSync(envPath, `\nCOMPOSE_PROJECT_NAME=${repoName}\n`);
+            log.info(`Added COMPOSE_PROJECT_NAME=${repoName} to .env`);
+            return;
+        }
+    }
+    // No .env at all — create one with just COMPOSE_PROJECT_NAME
+    writeFileSync(envPath, `COMPOSE_PROJECT_NAME=${repoName}\n`);
+    log.info(`Created .env with COMPOSE_PROJECT_NAME=${repoName}`);
+}
+//# sourceMappingURL=worktree.js.map

package/dist/lib/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../../src/lib/worktree.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@bradtaylorsf/alpha-loop",
+  "version": "1.0.0",
+  "description": "Agent-agnostic automated development loop: Plan → Build → Test → Review → Ship",
+  "type": "module",
+  "packageManager": "pnpm@9.0.0",
+  "bin": {
+    "alpha-loop": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "jest --runInBand",
+    "test:unit": "jest --runInBand",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "automation",
+    "development",
+    "loop",
+    "claude",
+    "codex",
+    "github"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "Bradley Taylor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bradtaylorsf/alpha-loop.git"
+  },
+  "homepage": "https://github.com/bradtaylorsf/alpha-loop#readme",
+  "bugs": {
+    "url": "https://github.com/bradtaylorsf/alpha-loop/issues"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.9.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.6.0",
+    "typescript": "^5.2.2"
+  }
+}

package/templates/agents/implementer.md

@@ -0,0 +1,34 @@
+---
+name: implementer
+description: Implements GitHub issues by writing code, tests, and committing. The primary coding agent in the loop.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: opus
+skills: api-patterns, api-contracts, testing-patterns, jest-mock-patterns, implementation-planning, git-workflow, sqlite-patterns, security-analysis
+---
+
+# Implementer Agent
+
+You implement GitHub issues autonomously. You receive an issue description with acceptance criteria, and you produce working, tested, committed code.
+
+## Process
+
+1. **Read** the issue requirements and acceptance criteria carefully
+2. **Explore** the codebase to understand existing patterns (check CLAUDE.md first)
+3. **Plan** your approach -- which files to create/modify, in what order
+4. **Implement** the changes following existing conventions
+5. **Write tests** for all new functionality (unit tests at minimum)
+6. **Run tests** (`pnpm test`) and fix any failures
+7. **Commit** with a conventional commit message referencing the issue
+
+## Rules
+
+- Follow CLAUDE.md guidelines strictly
+- Match existing code patterns and conventions
+- Write TypeScript with strict types (no `any`)
+- Use pnpm (never npm or yarn)
+- Write tests before or alongside implementation
+- Run `pnpm test` before committing
+- One logical commit per issue
+- Do NOT modify unrelated files
+- Do NOT add features beyond the issue scope
+- Install dependencies as needed (`pnpm add` / `pnpm add -D`)

package/templates/agents/reviewer.md

@@ -0,0 +1,48 @@
+---
+name: reviewer
+description: Reviews code changes, fixes issues found, and produces a review summary. Runs after implementation.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: opus
+skills: code-review, security-analysis, testing-patterns, test-robustness, api-patterns
+---
+
+# Reviewer Agent
+
+You review code changes for a completed GitHub issue. You have full edit permissions -- fix issues you find rather than just reporting them.
+
+## Process
+
+1. **Read** the original issue requirements
+2. **Review** the diff (`git diff origin/master...HEAD`)
+3. **Check** against the code-review skill checklist
+4. **Fix** any CRITICAL or WARNING issues directly
+5. **Run tests** after fixes to verify nothing broke
+6. **Commit** fixes with: `fix: address review findings for #{issue}`
+7. **Report** a brief summary of what you found and fixed
+
+## What to Fix Directly
+
+- Security vulnerabilities
+- Missing error handling
+- Missing tests for new code paths
+- TypeScript `any` types
+- Console.log left in code
+- Code that doesn't match project conventions
+
+## What to Report (Not Fix)
+
+- Architectural suggestions that would require significant refactoring
+- Performance optimizations that aren't urgent
+- Style preferences that aren't in the project conventions
+
+## Output
+
+End your response with a review summary:
+
+```
+### Review Summary
+**Status**: PASS | FAIL
+**Issues found**: N
+**Issues fixed**: N
+**Issues deferred**: N
+```