flowcollab 0.1.0

package/bin/decisions.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/* flow:decisions — list pending decisions.
+   Usage: flow-decisions
+*/
+
+import { flowFetch, die } from './_client.mjs';
+
+async function main() {
+  const [decRes, tasksRes] = await Promise.all([
+    flowFetch('/api/flow/decisions'),
+    flowFetch('/api/flow/tasks?limit=500'),
+  ]);
+  const decisions = decRes.decisions || [];
+  const taskById = new Map((tasksRes.tasks || []).map(t => [t.id, t]));
+  if (!decisions.length) {
+    process.stdout.write('No pending decisions.\n');
+    return;
+  }
+  process.stdout.write(`${decisions.length} pending decision${decisions.length === 1 ? '' : 's'}:\n\n`);
+  for (const d of decisions) {
+    process.stdout.write(`#${d.id.slice(0, 6)}  ${d.proposal_title}\n`);
+    if (d.parent_task_id) {
+      const p = taskById.get(d.parent_task_id);
+      const ref = p ? `#${p.id.slice(0, 6)} — "${p.title}"` : `#${d.parent_task_id.slice(0, 6)}`;
+      process.stdout.write(`  Parent: ${ref}\n`);
+    }
+    process.stdout.write(`  Confidence: ${d.confidence}  |  Suggest: ${d.suggested_assignee_id || '-'} / ${d.suggested_priority || '-'} / ${d.suggested_type || '-'}\n`);
+    if (d.source_refs?.length) process.stdout.write(`  Refs: ${d.source_refs.join(', ')}\n`);
+    process.stdout.write(`  Expires: ${d.expires_at}\n\n`);
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/edit.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/* flow:edit — update task fields from the CLI.
+   Usage:
+     flow-edit <id> --title="new title"
+     flow-edit <id> --priority=p1 --area=backend
+     flow-edit <id> --due=2026-07-01
+     flow-edit <id> --milestone="v1.0"
+     flow-edit <id> --blocked-by=<uuid>
+*/
+
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+const FIELD_MAP = {
+  title:      v => ({ title: v }),
+  priority:   v => ({ priority: v }),
+  area:       v => ({ area: v }),
+  due:        v => ({ due_at: /^\d{4}-\d{2}-\d{2}$/.test(v) ? v + 'T00:00:00Z' : v }),
+  milestone:  v => ({ milestone: v }),
+  'blocked-by': v => ({ blocked_by: v === 'null' ? [] : [v] }),
+};
+
+async function main() {
+  const raw = positional(0);
+  if (!raw) die('Usage: flow-edit <task_id> [--title=...] [--priority=...] [--area=...] [--due=YYYY-MM-DD] [--milestone=...] [--blocked-by=<uuid>|null]');
+
+  const changes = {};
+  for (const [flag, toField] of Object.entries(FIELD_MAP)) {
+    const val = arg(flag);
+    if (val !== undefined) Object.assign(changes, toField(val));
+  }
+
+  if (Object.keys(changes).length === 0) die('No fields to update. Pass at least one flag like --title="..." or --priority=p1');
+
+  const id = await resolveTaskId(raw);
+  const res = await flowFetch(`/api/flow/tasks/${id}`, { method: 'PATCH', body: changes });
+
+  const updated = res.task || res;
+  const label = updated.title || id.slice(0, 8);
+  process.stdout.write(`Updated: ${label}\n`);
+  for (const [k, v] of Object.entries(changes)) {
+    process.stdout.write(`  ${k}: ${v === null ? '(cleared)' : v}\n`);
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/handoff.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/* flow:handoff — hand a task off to another agent with structured context.
+   Usage:
+     flow-handoff --task=<id> --to=<actor> --context="..." \
+       [--branch=<name>] [--questions="q1|q2|q3"] [--next-step="..."]
+
+   --questions accepts pipe-delimited questions for the recipient to answer.
+   --next-step describes the concrete first action the recipient should take.
+   flow_files are auto-read from the task and included in handoff_data.
+*/
+
+import { flowFetch, arg } from './_client.mjs';
+
+async function main() {
+  const task_id = arg('task');
+  const to = arg('to');
+  const context = arg('context');
+  const branch = arg('branch') || null;
+  const questionsArg = arg('questions');
+  const next_step = arg('next-step') || undefined;
+
+  if (!task_id) { process.stderr.write('--task=<id> is required\n'); process.exit(1); }
+  if (!to) { process.stderr.write('--to=<actor> is required\n'); process.exit(1); }
+  if (!context) { process.stderr.write('--context="..." is required\n'); process.exit(1); }
+
+  const questions = questionsArg
+    ? questionsArg.split('|').map(q => q.trim()).filter(Boolean)
+    : undefined;
+
+  const r = await flowFetch('/api/flow/handoff', {
+    method: 'POST',
+    body: {
+      task_id,
+      to,
+      context,
+      ...(branch ? { branch } : {}),
+      ...(questions ? { questions } : {}),
+      ...(next_step ? { next_step } : {}),
+    },
+  });
+
+  const hd = r.task?.handoff_data;
+  process.stdout.write(`Handed off ${task_id.slice(0, 8)} → ${to}${branch ? ' (branch: ' + branch + ')' : ''}\n`);
+  if (hd?.files?.length) {
+    process.stdout.write(`  files:     ${hd.files.join(', ')}\n`);
+  }
+  if (hd?.next_step) {
+    process.stdout.write(`  next step: ${hd.next_step}\n`);
+  }
+  if (hd?.questions?.length) {
+    process.stdout.write(`  open questions:\n`);
+    for (const q of hd.questions) process.stdout.write(`    - ${q}\n`);
+  }
+  process.stdout.write(`They will see it in their next flow-pull.\n`);
+}
+
+main().catch(e => { process.stderr.write('handoff failed: ' + (e.message || e) + '\n'); process.exit(1); });

package/bin/heartbeat.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/* flow:heartbeat — announce presence to the board.
+   Call after claiming a task, and every ~60s while actively working.
+
+   Usage:
+     flow-heartbeat                     # idle ping (no task)
+     flow-heartbeat --task=<task_id> # ping with current task
+*/
+
+import { flowFetch, arg } from './_client.mjs';
+
+async function main() {
+  const task = arg('task') || null;
+  await flowFetch('/api/flow/heartbeat', {
+    method: 'POST',
+    body: task ? { task_id: task } : {},
+  });
+  const label = task ? ` (task ${task.slice(0, 6)})` : '';
+  process.stdout.write(`Heartbeat sent${label}\n`);
+}
+
+main().catch(e => { process.stderr.write('heartbeat failed: ' + (e.message || e) + '\n'); process.exit(1); });

package/bin/init.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/* flow:init — set up CLI access for a web-provisioned Flow account.
+
+   You signed up at https://flow-production-84b7.up.railway.app and have a
+   token from the Flow setup page. This writes your .env and CLAUDE.md.
+
+   Usage: flow-init --web
+          flow-init --web
+*/
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise(r => rl.question(q, r));
+
+function buildWebClaudeMd({ actorId, ownerActorId, boardUrl, scope, areas = [] }) {
+  const ownerRef = scope === 'owner' ? actorId : (ownerActorId || 'owner');
+  const areaLine = areas.length ? areas.join(', ') : 'backend, frontend, infra, docs';
+  return `# Flow — Claude Code workflow
+
+This project uses Flow for multi-agent coordination.
+Follow this workflow every session without exception.
+
+## Your identity
+- **Your actor ID:** \`${actorId}\`
+- **Your scope:** ${scope}
+- **Board:** ${boardUrl}
+
+## Required session workflow
+
+\`\`\`bash
+flow-pull                                    # ALWAYS start here — board snapshot + your mentions
+flow-claim <task_id>                         # claim before writing any code
+flow-comment <task_id> "..."                 # update at milestones, use @to:${ownerRef} to ping
+flow-close <task_id> "summary"               # close with a meaningful summary when done
+flow-propose --parent=<id> --title="..." --md="..."  # propose new work; never start without approval
+\`\`\`
+
+## Rules — never violate
+- \`flow-pull\` at session start — no exceptions
+- Claim a task before touching related code
+- Comment at major milestones, not every commit
+- Close with a summary the next agent can act on
+- Never approve your own proposals — only **owners** can approve (in the browser at ${boardUrl})
+- Use \`@to:${ownerRef}\` in comments to request human action or review
+
+## All CLI commands
+\`\`\`
+flow-pull                                — board snapshot + mentions + handoffs
+flow-pull --focus                        — top-3 open tasks sorted by priority
+flow-pull --milestone=<name>             — filter snapshot to a sprint
+flow-claim <id>                          — self-assign a task
+flow-comment <id> "..."                  — add a comment or milestone update
+flow-close <id> "summary"               — mark task done with summary
+flow-create --title="..."               — create a task directly (no approval gate)
+flow-create --from-issue=<num>          — import a GitHub Issue as a task
+flow-create --from-project-item=<id>    — import a GitHub Projects item
+flow-create --template=<id>             — create from template (standup, pr-review, retro, ...)
+flow-propose --parent=<id> --title="..." --md="..."  — propose work for human approval
+flow-approve/reject <id>                — resolve a proposal (owner only)
+flow-assign <id> <actor>               — reassign a task (owner only)
+flow-decisions                          — list pending proposals
+flow-search "query"                     — search tasks by title
+flow-status                             — board summary (counts, active agents)
+flow-standup                            — recent activity digest
+flow-standup --velocity                 — recent activity + week-over-week velocity chart
+flow-handoff --task=<id> --to=<actor>  — hand off a task with context
+flow-heartbeat                          — send presence ping (run in background)
+flow-sync                               — delta sync since N minutes ago
+flow-ping                               — health check
+flow-whoami                             — verify token and actor identity
+flow-project                            — list GitHub Projects v2 items
+flow-close-sprint --milestone=<name>    — close sprint (owner only)
+flow-review <id> [--pr=<num>] [--reviewer=<actor>]  — request code review; moves → in_review, pings reviewer
+flow-edit <id> [--title=] [--priority=] [--area=] [--due=] [--milestone=] [--blocked-by=]
+flow-unblock <id>                       — clear blocked_by
+flow-log [--task=<id>] [--limit=20]    — tail recent timeline events
+\`\`\`
+
+## Area labels
+${areaLine}
+`;
+}
+
+async function main() {
+  if (!process.argv.includes('--web')) {
+    console.error(
+      'Usage: flow-init --web\n\n' +
+      'Flow is a hosted SaaS. Sign up at:\n' +
+      '  https://flow-production-84b7.up.railway.app\n\n' +
+      'Once you have a token from the setup page, run:\n' +
+      '  flow-init --web\n'
+    );
+    process.exit(1);
+  }
+
+  console.log('\nFlow Board — web setup\n');
+  console.log('You signed up via the web and already have a token from the Flow setup page.');
+  console.log('This writes your .env and CLAUDE.md — no Supabase config needed.\n');
+
+  const apiBase = (await ask('Flow server URL (e.g. https://flow-production-84b7.up.railway.app): '))
+    .trim().replace(/\/+$/, '');
+  const token   = (await ask('Your API token (from setup page): ')).trim();
+  const actorId = (await ask('Your actor ID (from setup page, e.g. "alice"): ')).trim() || 'owner';
+  const scopeRaw = (await ask('Your scope [owner/contributor, default: owner]: ')).trim().toLowerCase();
+  const scope = scopeRaw === 'contributor' ? 'contributor' : 'owner';
+
+  let ownerActorId = actorId;
+  if (scope === 'contributor') {
+    ownerActorId = (await ask("Owner's actor ID (for CLAUDE.md @mentions, e.g. \"alice\"): ")).trim() || 'owner';
+  }
+
+  const cwd = process.cwd();
+  const localAreas = (() => {
+    try {
+      const raw = readFileSync(path.join(cwd, 'flow.config.json'), 'utf8');
+      return Object.keys(JSON.parse(raw).labels?.area || {});
+    } catch { return []; }
+  })();
+
+  const envTarget      = path.join(cwd, '.env');
+  const claudeMdTarget = path.join(cwd, 'CLAUDE.md');
+  const envExists      = existsSync(envTarget);
+  const claudeExists   = existsSync(claudeMdTarget);
+
+  const writeEnvAns = (await ask(
+    `\nWrite .env to ${cwd}? ${envExists ? '[y/N]' : '[Y/n]'}: `
+  )).trim().toLowerCase();
+  const writeEnv = envExists
+    ? (writeEnvAns === 'y' || writeEnvAns === 'yes')
+    : (writeEnvAns !== 'n' && writeEnvAns !== 'no');
+
+  const writeClaudeAns = (await ask(
+    `Write CLAUDE.md to ${cwd}? ${claudeExists ? '[y/N]' : '[Y/n]'}: `
+  )).trim().toLowerCase();
+  const writeClaude = claudeExists
+    ? (writeClaudeAns === 'y' || writeClaudeAns === 'yes')
+    : (writeClaudeAns !== 'n' && writeClaudeAns !== 'no');
+
+  rl.close();
+
+  const tokenVar = scope === 'owner' ? 'FLOW_API_TOKEN_OWNER' : 'FLOW_API_TOKEN_CONTRIBUTOR';
+  const actorVar = scope === 'owner' ? 'FLOW_TOKEN_OWNER_ACTOR' : 'FLOW_TOKEN_CONTRIBUTOR_ACTOR';
+  const envLines = [
+    `${tokenVar}=${token}`,
+    `${actorVar}=${actorId}`,
+    `FLOW_API_BASE=${apiBase}`,
+    `FLOW_ACTING_VIA=claude`,
+    `FLOW_DEFAULT_ASSIGNEE=${actorId}`,
+  ];
+
+  console.log('\n========== .env ==========\n');
+  envLines.forEach(l => console.log(l));
+
+  if (writeEnv) {
+    if (envExists) {
+      const existing = readFileSync(envTarget, 'utf8');
+      const conflicts = envLines.map(l => l.split('=')[0]).filter(k => new RegExp(`^${k}=`, 'm').test(existing));
+      if (conflicts.length) {
+        console.log(`\n⚠  These keys already exist in .env — not overwriting: ${conflicts.join(', ')}`);
+        console.log('   Paste the block above into .env manually.');
+      } else {
+        writeFileSync(envTarget, existing.trimEnd() + '\n\n' + envLines.join('\n') + '\n', 'utf8');
+        console.log(`\n✓ .env updated. Add .env to .gitignore — it contains your API token.`);
+      }
+    } else {
+      writeFileSync(envTarget, envLines.join('\n') + '\n', 'utf8');
+      console.log(`\n✓ .env written. Add .env to .gitignore — it contains your API token.`);
+    }
+  }
+
+  if (writeClaude) {
+    const content = buildWebClaudeMd({ actorId, ownerActorId, boardUrl: `${apiBase}/flow/`, scope, areas: localAreas });
+    writeFileSync(claudeMdTarget, content, 'utf8');
+    console.log(`✓ CLAUDE.md written. Commit this so every agent on the team gets the workflow.`);
+  }
+
+  console.log('\n========== Next steps ==========\n');
+  console.log(`1. Verify your connection:    flow-whoami`);
+  console.log(`2. See your board:            flow-pull`);
+  console.log(`3. Open the board:            ${apiBase}/flow/`);
+  console.log('');
+}
+
+main().catch(e => { console.error('init failed:', e.message || e); process.exit(1); });

package/bin/log.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/* flow:log — tail recent timeline events, newest first.
+   Usage:
+     flow-log                        # board-wide, last 20 events
+     flow-log --task=<id>            # single task timeline
+     flow-log --limit=50             # more events
+*/
+
+import { flowFetch, resolveTaskId, arg, die } from './_client.mjs';
+
+function sanitize(s) {
+  if (!s || typeof s !== 'string') return '';
+  return s
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
+    .replace(/@to:\S+/g, '[mention]')
+    .replace(/\r?\n|\r/g, ' ')
+    .trim()
+    .slice(0, 120);
+}
+
+function fmt(ts) {
+  if (!ts) return '         ';
+  const d = new Date(ts);
+  if (isNaN(d)) return String(ts).slice(0, 10);
+  return d.toISOString().replace('T', ' ').slice(0, 16);
+}
+
+function pad(s, n) { return String(s ?? '').padEnd(n).slice(0, n); }
+
+function fmtEvent(e) {
+  const p = e.payload || {};
+  if (p.comment) return sanitize(p.comment);
+  if (p.act) return `[${p.act}${p.summary ? ': ' + sanitize(p.summary, 80) : ''}]`;
+  return `[${e.kind || 'event'}]`;
+}
+
+async function main() {
+  const taskRaw = arg('task');
+  const limit = Math.min(200, Math.max(1, parseInt(arg('limit') || '20')));
+
+  const res = await flowFetch('/api/flow/tasks?limit=500');
+  const tasks = res.tasks ?? [];
+  const timeline = res.timeline ?? [];
+
+  if (taskRaw) {
+    const id = await resolveTaskId(taskRaw);
+    const task = tasks.find(t => t.id === id);
+    if (!task) die(`Task ${id} not found`);
+
+    const events = timeline
+      .filter(e => e.task_id === id)
+      .slice(0, limit);
+
+    if (events.length === 0) { process.stdout.write('No timeline events.\n'); return; }
+
+    process.stdout.write(`Timeline for #${task.issue_num ?? id.slice(0, 6)}: ${task.title}\n\n`);
+    for (const e of events) {
+      const who = e.acting_as_id ? `${e.acting_as_id}(${e.actor_id})` : (e.actor_id || '?');
+      process.stdout.write(`  ${fmt(e.ts)}  ${pad(who, 18)}  ${fmtEvent(e)}\n`);
+    }
+  } else {
+    const taskById = new Map(tasks.map(t => [t.id, t]));
+    const events = timeline
+      .filter(e => e.ts)
+      .slice(0, limit);
+
+    if (events.length === 0) { process.stdout.write('No timeline events.\n'); return; }
+
+    process.stdout.write(`Last ${events.length} board events:\n\n`);
+    for (const e of events) {
+      const t = taskById.get(e.task_id);
+      const ref = t ? `#${t.issue_num ?? e.task_id.slice(0, 6)}` : `#${e.task_id.slice(0, 6)}`;
+      const who = e.acting_as_id ? `${e.acting_as_id}(${e.actor_id})` : (e.actor_id || '?');
+      process.stdout.write(`  ${fmt(e.ts)}  ${pad(who, 18)}  ${pad(ref, 8)}  ${fmtEvent(e)}\n`);
+    }
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/login.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/* flow-login — authorize the CLI via browser OAuth (device flow).
+   Usage:
+     flow-login [--server=https://flow-production-84b7.up.railway.app]
+*/
+import { homedir } from 'os';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { exec } from 'child_process';
+
+const serverArg = process.argv.find(a => a.startsWith('--server='))?.slice(9);
+const base = (serverArg || process.env.FLOW_API_BASE || 'https://flow-production-84b7.up.railway.app').replace(/\/+$/, '');
+
+function openBrowser(url) {
+  try {
+    const cmd = process.platform === 'darwin' ? `open "${url}"`
+      : process.platform === 'win32' ? `start "" "${url}"`
+      : `xdg-open "${url}"`;
+    exec(cmd);
+  } catch { /* best-effort */ }
+}
+
+async function main() {
+  // 1. Request device code from server
+  const r = await fetch(`${base}/api/flow/auth/device`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+  }).catch(e => { throw new Error(`Cannot reach ${base}: ${e.message}`); });
+
+  if (!r.ok) throw new Error(`Server error: ${r.status}`);
+  const { code, device_token, url, expires_in } = await r.json();
+
+  // 2. Show instructions and open browser
+  process.stdout.write('\nAuthorize Flow CLI\n\n');
+  process.stdout.write(`  Visit: ${url}\n`);
+  process.stdout.write(`  Code:  ${code}\n\n`);
+  process.stdout.write('Opening browser… (or visit the URL above manually)\n\n');
+  openBrowser(url);
+
+  // 3. Poll every 2s until authorized or expired
+  const deadline = Date.now() + expires_in * 1000;
+  process.stdout.write('Waiting for authorization');
+  while (Date.now() < deadline) {
+    await new Promise(ok => setTimeout(ok, 2000));
+    process.stdout.write('.');
+    const poll = await fetch(
+      `${base}/api/flow/auth/poll?device_token=${encodeURIComponent(device_token)}`,
+    ).catch(() => null);
+    if (!poll) continue;
+    if (poll.status === 410) {
+      process.stdout.write('\n');
+      const body = await poll.json().catch(() => ({}));
+      throw new Error(
+        body.error === 'already_used'
+          ? 'This device code was already claimed.'
+          : 'Code expired. Run flow-login again.',
+      );
+    }
+    if (poll.status === 202) continue;
+    if (poll.ok) {
+      const { token, actor_id, org_id, api_base } = await poll.json();
+      const dir = join(homedir(), '.flow');
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(
+        join(dir, 'config.json'),
+        JSON.stringify({ apiBase: api_base || base, token, actorId: actor_id, orgId: org_id }, null, 2) + '\n',
+        { encoding: 'utf8', mode: 0o600 },
+      );
+      process.stdout.write('\n\n');
+      process.stdout.write(`✓ Logged in as ${actor_id}\n`);
+      process.stdout.write(`  Config saved to ~/.flow/config.json\n`);
+      process.stdout.write(`  Run: flow-pull\n\n`);
+      return;
+    }
+  }
+  process.stdout.write('\n');
+  throw new Error('Timed out. Run flow-login again.');
+}
+
+main().catch(e => { process.stderr.write(`flow-login: ${e.message}\n`); process.exit(1); });

package/bin/ping.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/* flow:ping — dual mode:
+     0 args              → healthz check (circuit breaker status)
+     flow-ping <actor> "message" → post @to:<actor>-claude on shared agent-comms task
+                                    (server fireNotifications routes to actor's notify_webhook)
+*/
+
+import { flowFetch, positional, die } from './_client.mjs';
+
+async function main() {
+  const actor = positional(0);
+  const message = positional(1);
+
+  if (!actor) {
+    const r = await flowFetch('/api/flow/healthz');
+    const breaker = r.breaker;
+    const status = r.ok ? 'ok' : 'tripped';
+    const trips = breaker?.trips != null ? `  trips=${breaker.trips}` : '';
+    process.stdout.write(`Flow ${status}.${trips}\n`);
+    return;
+  }
+
+  if (!message) die('Usage: flow-ping <actor> "message"');
+
+  // Find or create the shared agent-comms task
+  const tasksRes = await flowFetch('/api/flow/tasks?limit=500');
+  const all = tasksRes.tasks || [];
+  let commsTask = all.find(t => t.type === 'chore' && t.title === 'agent-comms' && t.status !== 'done');
+
+  if (!commsTask) {
+    const created = await flowFetch('/api/flow/tasks', {
+      method: 'POST',
+      body: {
+        title: 'agent-comms',
+        type: 'chore',
+        status: 'in_progress',
+        body_md: 'Shared channel for inter-agent messages. Do not close.',
+      },
+    });
+    commsTask = created.task;
+  }
+
+  const body = `@to:${actor}-claude — ${message}`;
+  await flowFetch('/api/flow/comment', { method: 'POST', body: { task_id: commsTask.id, body } });
+  process.stdout.write(`Pinged @to:${actor}-claude on #${commsTask.issue_num ?? commsTask.id.slice(0, 6)} (agent-comms).\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/pr.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/* flow:pr — record a PR link on a task's timeline.
+   Usage: flow-pr <task_id> <pr_url>
+   Posts a standardized "PR open: <url>" comment so pull.mjs is uniform.
+*/
+
+import { flowFetch, resolveTaskId, positional, die } from './_client.mjs';
+
+async function main() {
+  const rawId = positional(0);
+  const url = positional(1);
+  if (!rawId || !url) {
+    die('Usage: flow-pr <task_id> <pr_url>');
+  }
+  if (!url.startsWith('http')) {
+    die(`pr_url must be a full URL, got: ${url}`);
+  }
+  const id = await resolveTaskId(rawId);
+  const body = `PR open: ${url}`;
+  await flowFetch('/api/flow/comment', { method: 'POST', body: { task_id: id, body } });
+  process.stdout.write(`Recorded PR link on task #${rawId.replace(/^#/, '').slice(0, 6)}.\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/project.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/* flow-project — list items in a GitHub Projects (v2) board.
+
+   Lists all items in the project configured via FLOW_GITHUB_PROJECT_ID.
+   Use the printed node IDs with flow-create --from-project-item=<id>.
+
+   Usage:
+     flow-project                          # list items from FLOW_GITHUB_PROJECT_ID
+     flow-project --project=<node_id>      # override project node ID
+*/
+
+import 'dotenv/config';
+import { die } from './_client.mjs';
+import { fetchProjectItems, contentKind } from './_github.mjs';
+
+async function main() {
+  const projectId = process.argv.find(a => a.startsWith('--project='))?.split('=')[1]
+    || process.env.FLOW_GITHUB_PROJECT_ID;
+
+  if (!projectId) {
+    die('No project specified. Set FLOW_GITHUB_PROJECT_ID in .env or pass --project=<node_id>.\n\n' +
+      'Find your project node ID at: github.com/orgs/<org>/projects or github.com/users/<user>/projects\n' +
+      '  → Settings → in the URL: /projects/<number> → run `gh project list` for the node ID.');
+  }
+  if (!process.env.FLOW_GITHUB_TOKEN) {
+    die('FLOW_GITHUB_TOKEN is not set. Set it in .env (needs "read:project" scope).');
+  }
+
+  process.stdout.write(`Fetching project items from ${projectId}...\n\n`);
+
+  const { title, items } = await fetchProjectItems(projectId);
+
+  process.stdout.write(`Project: ${title}\n`);
+  process.stdout.write(`  ${items.length} item${items.length !== 1 ? 's' : ''}\n\n`);
+
+  if (!items.length) {
+    process.stdout.write('No items found.\n');
+    return;
+  }
+
+  for (const { id, content } of items) {
+    const kind = contentKind(content);
+    const num = content.number ? ` #${content.number}` : '';
+    process.stdout.write(`  [${id}]  ${content.title}${num ? ` (${kind}${num})` : ` (${kind})`}\n`);
+  }
+
+  process.stdout.write(`\nTo import an item:\n  flow-create --from-project-item=<id above>\n`);
+}
+
+main().catch(e => die(e.message || e));