@warpmetrics/coder 0.1.3 → 0.2.1

package/README.md

@@ -1,41 +1,76 @@
 # @warpmetrics/coder
 
-Agent pipeline for implementing GitHub issues with Claude Code. Label an issue with `agent` and it gets implemented, reviewed, and revised automatically.
+Local agent loop that watches a GitHub Projects board for tasks, implements them using Claude Code, and pushes PRs.
 
 ## Quick Start
 
 ```bash
 npx @warpmetrics/coder init
+npx @warpmetrics/coder watch
 ```
 
-This will:
-1. Set up `ANTHROPIC_API_KEY` and `WARPMETRICS_API_KEY` as GitHub secrets
-2. Add two workflow files to `.github/workflows/`
-3. Add pipeline scripts to `.github/scripts/`
-4. Register outcome classifications with WarpMetrics
-
 ## How It Works
 
 ```
-Issue labeled "agent"
-  → agent-implement.yml runs Claude Code Action
-    → Claude reads the issue, creates a branch, implements, opens PR
-      → warp-review reviews the PR (if installed)
-        → agent-revise.yml applies feedback and pushes fixes
-          → Loop until approved or revision limit (3) reached
+Board: "Todo" column
+  → warp-coder picks up the task
+    → clones repo, creates branch, runs Claude Code
+      → pushes branch, opens PR, moves to "In Review"
+        → if review feedback arrives: applies fixes, pushes again
+          → if approved: squash-merges, moves to "Done"
 ```
 
