claudeboard 1.0.0

package/agents/orchestrator.js

@@ -0,0 +1,204 @@
+import chalk from "chalk";
+import ora from "ora";
+import fs from "fs";
+import path from "path";
+import { runArchitectAgent } from "./architect.js";
+import { runDeveloperAgent } from "./developer.js";
+import { runQAAgent, runFullAppQA } from "./qa.js";
+import {
+  initBoard,
+  getNextTask,
+  getAllTasks,
+  getStats,
+  addLog,
+  createTask,
+  createEpic,
+} from "./board-client.js";
+import { initSupabaseReader } from "../tools/supabase-reader.js";
+import { runCommand, startProcess, waitForPort } from "../tools/terminal.js";
+
+const PHASES = {
+  ARCHITECTURE: "architecture",
+  DEVELOPMENT: "development",
+  QA_FINAL: "qa_final",
+  COMPLETE: "complete",
+};
+
+export async function runOrchestrator(config) {
+  const {
+    prdPath,
+    projectPath,
+    supabaseUrl,
+    supabaseKey,
+    projectName,
+    expoPort = 8081,
+    skipArchitect = false,
+  } = config;
+
+  console.log(chalk.cyan("\n╔═══════════════════════════════════════╗"));
+  console.log(chalk.cyan("║") + chalk.bold("  🤖 CLAUDEBOARD ORCHESTRATOR STARTING ") + chalk.cyan("║"));
+  console.log(chalk.cyan("╚═══════════════════════════════════════╝\n"));
+
+  // Init board connection
+  initBoard(supabaseUrl, supabaseKey, projectName);
+  initSupabaseReader(supabaseUrl, supabaseKey);
+
+  // Read PRD
+  const prdContent = fs.readFileSync(prdPath, "utf8");
+  console.log(chalk.dim(`  PRD: ${prdPath} (${prdContent.length} chars)`));
+  console.log(chalk.dim(`  Project: ${projectPath}\n`));
+
+  let techStack = {};
+
+  // ── PHASE 1: ARCHITECTURE ──────────────────────────────────────────────────
+  if (!skipArchitect) {
+    console.log(chalk.bold.cyan("[ PHASE 1: ARCHITECTURE ]\n"));
+    const archResult = await runArchitectAgent(prdContent, projectName);
+    techStack = archResult.techStack;
+    console.log(chalk.green(`\n  ✓ ${archResult.totalTasks} tasks created across ${archResult.epics.length} epics\n`));
+  } else {
+    console.log(chalk.dim("  Skipping architect (tasks already exist)\n"));
+  }
+
+  // ── START EXPO ─────────────────────────────────────────────────────────────
+  let expoProcess = null;
+  let expoReady = false;
+  const logFile = path.join(projectPath, ".claudeboard-logs.txt");
+  const logStream = fs.createWriteStream(logFile, { flags: "a" });
+
+  // Check if expo project exists
+  const hasPackageJson = fs.existsSync(path.join(projectPath, "package.json"));
+
+  if (hasPackageJson) {
+    console.log(chalk.dim("  Starting Expo Web for QA screenshots...\n"));
+    expoProcess = startProcess(
+      "npx",
+      ["expo", "start", "--web", "--port", String(expoPort)],
+      projectPath,
+      (log) => {
+        logStream.write(log);
+        if (log.includes("Metro waiting") || log.includes("localhost:" + expoPort)) {
+          expoReady = true;
+        }
+      }
+    );
+
+    // Wait up to 30s for expo to start
+    await waitForPort(expoPort, 30000);
+    expoReady = true;
+    console.log(chalk.dim(`  Expo Web running at http://localhost:${expoPort}\n`));
+  }
+
+  // ── PHASE 2: DEVELOPMENT LOOP ─────────────────────────────────────────────
+  console.log(chalk.bold.cyan("[ PHASE 2: DEVELOPMENT ]\n"));
+
+  let consecutiveFailures = 0;
+  const MAX_CONSECUTIVE_FAILURES = 3;
+
+  while (true) {
+    const task = await getNextTask();
+
+    if (!task) {
+      console.log(chalk.green("\n  ✓ All tasks complete!\n"));
+      break;
+    }
+
+    const stats = await getStats();
+    const pct = stats.pct;
+    const bar = "█".repeat(Math.floor(pct / 5)) + "░".repeat(20 - Math.floor(pct / 5));
+    console.log(chalk.dim(`\n  [${bar}] ${pct}% — ${stats.done}/${stats.total} tasks done`));
+    console.log(chalk.bold(`\n  → ${task.title}`));
+    console.log(chalk.dim(`    Epic: ${task.cb_epics?.name || "—"} | ${task.priority} | ${task.type}`));
+
+    // Run developer agent
+    const devResult = await runDeveloperAgent(task, projectPath, techStack);
+
+    if (!devResult.success) {
+      consecutiveFailures++;
+      console.log(chalk.red(`  ✗ Dev failed (${consecutiveFailures} consecutive)`));
+
+      if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+        console.log(chalk.yellow("\n  ⚠️  Too many consecutive failures — pausing for human review"));
+        console.log(chalk.yellow("  Check the dashboard for blocked tasks.\n"));
+        break;
+      }
+      continue;
+    }
+
+    consecutiveFailures = 0;
+
+    // Run QA agent (only if expo is running and this is a UI/feature task)
+    const shouldRunQA = expoReady && ["feature", "bug"].includes(task.type);
+
+    if (shouldRunQA) {
+      // Give Expo a moment to hot-reload
+      await new Promise((r) => setTimeout(r, 3000));
+
+      const qaResult = await runQAAgent(task, devResult, projectPath, prdContent, expoPort);
+
+      if (!qaResult.passed && qaResult.fixInstructions) {
+        console.log(chalk.yellow("  ↩️  QA failed — sending back to developer..."));
+
+        // Create a fix task right after current
+        await createEpicIfNeeded();
+        const fixedByDev = await runDeveloperAgent(
+          { ...task, title: `FIX: ${task.title}`, description: qaResult.fixInstructions },
+          projectPath,
+          techStack,
+          qaResult.fixInstructions
+        );
+
+        if (fixedByDev.success) {
+          await new Promise((r) => setTimeout(r, 3000));
+          await runQAAgent(task, fixedByDev, projectPath, prdContent, expoPort);
+        }
+      }
+    }
+
+    // Small delay between tasks
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  // ── PHASE 3: FINAL QA ─────────────────────────────────────────────────────
+  if (expoReady) {
+    console.log(chalk.bold.cyan("\n[ PHASE 3: FINAL QA ]\n"));
+    const fullQAReport = await runFullAppQA(projectPath, prdContent, expoPort);
+
+    if (fullQAReport.issues.length > 0) {
+      console.log(chalk.yellow(`  ⚠️  Final QA found ${fullQAReport.issues.length} issues:`));
+      fullQAReport.issues.forEach((issue) => {
+        console.log(chalk.dim(`    ${issue.route}: ${issue.note}`));
+      });
+
+      // Create fix tasks for final issues
+      for (const issue of fullQAReport.issues) {
+        await createTask({
+          title: `Final QA fix: ${issue.route}`,
+          description: issue.note,
+          priority: "high",
+          type: "bug",
+        });
+      }
+
+      console.log(chalk.yellow("\n  Fix tasks added to board. Run claudeboard run --skip-architect to continue.\n"));
+    } else {
+      console.log(chalk.green(`  ✓ Full QA passed — ${fullQAReport.screenshotsCaptures} screens checked\n`));
+    }
+  }
+
+  // ── COMPLETE ───────────────────────────────────────────────────────────────
+  const finalStats = await getStats();
+  console.log(chalk.cyan("\n╔═══════════════════════════════════════╗"));
+  console.log(chalk.cyan("║") + chalk.bold.green(`  ✓ COMPLETE — ${finalStats.done}/${finalStats.total} tasks done (${finalStats.pct}%) `) + chalk.cyan("║"));
+  console.log(chalk.cyan("╚═══════════════════════════════════════╝\n"));
+
+  if (expoProcess) {
+    expoProcess.kill();
+    logStream.end();
+  }
+}
+
+async function createEpicIfNeeded() {
+  // Dummy — fix tasks go into a "Fixes" epic
+  // In practice the board-client handles this
+}

