@jlongo78/agent-spaces 0.9.8 → 0.9.9

package/.next/standalone/docs/superpowers/plans/2026-04-21-workspace-todos.md

@@ -0,0 +1,1097 @@
+# Workspace Todos Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a workspace-scoped todo list to Spaces, rendered inline above the pane grid on `/terminal`, with minimal CRUD (add/edit/toggle/delete) and a "show completed" toggle.
+
+**Architecture:** New SQLite table `workspace_todos` (FK to `workspaces` with `ON DELETE CASCADE`), new query helpers in `src/lib/db/queries.ts`, new Next.js API routes under `src/app/api/workspaces/[id]/todos/`, and a new client component `src/components/workspace/workspace-todos.tsx` mounted in `src/app/(desktop)/terminal/page.tsx`. Mutations are optimistic with rollback on failure.
+
+**Tech Stack:** Next.js App Router, React 18 client components, better-sqlite3, TypeScript, Tailwind, lucide-react, vitest + better-sqlite3 for tests.
+
+**Spec:** `docs/superpowers/specs/2026-04-21-workspace-todos-design.md`
+
+**Repo workflow note:** Per user preference, commit directly to `main`. No feature branch, no PR. Each task ends with a commit.
+
+---
+
+## File Structure
+
+**Create:**
+- `src/app/api/workspaces/[id]/todos/route.ts` — GET + POST handlers
+- `src/app/api/workspaces/[id]/todos/[todoId]/route.ts` — PATCH + DELETE handlers
+- `src/components/workspace/workspace-todos.tsx` — inline UI component
+- `tests/db/workspace-todos.test.ts` — query-layer tests (in-process better-sqlite3 instance)
+- `docs/features/workspace-todos.md` — feature doc (per `docs/FEATURE_DOC_GUIDE.md`)
+
+**Modify:**
+- `src/lib/db/schema.ts` — add `workspace_todos` table + index inside `initSchema()`
+- `src/lib/db/queries.ts` — add `getWorkspaceTodos`, `addWorkspaceTodo`, `updateWorkspaceTodo`, `deleteWorkspaceTodo`
+- `src/types/claude.ts` (or equivalent types file — confirm in Task 2) — add `WorkspaceTodo` type
+- `src/app/(desktop)/terminal/page.tsx` — mount `<WorkspaceTodos>` above the pane grid
+
+---
+
+## Task 1: DB schema — add `workspace_todos` table
+
+**Files:**
+- Modify: `src/lib/db/schema.ts`
+
+- [ ] **Step 1: Append CREATE TABLE + INDEX DDL inside `initSchema()`**
+
+Open `src/lib/db/schema.ts`. Locate the multi-statement SQL block inside `initSchema()` that defines all existing tables (roughly lines 27-116, inside the template-literal string passed to better-sqlite3). At the **end** of that template-literal block (right before the closing `` ` ``), append the following SQL:
+
+```sql
+    CREATE TABLE IF NOT EXISTS workspace_todos (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      workspace_id INTEGER NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      text TEXT NOT NULL,
+      completed INTEGER NOT NULL DEFAULT 0,
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      created TEXT NOT NULL DEFAULT (datetime('now')),
+      completed_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workspace_todos_workspace
+      ON workspace_todos(workspace_id);
+```
+
+No `addCol` calls are needed — this is a brand new table, and `IF NOT EXISTS` makes the migration safe on existing DBs.
+
+- [ ] **Step 2: Start the app, confirm the table was created**
+
+Run:
+```bash
+npm run build && npm start
+```
+
+In a second terminal, open the user's SQLite DB (adjust path if needed):
+```bash
+sqlite3 ~/.spaces/*.db ".schema workspace_todos"
+```
+
+Expected output includes the `CREATE TABLE workspace_todos (...)` statement and the `CREATE INDEX` line.
+
+Stop the dev server.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/lib/db/schema.ts
+git commit -m "feat(db): add workspace_todos table for workspace-scoped todos"
+```
+
+---
+
+## Task 2: TypeScript type + DB query helpers
+
+**Files:**
+- Modify: `src/types/claude.ts` (or whichever types file holds `Workspace`/`PaneData` — grep to confirm)
+- Modify: `src/lib/db/queries.ts`
+
+- [ ] **Step 1: Locate the types file**
+
+Run:
+```bash
+grep -rn "export interface Workspace" src/types src/lib
+```
+
+Expected: one or two hits showing where `Workspace` is declared (likely `src/types/claude.ts`). Use that same file for `WorkspaceTodo`.
+
+- [ ] **Step 2: Add the `WorkspaceTodo` type**
+
+At the bottom of the types file from Step 1, add:
+
+```ts
+export interface WorkspaceTodo {
+  id: number;
+  workspaceId: number;
+  text: string;
+  completed: boolean;
+  sortOrder: number;
+  created: string;
+  completedAt: string | null;
+}
+```
+
+- [ ] **Step 3: Add query helpers to `src/lib/db/queries.ts`**
+
+At the **end** of `src/lib/db/queries.ts` (after the last existing helper), append:
+
+```ts
+// ─── Workspace Todos ───────────────────────────────────────
+
+import type { WorkspaceTodo } from '@/types/claude'; // Adjust path if Step 1 found a different file
+
+interface TodoRow {
+  id: number;
+  workspace_id: number;
+  text: string;
+  completed: number;
+  sort_order: number;
+  created: string;
+  completed_at: string | null;
+}
+
+function rowToTodo(r: TodoRow): WorkspaceTodo {
+  return {
+    id: r.id,
+    workspaceId: r.workspace_id,
+    text: r.text,
+    completed: !!r.completed,
+    sortOrder: r.sort_order,
+    created: r.created,
+    completedAt: r.completed_at,
+  };
+}
+
+export function getWorkspaceTodos(workspaceId: number): WorkspaceTodo[] {
+  const db = getDb();
+  const rows = db.prepare(`
+    SELECT id, workspace_id, text, completed, sort_order, created, completed_at
+    FROM workspace_todos
+    WHERE workspace_id = ?
+    ORDER BY completed ASC,
+             CASE WHEN completed = 0 THEN sort_order END ASC,
+             completed_at DESC
+  `).all(workspaceId) as TodoRow[];
+  return rows.map(rowToTodo);
+}
+
+export function addWorkspaceTodo(workspaceId: number, text: string): WorkspaceTodo {
+  const db = getDb();
+  const trimmed = text.trim();
+  if (!trimmed) throw new Error('todo text is required');
+
+  const maxRow = db.prepare(`
+    SELECT COALESCE(MAX(sort_order), -1) AS max_order
+    FROM workspace_todos
+    WHERE workspace_id = ? AND completed = 0
+  `).get(workspaceId) as { max_order: number };
+  const nextOrder = (maxRow?.max_order ?? -1) + 1;
+
+  const info = db.prepare(`
+    INSERT INTO workspace_todos (workspace_id, text, sort_order)
+    VALUES (?, ?, ?)
+  `).run(workspaceId, trimmed, nextOrder);
+
+  const row = db.prepare(`
+    SELECT id, workspace_id, text, completed, sort_order, created, completed_at
+    FROM workspace_todos WHERE id = ?
+  `).get(Number(info.lastInsertRowid)) as TodoRow;
+  return rowToTodo(row);
+}
+
+export function updateWorkspaceTodo(
+  todoId: number,
+  data: { text?: string; completed?: boolean }
+): WorkspaceTodo | null {
+  const db = getDb();
+
+  if (data.text !== undefined) {
+    const trimmed = data.text.trim();
+    if (!trimmed) throw new Error('todo text cannot be empty');
+    db.prepare('UPDATE workspace_todos SET text = ? WHERE id = ?').run(trimmed, todoId);
+  }
+
+  if (data.completed !== undefined) {
+    if (data.completed) {
+      db.prepare(`
+        UPDATE workspace_todos
+        SET completed = 1, completed_at = datetime('now')
+        WHERE id = ?
+      `).run(todoId);
+    } else {
+      db.prepare(`
+        UPDATE workspace_todos
+        SET completed = 0, completed_at = NULL
+        WHERE id = ?
+      `).run(todoId);
+    }
+  }
+
+  const row = db.prepare(`
+    SELECT id, workspace_id, text, completed, sort_order, created, completed_at
+    FROM workspace_todos WHERE id = ?
+  `).get(todoId) as TodoRow | undefined;
+  return row ? rowToTodo(row) : null;
+}
+
+export function deleteWorkspaceTodo(todoId: number): void {
+  const db = getDb();
+  db.prepare('DELETE FROM workspace_todos WHERE id = ?').run(todoId);
+}
+```
+
+**Note:** If the top of `queries.ts` already imports from `@/types/claude`, merge `WorkspaceTodo` into that existing import instead of duplicating.
+
+- [ ] **Step 4: Type-check**
+
+Run:
+```bash
+npx tsc --noEmit
+```
+
+Expected: no new errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/db/queries.ts src/types/claude.ts
+git commit -m "feat(db): add workspace-todo query helpers"
+```
+
+---
+
+## Task 3: Tests for the DB query helpers
+
+**Files:**
+- Create: `tests/db/workspace-todos.test.ts`
+- Modify: `src/lib/db/schema.ts` (export a test-only accessor to the internal connection cache)
+
+- [ ] **Step 1: Add a test-only accessor in `schema.ts`**
+
+Open `src/lib/db/schema.ts`. At the very bottom of the file (after the `closeDb` function), append:
+
+```ts
+// Test-only export. Do not use outside of tests.
+export const __testing = {
+  dbs: _dbs,
+};
+```
+
+This exposes the private per-user connection cache so tests can inject a throwaway DB without touching the user's real `~/.spaces/<user>.db`.
+
+- [ ] **Step 2: Write the test file**
+
+Create `tests/db/workspace-todos.test.ts` with:
+
+```ts
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import Database from 'better-sqlite3';
+
+import { __testing } from '@/lib/db/schema';
+import {
+  getWorkspaceTodos,
+  addWorkspaceTodo,
+  updateWorkspaceTodo,
+  deleteWorkspaceTodo,
+} from '@/lib/db/queries';
+
+const TEST_USER = 'test-user'; // matches tests/setup.ts auth mock
+let db: Database.Database;
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spaces-todos-test-'));
+  const dbPath = path.join(tempDir, 'test.db');
+  db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  // Recreate just the tables we need for these tests
+  const ddl = `
+    CREATE TABLE workspaces (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      color TEXT DEFAULT '#6366f1',
+      created TEXT DEFAULT (datetime('now'))
+    );
+    CREATE TABLE workspace_todos (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      workspace_id INTEGER NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      text TEXT NOT NULL,
+      completed INTEGER NOT NULL DEFAULT 0,
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      created TEXT NOT NULL DEFAULT (datetime('now')),
+      completed_at TEXT
+    );
+    CREATE INDEX idx_workspace_todos_workspace ON workspace_todos(workspace_id);
+  `;
+  // Multi-statement DDL goes through the driver's batch API
+  (db as any).exec(ddl);
+
+  // Inject our test DB into the module cache so getDb() returns it
+  __testing.dbs.set(TEST_USER, db);
+
+  // Seed one workspace
+  db.prepare("INSERT INTO workspaces (id, name) VALUES (1, 'Test WS')").run();
+});
+
+afterEach(() => {
+  try { db.close(); } catch {}
+  __testing.dbs.delete(TEST_USER);
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('workspace todos query helpers', () => {
+  it('adds a todo with incrementing sort_order among uncompleted rows', () => {
+    const a = addWorkspaceTodo(1, 'first');
+    const b = addWorkspaceTodo(1, 'second');
+    const c = addWorkspaceTodo(1, 'third');
+
+    expect(a.sortOrder).toBe(0);
+    expect(b.sortOrder).toBe(1);
+    expect(c.sortOrder).toBe(2);
+    expect(a.completed).toBe(false);
+    expect(a.text).toBe('first');
+  });
+
+  it('trims text and rejects empty', () => {
+    const t = addWorkspaceTodo(1, '  hello  ');
+    expect(t.text).toBe('hello');
+
+    expect(() => addWorkspaceTodo(1, '   ')).toThrow();
+    expect(() => addWorkspaceTodo(1, '')).toThrow();
+  });
+
+  it('toggles completed and sets/clears completed_at', () => {
+    const t = addWorkspaceTodo(1, 'toggle me');
+    expect(t.completedAt).toBeNull();
+
+    const done = updateWorkspaceTodo(t.id, { completed: true });
+    expect(done?.completed).toBe(true);
+    expect(done?.completedAt).not.toBeNull();
+
+    const undone = updateWorkspaceTodo(t.id, { completed: false });
+    expect(undone?.completed).toBe(false);
+    expect(undone?.completedAt).toBeNull();
+  });
+
+  it('updates text, trims, rejects empty', () => {
+    const t = addWorkspaceTodo(1, 'original');
+    const upd = updateWorkspaceTodo(t.id, { text: '  edited  ' });
+    expect(upd?.text).toBe('edited');
+
+    expect(() => updateWorkspaceTodo(t.id, { text: '   ' })).toThrow();
+  });
+
+  it('lists todos: uncompleted first by sort_order, completed last by completed_at desc', () => {
+    const a = addWorkspaceTodo(1, 'a');
+    const b = addWorkspaceTodo(1, 'b');
+    const c = addWorkspaceTodo(1, 'c');
+
+    // Complete b first, then a. Expected completed order: a (newest completed) then b.
+    updateWorkspaceTodo(b.id, { completed: true });
+    updateWorkspaceTodo(a.id, { completed: true });
+
+    const list = getWorkspaceTodos(1);
+    expect(list.map(t => t.text)).toEqual(['c', 'a', 'b']);
+  });
+
+  it('deletes a todo', () => {
+    const t = addWorkspaceTodo(1, 'doomed');
+    deleteWorkspaceTodo(t.id);
+    expect(getWorkspaceTodos(1)).toHaveLength(0);
+  });
+
+  it('cascades when the workspace is deleted', () => {
+    addWorkspaceTodo(1, 'x');
+    addWorkspaceTodo(1, 'y');
+    db.prepare('DELETE FROM workspaces WHERE id = 1').run();
+    const rows = db.prepare('SELECT COUNT(*) AS n FROM workspace_todos').get() as { n: number };
+    expect(rows.n).toBe(0);
+  });
+
+  it('scopes listing by workspace', () => {
+    db.prepare("INSERT INTO workspaces (id, name) VALUES (2, 'Other')").run();
+    addWorkspaceTodo(1, 'ws-1-a');
+    addWorkspaceTodo(2, 'ws-2-a');
+    addWorkspaceTodo(1, 'ws-1-b');
+
+    const ws1 = getWorkspaceTodos(1);
+    const ws2 = getWorkspaceTodos(2);
+    expect(ws1.map(t => t.text).sort()).toEqual(['ws-1-a', 'ws-1-b']);
+    expect(ws2.map(t => t.text)).toEqual(['ws-2-a']);
+  });
+});
+```
+
+- [ ] **Step 3: Run the tests**
+
+Run:
+```bash
+npx vitest run tests/db/workspace-todos.test.ts
+```
+
+Expected: 8 tests pass.
+
+If any test fails, re-check that Task 2's queries were added correctly and that the `__testing` accessor from Step 1 exports the same `_dbs` Map used internally by `getDb()`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/db/workspace-todos.test.ts src/lib/db/schema.ts
+git commit -m "test(db): cover workspace-todo query helpers and ordering invariants"
+```
+
+---
+
+## Task 4: API route — `GET`/`POST /api/workspaces/:id/todos`
+
+**Files:**
+- Create: `src/app/api/workspaces/[id]/todos/route.ts`
+
+- [ ] **Step 1: Create the route file**
+
+Create `src/app/api/workspaces/[id]/todos/route.ts` with:
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getAuthUser, withUser } from '@/lib/auth';
+import { ensureInitialized } from '@/lib/db/init';
+import { getWorkspaceTodos, addWorkspaceTodo } from '@/lib/db/queries';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = getAuthUser(request);
+  return withUser(user, async () => {
+    await ensureInitialized();
+    const { id } = await params;
+    const wsId = parseInt(id, 10);
+    if (!Number.isFinite(wsId)) {
+      return NextResponse.json({ error: 'invalid workspace id' }, { status: 400 });
+    }
+    const todos = getWorkspaceTodos(wsId);
+    return NextResponse.json(todos);
+  });
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = getAuthUser(request);
+  return withUser(user, async () => {
+    await ensureInitialized();
+    const { id } = await params;
+    const wsId = parseInt(id, 10);
+    if (!Number.isFinite(wsId)) {
+      return NextResponse.json({ error: 'invalid workspace id' }, { status: 400 });
+    }
+    const body = await request.json().catch(() => null);
+    const text = typeof body?.text === 'string' ? body.text : '';
+    if (!text.trim()) {
+      return NextResponse.json({ error: 'text is required' }, { status: 400 });
+    }
+    const todo = addWorkspaceTodo(wsId, text);
+    return NextResponse.json(todo, { status: 201 });
+  });
+}
+```
+
+- [ ] **Step 2: Smoke-test against the running server**
+
+In one terminal:
+```bash
+npm run dev
+```
+
+In another (replace `1` with an existing workspace id from your DB):
+```bash
+curl -s http://localhost:3457/api/workspaces/1/todos
+curl -s -X POST http://localhost:3457/api/workspaces/1/todos \
+  -H 'content-type: application/json' \
+  -d '{"text":"wire up API"}'
+curl -s http://localhost:3457/api/workspaces/1/todos
+```
+
+Expected:
+1. First GET returns `[]`.
+2. POST returns a JSON todo with `id`, `workspaceId: 1`, `text: "wire up API"`, `completed: false`.
+3. Second GET returns an array containing that todo.
+
+Stop the dev server.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add "src/app/api/workspaces/[id]/todos/route.ts"
+git commit -m "feat(api): add GET/POST /api/workspaces/:id/todos"
+```
+
+---
+
+## Task 5: API route — `PATCH`/`DELETE /api/workspaces/:id/todos/:todoId`
+
+**Files:**
+- Create: `src/app/api/workspaces/[id]/todos/[todoId]/route.ts`
+
+- [ ] **Step 1: Create the route file**
+
+Create `src/app/api/workspaces/[id]/todos/[todoId]/route.ts` with:
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getAuthUser, withUser } from '@/lib/auth';
+import { ensureInitialized } from '@/lib/db/init';
+import { updateWorkspaceTodo, deleteWorkspaceTodo } from '@/lib/db/queries';
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; todoId: string }> }
+) {
+  const user = getAuthUser(request);
+  return withUser(user, async () => {
+    await ensureInitialized();
+    const { todoId } = await params;
+    const tid = parseInt(todoId, 10);
+    if (!Number.isFinite(tid)) {
+      return NextResponse.json({ error: 'invalid todo id' }, { status: 400 });
+    }
+    const body = await request.json().catch(() => null);
+    if (!body || (body.text === undefined && body.completed === undefined)) {
+      return NextResponse.json({ error: 'text or completed required' }, { status: 400 });
+    }
+    try {
+      const updated = updateWorkspaceTodo(tid, {
+        text: typeof body.text === 'string' ? body.text : undefined,
+        completed: typeof body.completed === 'boolean' ? body.completed : undefined,
+      });
+      if (!updated) {
+        return NextResponse.json({ error: 'not found' }, { status: 404 });
+      }
+      return NextResponse.json(updated);
+    } catch (err: any) {
+      return NextResponse.json({ error: err.message || 'update failed' }, { status: 400 });
+    }
+  });
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string; todoId: string }> }
+) {
+  const user = getAuthUser(request);
+  return withUser(user, async () => {
+    await ensureInitialized();
+    const { todoId } = await params;
+    const tid = parseInt(todoId, 10);
+    if (!Number.isFinite(tid)) {
+      return NextResponse.json({ error: 'invalid todo id' }, { status: 400 });
+    }
+    deleteWorkspaceTodo(tid);
+    return NextResponse.json({ ok: true });
+  });
+}
+```
+
+- [ ] **Step 2: Smoke-test**
+
+With `npm run dev` running, and assuming you still have the todo from Task 4 (example id=1):
+
+```bash
+# Toggle completed
+curl -s -X PATCH http://localhost:3457/api/workspaces/1/todos/1 \
+  -H 'content-type: application/json' \
+  -d '{"completed":true}'
+
+# Edit text
+curl -s -X PATCH http://localhost:3457/api/workspaces/1/todos/1 \
+  -H 'content-type: application/json' \
+  -d '{"text":"wire up the API (done)"}'
+
+# Delete
+curl -s -X DELETE http://localhost:3457/api/workspaces/1/todos/1
+```
+
+Expected: each call returns the updated todo JSON (or `{"ok":true}` for DELETE); a final GET on the list endpoint returns `[]`.
+
+Stop the dev server.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add "src/app/api/workspaces/[id]/todos/[todoId]/route.ts"
+git commit -m "feat(api): add PATCH/DELETE /api/workspaces/:id/todos/:todoId"
+```
+
+---
+
+## Task 6: UI component — `<WorkspaceTodos />`
+
+**Files:**
+- Create: `src/components/workspace/workspace-todos.tsx`
+
+- [ ] **Step 1: Write the component**
+
+Create `src/components/workspace/workspace-todos.tsx` with:
+
+```tsx
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Check, Plus, X, ListTodo, Eye, EyeOff } from 'lucide-react';
+import { api } from '@/lib/api';
+import type { WorkspaceTodo } from '@/types/claude';
+
+export function WorkspaceTodos({ workspaceId }: { workspaceId: number | null }) {
+  const [todos, setTodos] = useState<WorkspaceTodo[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [input, setInput] = useState('');
+  const [showCompleted, setShowCompleted] = useState(true);
+  const [editingId, setEditingId] = useState<number | null>(null);
+  const [editText, setEditText] = useState('');
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Load on workspace change
+  useEffect(() => {
+    if (workspaceId == null) { setTodos([]); return; }
+    let cancelled = false;
+    setLoading(true);
+    fetch(api(`/api/workspaces/${workspaceId}/todos`))
+      .then(r => r.json())
+      .then((data: WorkspaceTodo[]) => {
+        if (!cancelled) setTodos(Array.isArray(data) ? data : []);
+      })
+      .catch(() => { if (!cancelled) setTodos([]); })
+      .finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [workspaceId]);
+
+  const addTodo = useCallback(async () => {
+    const text = input.trim();
+    if (!text || workspaceId == null) return;
+
+    // Optimistic: append a temp row with a negative id and max sort order
+    const tempId = -Date.now();
+    const temp: WorkspaceTodo = {
+      id: tempId,
+      workspaceId,
+      text,
+      completed: false,
+      sortOrder: Number.MAX_SAFE_INTEGER,
+      created: new Date().toISOString(),
+      completedAt: null,
+    };
+    setTodos(prev => [...prev, temp]);
+    setInput('');
+    inputRef.current?.focus();
+
+    try {
+      const res = await fetch(api(`/api/workspaces/${workspaceId}/todos`), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text }),
+      });
+      if (!res.ok) throw new Error(await res.text());
+      const real: WorkspaceTodo = await res.json();
+      setTodos(prev => prev.map(t => t.id === tempId ? real : t));
+    } catch (err) {
+      console.error('failed to add todo', err);
+      setTodos(prev => prev.filter(t => t.id !== tempId));
+    }
+  }, [input, workspaceId]);
+
+  const toggleTodo = useCallback(async (todo: WorkspaceTodo) => {
+    if (workspaceId == null) return;
+    const next = !todo.completed;
+    setTodos(prev => prev.map(t => t.id === todo.id
+      ? { ...t, completed: next, completedAt: next ? new Date().toISOString() : null }
+      : t
+    ));
+
+    try {
+      const res = await fetch(api(`/api/workspaces/${workspaceId}/todos/${todo.id}`), {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ completed: next }),
+      });
+      if (!res.ok) throw new Error();
+      const real: WorkspaceTodo = await res.json();
+      setTodos(prev => prev.map(t => t.id === todo.id ? real : t));
+    } catch {
+      setTodos(prev => prev.map(t => t.id === todo.id ? todo : t));
+    }
+  }, [workspaceId]);
+
+  const deleteTodo = useCallback(async (todo: WorkspaceTodo) => {
+    if (workspaceId == null) return;
+    const snapshot = todos;
+    setTodos(prev => prev.filter(t => t.id !== todo.id));
+    try {
+      const res = await fetch(api(`/api/workspaces/${workspaceId}/todos/${todo.id}`), {
+        method: 'DELETE',
+      });
+      if (!res.ok) throw new Error();
+    } catch {
+      setTodos(snapshot);
+    }
+  }, [workspaceId, todos]);
+
+  const saveEdit = useCallback(async (todo: WorkspaceTodo) => {
+    const text = editText.trim();
+    setEditingId(null);
+    if (!text || text === todo.text || workspaceId == null) return;
+
+    const snapshot = todos;
+    setTodos(cur => cur.map(t => t.id === todo.id ? { ...t, text } : t));
+    try {
+      const res = await fetch(api(`/api/workspaces/${workspaceId}/todos/${todo.id}`), {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text }),
+      });
+      if (!res.ok) throw new Error();
+    } catch {
+      setTodos(snapshot);
+    }
+  }, [editText, workspaceId, todos]);
+
+  // Client-side sort — matches server ordering and accommodates optimistic temp rows
+  const sorted = [...todos].sort((a, b) => {
+    if (a.completed !== b.completed) return a.completed ? 1 : -1;
+    if (!a.completed) return a.sortOrder - b.sortOrder;
+    const aT = a.completedAt ?? '';
+    const bT = b.completedAt ?? '';
+    return bT.localeCompare(aT);
+  });
+
+  const visible = showCompleted ? sorted : sorted.filter(t => !t.completed);
+  const completedCount = sorted.filter(t => t.completed).length;
+
+  return (
+    <div className="border-b border-zinc-800 bg-zinc-900/40 px-4 py-2 flex-shrink-0">
+      <div className="flex items-center gap-2 mb-1.5">
+        <ListTodo className="w-3.5 h-3.5 text-zinc-500" />
+        <span className="text-[11px] font-medium text-zinc-400 uppercase tracking-wider">Todos</span>
+        {completedCount > 0 && (
+          <button
+            onClick={() => setShowCompleted(s => !s)}
+            className="ml-auto flex items-center gap-1 text-[10px] text-zinc-500 hover:text-zinc-300 transition-colors"
+            title={showCompleted ? 'Hide completed' : 'Show completed'}
+          >
+            {showCompleted ? <Eye className="w-3 h-3" /> : <EyeOff className="w-3 h-3" />}
+            {completedCount} done
+          </button>
+        )}
+      </div>
+
+      <div className="flex items-center gap-1.5 mb-1">
+        <Plus className="w-3.5 h-3.5 text-zinc-600" />
+        <input
+          ref={inputRef}
+          value={input}
+          onChange={e => setInput(e.target.value)}
+          onKeyDown={e => { if (e.key === 'Enter') addTodo(); }}
+          placeholder={workspaceId == null ? 'Select a workspace to add todos…' : 'Add todo…'}
+          disabled={workspaceId == null}
+          className="flex-1 bg-transparent text-sm text-white placeholder:text-zinc-600 focus:outline-none disabled:opacity-50"
+        />
+      </div>
+
+      {loading && visible.length === 0 ? null : (
+        <ul className="space-y-0.5 max-h-[40vh] overflow-y-auto">
+          {visible.map(todo => (
+            <li
+              key={todo.id}
+              className="group flex items-center gap-2 px-1.5 py-1 rounded hover:bg-zinc-800/50 transition-colors"
+            >
+              <button
+                onClick={() => toggleTodo(todo)}
+                className={`w-3.5 h-3.5 rounded border flex items-center justify-center transition-colors flex-shrink-0 ${
+                  todo.completed
+                    ? 'bg-indigo-500 border-indigo-500'
+                    : 'border-zinc-600 hover:border-zinc-400'
+                }`}
+                aria-label={todo.completed ? 'Mark incomplete' : 'Mark complete'}
+              >
+                {todo.completed && <Check className="w-2.5 h-2.5 text-white" />}
+              </button>
+
+              {editingId === todo.id ? (
+                <input
+                  autoFocus
+                  value={editText}
+                  onChange={e => setEditText(e.target.value)}
+                  onBlur={() => saveEdit(todo)}
+                  onKeyDown={e => {
+                    if (e.key === 'Enter') saveEdit(todo);
+                    if (e.key === 'Escape') setEditingId(null);
+                  }}
+                  className="flex-1 bg-zinc-800 border border-zinc-700 rounded px-1.5 py-0.5 text-sm text-white focus:outline-none focus:border-indigo-500"
+                />
+              ) : (
+                <button
+                  onClick={() => { setEditingId(todo.id); setEditText(todo.text); }}
+                  className={`flex-1 text-left text-sm truncate ${
+                    todo.completed ? 'text-zinc-500 line-through' : 'text-zinc-200'
+                  }`}
+                >
+                  {todo.text}
+                </button>
+              )}
+
+              <button
+                onClick={() => deleteTodo(todo)}
+                className="p-0.5 text-zinc-600 hover:text-red-400 opacity-0 group-hover:opacity-100 transition-opacity"
+                aria-label="Delete todo"
+              >
+                <X className="w-3 h-3" />
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+Run:
+```bash
+npx tsc --noEmit
+```
+
+Expected: no new errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/components/workspace/workspace-todos.tsx
+git commit -m "feat(ui): add WorkspaceTodos component"
+```
+
+---
+
+## Task 7: Mount `<WorkspaceTodos>` on the terminal page
+
+**Files:**
+- Modify: `src/app/(desktop)/terminal/page.tsx`
+
+- [ ] **Step 1: Import and place the component**
+
+Open `src/app/(desktop)/terminal/page.tsx`. Near the other `import` statements at the top (around line 30, next to the `ProjectWizard` import), add:
+
+```tsx
+import { WorkspaceTodos } from '@/components/workspace/workspace-todos';
+```
+
+Then in the entered-workspace render path, mount it directly **below** the popped-out-panes indicator row and **above** the `{/* File Explorer + Terminal grid + Activity Panel */}` div. Look for this block around lines 1194-1221:
+
+```tsx
+      {/* Popped-out pane indicators */}
+      {poppedOut.size > 0 && (
+        <div className="flex items-center gap-2 px-4 py-1.5 border-b border-zinc-800 bg-zinc-900/50">
+          ...
+        </div>
+      )}
+
+      {/* File Explorer + Terminal grid + Activity Panel */}
+      <div className="flex-1 flex overflow-hidden min-h-0">
+```
+
+Insert between them:
+
+```tsx
+      {/* Workspace todos */}
+      <WorkspaceTodos workspaceId={activeWorkspace?.id ?? null} />
+```
+
+- [ ] **Step 2: Start the dev server for manual QA**
+
+Run:
+```bash
+npm run dev
+```
+
+Open `http://localhost:3457/terminal`, enter a workspace.
+
+- [ ] **Step 3: Walk through the QA checklist**
+
+1. Todos bar renders above the pane grid.
+2. Type "first todo" + Enter → appears in list. Input clears and stays focused.
+3. Add "second todo", "third todo". They stack top-to-bottom in creation order.
+4. Click the checkbox on "second todo" → strikes through, sinks below the uncompleted pair. A "1 done" counter + eye toggle appears in the header.
+5. Click the eye icon → "second todo" hides. Click again → reappears.
+6. Click the text of "first todo" → inline edit. Type "first todo (edited)", Enter → text updates. Reload the page → edit persisted.
+7. Hover any todo → `×` button appears; click → deletes.
+8. Open the workspace chooser, switch to another workspace → todo list swaps. Switch back → original list intact.
+9. Delete a workspace that has todos (ensure it's not the active one): its todos should be gone from the DB.
+```bash
+sqlite3 ~/.spaces/*.db "SELECT COUNT(*) FROM workspace_todos WHERE workspace_id = <deleted-id>;"
+```
+Expected: `0`.
+
+Stop the dev server after QA passes.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add "src/app/(desktop)/terminal/page.tsx"
+git commit -m "feat(terminal): mount WorkspaceTodos above pane grid"
+```
+
+---
+
+## Task 8: Feature doc
+
+**Files:**
+- Create: `docs/features/workspace-todos.md`
+
+- [ ] **Step 1: Write the feature doc**
+
+Create `docs/features/workspace-todos.md`:
+
+````markdown
+# Workspace Todos
+
+**Status:** stable
+**Owner:** jlongo
+**Last updated:** 2026-04-21
+
+## Overview
+
+A lightweight todo list attached to each workspace. Renders inline at the top of `/terminal` above the pane grid, always visible. Minimal model: text + checkbox + delete. Scoped per-workspace — switching workspaces swaps the list. Not in scope: agent read/write, drag-reorder, priorities/due dates, cross-workspace views.
+
+## User-facing behavior
+
+- Visit `/terminal`, enter any workspace.
+- A "Todos" bar renders above the pane grid with an "Add todo…" input.
+- Enter adds a todo at the bottom of the uncompleted list. Input stays focused.
+- Click the checkbox → strike-through + sink to the completed section.
+- Click text → inline edit. Enter saves, Esc cancels, blur saves.
+- Hover row → `×` delete button.
+- Eye icon in the header toggles visibility of completed todos (ephemeral, resets on reload).
+
+## Architecture
+
+UI (`src/components/workspace/workspace-todos.tsx`) → API routes (`src/app/api/workspaces/[id]/todos/*`) → DB helpers (`src/lib/db/queries.ts`) → SQLite (`workspace_todos` table in the per-user DB at `~/.spaces/<user>.db`).
+
+Mutations are optimistic client-side with rollback on failure. Workspace switch triggers a fresh refetch keyed on `workspaceId`.
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `src/components/workspace/workspace-todos.tsx` | Inline UI component — fetching, optimistic CRUD, rendering |
+| `src/app/api/workspaces/[id]/todos/route.ts` | `GET` list, `POST` create |
+| `src/app/api/workspaces/[id]/todos/[todoId]/route.ts` | `PATCH` update, `DELETE` remove |
+| `src/lib/db/schema.ts` | `workspace_todos` table declaration inside `initSchema()` |
+| `src/lib/db/queries.ts` | `getWorkspaceTodos`, `addWorkspaceTodo`, `updateWorkspaceTodo`, `deleteWorkspaceTodo` |
+| `src/types/claude.ts` (or wherever `Workspace` is defined) | `WorkspaceTodo` type |
+| `src/app/(desktop)/terminal/page.tsx` | Mounts `<WorkspaceTodos>` above the pane grid |
+| `tests/db/workspace-todos.test.ts` | Query-layer tests — ordering, cascade, scoping |
+
+## Data model
+
+### `workspace_todos`
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | INTEGER PK | autoincrement |
+| `workspace_id` | INTEGER NOT NULL | FK → `workspaces(id)` ON DELETE CASCADE |
+| `text` | TEXT NOT NULL | trimmed on insert/update; empty rejected |
+| `completed` | INTEGER NOT NULL DEFAULT 0 | 0 or 1 |
+| `sort_order` | INTEGER NOT NULL DEFAULT 0 | meaningful only among uncompleted rows |
+| `created` | TEXT NOT NULL DEFAULT datetime('now') | |
+| `completed_at` | TEXT | set when completed flips 0→1, cleared on 1→0 |
+
+Index: `idx_workspace_todos_workspace` on `workspace_id`.
+
+### TypeScript
+
+```ts
+interface WorkspaceTodo {
+  id: number;
+  workspaceId: number;
+  text: string;
+  completed: boolean;
+  sortOrder: number;
+  created: string;
+  completedAt: string | null;
+}
+```
+
+### Invariants
+
+- Listing order: uncompleted first by `sort_order` ASC, then completed by `completed_at` DESC.
+- New todos get `sort_order = MAX(sort_order WHERE completed=0) + 1`.
+- `completed_at` is `NULL` iff `completed = 0`.
+- Deleting a workspace deletes its todos via FK cascade.
+
+## APIs / contracts
+
+### Internal endpoints
+
+| Method | Path | Request | Response |
+|---|---|---|---|
+| `GET` | `/api/workspaces/:id/todos` | — | `WorkspaceTodo[]` |
+| `POST` | `/api/workspaces/:id/todos` | `{ text: string }` | `201 WorkspaceTodo` or `400 { error }` |
+| `PATCH` | `/api/workspaces/:id/todos/:todoId` | `{ text?, completed? }` | `WorkspaceTodo` or `400`/`404` |
+| `DELETE` | `/api/workspaces/:id/todos/:todoId` | — | `{ ok: true }` |
+
+Auth via `getAuthUser` + `withUser`, same pattern as sibling workspace routes.
+
+### External calls
+N/A.
+
+## Configuration & environment
+None. Always-on Community-tier feature. No env vars, flags, or tier gates.
+
+## How to run / test locally
+
+```bash
+npm install
+npm run build
+npm start
+# visit http://localhost:3457/terminal, enter any workspace
+```
+
+Automated:
+```bash
+npx vitest run tests/db/workspace-todos.test.ts
+```
+
+## Known quirks & decisions
+
+- **Schema lives in `initSchema()`, no migration file.** Matches the pattern in `src/lib/db/schema.ts`; the repo has no separate migration system.
+- **No agent write path in v1.** The coworker's "pi /todos" plugin that inspired this lets agents add todos from inside the session — deferred because it requires an MCP tool or CLI surface.
+- **Optimistic updates without toasts.** Failures `console.error` and revert local state; this is a local-only app, so silent revert is acceptable for v1.
+- **`sort_order = Number.MAX_SAFE_INTEGER` for optimistic inserts.** The temp row sorts to the bottom of uncompleted; the server returns the real `sort_order` on response and replaces the temp.
+- **No confirm on delete.** Minimal ethos. Add undo toast in a follow-up if this proves painful.
+- **Direct-to-main workflow.** Per repo convention for this codebase; no PR flow.
+
+## Open questions / TODOs
+
+- [ ] Agent write access via MCP tool once UI v1 proves out.
+- [ ] Optional: persist the "show completed" toggle in localStorage.
+- [ ] Optional: keyboard shortcut to focus the add-input from anywhere on `/terminal`.
+
+## Changelog
+
+- 2026-04-21 — Initial implementation. v1 ships direct to `main`.
+````
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/features/workspace-todos.md
+git commit -m "docs(features): add workspace-todos feature doc"
+```
+
+---
+
+## Self-Review Notes (filled in after writing)
+
+**Spec coverage:** every section in `docs/superpowers/specs/2026-04-21-workspace-todos-design.md` has a task:
+- Data model → Task 1
+- Type + query helpers → Task 2
+- Query tests → Task 3
+- `GET`/`POST` routes → Task 4
+- `PATCH`/`DELETE` routes → Task 5
+- UI component → Task 6
+- Terminal page integration → Task 7
+- Feature doc → Task 8
+
+**Placeholder scan:** no TBD/TODO outside the explicit "Open questions / TODOs" section of the feature doc, which is itself a required section per `FEATURE_DOC_GUIDE.md`.
+
+**Type consistency:** `WorkspaceTodo` shape is identical across Task 2 (declaration), Task 3 (test assertions), Task 4/5 (route returns), Task 6 (UI import), Task 8 (doc). Function names `getWorkspaceTodos` / `addWorkspaceTodo` / `updateWorkspaceTodo` / `deleteWorkspaceTodo` used consistently.
+
+**Manual QA gate:** Task 7 Step 3 is the final smoke test — requires a running server and a browser session.