-Every step is instrumented with [WarpMetrics](https://warpmetrics.com) — you get runs, groups, and outcomes tracking the full pipeline.
+The agent polls your GitHub Projects board and processes tasks sequentially:
 
-## Workflows
+1. **Todo** — picks the first item, implements it, opens a PR
+2. **In Review** — detects new review comments, applies feedback (up to 3 revisions)
+3. **Approved** — squash-merges the PR, runs `onMerged` hook, moves to "Done"
+
+Every step is instrumented with [WarpMetrics](https://warpmetrics.com) — you get runs, groups, and outcomes tracking the full pipeline.
 
-### agent-implement.yml
+## Config
+
+`warp-coder init` creates `.warp-coder/config.json`:
+
+```json
+{
+  "board": {
+    "provider": "github-projects",
+    "project": 1,
+    "owner": "your-org",
+    "columns": {
+      "todo": "Todo",
+      "inProgress": "In Progress",
+      "inReview": "In Review",
+      "done": "Done",
+      "blocked": "Blocked"
+    }
+  },
+  "hooks": {
+    "onBeforePush": "npm test",
+    "onMerged": "npm run deploy:prod"
+  },
+  "claude": {
+    "allowedTools": "Bash,Read,Edit,Write,Glob,Grep",
+    "maxTurns": 20
+  },
+  "pollInterval": 30,
+  "maxRevisions": 3,
+  "repo": "git@github.com:your-org/your-repo.git"
+}
+```
 
-Triggered when an issue is labeled `agent`. Creates a branch `agent/issue-{number}`, implements the issue, and opens a PR.
+## Lifecycle Hooks
 
-### agent-revise.yml
+| Hook | When | Use case |
+|------|------|----------|
+| `onBranchCreate` | After creating the implementation branch | Set up environment |
+| `onBeforePush` | Before pushing (implement or revise) | Run tests/lint |
+| `onPRCreated` | After opening a PR | Notify, add labels |
+| `onBeforeMerge` | Before squash-merging | Final checks |
+| `onMerged` | After merge completes | Deploy |
 
-Triggered when `github-actions[bot]` submits a review with comments (i.e., warp-review feedback). Applies the review feedback and pushes to the same branch. Stops after 3 revision attempts.
+Hooks receive env vars: `ISSUE_NUMBER`, `PR_NUMBER`, `BRANCH`, `REPO`.
 
 ## Outcome Classifications
 
@@ -51,13 +86,11 @@ Triggered when `github-actions[bot]` submits a review with comments (i.e., warp-
 | Revision Failed | failure |
 | Max Retries | failure |
 
-## Pairing with warp-review
-
-For the full implement → review → revise loop, install [warp-review](https://github.com/warpmetrics/warp-review):
+## Requirements
 
-```bash
-npx @warpmetrics/review init
-```
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
+- A GitHub Projects v2 board with Status field
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'readline';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { registerClassifications } from '../src/warp.js';
+import { discoverProjectFields } from '../src/boards/github-projects.js';
+import { loadMemory } from '../src/memory.js';
+import { reflect } from '../src/reflect.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultsDir = join(__dirname, '..', 'defaults');
+
+const command = process.argv[2];
+
+if (command === 'watch') {
+  const { watch } = await import('../src/watch.js');
+  await watch();
+} else if (command === 'init') {
+  await runInit();
+} else if (command === 'memory') {
+  const configDir = join(process.cwd(), '.warp-coder');
+  const memory = loadMemory(configDir);
+  console.log(memory || '(no memory yet)');
+} else if (command === 'compact') {
+  const configDir = join(process.cwd(), '.warp-coder');
+  const { loadConfig } = await import('../src/config.js');
+  const config = loadConfig();
+  console.log('Compacting memory...');
+  await reflect({ configDir, step: 'compact', success: true, maxLines: config.memory?.maxLines || 100 });
+  console.log('Done.');
+} else {
+  console.log('');
+  console.log('  warp-coder — local agent loop for implementing GitHub issues');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    warp-coder init      Set up config for a project');
+  console.log('    warp-coder watch     Start the poll loop');
+  console.log('    warp-coder memory    Print current memory file');
+  console.log('    warp-coder compact   Force-rewrite memory file');
+  console.log('');
+  process.exit(command ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Init wizard
+// ---------------------------------------------------------------------------
+
+async function runInit() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = q => new Promise(resolve => rl.question(q, resolve));
+  const log = msg => console.log(msg);
+
+  try {
+    log('');
+    log('  warp-coder — set up agent config');
+    log('');
+
+    // 1. WarpMetrics API key
+    const wmKey = await ask('  ? WarpMetrics API key (get one at warpmetrics.com/app/api-keys): ');
+    if (wmKey && !wmKey.startsWith('wm_')) {
+      log('  \u26a0 Warning: key doesn\'t start with wm_ — make sure this is a valid WarpMetrics API key');
+    }
+    log('');
+
+    // 2. Repo URL
+    let repoDefault = '';
+    try {
+      repoDefault = execSync('git remote get-url origin', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    } catch {}
+    const repoPrompt = repoDefault ? `  ? Repository URL (${repoDefault}): ` : '  ? Repository URL: ';
+    const repoInput = await ask(repoPrompt);
+    const repo = repoInput || repoDefault;
+    if (!repo) {
+      log('  \u2717 Repository URL is required');
+      process.exit(1);
+    }
+    log('');
+
+    // 3. Board provider
+    log('  Board: GitHub Projects v2');
+    const projectNumber = await ask('  ? Project number: ');
+    if (!projectNumber) {
+      log('  \u2717 Project number is required');
+      process.exit(1);
+    }
+
+    // Try to infer owner from repo URL
+    let ownerDefault = '';
+    const match = repo.match(/github\.com[:/]([^/]+)\//);
+    if (match) ownerDefault = match[1];
+    const ownerPrompt = ownerDefault ? `  ? Project owner (${ownerDefault}): ` : '  ? Project owner: ';
+    const ownerInput = await ask(ownerPrompt);
+    const owner = ownerInput || ownerDefault;
+    log('');
+
+    // 4. Discover field IDs and column names
+    let columns = { todo: 'Todo', inProgress: 'In Progress', inReview: 'In Review', done: 'Done', blocked: 'Blocked' };
+    try {
+      log('  Discovering project fields...');
+      const fields = discoverProjectFields(parseInt(projectNumber, 10), owner);
+      const statusField = fields.find(f => f.name === 'Status');
+      if (statusField?.options) {
+        const available = statusField.options.map(o => o.name);
+        log(`  Found columns: ${available.join(', ')}`);
+        // Map available columns to our column keys, keeping defaults for any not found
+        for (const key of Object.keys(columns)) {
+          if (!available.includes(columns[key])) {
+            log(`  \u26a0 Column "${columns[key]}" not found in project`);
+          }
+        }
+      }
+      log('');
+    } catch (err) {
+      log(`  \u26a0 Could not discover fields: ${err.message}`);
+      log('  Using default column names');
+      log('');
+    }
+
+    // 5. Build config
+    const config = {
+      board: {
+        provider: 'github-projects',
+        project: parseInt(projectNumber, 10),
+        owner,
+        columns,
+      },
+      hooks: {},
+      claude: {
+        allowedTools: 'Bash,Read,Edit,Write,Glob,Grep',
+        maxTurns: 20,
+      },
+      pollInterval: 30,
+      maxRevisions: 3,
+      repo,
+    };
+
+    if (wmKey) {
+      config.warpmetricsApiKey = wmKey;
+    }
+
+    // 6. Write config
+    const configDir = '.warp-coder';
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(join(configDir, 'config.json'), JSON.stringify(config, null, 2) + '\n');
+    log(`  \u2713 ${configDir}/config.json created`);
+
+    // 7. Register outcome classifications
+    if (wmKey) {
+      log('  Registering outcome classifications with WarpMetrics...');
+      try {
+        await registerClassifications(wmKey);
+        log('  \u2713 Outcomes configured');
+      } catch (err) {
+        log(`  \u26a0 Some classifications failed: ${err.message}`);
+        log('  You can set them manually in the WarpMetrics dashboard');
+      }
+    }
+
+    // 8. Next steps
+    log('');
+    log('  Done! Next steps:');
+    log('  1. Add .warp-coder/config.json to .gitignore (contains API key)');
+    log('  2. Run: warp-coder watch');
+    log('  3. Add issues to the "Todo" column of your project board');
+    log('  4. View pipeline analytics at https://app.warpmetrics.com');
+    log('');
+  } finally {
+    rl.close();
+  }
+}

package/defaults/config.json

@@ -0,0 +1,26 @@
+{
+  "board": {
+    "provider": "github-projects",
+    "project": 1,
+    "owner": "your-org",
+    "columns": {
+      "todo": "Todo",
+      "inProgress": "In Progress",
+      "inReview": "In Review",
+      "done": "Done",
+      "blocked": "Blocked"
+    }
+  },
+  "hooks": {},
+  "claude": {
+    "allowedTools": "Bash,Read,Edit,Write,Glob,Grep",
+    "maxTurns": 20
+  },
+  "memory": {
+    "enabled": true,
+    "maxLines": 100
+  },
+  "pollInterval": 30,
+  "maxRevisions": 3,
+  "repo": "git@github.com:your-org/your-repo.git"
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@warpmetrics/coder",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
-  "description": "Agent pipeline for implementing GitHub issues with Claude Code. Powered by WarpMetrics.",
+  "description": "Local agent loop for implementing GitHub issues with Claude Code. Powered by WarpMetrics.",
   "bin": {
-    "warp-coder": "./bin/init.js"
+    "warp-coder": "./bin/cli.js"
   },
   "scripts": {
     "release:patch": "npm version patch && git push origin main --tags",
@@ -12,6 +12,7 @@
   },
   "files": [
     "bin/",
+    "src/",
     "defaults/",
     "README.md",
     "LICENSE"
@@ -24,9 +25,9 @@
   "keywords": [
     "agent",
     "claude-code",
-    "github-action",
     "warpmetrics",
     "llm",
-    "code-generation"
+    "code-generation",
+    "automation"
   ]
 }

package/src/agent.js

@@ -0,0 +1,202 @@
+// Implement a single task: clone → branch → claude → push → PR
+
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdirSync, rmSync } from 'fs';
+import * as git from './git.js';
+import * as claude from './claude.js';
+import * as warp from './warp.js';
+import { runHook } from './hooks.js';
+import { loadMemory } from './memory.js';
+import { reflect } from './reflect.js';
+
+const CONFIG_DIR = '.warp-coder';
+
+export async function implement(item, { board, config, log }) {
+  const issueNumber = item.content?.number;
+  const issueTitle = item.content?.title || `Issue #${issueNumber}`;
+  const issueBody = item.content?.body || '';
+  const repo = config.repo;
+  const repoName = repo.replace(/\.git$/, '').split('/').pop(); // owner/repo or just repo
+  const branch = `agent/issue-${issueNumber}`;
+  const workdir = join(tmpdir(), 'warp-coder', String(issueNumber));
+  const configDir = join(process.cwd(), CONFIG_DIR);
+
+  log(`Implementing #${issueNumber}: ${issueTitle}`);
+
+  // Move to In Progress
+  try {
+    await board.moveToInProgress(item);
+  } catch (err) {
+    log(`  warning: could not move to In Progress: ${err.message}`);
+  }
+
+  // WarpMetrics: start pipeline
+  let groupId = null;
+  if (config.warpmetricsApiKey) {
+    try {
+      const pipeline = await warp.startPipeline(config.warpmetricsApiKey, {
+        step: 'implement',
+        repo: repoName,
+        issueNumber,
+        issueTitle,
+      });
+      groupId = pipeline.groupId;
+      log(`  pipeline: run=${pipeline.runId} group=${groupId}`);
+    } catch (err) {
+      log(`  warning: pipeline start failed: ${err.message}`);
+    }
+  }
+
+  let success = false;
+  let claudeResult = null;
+  let taskError = null;
+  const hookOutputs = [];
+
+  try {
+    // Clone
+    rmSync(workdir, { recursive: true, force: true });
+    mkdirSync(workdir, { recursive: true });
+    log(`  cloning into ${workdir}`);
+    git.cloneRepo(repo, workdir);
+
+    // Branch
+    git.createBranch(workdir, branch);
+    log(`  branch: ${branch}`);
+
+    // Hook: onBranchCreate
+    try {
+      const h = runHook('onBranchCreate', config, { workdir, issueNumber, branch, repo: repoName });
+      if (h.ran) hookOutputs.push(h);
+    } catch (err) {
+      if (err.hookResult) hookOutputs.push(err.hookResult);
+      throw err;
+    }
+
+    // Load memory for prompt enrichment
+    const memory = config.memory?.enabled !== false ? loadMemory(configDir) : '';
+
+    // Claude
+    const promptParts = [
+      `You are working on the repository ${repoName}.`,
+      '',
+    ];
+
+    if (memory) {
+      promptParts.push(
+        'Lessons learned from previous tasks in this repository:',
+        '',
+        memory,
+        '',
+      );
+    }
+
+    promptParts.push(
+      `Implement the following GitHub issue:`,
+      '',
+      `**#${issueNumber}: ${issueTitle}**`,
+      '',
+      issueBody,
+      '',
+      'Steps:',
+      '1. Read the codebase to understand relevant context',
+      '2. Implement the changes',
+      '3. Run tests to verify nothing is broken',
+      '4. Commit with a clear message',
+      '',
+      'Do NOT create branches, push, or open PRs — just implement and commit.',
+      'If the issue is unclear or you cannot implement it, explain what is missing.',
+    );
+
+    const prompt = promptParts.join('\n');
+
+    log('  running claude...');
+    claudeResult = await claude.run({
+      prompt,
+      workdir,
+      allowedTools: config.claude?.allowedTools,
+      maxTurns: config.claude?.maxTurns,
+    });
+    log(`  claude done (cost: $${claudeResult.costUsd ?? '?'})`);
+
+    // Hook: onBeforePush
+    try {
+      const h = runHook('onBeforePush', config, { workdir, issueNumber, branch, repo: repoName });
+      if (h.ran) hookOutputs.push(h);
+    } catch (err) {
+      if (err.hookResult) hookOutputs.push(err.hookResult);
+      throw err;
+    }
+
+    // Push + PR
+    log('  pushing...');
+    git.push(workdir, branch);
+    const pr = git.createPR(workdir, {
+      title: issueTitle,
+      body: `Closes #${issueNumber}\n\nImplemented by warp-coder.`,
+    });
+    log(`  PR created: ${pr.url}`);
+
+    // Hook: onPRCreated
+    try {
+      const h = runHook('onPRCreated', config, { workdir, issueNumber, prNumber: pr.number, branch, repo: repoName });
+      if (h.ran) hookOutputs.push(h);
+    } catch (err) {
+      if (err.hookResult) hookOutputs.push(err.hookResult);
+      throw err;
+    }
+
+    // Move to In Review
+    try {
+      await board.moveToReview(item);
+    } catch (err) {
+      log(`  warning: could not move to In Review: ${err.message}`);
+    }
+
+    success = true;
+  } catch (err) {
+    taskError = err.message;
+    log(`  failed: ${err.message}`);
+  } finally {
+    // WarpMetrics: record outcome
+    if (config.warpmetricsApiKey && groupId) {
+      try {
+        const outcome = await warp.recordOutcome(config.warpmetricsApiKey, groupId, {
+          step: 'implement',
+          success,
+          costUsd: claudeResult?.costUsd,
+          error: taskError,
+          hooksFailed: hookOutputs.some(h => h.exitCode !== 0),
+          issueNumber,
+        });
+        log(`  outcome: ${outcome.name}`);
+      } catch (err) {
+        log(`  warning: outcome recording failed: ${err.message}`);
+      }
+    }
+
+    // Reflect
+    if (config.memory?.enabled !== false) {
+      try {
+        await reflect({
+          configDir,
+          step: 'implement',
+          issue: { number: issueNumber, title: issueTitle },
+          success,
+          error: taskError,
+          hookOutputs: hookOutputs.filter(h => h.ran),
+          claudeOutput: claudeResult?.result,
+          maxLines: config.memory?.maxLines || 100,
+        });
+        log('  reflect: memory updated');
+      } catch (err) {
+        log(`  warning: reflect failed: ${err.message}`);
+      }
+    }
+
+    // Cleanup
+    rmSync(workdir, { recursive: true, force: true });
+  }
+
+  return success;
+}

package/src/boards/github-projects.js

@@ -0,0 +1,114 @@
+// GitHub Projects v2 board adapter.
+// Uses `gh` CLI for all API interactions.
+
+import { execSync } from 'child_process';
+
+function gh(args, opts = {}) {
+  return execSync(`gh ${args}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...opts }).trim();
+}
+
+function ghJson(args, opts = {}) {
+  const out = gh(args, opts);
+  return out ? JSON.parse(out) : null;
+}
+
+export function create({ project, owner, statusField = 'Status', columns = {} }) {
+  const colNames = {
+    todo: columns.todo || 'Todo',
+    inProgress: columns.inProgress || 'In Progress',
+    inReview: columns.inReview || 'In Review',
+    done: columns.done || 'Done',
+    blocked: columns.blocked || 'Blocked',
+  };
+
+  // Cache field/option IDs (discovered on first use)
+  let fieldId = null;
+  let optionIds = null;
+
+  function discoverField() {
+    if (fieldId) return;
+    const fields = ghJson(`project field-list ${project} --owner ${owner} --format json`);
+    const field = fields?.fields?.find(f => f.name === statusField);
+    if (!field) throw new Error(`Status field "${statusField}" not found in project ${project}`);
+    fieldId = field.id;
+    optionIds = {};
+    for (const opt of field.options || []) {
+      optionIds[opt.name] = opt.id;
+    }
+  }
+
+  function getOptionId(colKey) {
+    discoverField();
+    const name = colNames[colKey];
+    const id = optionIds[name];
+    if (!id) throw new Error(`Column "${name}" not found. Available: ${Object.keys(optionIds).join(', ')}`);
+    return id;
+  }
+
+  async function listItemsByStatus(statusName) {
+    const items = ghJson(`project item-list ${project} --owner ${owner} --format json`);
+    return (items?.items || []).filter(item => {
+      const status = item.status || item.fields?.find(f => f.name === statusField)?.value;
+      return status === statusName;
+    });
+  }
+
+  async function moveItem(item, colKey) {
+    discoverField();
+    const optId = getOptionId(colKey);
+    gh(`project item-edit --id ${item.id} --project-id ${item.projectId || project} --field-id ${fieldId} --single-select-option-id ${optId}`);
+  }
+
+  return {
+    async listTodo() {
+      return listItemsByStatus(colNames.todo);
+    },
+
+    async listInReview() {
+      const items = await listItemsByStatus(colNames.inReview);
+      // Filter to items that have new reviews
+      const withReviews = [];
+      for (const item of items) {
+        if (!item.content?.number) continue;
+        try {
+          const reviews = ghJson(`api repos/${owner}/${item.content.repository}/pulls/${item.content.number}/reviews`);
+          const hasNew = reviews?.some(r => r.state === 'COMMENTED' || r.state === 'CHANGES_REQUESTED');
+          if (hasNew) withReviews.push(item);
+        } catch {
+          // Skip items we can't check
+        }
+      }
+      return withReviews;
+    },
+
+    async listApproved() {
+      const items = await listItemsByStatus(colNames.inReview);
+      const approved = [];
+      for (const item of items) {
+        if (!item.content?.number) continue;
+        try {
+          const reviews = ghJson(`api repos/${owner}/${item.content.repository}/pulls/${item.content.number}/reviews`);
+          const isApproved = reviews?.some(r => r.state === 'APPROVED');
+          if (isApproved) approved.push(item);
+        } catch {
+          // Skip
+        }
+      }
+      return approved;
+    },
+
+    moveToInProgress(item) { return moveItem(item, 'inProgress'); },
+    moveToReview(item) { return moveItem(item, 'inReview'); },
+    moveToBlocked(item) { return moveItem(item, 'blocked'); },
+    moveToDone(item) { return moveItem(item, 'done'); },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Field discovery for init wizard
+// ---------------------------------------------------------------------------
+
+export function discoverProjectFields(project, owner) {
+  const fields = ghJson(`project field-list ${project} --owner ${owner} --format json`);
+  return fields?.fields || [];
+}

package/src/boards/index.js

@@ -0,0 +1,14 @@
+import { create as createGitHubProjects } from './github-projects.js';
+
+const providers = {
+  'github-projects': createGitHubProjects,
+};
+
+export function createBoard(config) {
+  const provider = config.board?.provider;
+  const factory = providers[provider];
+  if (!factory) {
+    throw new Error(`Unknown board provider: ${provider}. Available: ${Object.keys(providers).join(', ')}`);
+  }
+  return factory(config.board);
+}