package/agents/qa.js

@@ -0,0 +1,208 @@
+import { callClaude, callClaudeJSON, callClaudeWithImage } from "./claude-api.js";
+import { addLog, createTask, startTask, completeTask, failTask } from "./board-client.js";
+import { readFile, listFiles, projectTree } from "../tools/filesystem.js";
+import { runCommand, waitForPort } from "../tools/terminal.js";
+import { screenshotExpoWeb } from "../tools/screenshot.js";
+import { readRecentLogs, readErrorLogs } from "../tools/supabase-reader.js";
+import path from "path";
+import fs from "fs";
+
+const SYSTEM_QA = `You are a senior QA engineer for mobile apps built with React Native / Expo.
+Your job is to verify that implemented features work correctly and look good.
+
+You receive:
+- The original PRD description of a feature
+- Console logs from the app
+- A screenshot of the current state
+- TypeScript/build errors if any
+
+You must determine:
+1. Does the feature work as described in the PRD?
+2. Does the UI look polished and correct?
+3. Are there any errors in the logs?
+4. What bugs or issues need to be fixed?
+
+Be specific about what's wrong and what needs to change.`;
+
+export async function runQAAgent(task, devResult, projectPath, prdContent, expoPort = 8081) {
+  console.log(`  🔍  QA checking: ${task.title}`);
+  await addLog(task.id, "QA agent starting verification", "progress");
+
+  const qaReport = {
+    passed: false,
+    issues: [],
+    screenshotPath: null,
+    fixInstructions: null,
+  };
+
+  // 1. Check for TypeScript errors
+  const tsResult = await runCommand("npx tsc --noEmit 2>&1 | head -30", projectPath, 30000);
+  if (tsResult.stdout.includes("error TS")) {
+    qaReport.issues.push(`TypeScript errors found:\n${tsResult.stdout}`);
+    await addLog(task.id, `QA: TypeScript errors detected`, "error");
+  }
+
+  // 2. Read console/app logs
+  let appLogs = "";
+  try {
+    // Read from Expo CLI output (saved to temp file by runner)
+    const logFile = path.join(projectPath, ".claudeboard-logs.txt");
+    if (fs.existsSync(logFile)) {
+      appLogs = fs.readFileSync(logFile, "utf8").slice(-3000);
+    }
+  } catch {}
+
+  // 3. Read Supabase error logs if project uses Supabase
+  let supabaseLogs = [];
+  try {
+    supabaseLogs = await readErrorLogs("logs", 10);
+  } catch {}
+
+  // 4. Take screenshot
+  await addLog(task.id, "Taking screenshot of Expo Web...", "progress");
+  const screenshotDir = path.join(projectPath, ".claudeboard-screenshots");
+  const screenshot = await screenshotExpoWeb(expoPort, screenshotDir);
+
+  if (screenshot.success) {
+    qaReport.screenshotPath = screenshot.imagePath;
+    await addLog(task.id, `Screenshot captured: ${path.basename(screenshot.imagePath)}`, "progress");
+  } else {
+    await addLog(task.id, `Screenshot failed: ${screenshot.error}`, "progress");
+  }
+
+  // 5. Visual QA via Claude Vision
+  let visualVerdict = null;
+  if (screenshot.success && screenshot.base64) {
+    const visualPrompt = `
+This is a screenshot of a React Native / Expo app screen.
+
+Task that was just implemented: ${task.title}
+Expected behavior from PRD: ${task.description}
+
+Evaluate:
+1. Does the screen look implemented? (not blank, not error screen)
+2. Does the UI look polished? (proper layout, readable text, no obvious visual bugs)
+3. Does it appear to match what was described in the task?
+4. Any visual issues? (overlapping elements, cut off text, missing components)
+
+Be concise and specific.`;
+
+    const visionResult = await callClaudeWithImage(SYSTEM_QA, visualPrompt, screenshot.base64);
+    visualVerdict = visionResult.text;
+    await addLog(task.id, `Visual QA: ${visualVerdict.slice(0, 200)}`, "progress");
+  }
+
+  // 6. Functional QA — read code and verify logic
+  const relevantFiles = listFiles(projectPath, [".ts", ".tsx"])
+    .filter((f) => {
+      const rel = path.relative(projectPath, f).toLowerCase();
+      return task.title.toLowerCase().split(" ").some((w) => w.length > 4 && rel.includes(w));
+    })
+    .slice(0, 5);
+
+  let codeContext = "";
+  for (const f of relevantFiles) {
+    const content = readFile(f);
+    if (content) {
+      codeContext += `\n### ${path.relative(projectPath, f)}\n${content.slice(0, 1500)}\n`;
+    }
+  }
+
+  const functionalVerdict = await callClaudeJSON(
+    SYSTEM_QA,
+    `
+Task: ${task.title}
+Description: ${task.description}
+
+Code implemented:
+${codeContext || "Could not read relevant files"}
+
+Console logs:
+${appLogs || "No logs captured"}
+
+Supabase errors:
+${supabaseLogs.length > 0 ? JSON.stringify(supabaseLogs) : "None"}
+
+TypeScript status:
+${tsResult.stdout.includes("error TS") ? tsResult.stdout : "No TypeScript errors"}
+
+Visual QA notes:
+${visualVerdict || "No screenshot available"}
+
+Respond with JSON:
+{
+  "passed": true/false,
+  "confidence": 0-100,
+  "issues": ["specific issue 1", "specific issue 2"],
+  "summary": "One sentence verdict",
+  "fixInstructions": "If failed: specific instructions for the developer to fix. If passed: null"
+}`,
+    { maxTokens: 2000 }
+  );
+
+  qaReport.passed = functionalVerdict.passed;
+  qaReport.issues = functionalVerdict.issues || [];
+  qaReport.fixInstructions = functionalVerdict.fixInstructions;
+
+  if (qaReport.passed) {
+    await addLog(task.id, `✓ QA passed (${functionalVerdict.confidence}%): ${functionalVerdict.summary}`, "complete");
+    console.log(`  ✓ QA passed: ${task.title}`);
+  } else {
+    await addLog(
+      task.id,
+      `✗ QA failed: ${functionalVerdict.summary}. Issues: ${qaReport.issues.slice(0, 2).join("; ")}`,
+      "error"
+    );
+    console.log(`  ✗ QA failed: ${task.title}`);
+    console.log(`    Issues: ${qaReport.issues.join(", ")}`);
+  }
+
+  return qaReport;
+}
+
+/**
+ * Full app QA — run at end of development phase
+ * Goes through every major screen and validates against PRD
+ */
+export async function runFullAppQA(projectPath, prdContent, expoPort = 8081) {
+  console.log("\n  🔍  Running full app QA...");
+
+  // Detect routes from expo-router structure
+  const routeFiles = listFiles(path.join(projectPath, "app"), [".tsx", ".ts"])
+    .filter((f) => !f.includes("_layout") && !f.includes("_error"))
+    .map((f) => {
+      const rel = path.relative(path.join(projectPath, "app"), f);
+      return "/" + rel.replace(/\.(tsx|ts)$/, "").replace(/index$/, "");
+    });
+
+  const screenshotDir = path.join(projectPath, ".claudeboard-screenshots", "full-qa");
+  const screenshots = [];
+
+  for (const route of routeFiles.slice(0, 10)) {
+    const shot = await screenshotExpoWeb(expoPort, screenshotDir, route);
+    if (shot.success) screenshots.push({ route, ...shot });
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  // Send all screenshots + PRD to Claude for final verdict
+  const report = {
+    passed: screenshots.length > 0,
+    routes: routeFiles,
+    screenshotsCaptures: screenshots.length,
+    issues: [],
+  };
+
+  for (const shot of screenshots) {
+    if (!shot.base64) continue;
+    const verdict = await callClaudeWithImage(
+      SYSTEM_QA,
+      `Route: ${shot.route}\n\nPRD for reference:\n${prdContent.slice(0, 2000)}\n\nDoes this screen look complete and working? Any issues?`,
+      shot.base64
+    );
+    if (verdict.text.toLowerCase().includes("issue") || verdict.text.toLowerCase().includes("problem")) {
+      report.issues.push({ route: shot.route, note: verdict.text.slice(0, 200) });
+    }
+  }
+
+  return report;
+}

package/bin/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+import { spawn } from "child_process";
+import open from "open";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const LOGO = `
+${chalk.cyan("╔══════════════════════════════════════╗")}
+${chalk.cyan("║")}  ${chalk.bold.white("●")} ${chalk.bold.cyan("CLAUDEBOARD")}  ${chalk.dim("ai engineering team")}  ${chalk.cyan("║")}
+${chalk.cyan("╚══════════════════════════════════════╝")}
+`;
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(process.cwd(), ".claudeboard.json"), "utf8"));
+  } catch {
+    console.log(chalk.yellow("No .claudeboard.json found. Run: claudeboard init"));
+    process.exit(1);
+  }
+}
+
+// ─── INIT ────────────────────────────────────────────────────────────────────
+program
+  .command("init")
+  .description("Initialize claudeboard in a project")
+  .action(async () => {
+    console.log(LOGO);
+    const { default: Enquirer } = await import("enquirer");
+    const enquirer = new Enquirer();
+    console.log(chalk.bold("Let's set up your AI engineering team.\n"));
+
+    const answers = await enquirer.prompt([
+      { type: "input", name: "projectName", message: "Project name:", initial: path.basename(process.cwd()) },
+      { type: "input", name: "supabaseUrl", message: "Supabase URL:", hint: "https://xxxx.supabase.co" },
+      { type: "input", name: "supabaseKey", message: "Supabase anon key:" },
+      { type: "input", name: "port", message: "Dashboard port:", initial: "3131" },
+    ]);
+
+    const spinner = ora("Creating config...").start();
+
+    const config = {
+      projectName: answers.projectName,
+      port: parseInt(answers.port),
+      supabaseUrl: answers.supabaseUrl,
+      supabaseKey: answers.supabaseKey,
+      createdAt: new Date().toISOString(),
+    };
+
+    fs.writeFileSync(path.join(process.cwd(), ".claudeboard.json"), JSON.stringify(config, null, 2));
+
+    const sqlSrc = path.join(__dirname, "../sql/setup.sql");
+    fs.copyFileSync(sqlSrc, path.join(process.cwd(), "claudeboard-setup.sql"));
+
+    spinner.succeed(chalk.green("Config created!"));
+
+    console.log(`
+${chalk.bold("Next steps:")}
+
+${chalk.cyan("1.")} Run the SQL in your Supabase SQL Editor:
+   ${chalk.dim("→ claudeboard-setup.sql")}
+
+${chalk.cyan("2.")} Start the dashboard:
+   ${chalk.bold("claudeboard start")}
+
+${chalk.cyan("3.")} Run the AI team with your PRD:
+   ${chalk.bold("claudeboard run --prd ./PRD.md --project ./your-app")}
+`);
+  });
+
+// ─── START DASHBOARD ─────────────────────────────────────────────────────────
+program
+  .command("start")
+  .description("Start the dashboard server")
+  .option("-p, --port <port>", "Port number")
+  .action(async (opts) => {
+    console.log(LOGO);
+    const config = loadConfig();
+    const port = opts.port || config.port || 3131;
+    const spinner = ora("Starting dashboard...").start();
+
+    const serverPath = path.join(__dirname, "../dashboard/server.js");
+    const server = spawn("node", [serverPath], {
+      env: {
+        ...process.env,
+        SUPABASE_URL: config.supabaseUrl,
+        SUPABASE_KEY: config.supabaseKey,
+        PORT: String(port),
+        PROJECT_NAME: config.projectName,
+      },
+      stdio: "pipe",
+    });
+
+    server.stdout.on("data", (data) => {
+      if (data.toString().includes("READY")) {
+        spinner.succeed(chalk.green("Dashboard running!"));
+        console.log(`\n  ${chalk.bold("→")} ${chalk.cyan(`http://localhost:${port}`)}\n`);
+        console.log(chalk.dim("  Press Ctrl+C to stop\n"));
+        open(`http://localhost:${port}`);
+      }
+    });
+
+    server.stderr.on("data", (d) => console.error(chalk.red(d.toString())));
+    process.on("SIGINT", () => { server.kill(); process.exit(0); });
+  });
+
+// ─── RUN AI TEAM ─────────────────────────────────────────────────────────────
+program
+  .command("run")
+  .description("Run the AI engineering team on your project")
+  .requiredOption("--prd <path>", "Path to PRD markdown file")
+  .requiredOption("--project <path>", "Path to your app project directory")
+  .option("--skip-architect", "Skip architecture phase (tasks already exist)")
+  .option("--expo-port <port>", "Expo Web port for QA screenshots", "8081")
+  .action(async (opts) => {
+    console.log(LOGO);
+    const config = loadConfig();
+
+    if (!fs.existsSync(opts.prd)) {
+      console.log(chalk.red(`PRD not found: ${opts.prd}`)); process.exit(1);
+    }
+    if (!fs.existsSync(opts.project)) {
+      console.log(chalk.red(`Project not found: ${opts.project}`)); process.exit(1);
+    }
+
+    console.log(chalk.bold(`  AI Team starting for: ${chalk.cyan(config.projectName)}\n`));
+    console.log(chalk.dim(`  Dashboard → http://localhost:${config.port}`));
+    console.log(chalk.dim(`  PRD       → ${opts.prd}`));
+    console.log(chalk.dim(`  Project   → ${opts.project}\n`));
+
+    const { runOrchestrator } = await import("../agents/orchestrator.js");
+
+    await runOrchestrator({
+      prdPath: path.resolve(opts.prd),
+      projectPath: path.resolve(opts.project),
+      supabaseUrl: config.supabaseUrl,
+      supabaseKey: config.supabaseKey,
+      projectName: config.projectName,
+      expoPort: parseInt(opts.expoPort),
+      skipArchitect: !!opts.skipArchitect,
+    });
+  });
+
+// ─── IMPORT PRD ──────────────────────────────────────────────────────────────
+program
+  .command("import-prd <file>")
+  .description("Parse PRD → create tasks in board (no agents run)")
+  .action(async (file) => {
+    console.log(LOGO);
+    const config = loadConfig();
+
+    if (!fs.existsSync(file)) {
+      console.log(chalk.red(`File not found: ${file}`)); process.exit(1);
+    }
+
+    const prdContent = fs.readFileSync(file, "utf8");
+    const { initBoard } = await import("../agents/board-client.js");
+    const { runArchitectAgent } = await import("../agents/architect.js");
+
+    initBoard(config.supabaseUrl, config.supabaseKey, config.projectName);
+    const result = await runArchitectAgent(prdContent, config.projectName);
+
+    console.log(chalk.green(`\n  ✓ Created ${result.totalTasks} tasks across ${result.epics.length} epics`));
+    console.log(`\n  Run ${chalk.bold("claudeboard start")} to see your board.\n`);
+  });
+
+// ─── STATUS ──────────────────────────────────────────────────────────────────
+program
+  .command("status")
+  .description("Show current board status in terminal")
+  .action(async () => {
+    const config = loadConfig();
+    const { initBoard, getStats } = await import("../agents/board-client.js");
+    initBoard(config.supabaseUrl, config.supabaseKey, config.projectName);
+
+    const stats = await getStats();
+    const bar = "█".repeat(Math.floor(stats.pct / 5)) + "░".repeat(20 - Math.floor(stats.pct / 5));
+
+    console.log(LOGO);
+    console.log(chalk.bold(`  ${config.projectName}\n`));
+    console.log(`  [${chalk.green(bar)}] ${chalk.bold(stats.pct + "%")}`);
+    console.log(`\n  ${chalk.green("✓ Done:")}     ${stats.done}`);
+    console.log(`  ${chalk.yellow("◌ Running:")}  ${stats.in_progress}`);
+    console.log(`  ${chalk.dim("○ Todo:")}     ${stats.todo}`);
+    console.log(`  ${chalk.red("✗ Error:")}    ${stats.error}\n`);
+  });
+
+program
+  .name("claudeboard")
+  .description("AI engineering team — from PRD to working app, autonomously")
+  .version("1.0.0");
+
+program.parse();