claudeboard 1.0.0

package/README.md

@@ -0,0 +1,128 @@
+# ClaudeBoard 🤖
+
+**Autonomous coding dashboard for Claude Code.**  
+Turn a PRD into tasks → let Claude work autonomously → watch progress in real time.
+
+---
+
+## How it works
+
+```
+claudeboard init          → Configure project + Supabase
+claudeboard import-prd    → Parse PRD → create tasks automatically
+claudeboard start         → Launch dashboard on localhost
+                          → Give Claude Code the AGENT.md file
+                          → Claude works autonomously 24/7
+```
+
+---
+
+## Install
+
+```bash
+npm install -g claudeboard
+```
+
+---
+
+## Setup (one time per project)
+
+### 1. Init
+```bash
+cd your-project
+claudeboard init
+```
+You'll be asked for:
+- Project name
+- Supabase URL
+- Supabase anon key
+- Port (default 3131)
+
+### 2. Run SQL in Supabase
+Open `claudeboard-setup.sql` and run it in your Supabase SQL Editor.  
+This creates the tables `cb_epics`, `cb_tasks`, `cb_logs` with Realtime enabled.
+
+### 3. Import your PRD
+```bash
+claudeboard import-prd ./PRD.md
+```
+Claude parses your PRD and creates structured tasks grouped by epic automatically.
+
+### 4. Start the dashboard
+```bash
+claudeboard start
+```
+Opens `http://localhost:3131` in your browser.
+
+---
+
+## Running Claude Code autonomously
+
+```bash
+claude --context AGENT.md
+```
+
+The `AGENT.md` file (auto-generated by `claudeboard init`) tells Claude to:
+1. Fetch the next pending task from the API
+2. Start it → mark as `in_progress`
+3. Do the work (write code, run tests, fix errors)
+4. Log progress in real time
+5. Mark as `done` or `error`
+6. Repeat until all tasks are complete
+
+---
+
+## Dashboard features
+
+- **Kanban view** — tasks grouped by epic with status colors
+- **Live activity log** — every action Claude takes
+- **Progress bar** — overall completion %
+- **Add tasks** — add new tasks manually (Claude picks them up automatically)
+- **Task detail** — click any task to see its full log
+- **Real-time** — WebSocket updates, no refresh needed
+
+---
+
+## API (used by Claude Code)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/board` | Full board state |
+| GET | `/api/tasks/next` | Next pending task |
+| POST | `/api/tasks/:id/start` | Mark task as in_progress |
+| POST | `/api/tasks/:id/log` | Add a log entry |
+| POST | `/api/tasks/:id/complete` | Mark task as done |
+| POST | `/api/tasks/:id/fail` | Mark task as error |
+| POST | `/api/tasks` | Add a new task |
+| GET | `/api/tasks/:id/logs` | Get logs for a task |
+
+---
+
+## Remote access
+
+To monitor from another computer:
+
+```bash
+# On the notebook running claudeboard:
+# Install Tailscale: https://tailscale.com
+tailscale up
+
+# Then from your main computer:
+# Visit http://<notebook-tailscale-ip>:3131
+```
+
+Or with SSH tunnel:
+```bash
+ssh -L 3131:localhost:3131 user@notebook-ip
+# Then open http://localhost:3131 locally
+```
+
+---
+
+## Stack
+
+- **CLI**: Node.js + Commander + Enquirer
+- **Server**: Express + WebSockets
+- **Database**: Supabase (Postgres + Realtime)
+- **Dashboard**: Vanilla HTML/CSS/JS (no build step)
+- **AI parsing**: Claude claude-sonnet-4-20250514 for PRD analysis

package/agents/architect.js

