openspecpm 0.1.0-alpha.0

package/cli/src/commands/init.js

@@ -0,0 +1,111 @@
+import * as p from '@clack/prompts';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeConfig, readConfig } from '../config.js';
+import { listAdapters } from '../adapters/index.js';
+
+export async function runInit({ nonInteractive = false } = {}) {
+  const existing = await readConfig();
+  if (existing && nonInteractive) {
+    p.note(`Config already exists at .openspecpm/config.json (adapter: ${existing.adapter}).`, 'init');
+    return existing;
+  }
+
+  p.intro('openspecpm init — pick your PM tool');
+
+  // Detect existing OpenSpec setup (brownfield).
+  const openspecDir = join(process.cwd(), 'openspec');
+  if (existsSync(openspecDir)) {
+    p.note(`Detected existing openspec/ — will not re-run \`openspec init\`. Existing proposals will be reused.`, 'brownfield');
+  }
+
+  if (existing) {
+    const overwrite = await p.confirm({
+      message: `A config already exists (adapter: ${existing.adapter}). Overwrite?`,
+      initialValue: false,
+    });
+    if (p.isCancel(overwrite) || !overwrite) {
+      p.cancel('Keeping existing config.');
+      return existing;
+    }
+  }
+
+  const adapter = await p.select({
+    message: 'Which PM tool does your team use?',
+    options: [
+      { value: 'github', label: 'GitHub Issues / Projects', hint: 'Stable (gh CLI)' },
+      { value: 'azure', label: 'Azure DevOps Boards', hint: 'Beta — REST + PAT' },
+      { value: 'jira', label: 'Jira', hint: 'Beta — REST + API token' },
+      { value: 'linear', label: 'Linear', hint: 'Beta — GraphQL + Personal API Key' },
+      { value: 'gitlab', label: 'GitLab Issues', hint: 'Beta — REST v4 + PAT' },
+    ],
+  });
+  if (p.isCancel(adapter)) return cancelled();
+  if (!listAdapters().includes(adapter)) return cancelled();
+
+  const config = { adapter };
+
+  if (adapter === 'github') {
+    const repo = await p.text({
+      message: 'GitHub repo (owner/name)',
+      placeholder: 'aks-builds/openspecpm',
+      validate: (v) => (/^[^/]+\/[^/]+$/.test(v ?? '') ? undefined : 'Format must be owner/name'),
+    });
+    if (p.isCancel(repo)) return cancelled();
+    config.repo = repo;
+  } else if (adapter === 'azure') {
+    const organization = await p.text({ message: 'Azure DevOps organization', placeholder: 'contoso' });
+    if (p.isCancel(organization)) return cancelled();
+    const project = await p.text({ message: 'Project name', placeholder: 'MyProject' });
+    if (p.isCancel(project)) return cancelled();
+    config.organization = organization;
+    config.project = project;
+    p.note('Set AZURE_DEVOPS_EXT_PAT in your environment with Work Items (Read/Write) scope.', 'azure auth');
+  } else if (adapter === 'jira') {
+    const baseUrl = await p.text({
+      message: 'Jira base URL',
+      placeholder: 'https://yourorg.atlassian.net',
+      validate: (v) => (/^https?:\/\//.test(v ?? '') ? undefined : 'Must be an http(s) URL'),
+    });
+    if (p.isCancel(baseUrl)) return cancelled();
+    const projectKey = await p.text({ message: 'Project key', placeholder: 'PROJ' });
+    if (p.isCancel(projectKey)) return cancelled();
+    config.baseUrl = baseUrl;
+    config.projectKey = projectKey;
+    p.note('Set JIRA_EMAIL and JIRA_API_TOKEN in your environment.', 'jira auth');
+  } else if (adapter === 'linear') {
+    const teamId = await p.text({
+      message: 'Linear team ID (UUID from team settings URL)',
+      placeholder: '12345678-90ab-cdef-1234-567890abcdef',
+      validate: (v) => (v && v.length >= 4 ? undefined : 'Team ID is required'),
+    });
+    if (p.isCancel(teamId)) return cancelled();
+    config.teamId = teamId;
+    p.note('Set LINEAR_API_KEY in your environment (create at linear.app/settings/api).', 'linear auth');
+  } else if (adapter === 'gitlab') {
+    const baseUrl = await p.text({
+      message: 'GitLab base URL',
+      placeholder: 'https://gitlab.com',
+      validate: (v) => (/^https?:\/\//.test(v ?? '') ? undefined : 'Must be an http(s) URL'),
+    });
+    if (p.isCancel(baseUrl)) return cancelled();
+    const projectId = await p.text({
+      message: 'Project ID (numeric or URL-encoded "group/repo")',
+      placeholder: '12345 or mygroup%2Fmyrepo',
+      validate: (v) => (v ? undefined : 'Project ID is required'),
+    });
+    if (p.isCancel(projectId)) return cancelled();
+    config.baseUrl = baseUrl;
+    config.projectId = projectId;
+    p.note('Set GITLAB_TOKEN with `api` scope in your environment.', 'gitlab auth');
+  }
+
+  const path = await writeConfig(config);
+  p.outro(`Wrote ${path}. Next: run \`openspecpm doctor ${adapter}\` to verify auth.`);
+  return config;
+}
+
+function cancelled() {
+  p.cancel('Aborted.');
+  return null;
+}

package/cli/src/commands/next.js

@@ -0,0 +1,18 @@
+import { listChanges, findNextTasks } from '../tracking.js';
+
+export async function runNext({ limit = 5 } = {}) {
+  const changes = await listChanges();
+  const candidates = findNextTasks(changes);
+  out(`openspecpm next — ${candidates.length} task(s) ready to start\n`);
+  if (!candidates.length) return;
+  for (const { change, task } of candidates.slice(0, limit)) {
+    const tag = task.external_id ? ` [${task.external_id}]` : ` [unsynced]`;
+    const parallel = task.parallel ? ' parallel' : '';
+    out(`  • ${change} — ${task.title}${tag}${parallel}`);
+  }
+  if (candidates.length > limit) out(`  …and ${candidates.length - limit} more.`);
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}

package/cli/src/commands/propose.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { propose, changeExists, changeDir, OpenSpecError } from '../openspec-bridge.js';
+import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { CHANGE_TYPES, proposalTemplate, specsTemplate, STARTER_TASKS } from '../bdd/templates.js';
+
+export async function runPropose({ feature, prompt, type = 'feature', offline = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  if (!CHANGE_TYPES.includes(type)) {
+    const err = new Error(`Unknown change type "${type}".`);
+    err.remediation = `Use one of: ${CHANGE_TYPES.join(', ')}`;
+    throw err;
+  }
+
+  if (changeExists(feature)) {
+    process.stdout.write(`Change "${feature}" already exists at ${changeDir(feature)}. Skipping propose.\n`);
+    await softLint(changeDir(feature));
+    return changeDir(feature);
+  }
+
+  if (offline) {
+    const dir = await scaffoldOffline(feature, type);
+    process.stdout.write(`\nProposal scaffolded offline at ${dir} (type=${type}).\n`);
+    await softLint(dir);
+    process.stdout.write(`Next: refine the templates, then run \`openspecpm sync ${feature}\`.\n`);
+    return dir;
+  }
+
+  const seed = prompt ?? `Author a BDD-shaped ${type} proposal for ${feature}. Use Given/When/Then scenarios in specs/.`;
+  try {
+    const dir = await propose(feature, seed);
+    process.stdout.write(`\nProposal created at ${dir}.\n`);
+    await softLint(dir);
+    process.stdout.write(`Next: review proposal.md + specs/, then run \`openspecpm sync ${feature}\`.\n`);
+    return dir;
+  } catch (err) {
+    if (err instanceof OpenSpecError) throw err;
+    throw new OpenSpecError(`openspec propose failed: ${err.message}`, {
+      remediation: 'Run `openspecpm doctor` to verify OpenSpec is installed, or pass --offline to scaffold from a template.',
+    });
+  }
+}
+
+async function scaffoldOffline(feature, type) {
+  const dir = changeDir(feature);
+  await mkdir(join(dir, 'specs'), { recursive: true });
+  if (!existsSync(join(dir, 'proposal.md'))) {
+    await writeFile(join(dir, 'proposal.md'), proposalTemplate(type, feature), 'utf8');
+  }
+  if (!existsSync(join(dir, 'tasks.md'))) {
+    await writeFile(join(dir, 'tasks.md'), STARTER_TASKS, 'utf8');
+  }
+  if (!existsSync(join(dir, 'specs', 'main.md'))) {
+    await writeFile(join(dir, 'specs', 'main.md'), specsTemplate(type), 'utf8');
+  }
+  return dir;
+}
+
+async function softLint(dir) { // eslint-disable-line
+  const findings = await lintChange(dir);
+  const sum = summarize(findings);
+  if (!sum.total) return;
+  process.stdout.write(`\nBDD lint (soft): ${sum.errors} errors, ${sum.warnings} warnings\n`);
+  process.stdout.write(formatFindings(findings));
+  process.stdout.write('These will block `sync` unless you pass --force. Refine scenarios before pushing.\n');
+}

package/cli/src/commands/reconcile.js

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+import * as fm from '../frontmatter.js';
+
+export async function runReconcile({ feature, dryRun = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) throw new Error(`OpenSpec change "${feature}" not found.`);
+
+  const dir = changeDir(feature);
+  const tasksPath = join(dir, 'tasks.md');
+  let tasksRaw = '';
+  try { tasksRaw = await readFile(tasksPath, 'utf8'); } catch { /* missing */ }
+  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
+  const items = tdata.items ?? [];
+  if (!items.length) {
+    process.stdout.write('No items in tasks.md to reconcile.\n');
+    return;
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  await adapter.init();
+
+  let drift = 0;
+  const updated = [];
+  for (const task of items) {
+    if (!task.external_id) {
+      updated.push(task);
+      continue;
+    }
+    try {
+      const view = await adapter.getWorkItem({ adapter: config.adapter, id: task.external_id });
+      const remoteClosed = view.status === 'closed';
+      const next = { ...task };
+      if (remoteClosed && !task.closed) {
+        next.closed = true;
+        next.done = true;
+        drift++;
+        process.stdout.write(`! ${task.title} [${task.external_id}] closed remotely — marking done locally\n`);
+      } else if (!remoteClosed && task.closed) {
+        next.closed = false;
+        next.done = false;
+        drift++;
+        process.stdout.write(`! ${task.title} [${task.external_id}] re-opened remotely — clearing local closed flag\n`);
+      }
+      next.remote_status = view.status;
+      next.remote_assignee = view.assignee ?? null;
+      updated.push(next);
+    } catch (err) {
+      process.stdout.write(`✖ ${task.title} [${task.external_id}] — ${err.message}\n`);
+      updated.push({ ...task, last_reconcile_error: err.message });
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(`\n[dry-run] ${drift} item(s) would be updated locally.\n`);
+    return;
+  }
+  if (!drift && !updated.some((t, i) => t.remote_status !== items[i].remote_status)) {
+    process.stdout.write('Already in sync.\n');
+    return;
+  }
+  const patched = fm.serialize({ ...tdata, items: updated }, tbody);
+  await writeFile(tasksPath, patched, 'utf8');
+  process.stdout.write(`\n✓ Reconciled ${drift} drifted item(s); remote_status mirrored on every synced task.\n`);
+}

package/cli/src/commands/search.js

@@ -0,0 +1,52 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { OPENSPEC_CHANGES_DIR } from '../openspec-bridge.js';
+
+export async function runSearch({ query, limit = 50, caseSensitive = false } = {}) {
+  if (!query) throw new Error('query is required');
+  const flags = caseSensitive ? '' : 'i';
+  const re = new RegExp(escapeRegex(query), flags);
+  const root = process.cwd();
+  const dir = join(root, OPENSPEC_CHANGES_DIR);
+  if (!existsSync(dir)) {
+    process.stdout.write('No OpenSpec changes to search.\n');
+    return;
+  }
+  const hits = [];
+  await walk(dir, async (path) => {
+    if (!/\.md$/i.test(path)) return;
+    const lines = (await readFile(path, 'utf8')).split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i])) {
+        hits.push({ path: relative(root, path), line: i + 1, text: lines[i].trim().slice(0, 200) });
+        if (hits.length >= limit * 2) return;
+      }
+    }
+  });
+  if (!hits.length) {
+    process.stdout.write(`No matches for /${query}/${flags}.\n`);
+    return;
+  }
+  for (const h of hits.slice(0, limit)) {
+    process.stdout.write(`${h.path}:${h.line}: ${h.text}\n`);
+  }
+  if (hits.length > limit) process.stdout.write(`…and ${hits.length - limit} more.\n`);
+}
+
+async function walk(dir, fn) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      await walk(full, fn);
+    } else if (e.isFile()) {
+      await fn(full);
+    }
+  }
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/cli/src/commands/ship.js

