flowcollab 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Prefabs AI. All rights reserved.
+
+Permission is granted to download and use this CLI software solely for the
+purpose of accessing the Flow hosted service. No part of this software may be
+reproduced, distributed, modified, or transmitted in any form or by any means
+without the prior written permission of the copyright holder.

package/bin/_client.mjs

@@ -0,0 +1,97 @@
+/* Flow CLI — shared client.
+   - Resolves API base + token from env vars → ~/.flow/config.json → defaults
+   - Exposes one fetch helper with sensible error reporting
+   - All CLI scripts import from here
+*/
+
+import 'dotenv/config';
+import { homedir } from 'os';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+function loadGlobalConfig() {
+  try { return JSON.parse(readFileSync(join(homedir(), '.flow', 'config.json'), 'utf8')); }
+  catch { return {}; }
+}
+const _gc = loadGlobalConfig();
+
+const DEFAULT_BASE = process.env.FLOW_API_BASE || _gc.apiBase || 'http://localhost:3000';
+
+function envToken() {
+  return process.env.FLOW_API_TOKEN_OWNER || process.env.FLOW_API_TOKEN_CONTRIBUTOR || _gc.token || '';
+}
+
+function actingViaClaude() {
+  const v = (process.env.FLOW_ACTING_VIA || 'claude').toLowerCase();
+  return v === 'claude';
+}
+
+export async function flowFetch(path, { method = 'GET', body } = {}) {
+  const token = envToken();
+  if (!token) {
+    throw new Error('No FLOW_API_TOKEN_OWNER or FLOW_API_TOKEN_CONTRIBUTOR in env. Aborting.');
+  }
+  const url = DEFAULT_BASE.replace(/\/+$/, '') + path;
+  const headers = {
+    'x-flow-token': token,
+    'content-type': 'application/json',
+  };
+  if (actingViaClaude()) headers['x-flow-acting-via'] = 'claude';
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let parsed = null;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { raw: text }; }
+  if (!res.ok) {
+    const err = new Error(`Flow API ${method} ${path} -> ${res.status}: ${parsed?.error || text}`);
+    err.status = res.status;
+    err.body = parsed;
+    throw err;
+  }
+  return parsed;
+}
+
+export function die(msg, code = 1) {
+  process.stderr.write(`flow-cli: ${msg}\n`);
+  process.exit(code);
+}
+
+export function arg(name, fallback) {
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === `--${name}`) return argv[i + 1] ?? '';
+    if (a.startsWith(`--${name}=`)) return a.slice(name.length + 3);
+  }
+  return fallback;
+}
+
+export function positional(idx) {
+  const pos = process.argv.slice(2).filter(a => !a.startsWith('--'));
+  return pos[idx];
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function resolveTaskId(input) {
+  if (!input) return input;
+  const stripped = input.replace(/^#/, '');
+  if (UUID_RE.test(stripped)) return stripped;
+  const [tasksRes, decRes] = await Promise.all([
+    flowFetch('/api/flow/tasks?limit=500'),
+    flowFetch('/api/flow/decisions'),
+  ]);
+  const list = Array.isArray(tasksRes) ? tasksRes : (tasksRes.tasks ?? []);
+  const taskMatches = list.filter(t => t.id.startsWith(stripped));
+  if (taskMatches.length === 1) return taskMatches[0].id;
+  if (taskMatches.length > 1) throw new Error(`Ambiguous prefix "${stripped}" matches ${taskMatches.length} tasks:\n${taskMatches.map(t => `  #${t.id.slice(0, 6)}  ${t.title}`).join('\n')}`);
+  const decisions = decRes.decisions || [];
+  const decMatches = decisions.filter(d => d.id.startsWith(stripped));
+  if (decMatches.length === 0) throw new Error(`No task or decision found with ID prefix "${stripped}". Run \`flow-pull\` to see your current tasks.`);
+  if (decMatches.length > 1) throw new Error(`Ambiguous prefix "${stripped}" matches ${decMatches.length} decisions:\n${decMatches.map(d => `  #${d.id.slice(0, 6)}  ${d.proposal_title || ''}`).join('\n')}`);
+  return decMatches[0].id;
+}

package/bin/_github.mjs

@@ -0,0 +1,98 @@
+/* Shared GitHub API helpers for Flow CLI commands. */
+
+import 'dotenv/config';
+
+export function githubHeaders() {
+  const token = process.env.FLOW_GITHUB_TOKEN;
+  const headers = { 'User-Agent': 'flowcollab/1', 'Accept': 'application/vnd.github+json' };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+  return headers;
+}
+
+export async function githubGraphQL(query, variables = {}) {
+  const res = await fetch('https://api.github.com/graphql', {
+    method: 'POST',
+    headers: { ...githubHeaders(), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+  });
+  if (!res.ok) throw new Error(`GitHub GraphQL HTTP ${res.status}`);
+  const json = await res.json();
+  if (json.errors?.length) throw new Error(json.errors.map(e => e.message).join('; '));
+  return json.data;
+}
+
+export async function fetchProjectItem(nodeId) {
+  const data = await githubGraphQL(`
+    query($id: ID!) {
+      node(id: $id) {
+        ... on ProjectV2Item {
+          id
+          content {
+            ... on Issue {
+              title body number url
+              labels(first: 10) { nodes { name } }
+            }
+            ... on DraftIssue { title body }
+            ... on PullRequest { title body number url }
+          }
+        }
+      }
+    }
+  `, { id: nodeId });
+  const item = data?.node;
+  if (!item?.content) throw new Error(`Node "${nodeId}" is not a ProjectV2Item or has no content.`);
+  return item;
+}
+
+export async function fetchProjectItems(projectNodeId) {
+  const items = [];
+  let cursor = null;
+
+  while (true) {
+    const data = await githubGraphQL(`
+      query($projectId: ID!, $cursor: String) {
+        node(id: $projectId) {
+          ... on ProjectV2 {
+            title
+            items(first: 50, after: $cursor) {
+              pageInfo { hasNextPage endCursor }
+              nodes {
+                id
+                content {
+                  ... on Issue      { title number }
+                  ... on DraftIssue { title }
+                  ... on PullRequest { title number }
+                }
+              }
+            }
+          }
+        }
+      }
+    `, { projectId: projectNodeId, cursor });
+
+    const proj = data?.node;
+    if (!proj?.items) throw new Error(`Node "${projectNodeId}" is not a ProjectV2 or is inaccessible.`);
+
+    for (const node of proj.items.nodes || []) {
+      if (node?.content) items.push({ id: node.id, content: node.content });
+    }
+
+    if (!proj.items.pageInfo.hasNextPage) {
+      return { title: proj.title, items };
+    }
+    cursor = proj.items.pageInfo.endCursor;
+  }
+}
+
+export function labelsToType(labels) {
+  const lower = (labels || []).map(l => l.name?.toLowerCase() || '');
+  if (lower.some(l => l === 'bug')) return 'bug';
+  if (lower.some(l => l === 'documentation')) return 'docs';
+  return 'feature';
+}
+
+export function contentKind(content) {
+  if ('number' in content && content.url?.includes('/issues/')) return 'Issue';
+  if ('number' in content && content.url?.includes('/pull/')) return 'PR';
+  return 'Draft';
+}

package/bin/approve.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/* flow:approve — promote a decision to a real Todo task.
+   Usage:
+     flow-approve <decision_id>
+     flow-approve <decision_id> --title="override" --assignee=...
+*/
+
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  if (!raw) die('Usage: flow-approve <decision_id>');
+  const id = await resolveTaskId(raw);
+
+  const overrides = {};
+  for (const k of ['title', 'body_md', 'assignee_id', 'priority', 'type', 'area']) {
+    const v = arg(k);
+    if (v !== undefined && v !== '') overrides[k] = v;
+  }
+
+  const r = await flowFetch(`/api/flow/decisions/${id}/approve`, {
+    method: 'POST', body: overrides,
+  });
+  process.stdout.write(`Promoted to task #${r.task.id.slice(0, 6)} — "${r.task.title}"\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/assign.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/* flow:assign — reassign or assign a task to any actor.
+
+   Usage:
+     flow-assign <task_id> <actor_id>
+     flow-assign <task_id> none      # clear assignee
+
+   Server-side: human-only (claude alone cannot push work onto humans).
+*/
+
+import { flowFetch, resolveTaskId, positional, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  const who = positional(1);
+  if (!raw || !who) die('Required: <task_id> <actor_id|none>');
+  const taskId = await resolveTaskId(raw);
+
+  const assignee_id = (who === 'none' || who === 'null' || who === '-') ? null : who;
+
+  try {
+    const r = await flowFetch(`/api/flow/tasks/${taskId}/assign`, {
+      method: 'POST',
+      body: { assignee_id },
+    });
+    process.stdout.write(`Assigned: ${r.task.title}\n`);
+    process.stdout.write(`  Now assignee: ${r.task.assignee_id || '(unassigned)'}\n`);
+  } catch (e) {
+    if (e.status === 403) die('Assignment requires a human actor (FLOW_ACTING_VIA=self or no claude header).');
+    if (e.status === 404) die('Task not found.');
+    if (e.status === 400) die(`Invalid body: ${e.body?.error || e.message}`);
+    die(e.message || e);
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/claim.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/* flow:claim — self-assign a task and move it to in_progress.
+   Usage: flow-claim <task_id>
+*/
+
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  if (!raw) die('Usage: flow-claim <task_id> [--files=src/a.js,lib/b.js] [--watch]');
+  const id = await resolveTaskId(raw);
+
+  const filesArg = arg('files');
+  const files = filesArg ? filesArg.split(',').map(f => f.trim()).filter(Boolean) : undefined;
+  const watch = arg('watch') !== undefined;
+
+  const body = { task_id: id, ...(files ? { files } : {}) };
+
+  let r;
+  if (watch) {
+    while (true) {
+      try {
+        r = await flowFetch('/api/flow/claim', { method: 'POST', body });
+        break;
+      } catch (e) {
+        if (e.status === 409 || e.status === 429) {
+          const reason = e.status === 429 ? 'WIP limit reached' : 'Task already claimed';
+          process.stdout.write(`${reason} — retrying in 30s… (Ctrl+C to cancel)\n`);
+          await new Promise(ok => setTimeout(ok, 30000));
+        } else {
+          throw e;
+        }
+      }
+    }
+  } else {
+    r = await flowFetch('/api/flow/claim', { method: 'POST', body });
+  }
+  process.stdout.write(`Claimed #${r.task.issue_num ?? r.task.id.slice(0, 6)} — "${r.task.title}"\n`);
+
+  // Warn on file conflicts
+  if (r.conflict_warnings?.length) {
+    process.stdout.write(`\n⚠  File conflict${r.conflict_warnings.length === 1 ? '' : 's'} detected:\n`);
+    for (const w of r.conflict_warnings) {
+      process.stdout.write(`  #${w.task_ref}  "${w.title}"  (${w.claimed_by || 'unassigned'})\n`);
+      process.stdout.write(`    overlapping files: ${w.overlapping_files.join(', ')}\n`);
+    }
+    process.stdout.write('Consider coordinating before editing these files.\n\n');
+  } else if (!files && !r.files_checked?.length) {
+    process.stdout.write('Tip: use --files=src/a.js,lib/b.js to enable file conflict detection.\n');
+  }
+
+  // Announce presence on this task (non-fatal if heartbeat fails)
+  try {
+    await flowFetch('/api/flow/heartbeat', { method: 'POST', body: { task_id: r.task.id } });
+  } catch { /* best-effort */ }
+
+  // Print suggested branch name
+  const slug = r.task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+  const num = r.task.issue_num ?? r.task.id.slice(0, 6);
+  process.stdout.write(`Suggested branch: flow/${num}-${slug}\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/close-sprint.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/* flow:close-sprint — close a sprint milestone.
+   Archives all done tasks (clears their milestone field, appends sprint_closed event).
+   Non-done tasks keep the milestone so they can be carried to the next sprint.
+
+   Usage:
+     flow-close-sprint --milestone="Sprint 3"
+*/
+
+import { flowFetch, arg } from './_client.mjs';
+
+function pad(s, n) { return String(s || '').padEnd(n).slice(0, n); }
+function sanitize(s, max = 65) {
+  if (!s || typeof s !== 'string') return '';
+  return s.replace(/[\x00-\x1f]/g, ' ').trim().slice(0, max);
+}
+
+async function main() {
+  const milestone = arg('milestone');
+  if (!milestone) {
+    process.stderr.write('Usage: flow-close-sprint --milestone="Sprint Name"\n');
+    process.exit(1);
+  }
+
+  const res = await flowFetch(`/api/flow/milestones/${encodeURIComponent(milestone)}/close`, { method: 'POST' });
+
+  const { completed = [], carried_forward = [] } = res;
+  const total = completed.length + carried_forward.length;
+  const pct = total ? Math.round(completed.length / total * 100) : 0;
+
+  const out = [];
+  out.push(`=== Sprint closed: ${milestone} ===`);
+  out.push(`${completed.length}/${total} tasks done (${pct}%)`);
+  out.push('');
+
+  if (completed.length) {
+    out.push(`[completed — ${completed.length}]`);
+    for (const t of completed) {
+      const ref = `#${t.issue_num ?? t.id.slice(0, 6)}`;
+      out.push(`  ${ref}  ${pad(t.assignee_id || 'unassigned', 14)}  ${sanitize(t.title)}`);
+    }
+    out.push('');
+  }
+
+  if (carried_forward.length) {
+    out.push(`[carried forward — ${carried_forward.length}]`);
+    for (const t of carried_forward) {
+      const ref = `#${t.issue_num ?? t.id.slice(0, 6)}`;
+      out.push(`  ${ref}  ${pad(t.assignee_id || 'unassigned', 14)}  [${t.status}]  ${sanitize(t.title, 50)}`);
+    }
+    out.push('');
+  }
+
+  out.push('Done tasks archived (milestone cleared). Carried tasks keep the milestone for the next sprint.');
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+main().catch(e => {
+  process.stderr.write('close-sprint failed: ' + (e.message || e) + '\n');
+  process.exit(1);
+});

package/bin/close.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/* flow:close — mark a task done.
+   Usage: flow-close <task_id> [--summary="..."]
+*/
+
+import { flowFetch, resolveTaskId, positional, arg, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  if (!raw) die('Usage: flow-close <task_id> [--summary="..."]');
+  const id = await resolveTaskId(raw);
+  const summary = arg('summary');
+
+  const r = await flowFetch('/api/flow/close', {
+    method: 'POST',
+    body: { task_id: id, ...(summary ? { summary } : {}) },
+  });
+
+  process.stdout.write(`Closed #${r.task.id.slice(0, 6)} — "${r.task.title}"\n`);
+}
+
+main().catch(e => die(e.message || e));

package/bin/comment.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/* flow:comment — append a free-form comment to a task's timeline.
+   Usage: flow-comment <task_id> "<body>"
+*/
+
+import { flowFetch, resolveTaskId, positional, die } from './_client.mjs';
+
+async function main() {
+  const raw = positional(0);
+  const body = positional(1);
+  if (!raw || !body) die('Usage: flow-comment <task_id> "<body>"');
+  const id = await resolveTaskId(raw);
+  await flowFetch('/api/flow/comment', { method: 'POST', body: { task_id: id, body } });
+  process.stdout.write('Comment posted.\n');
+}
+
+main().catch(e => die(e.message || e));

package/bin/completion.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/* flow:completion — generate shell completion scripts.
+   Usage:
+     flow-completion bash   # print bash completion script
+     flow-completion zsh    # print zsh completion script
+     flow-completion fish   # print fish completion script
+*/
+
+import { positional, die } from './_client.mjs';
+
+const COMMANDS = [
+  'pull', 'claim', 'comment', 'close', 'create', 'propose', 'approve', 'reject',
+  'assign', 'decisions', 'ping', 'whoami', 'heartbeat', 'sync', 'status', 'handoff',
+  'standup', 'search', 'init', 'project', 'close-sprint', 'review', 'login',
+  'edit', 'unblock', 'log', 'completion',
+];
+
+const FLAGS = {
+  pull:    ['--focus', '--milestone=', '--sync-md'],
+  claim:   ['--files=', '--watch'],
+  create:  ['--title=', '--type=', '--area=', '--priority=', '--due=', '--blocked-by=', '--milestone=', '--from-issue=', '--from-project-item=', '--template='],
+  handoff: ['--task=', '--to=', '--context=', '--branch=', '--questions=', '--next-step='],
+  standup: ['--since=', '--velocity'],
+  search:  ['--status=', '--area=', '--assignee='],
+  sync:    ['--since='],
+  review:  ['--pr=', '--reviewer=', '--context='],
+  edit:    ['--title=', '--priority=', '--area=', '--due=', '--milestone=', '--blocked-by='],
+  log:     ['--task=', '--limit='],
+  'close-sprint': ['--milestone='],
+};
+
+function bashScript() {
+  const cmds = COMMANDS.map(c => `flow-${c}`).join(' ');
+  return `# Flow CLI bash completion
+# Source this file or add to ~/.bash_completion.d/flow
+
+_flow_complete() {
+  local cur prev words
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  local commands="${cmds}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( \$(compgen -W "\$commands" "\$cur") )
+    return
+  fi
+
+  local cmd="\${COMP_WORDS[0]}"
+  local subcmd="\${cmd#flow-}"
+  case "\$subcmd" in
+${Object.entries(FLAGS).map(([cmd, flags]) => `    ${cmd})
+      COMPREPLY=( \$(compgen -W "${flags.join(' ')}" "\$cur") )
+      return ;;`).join('\n')}
+  esac
+}
+
+${COMMANDS.map(c => `complete -F _flow_complete flow-${c}`).join('\n')}
+`;
+}
+
+function zshScript() {
+  const cmds = COMMANDS.map(c => `flow-${c}`);
+  return `#compdef ${cmds.join(' ')}
+# Flow CLI zsh completion
+# Place in ~/.zfunc/_flow and add fpath=(~/.zfunc $fpath) to ~/.zshrc
+
+_flow_args() {
+  local cmd="\${words[1]#flow-}"
+  case "\$cmd" in
+${Object.entries(FLAGS).map(([cmd, flags]) => `    ${cmd})
+      local opts=(${flags.map(f => `'${f}'`).join(' ')})
+      _arguments "\${opts[@]}"
+      ;;`).join('\n')}
+    *)
+      _arguments '*:arg:'
+      ;;
+  esac
+}
+
+${cmds.map(c => `compdef _flow_args ${c}`).join('\n')}
+`;
+}
+
+function fishScript() {
+  const lines = [];
+  for (const cmd of COMMANDS) {
+    lines.push(`# flow-${cmd}`);
+    const flags = FLAGS[cmd] || [];
+    for (const f of flags) {
+      const name = f.replace(/^--/, '').replace(/=$/, '');
+      const hasArg = f.endsWith('=');
+      lines.push(`complete -c flow-${cmd} -l ${name}${hasArg ? ' -r' : ''}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+async function main() {
+  const shell = positional(0);
+  if (!shell) die('Usage: flow-completion <bash|zsh|fish>');
+
+  switch (shell) {
+    case 'bash': process.stdout.write(bashScript()); break;
+    case 'zsh':  process.stdout.write(zshScript());  break;
+    case 'fish': process.stdout.write(fishScript()); break;
+    default: die(`Unknown shell "${shell}". Supported: bash, zsh, fish`);
+  }
+}
+
+main().catch(e => die(e.message || e));

package/bin/create.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/* flow:create — directly create a task (no propose→approve gate).
+
+   Usage:
+     flow-create --title="..." \
+       [--body="..."] \
+       [--type=bug|feature|chore|docs] \
+       [--area=<area>] \
+       [--priority=P0-now|P1-soon|P2-later] \
+       [--status=backlog|todo|in_progress|in_review|done] \
+       [--assignee=<actor_id>] \
+       [--due=YYYY-MM-DD] \
+       [--blocked-by=<uuid>,...] \
+       [--milestone=<name>] \
+       [--from-issue=<num>]            Import a GitHub Issue (requires FLOW_GITHUB_TOKEN + FLOW_GITHUB_REPO)
+       [--from-project-item=<node_id>] Import a GitHub Projects item by node ID (requires FLOW_GITHUB_TOKEN)
+       [--template=<id>]               Pre-fill from a task template defined in flow.config.json
+
+   Use flow-propose when the work needs human approval before it starts.
+   Use flow-create for tasks you are directly starting or tracking.
+*/
+
+import 'dotenv/config';
+import { flowFetch, arg, die } from './_client.mjs';
+import { githubHeaders, fetchProjectItem, labelsToType } from './_github.mjs';
+
+async function fetchGithubIssue(issueNum) {
+  const repo = process.env.FLOW_GITHUB_REPO;
+  if (!repo) die('FLOW_GITHUB_REPO is not set. Set it in .env to use --from-issue.');
+  const url = `https://api.github.com/repos/${repo}/issues/${issueNum}`;
+  const res = await fetch(url, { headers: githubHeaders() });
+  if (res.status === 404) die(`GitHub Issue #${issueNum} not found in ${repo}.`);
+  if (!res.ok) die(`GitHub API error ${res.status} fetching issue #${issueNum}.`);
+  return res.json();
+}
+
+async function main() {
+  const fromIssue = arg('from-issue');
+  const fromProjectItem = arg('from-project-item');
+  const fromTemplate = arg('template');
+  if ([fromIssue, fromProjectItem, fromTemplate].filter(Boolean).length > 1) die('Use only one of --from-issue, --from-project-item, --template.');
+  let prefill = {};
+
+  if (fromTemplate) {
+    const r = await flowFetch('/api/flow/templates');
+    const tmpl = r.templates?.[fromTemplate];
+    if (!tmpl) die(`Unknown template "${fromTemplate}". Available: ${Object.keys(r.templates || {}).join(', ') || 'none'}`);
+    prefill = { ...tmpl };
+  }
+
+  if (fromIssue) {
+    const num = parseInt(fromIssue, 10);
+    if (!num || num < 1) die('--from-issue must be a positive integer (e.g. --from-issue=42)');
+    process.stdout.write(`Fetching GitHub Issue #${num}...\n`);
+    const issue = await fetchGithubIssue(num);
+    const labels = (issue.labels || []).map(l => l.name.toLowerCase());
+    const type = labels.includes('bug') ? 'bug'
+      : labels.includes('documentation') ? 'docs'
+      : 'feature';
+    prefill = {
+      title: issue.title,
+      body_md: issue.body || '',
+      type,
+      status: 'backlog',
+      github_issue_num: issue.number,
+    };
+  }
+
+  if (fromProjectItem) {
+    if (!process.env.FLOW_GITHUB_TOKEN) die('FLOW_GITHUB_TOKEN is not set. Set it in .env to use --from-project-item.');
+    process.stdout.write(`Fetching GitHub Projects item ${fromProjectItem}...\n`);
+    const item = await fetchProjectItem(fromProjectItem);
+    const c = item.content;
+    const type = labelsToType(c.labels?.nodes);
+    prefill = {
+      title: c.title,
+      body_md: c.body || '',
+      type,
+      status: 'backlog',
+      ...(c.number && c.url?.includes('/issues/') ? { github_issue_num: c.number } : {}),
+    };
+  }
+
+  const title = arg('title') || prefill.title;
+  if (!title) die('Required: --title="..." (or use --from-issue=<num> / --template=<id>)\n\nUsage: flow-create --title="..." [--type=bug|feature|chore|docs] [--area=<area>] [--priority=P0-now|P1-soon|P2-later] [--status=backlog|todo] [--assignee=<actor_id>] [--from-issue=<num>] [--template=<id>]');
+
+  const body = {
+    ...prefill,
+    title,
+    ...(arg('body')       ? { body_md:          arg('body')       } : {}),
+    ...(arg('type')       ? { type:              arg('type')       } : {}),
+    ...(arg('area')       ? { area:              arg('area')       } : {}),
+    ...(arg('priority')   ? { priority:          arg('priority')   } : {}),
+    ...(arg('status')     ? { status:            arg('status')     } : {}),
+    ...(arg('assignee')   ? { assignee_id:       arg('assignee')   } : {}),
+    ...(arg('due')        ? { due_at: new Date(arg('due')).toISOString() } : {}),
+    ...(arg('blocked-by') ? { blocked_by: arg('blocked-by').split(',').map(s => s.trim()).filter(Boolean) } : {}),
+    ...(arg('milestone')  ? { milestone:         arg('milestone')  } : {}),
+  };
+
+  try {
+    const r = await flowFetch('/api/flow/tasks', { method: 'POST', body });
+    const t = r.task;
+    process.stdout.write(`Created #${t.id.slice(0, 6)} — "${t.title}"\n`);
+    process.stdout.write(`  id:       ${t.id}\n`);
+    process.stdout.write(`  status:   ${t.status}\n`);
+    process.stdout.write(`  priority: ${t.priority}  type: ${t.type}  area: ${t.area}\n`);
+    if (t.assignee_id) process.stdout.write(`  assignee: ${t.assignee_id}\n`);
+    if (t.github_issue_num) process.stdout.write(`  github:   #${t.github_issue_num}\n`);
+  } catch (e) {
+    if (e.status === 400) die(`Invalid fields: ${e.body?.error || e.message}`);
+    die(e.message || e);
+  }
+}
+
+main().catch(e => die(e.message || e));