@@ -0,0 +1,76 @@
+import { callClaudeJSON } from "./claude-api.js";
+import { createEpic, createTask, addLog } from "./board-client.js";
+
+const SYSTEM = `You are a senior mobile app architect specializing in React Native / Expo apps.
+Your job is to read a PRD and produce a complete, ordered task breakdown.
+
+Rules:
+- Think like a real engineering team: setup first, core features, then polish, then QA
+- Each task must be self-contained and implementable by a single developer agent
+- Be specific — tasks like "implement auth" are too vague. Break into: "create login screen UI", "implement Supabase auth hook", "add protected route navigation"
+- Always include: project setup, navigation, data layer, each feature screen, error handling, loading states, and final QA tasks
+- Priority: high = blocking/core, medium = main features, low = polish/nice-to-have
+- Types: config (setup/deps), feature (new screen or functionality), bug (fix), refactor, test (QA task)`;
+
+export async function runArchitectAgent(prdContent, projectName) {
+  console.log("  🏗️  Architect analyzing PRD...");
+
+  const result = await callClaudeJSON(SYSTEM, `
+Project: ${projectName}
+
+PRD:
+${prdContent}
+
+Return this JSON structure:
+{
+  "techStack": {
+    "framework": "expo",
+    "navigation": "expo-router or react-navigation",
+    "stateManagement": "...",
+    "backend": "supabase / firebase / none",
+    "ui": "nativewind / tamagui / stylesheet",
+    "otherDeps": ["list of npm packages needed"]
+  },
+  "epics": [
+    {
+      "name": "Epic name (e.g. Project Setup, Authentication, Home Screen)",
+      "order": 1,
+      "tasks": [
+        {
+          "title": "Specific task title",
+          "description": "Detailed description of exactly what needs to be implemented. Include: what file(s) to create/modify, what the component/function should do, any specific requirements from the PRD.",
+          "priority": "high|medium|low",
+          "type": "config|feature|test",
+          "acceptanceCriteria": "How to verify this task is done correctly"
+        }
+      ]
+    }
+  ]
+}
+
+Order epics from first to last in implementation order.
+Include 25-50 tasks total for a complete mobile app.`);
+
+  console.log(`  ✓ Architect created ${result.epics.length} epics`);
+
+  // Persist to board
+  let totalTasks = 0;
+  for (let i = 0; i < result.epics.length; i++) {
+    const epicData = result.epics[i];
+    const epic = await createEpic(epicData.name);
+
+    for (const task of epicData.tasks) {
+      await createTask({
+        epicId: epic.id,
+        title: task.title,
+        description: `${task.description}\n\nAcceptance: ${task.acceptanceCriteria || ""}`,
+        priority: task.priority,
+        type: task.type,
+      });
+      totalTasks++;
+    }
+  }
+
+  console.log(`  ✓ Created ${totalTasks} tasks in board`);
+  return { techStack: result.techStack, epics: result.epics, totalTasks };
+}

package/agents/board-client.js

@@ -0,0 +1,91 @@
+import { createClient } from "@supabase/supabase-js";
+
+let supabase = null;
+let PROJECT = "default";
+
+export function initBoard(url, key, project) {
+  supabase = createClient(url, key);
+  PROJECT = project;
+}
+
+export async function getNextTask() {
+  const { data } = await supabase
+    .from("cb_tasks")
+    .select("*, cb_epics(name)")
+    .eq("project", PROJECT)
+    .eq("status", "todo")
+    .order("priority_order", { ascending: true })
+    .limit(1)
+    .single();
+  return data || null;
+}
+
+export async function getAllTasks() {
+  const { data } = await supabase
+    .from("cb_tasks")
+    .select("*, cb_epics(name)")
+    .eq("project", PROJECT)
+    .order("priority_order");
+  return data || [];
+}
+
+export async function startTask(id, log) {
+  await supabase.from("cb_tasks").update({ status: "in_progress", started_at: new Date().toISOString() }).eq("id", id);
+  if (log) await addLog(id, log, "start");
+}
+
+export async function completeTask(id, log) {
+  await supabase.from("cb_tasks").update({ status: "done", completed_at: new Date().toISOString() }).eq("id", id);
+  if (log) await addLog(id, log, "complete");
+}
+
+export async function failTask(id, log) {
+  await supabase.from("cb_tasks").update({ status: "error" }).eq("id", id);
+  if (log) await addLog(id, log, "error");
+}
+
+export async function blockTask(id, log) {
+  await supabase.from("cb_tasks").update({ status: "blocked" }).eq("id", id);
+  if (log) await addLog(id, log, "error");
+}
+
+export async function addLog(taskId, message, type = "progress") {
+  await supabase.from("cb_logs").insert({ project: PROJECT, task_id: taskId, message, type });
+}
+
+export async function createEpic(name) {
+  const { data } = await supabase.from("cb_epics").insert({ name, project: PROJECT }).select().single();
+  return data;
+}
+
+export async function createTask({ epicId, title, description, priority = "medium", type = "feature" }) {
+  const priorityOrder = { high: 1, medium: 2, low: 3 };
+  const { data } = await supabase
+    .from("cb_tasks")
+    .insert({
+      project: PROJECT,
+      epic_id: epicId,
+      title,
+      description,
+      priority,
+      priority_order: priorityOrder[priority] || 2,
+      type,
+      status: "todo",
+    })
+    .select()
+    .single();
+  return data;
+}
+
+export async function getStats() {
+  const tasks = await getAllTasks();
+  return {
+    total: tasks.length,
+    todo: tasks.filter((t) => t.status === "todo").length,
+    in_progress: tasks.filter((t) => t.status === "in_progress").length,
+    done: tasks.filter((t) => t.status === "done").length,
+    error: tasks.filter((t) => t.status === "error").length,
+    blocked: tasks.filter((t) => t.status === "blocked").length,
+    pct: tasks.length > 0 ? Math.round((tasks.filter((t) => t.status === "done").length / tasks.length) * 100) : 0,
+  };
+}