@@ -0,0 +1,79 @@
+import * as p from '@clack/prompts';
+import { execa } from 'execa';
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { loadChange } from '../tracking.js';
+import { changeExists } from '../openspec-bridge.js';
+
+export async function runShip({ feature, yes = false, skipArchive = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) {
+    const err = new Error(`OpenSpec change "${feature}" not found.`);
+    err.remediation = `Did you mean another feature? Run \`openspecpm status\`.`;
+    throw err;
+  }
+
+  const change = await loadChange(feature);
+  const epicRef = change.proposal.external?.[config.adapter];
+  const synced = change.items.filter((t) => t.sync_state === 'created' && t.external_id);
+  const open = synced.filter((t) => !t.done && !t.closed);
+
+  p.intro(`openspecpm ship ${feature}`);
+  p.note(
+    `Adapter: ${config.adapter}\nEpic: ${epicRef ? `${epicRef.id} (${epicRef.url ?? '?'})` : 'unsynced'}\nWork items: ${synced.length} total, ${open.length} still open`,
+    'plan',
+  );
+
+  if (!yes) {
+    const ok = await p.confirm({
+      message: `Close ${open.length} open work item(s) and ${epicRef ? 'the epic' : '(no epic)'}, then ${skipArchive ? 'leave the OpenSpec change in place' : 'archive the OpenSpec change'}?`,
+      initialValue: false,
+    });
+    if (p.isCancel(ok) || !ok) {
+      p.cancel('Ship aborted.');
+      return;
+    }
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  await adapter.init();
+
+  for (const t of open) {
+    try {
+      await adapter.closeWorkItem({ adapter: config.adapter, id: t.external_id }, `Shipped via openspecpm ship ${feature}`);
+      out(`✓ closed ${t.external_id} — ${t.title}`);
+    } catch (err) {
+      out(`✖ failed to close ${t.external_id}: ${err.message}`);
+    }
+  }
+
+  if (epicRef) {
+    try {
+      await adapter.closeWorkItem({ adapter: config.adapter, id: epicRef.id }, `Shipped: all tasks closed for ${feature}.`);
+      out(`✓ closed epic ${epicRef.id}`);
+    } catch (err) {
+      out(`✖ failed to close epic: ${err.message}`);
+    }
+  }
+
+  if (!skipArchive) {
+    try {
+      await execa('openspec', ['archive', feature], { stdio: 'inherit' });
+      out(`✓ archived ${feature}`);
+    } catch (err) {
+      out(`! openspec archive failed: ${err.message}. The change folder still exists at openspec/changes/${feature}/.`);
+    }
+  }
+
+  p.outro(`Shipped ${feature}.`);
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}

package/cli/src/commands/standup.js

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises';
+import { listChanges, findRecentUpdates } from '../tracking.js';
+import { readConfig } from '../config.js';
+import { notify } from '../notify.js';
+
+export async function runStandup({ since = '24h', broadcast = false } = {}) {
+  const sinceMs = parseWindow(since);
+  const changes = await listChanges();
+  const recent = await findRecentUpdates(changes, sinceMs);
+  const lines = [`openspecpm standup — last ${since}`];
+  if (!recent.length) {
+    lines.push('No progress updates in window.');
+    process.stdout.write(lines.join('\n') + '\n');
+    return;
+  }
+  let lastChange = null;
+  for (const r of recent) {
+    if (r.change !== lastChange) {
+      lines.push(`\n[${r.change}]`);
+      lastChange = r.change;
+    }
+    const snippet = (await readFile(r.path, 'utf8')).split(/\r?\n/).slice(0, 5).join(' ').slice(0, 240);
+    lines.push(`  ${r.mtime.toISOString().slice(0, 16).replace('T', ' ')}  ${r.task}: ${snippet}`);
+  }
+  const text = lines.join('\n');
+  process.stdout.write(text + '\n');
+
+  if (broadcast) {
+    const config = await readConfig();
+    const r = await notify({ config, title: `OpenSpecPM standup (${since})`, body: text });
+    process.stdout.write(`\nBroadcast: ${r.sent} target(s)` + (r.errors.length ? `, ${r.errors.length} error(s)` : '') + '\n');
+    for (const e of r.errors) process.stdout.write(`  ✖ ${e.target}: ${e.error}\n`);
+  }
+}
+
+function parseWindow(s) {
+  const m = String(s).match(/^(\d+)([hdw])$/i);
+  if (!m) return 24 * 60 * 60 * 1000;
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  return n * (unit === 'h' ? 3600e3 : unit === 'd' ? 86400e3 : 7 * 86400e3);
+}

package/cli/src/commands/status.js

@@ -0,0 +1,29 @@
+import { readConfig } from '../config.js';
+import { listChanges, summarizeChange } from '../tracking.js';
+
+export async function runStatus() {
+  const config = await readConfig();
+  out('openspecpm status\n');
+  out(`Adapter: ${config?.adapter ?? '(not configured — run `openspecpm init`)'}`);
+  if (config?.repo) out(`Repo:    ${config.repo}`);
+  if (config?.organization) out(`Org:     ${config.organization} / ${config.project}`);
+  if (config?.baseUrl && config?.projectKey) out(`Jira:    ${config.baseUrl} / ${config.projectKey}`);
+
+  const changes = await listChanges();
+  out(`\nChanges: ${changes.length}`);
+  if (!changes.length) {
+    out('  (no OpenSpec changes yet — run `openspecpm propose <feature>`)');
+    return;
+  }
+  for (const c of changes) {
+    const { total, counts } = summarizeChange(c);
+    const flags = [];
+    if (c.proposal.status) flags.push(c.proposal.status);
+    if (c.proposal.external) flags.push('synced');
+    out(`  - ${c.name} (${total} tasks: ${counts.created} synced, ${counts.pending} pending, ${counts.failed} failed, ${counts.done} done)` + (flags.length ? ` [${flags.join(', ')}]` : ''));
+  }
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}

package/cli/src/commands/sync.js

@@ -0,0 +1,128 @@
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readConfig } from '../config.js';
+import { loadAdapter } from '../adapters/index.js';
+import { changeDir, changeExists } from '../openspec-bridge.js';
+import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import * as fm from '../frontmatter.js';
+
+export async function runSync({ feature, dryRun = false, force = false, diff = false } = {}) {
+  if (!feature) throw new Error('feature name is required');
+  const config = await readConfig();
+  if (!config) {
+    const err = new Error('No .openspecpm/config.json found.');
+    err.remediation = 'Run `openspecpm init` first.';
+    throw err;
+  }
+  if (!changeExists(feature)) {
+    const err = new Error(`OpenSpec change "${feature}" not found.`);
+    err.remediation = `Run \`openspecpm propose ${feature}\` first.`;
+    throw err;
+  }
+
+  const dir = changeDir(feature);
+  const findings = await lintChange(dir);
+  const sum = summarize(findings);
+  if (sum.errors > 0 && !force) {
+    process.stderr.write(`BDD lint: ${sum.errors} errors, ${sum.warnings} warnings\n`);
+    process.stderr.write(formatFindings(findings));
+    const err = new Error(`Sync blocked by ${sum.errors} BDD lint errors.`);
+    err.remediation = 'Refine the scenarios, or pass --force to override.';
+    throw err;
+  }
+  if (sum.total > 0) {
+    process.stdout.write(`BDD lint: ${sum.errors} errors, ${sum.warnings} warnings (${force && sum.errors ? 'overridden by --force' : 'soft'})\n`);
+    process.stdout.write(formatFindings(findings));
+  }
+
+  const adapter = loadAdapter(config.adapter, config);
+  if (!dryRun) await adapter.init();
+
+  if (diff) {
+    out(`\n[diff] adapter: ${config.adapter}`);
+    out(`[diff] hierarchy depth: ${adapter.capabilities().hierarchyDepth}`);
+  }
+
+  const proposalPath = join(dir, 'proposal.md');
+  const proposalRaw = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+  const { data: pdata } = fm.parse(proposalRaw);
+
+  // Idempotency: re-use existing epic ref if present.
+  let epicRef = pdata.external?.[config.adapter];
+  const featureSpec = { name: feature, summary: extractSummary(proposalRaw) || `OpenSpec change: ${feature}` };
+
+  if (!epicRef) {
+    if (dryRun) {
+      out(`[dry-run] would create epic for "${feature}" via ${config.adapter}`);
+      epicRef = { adapter: config.adapter, id: '<new>', url: '<new>' };
+    } else {
+      epicRef = await adapter.createEpic(featureSpec);
+      const patched = fm.patch(proposalRaw, {
+        ...pdata,
+        external: { ...(pdata.external ?? {}), [config.adapter]: epicRef },
+      });
+      await writeFile(proposalPath, patched, 'utf8');
+      out(`Created epic ${epicRef.url ?? epicRef.id}`);
+    }
+  } else {
+    out(`Epic already synced: ${epicRef.url ?? epicRef.id} (skipping)`);
+  }
+
+  // Walk tasks. OpenSpec stores them in tasks.md (a checklist) and/or specs/*.md.
+  // Sprint 1: read tasks.md as a flat list "- [ ] title" entries; create one work item per unchecked task.
+  const tasksPath = join(dir, 'tasks.md');
+  if (!existsSync(tasksPath)) {
+    out('No tasks.md found — only the epic was synced.');
+    return;
+  }
+  const tasksRaw = await readFile(tasksPath, 'utf8');
+  const { data: tdata, body: tbody } = fm.parse(tasksRaw);
+  const items = tdata.items ?? parseChecklist(tbody);
+  const updatedItems = [];
+
+  for (const task of items) {
+    if (task.sync_state === 'created' && task.external_id) {
+      out(`✓ ${task.title} (already created: ${task.external_id})`);
+      updatedItems.push(task);
+      continue;
+    }
+    if (dryRun) {
+      out(`[dry-run] would create work item: ${task.title}`);
+      updatedItems.push({ ...task, sync_state: 'pending' });
+      continue;
+    }
+    try {
+      const ref = await adapter.createWorkItem({ ...epicRef, feature }, { title: task.title, body: task.body ?? '' });
+      out(`+ ${task.title} → ${ref.url ?? ref.id}`);
+      updatedItems.push({ ...task, sync_state: 'created', external_id: ref.id, external_url: ref.url });
+    } catch (err) {
+      out(`✖ ${task.title} — ${err.message}`);
+      updatedItems.push({ ...task, sync_state: 'failed', last_error: err.message });
+    }
+  }
+
+  if (!dryRun) {
+    const patched = fm.serialize({ ...tdata, items: updatedItems }, tbody);
+    await writeFile(tasksPath, patched, 'utf8');
+  }
+}
+
+function out(s) {
+  process.stdout.write(s + '\n');
+}
+
+function extractSummary(md) {
+  const { body } = fm.parse(md);
+  const firstPara = body.split(/\r?\n\r?\n/).find((p) => p.trim() && !p.startsWith('#'));
+  return (firstPara ?? '').trim().slice(0, 1000);
+}
+
+function parseChecklist(body) {
+  const items = [];
+  for (const line of body.split(/\r?\n/)) {
+    const m = line.match(/^\s*-\s*\[( |x|X)\]\s+(.+?)\s*$/);
+    if (m) items.push({ title: m[2], done: m[1].toLowerCase() === 'x', sync_state: 'pending' });
+  }
+  return items;
+}