package/agents/claude-api.js

@@ -0,0 +1,91 @@
+/**
+ * Core Claude API caller for all agents
+ * All agents use claude-sonnet-4-20250514 with specific system prompts and tools
+ */
+
+const MODEL = "claude-sonnet-4-20250514";
+const MAX_TOKENS = 8096;
+
+/**
+ * Call Claude API and get text response
+ */
+export async function callClaude(systemPrompt, userMessage, options = {}) {
+  const body = {
+    model: MODEL,
+    max_tokens: options.maxTokens || MAX_TOKENS,
+    system: systemPrompt,
+    messages: [{ role: "user", content: userMessage }],
+  };
+
+  if (options.tools) body.tools = options.tools;
+
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Claude API error ${response.status}: ${err}`);
+  }
+
+  const data = await response.json();
+
+  // Extract text content
+  const text = data.content
+    .filter((b) => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+
+  return { text, raw: data };
+}
+
+/**
+ * Call Claude API expecting JSON response
+ * Returns parsed object or throws
+ */
+export async function callClaudeJSON(systemPrompt, userMessage, options = {}) {
+  const sys = systemPrompt + "\n\nYou MUST respond with valid JSON only. No markdown, no explanation, no backticks. Pure JSON.";
+  const { text } = await callClaude(sys, userMessage, options);
+
+  try {
+    const clean = text.replace(/```json|```/g, "").trim();
+    return JSON.parse(clean);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON from Claude: ${text.slice(0, 200)}`);
+  }
+}
+
+/**
+ * Call Claude with an image (for visual QA)
+ */
+export async function callClaudeWithImage(systemPrompt, userMessage, imageBase64, mediaType = "image/png") {
+  const body = {
+    model: MODEL,
+    max_tokens: MAX_TOKENS,
+    system: systemPrompt,
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "image",
+            source: { type: "base64", media_type: mediaType, data: imageBase64 },
+          },
+          { type: "text", text: userMessage },
+        ],
+      },
+    ],
+  };
+
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  const data = await response.json();
+  const text = data.content?.filter((b) => b.type === "text").map((b) => b.text).join("") || "";
+  return { text, raw: data };
+}

package/agents/developer.js

@@ -0,0 +1,161 @@
+import { callClaudeJSON, callClaude } from "./claude-api.js";
+import { startTask, completeTask, failTask, addLog } from "./board-client.js";
+import { readFile, writeFile, listFiles, projectTree, readFilesAsContext } from "../tools/filesystem.js";
+import { runCommand } from "../tools/terminal.js";
+import path from "path";
+
+const SYSTEM = `You are a senior React Native / Expo developer. You write clean, production-ready code.
+
+Rules:
+- Write complete, working code — never use placeholders or TODOs
+- Always use TypeScript when the project uses it
+- Follow the existing code style and patterns in the project
+- Add console.log statements for key operations so QA can verify functionality
+- Add error handling with meaningful error messages
+- When creating screens, make them visually polished — proper spacing, colors, typography
+- Use the existing navigation structure — never change routing patterns mid-project
+- Import only packages that are already installed or that you explicitly install first
+
+When you need to create or modify files, respond with a JSON array of file operations.`;
+
+export async function runDeveloperAgent(task, projectPath, techStack, retryContext = null) {
+  console.log(`  💻  Developer working on: ${task.title}`);
+  await startTask(task.id, `Starting implementation: ${task.title}`);
+
+  const MAX_RETRIES = 3;
+  let attempt = 0;
+  let lastError = null;
+
+  while (attempt < MAX_RETRIES) {
+    attempt++;
+    if (attempt > 1) {
+      console.log(`  🔄  Retry ${attempt}/${MAX_RETRIES} for: ${task.title}`);
+      await addLog(task.id, `Retry ${attempt}: fixing — ${lastError}`, "progress");
+    }
+
+    try {
+      // Gather context
+      const tree = projectTree(projectPath);
+      const relevantFiles = getRelevantFiles(task, projectPath);
+      const fileContext = readFilesAsContext(relevantFiles, projectPath);
+
+      const retryNote = retryContext
+        ? `\n\nPREVIOUS ATTEMPT FAILED:\n${retryContext}\n\nFix these issues.`
+        : "";
+
+      const lastErrorNote = lastError
+        ? `\n\nLAST ERROR: ${lastError}\nFix this specifically.`
+        : "";
+
+      const prompt = `
+Task: ${task.title}
+Description: ${task.description}
+
+Project structure:
+${tree}
+
+Relevant existing files:
+${fileContext || "No existing files yet — this may be a fresh setup task."}
+
+Tech stack: ${JSON.stringify(techStack || {}, null, 2)}
+${retryNote}${lastErrorNote}
+
+Respond with JSON:
+{
+  "plan": "Brief explanation of your approach",
+  "installPackages": ["pkg1", "pkg2"],
+  "files": [
+    {
+      "path": "relative/path/from/project/root.tsx",
+      "action": "create|modify|delete",
+      "content": "complete file content here"
+    }
+  ],
+  "commands": ["any post-file commands to run, e.g. npx expo install package"],
+  "verificationSteps": "What to check to verify this works"
+}`;
+
+      const result = await callClaudeJSON(SYSTEM, prompt);
+
+      // Install packages first
+      if (result.installPackages?.length > 0) {
+        const pkgs = result.installPackages.join(" ");
+        await addLog(task.id, `Installing: ${pkgs}`, "progress");
+        const install = await runCommand(`npx expo install ${pkgs}`, projectPath, 120000);
+        if (install.exitCode !== 0) {
+          // Try npm install as fallback
+          await runCommand(`npm install ${pkgs}`, projectPath, 120000);
+        }
+      }
+
+      // Write files
+      for (const file of result.files || []) {
+        const fullPath = path.join(projectPath, file.path);
+        if (file.action === "delete") {
+          try { fs.unlinkSync(fullPath); } catch {}
+        } else {
+          writeFile(fullPath, file.content);
+          await addLog(task.id, `${file.action}: ${file.path}`, "progress");
+        }
+      }
+
+      // Run any additional commands
+      for (const cmd of result.commands || []) {
+        await addLog(task.id, `Running: ${cmd}`, "progress");
+        await runCommand(cmd, projectPath, 60000);
+      }
+
+      // Verify it compiles
+      const typecheck = await runCommand("npx tsc --noEmit 2>&1 | head -20", projectPath, 30000);
+      const hasTSErrors = typecheck.stdout.includes("error TS");
+
+      if (hasTSErrors) {
+        lastError = `TypeScript errors:\n${typecheck.stdout}`;
+        continue; // retry
+      }
+
+      // Check for obvious JS syntax errors
+      const buildCheck = await runCommand(
+        "npx expo export --platform web --output-dir /tmp/cb-check 2>&1 | tail -10",
+        projectPath,
+        90000
+      );
+
+      if (buildCheck.stdout.includes("ERROR") || buildCheck.stdout.includes("Cannot find")) {
+        lastError = `Build error:\n${buildCheck.stdout}`;
+        continue; // retry
+      }
+
+      await completeTask(task.id, `✓ Implemented: ${result.plan}`);
+      console.log(`  ✓ Done: ${task.title}`);
+      return { success: true, files: result.files, verificationSteps: result.verificationSteps };
+
+    } catch (err) {
+      lastError = err.message;
+      console.error(`  ✗ Error on attempt ${attempt}:`, err.message);
+    }
+  }
+
+  await failTask(task.id, `Failed after ${MAX_RETRIES} attempts. Last error: ${lastError}`);
+  return { success: false, error: lastError };
+}
+
+/**
+ * Get files relevant to this task based on keywords
+ */
+function getRelevantFiles(task, projectPath) {
+  const keywords = task.title.toLowerCase().split(" ");
+  const allFiles = listFiles(projectPath, [".ts", ".tsx", ".js", ".jsx", ".json"]);
+
+  // Always include key config files
+  const alwaysInclude = ["package.json", "app.json", "tsconfig.json", "babel.config.js"];
+  const result = allFiles.filter((f) => {
+    const rel = path.relative(projectPath, f);
+    if (alwaysInclude.some((name) => rel.endsWith(name))) return true;
+    if (rel.includes("app/") && rel.endsWith("_layout")) return true;
+    // Include files that match task keywords
+    return keywords.some((kw) => kw.length > 4 && rel.toLowerCase().includes(kw));
+  });
+
+  return result.slice(0, 15); // Max 15 files for context
+}