@goodtek/vibeops 0.2.0

package/dist/commands/plan.js

@@ -0,0 +1,114 @@
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { briefToMarkdown, findMissingRequired, gatherBrief, parseBriefFromMarkdown, parseIdea, } from "../lib/brief.js";
+import { pathExists, readText, writeText } from "../lib/filesystem.js";
+import { bold, cyan, dim, log, yellow } from "../lib/logger.js";
+import { buildPlanPrompt } from "../lib/prompt-builder.js";
+const DEFAULT_BRIEF_REL = ".vibeops/brief/project-brief.md";
+const DEFAULT_PROMPT_REL = ".vibeops/generated/plan-prompt.md";
+function toAbsolute(root, candidate) {
+    return isAbsolute(candidate) ? candidate : resolve(root, candidate);
+}
+function relDisplay(root, abs) {
+    const r = relative(root, abs);
+    return r.length === 0 ? "." : r;
+}
+export async function planCommand(options) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const nonInteractive = options.nonInteractive === true;
+    const briefAbs = join(cwd, DEFAULT_BRIEF_REL);
+    const promptAbs = typeof options.output === "string" ? toAbsolute(cwd, options.output) : join(cwd, DEFAULT_PROMPT_REL);
+    log.info(bold(`vibeops plan`));
+    log.info(dim(`  cwd: ${cwd}`));
+    if (options.from)
+        log.info(dim(`  from: ${options.from}`));
+    if (options.idea)
+        log.info(dim(`  idea: ${options.idea}`));
+    if (nonInteractive)
+        log.info(dim(`  mode: non-interactive`));
+    log.blank();
+    let bundle;
+    if (typeof options.from === "string" && options.from.length > 0) {
+        bundle = await loadFromFile({
+            cwd,
+            fromPath: toAbsolute(cwd, options.from),
+            nonInteractive,
+            idea: options.idea,
+        });
+    }
+    else {
+        if (!nonInteractive && process.stdin.isTTY !== true) {
+            log.error("vibeops plan requires a TTY. In CI/piped environments, pass --non-interactive or supply --from <brief.md>.");
+            process.exitCode = 1;
+            return;
+        }
+        log.step(nonInteractive
+            ? "non-interactive: build the ProjectBrief from flag values + safe placeholders"
+            : "interactive: build the ProjectBrief from 20 questions (arrow keys · Space · Enter)");
+        log.blank();
+        bundle = await gatherBrief({
+            cwd,
+            idea: options.idea,
+            nonInteractive,
+        });
+    }
+    const briefMd = briefToMarkdown(bundle.brief, bundle.meta);
+    await writeText(briefAbs, briefMd);
+    log.ok(`Wrote brief: ${relDisplay(cwd, briefAbs)}`);
+    const promptMd = buildPlanPrompt({
+        brief: bundle.brief,
+        meta: bundle.meta,
+        briefRelativePath: relDisplay(cwd, briefAbs),
+    });
+    await writeText(promptAbs, promptMd);
+    log.ok(`Cursor planning prompt: ${relDisplay(cwd, promptAbs)}`);
+    if (bundle.meta.assumptions.length > 0) {
+        log.blank();
+        log.info(`${yellow("!")} ${bold("Assumptions")} (items the Planner Agent should reconfirm):`);
+        for (const a of bundle.meta.assumptions)
+            log.info(`  · ${a}`);
+    }
+    log.blank();
+    log.info(bold("Next steps:"));
+    log.info(`  1) Open a new Cursor chat and paste the full contents of ${cyan(relDisplay(cwd, promptAbs))}.`);
+    log.info(`  2) Review the Planner Agent's docs/project/* + initial backlog via git diff and commit.`);
+    log.info(`  3) To revise the brief, edit ${cyan(relDisplay(cwd, briefAbs))} and regenerate the prompt with`);
+    log.info(`     ${dim("vibeops plan --from " + DEFAULT_BRIEF_REL)}.`);
+}
+async function loadFromFile(inputs) {
+    const { cwd, fromPath, nonInteractive, idea } = inputs;
+    if (!(await pathExists(fromPath))) {
+        log.error(`--from path does not exist: ${fromPath}`);
+        process.exit(1);
+    }
+    const md = await readText(fromPath);
+    log.step(`Loading brief: ${relDisplay(cwd, fromPath)}`);
+    const parsed = parseBriefFromMarkdown(md);
+    parsed.meta.source = "from-file";
+    if (typeof idea === "string" && idea.length > 0) {
+        const ideaParsed = parseIdea(idea);
+        if (ideaParsed.projectName && parsed.brief.projectName.length === 0) {
+            parsed.brief.projectName = ideaParsed.projectName;
+        }
+        if (ideaParsed.oneLineIdea && parsed.brief.oneLineIdea.length === 0) {
+            parsed.brief.oneLineIdea = ideaParsed.oneLineIdea;
+        }
+    }
+    const missing = findMissingRequired(parsed.brief);
+    if (missing.length === 0) {
+        return parsed;
+    }
+    if (nonInteractive) {
+        log.warn(`Missing required fields: ${missing.join(", ")} → filling with placeholders and recording them in Assumptions.`);
+        return parsed;
+    }
+    log.warn(`Missing required fields: ${missing.join(", ")} → asking only the missing questions.`);
+    log.blank();
+    const filled = await gatherBrief({
+        cwd,
+        idea,
+        nonInteractive: false,
+        seed: parsed.brief,
+    });
+    filled.meta.source = "from-file";
+    return filled;
+}

package/dist/commands/status.js

@@ -0,0 +1,17 @@
+import { resolve } from "node:path";
+import { collectStatus } from "../status/collector.js";
+import { printHuman, toJson } from "../status/format.js";
+import { log } from "../lib/logger.js";
+export async function statusCommand(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const report = await collectStatus(cwd);
+    if (options.json) {
+        log.raw(toJson(report));
+    }
+    else {
+        printHuman(report);
+    }
+    if (!report.isVibeopsProject) {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/task-check.js

@@ -0,0 +1,155 @@
+import { join, relative, resolve } from "node:path";
+import { pathExists, readText } from "../lib/filesystem.js";
+import { gitAllChangedFilesSinceTaskStart, gitCommitsAhead, gitLogOneline, readGitInfo, } from "../lib/git.js";
+import { bold, cyan, dim, green, log, red, yellow } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+import { findAcceptanceCriteria, findExpectedFiles, findTaskFile, hasNonEmptySection, readGitContext, readSection, readTaskFile, statusDisplay, } from "../lib/task.js";
+import { buildTaskPromptString } from "../lib/task-prompt.js";
+function relOrAbs(root, p) {
+    const r = relative(root, p);
+    return r === "" ? "." : r.startsWith("..") ? p : r;
+}
+function todayLogFileName() {
+    const d = new Date();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}.md`;
+}
+export async function taskCheckCommand(taskId, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const agentName = options.agent ?? "reviewer";
+    let missing = 0;
+    const taskFile = await findTaskFile(paths.docsTasks, taskId);
+    if (!taskFile) {
+        log.error(`TASK not found: ${taskId} (looked in ${relOrAbs(cwd, paths.docsTasks)})`);
+        process.exitCode = 1;
+        return;
+    }
+    const meta = await readTaskFile(taskFile);
+    const body = await readText(taskFile);
+    log.info(bold(`vibeops task check ${meta.id}`));
+    log.info(`  ${dim("file")}    ${relOrAbs(cwd, taskFile)}`);
+    log.info(`  ${dim("title")}   ${meta.title || dim("(no title)")}`);
+    log.info(`  ${dim("status")}  ${statusDisplay(meta.status)}`);
+    log.blank();
+    log.info(bold("Git"));
+    const git = await readGitInfo(cwd);
+    if (!git.isRepo) {
+        log.info(`  ${red("✗")} not a git repository`);
+        missing++;
+    }
+    else {
+        log.info(`  ${dim("branch")}  ${git.branch ?? dim("(detached)")}`);
+        log.info(`  ${dim("status")}  ${git.dirty ? yellow("dirty") : green("clean")}`);
+    }
+    const ctx = await readGitContext(taskFile);
+    if (ctx === null) {
+        log.info(`  ${yellow("·")} no Git Context section yet — run \`vibeops task start ${meta.id}\` first.`);
+        missing++;
+    }
+    else {
+        log.info(`  ${dim("base")}    ${ctx.baseBranch} @ ${ctx.baseCommit}`);
+        log.info(`  ${dim("task branch")} ${cyan(ctx.taskBranch)}`);
+        log.info(`  ${dim("started at")} ${ctx.startedAt}`);
+        if (git.isRepo) {
+            const range = `${ctx.baseCommit}..HEAD`;
+            const summary = await gitAllChangedFilesSinceTaskStart(ctx.baseCommit, cwd);
+            const ahead = await gitCommitsAhead(cwd, ctx.baseCommit);
+            log.info(`  ${dim("commits ahead")} ${ahead}`);
+            log.info(`  ${dim("working tree changed files")} ${summary.workingTree.length}`);
+            log.info(`  ${dim("committed changed files")} ${summary.committed.length}`);
+            log.info(`  ${dim("total changed files")} ${summary.all.length}`);
+            const recent = await gitLogOneline(cwd, `${range}`);
+            const head = recent.slice(0, 5);
+            if (head.length > 0) {
+                log.info(`  ${dim("recent commits:")}`);
+                for (const c of head)
+                    log.info(`    · ${c.sha}  ${c.message}`);
+            }
+            const expected = findExpectedFiles(body);
+            if (expected.length > 0) {
+                log.blank();
+                log.info(bold("Expected Files to Change vs current diff"));
+                const lower = new Set(summary.all.map((c) => c.toLowerCase()));
+                let hit = 0;
+                for (const e of expected) {
+                    const present = lower.has(e.toLowerCase());
+                    if (present)
+                        hit++;
+                    log.info(`  ${present ? green("✓") : yellow("·")} ${e}${present ? "" : dim(" (not yet in diff)")}`);
+                }
+                log.info(dim(`  match ${hit}/${expected.length} (${Math.round((hit / expected.length) * 100)}%)`));
+                log.info(dim(`  basis: working tree(${summary.workingTree.length}) ∪ committed(${summary.committed.length}) = total(${summary.all.length}) files`));
+            }
+        }
+    }
+    log.blank();
+    log.info(bold("Acceptance Criteria"));
+    const ac = findAcceptanceCriteria(body);
+    if (ac.length === 0) {
+        log.info(`  ${dim("(none parsed — TASK file may not use \"1. …\" list format)")}`);
+    }
+    else {
+        for (let i = 0; i < ac.length; i++) {
+            log.info(`  ${dim(`${i + 1}.`)} ${ac[i]}`);
+        }
+        log.info(dim(`  → confirm each item manually with the diff before \`vibeops task done\`.`));
+    }
+    log.blank();
+    log.info(bold("Docs touched in this round"));
+    const docsChecks = [
+        { label: "current-state (03)", path: join(paths.docsProject, "03-current-state.md"), required: false },
+        { label: "current-state (05)", path: join(paths.docsProject, "05-current-state.md"), required: false },
+        { label: `log (${todayLogFileName()})`, path: join(paths.docsLogs, todayLogFileName()), required: false },
+    ];
+    let anyDoc = false;
+    for (const c of docsChecks) {
+        const present = await pathExists(c.path);
+        if (present)
+            anyDoc = true;
+        log.info(`  ${present ? green("✓") : dim("·")} ${c.label}  ${dim(relOrAbs(cwd, c.path))}`);
+    }
+    if (!anyDoc) {
+        log.info(`  ${yellow("!")} no current-state or today's log file found — Docs Agent must update them before \`task done\`.`);
+        missing++;
+    }
+    log.blank();
+    log.info(bold("TASK Result / Test Result"));
+    const resultOk = hasNonEmptySection(body, "Result");
+    const testResultOk = hasNonEmptySection(body, "Test Result");
+    log.info(`  ${resultOk ? green("✓") : yellow("·")} Result        ${dim(resultOk ? readSection(body, "Result").split("\n")[0]?.slice(0, 80) ?? "" : "(empty / placeholder)")}`);
+    log.info(`  ${testResultOk ? green("✓") : yellow("·")} Test Result   ${dim(testResultOk ? readSection(body, "Test Result").split("\n")[0]?.slice(0, 80) ?? "" : "(empty / placeholder)")}`);
+    if (!resultOk)
+        missing++;
+    if (!testResultOk)
+        missing++;
+    log.blank();
+    log.info(bold("Summary"));
+    if (missing === 0) {
+        log.ok("All checks present. Ready for `vibeops task done`.");
+    }
+    else {
+        log.info(`  ${yellow("!")} ${missing} item(s) need attention before \`vibeops task done\`.`);
+    }
+    log.blank();
+    const promptResult = await buildTaskPromptString({
+        projectRoot: paths.root,
+        agentsDir: paths.vibeopsAgents,
+        agentName,
+        taskFilePath: taskFile,
+    });
+    if (promptResult.ok) {
+        log.info(bold(`Cursor prompt (agent: ${agentName}):`));
+        log.info(dim("─".repeat(60)));
+        log.raw(promptResult.prompt.endsWith("\n") ? promptResult.prompt : `${promptResult.prompt}\n`);
+        log.info(dim("─".repeat(60)));
+    }
+    else {
+        log.info(dim(`(agent "${agentName}" not found — install \`.vibeops/agents/${agentName}.md\` or pass --agent <name>)`));
+    }
+    if (options.strict === true && missing > 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/task-done.js

@@ -0,0 +1,98 @@
+import { relative, resolve } from "node:path";
+import { readText } from "../lib/filesystem.js";
+import { bold, cyan, dim, green, log, yellow } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+import { findTaskFile, hasNonEmptySection, parseTaskFilename, pickNextTask, readGitContext, readTaskFile, scanTasks, statusDisplay, updateInlineStatus, } from "../lib/task.js";
+function relOrAbs(root, p) {
+    const r = relative(root, p);
+    return r === "" ? "." : r.startsWith("..") ? p : r;
+}
+function commitMessageFor(taskId, title, mvpPhase) {
+    const trimmed = (title || taskId).trim();
+    const slug = trimmed.replace(/^TASK-\d+\s*[·:\-]\s*/i, "").trim() || trimmed;
+    const scope = taskId.toLowerCase();
+    const typePrefix = typeof mvpPhase === "string" && /rollback/i.test(mvpPhase) ? "chore" : "feat";
+    return `${typePrefix}(${scope}): ${slug}`;
+}
+export async function taskDoneCommand(taskId, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const taskFile = await findTaskFile(paths.docsTasks, taskId);
+    if (!taskFile) {
+        log.error(`TASK not found: ${taskId} (looked in ${relOrAbs(cwd, paths.docsTasks)})`);
+        process.exitCode = 1;
+        return;
+    }
+    const meta = await readTaskFile(taskFile);
+    const body = await readText(taskFile);
+    log.info(bold(`vibeops task done ${meta.id}`));
+    log.info(`  ${dim("file")}    ${relOrAbs(cwd, taskFile)}`);
+    log.info(`  ${dim("title")}   ${meta.title || dim("(no title)")}`);
+    log.info(`  ${dim("status")}  ${statusDisplay(meta.status)}`);
+    log.blank();
+    const resultOk = hasNonEmptySection(body, "Result");
+    const testResultOk = hasNonEmptySection(body, "Test Result");
+    const docCheck = [
+        ["Result section", resultOk],
+        ["Test Result section", testResultOk],
+    ];
+    log.info(bold("Required sections"));
+    let missing = 0;
+    for (const [label, ok] of docCheck) {
+        if (!ok)
+            missing++;
+        log.info(`  ${ok ? green("✓") : yellow("·")} ${label}${ok ? "" : dim(" (empty or placeholder)")}`);
+    }
+    log.blank();
+    if (missing > 0) {
+        log.error(`${missing} required section(s) still empty. Fill Result / Test Result first, then re-run \`vibeops task done\`.`);
+        process.exitCode = 1;
+        return;
+    }
+    const target = options.finalize === true ? "done" : "review";
+    const targetDisplay = statusDisplay(target);
+    if (options.dryRun === true) {
+        log.info(bold("dry-run — would perform:"));
+        log.info(`  · update Status → ${targetDisplay} in ${relOrAbs(cwd, taskFile)}`);
+        log.info(`  · (no git commit, no Notion call)`);
+        log.blank();
+    }
+    else {
+        await updateInlineStatus(taskFile, target);
+        log.ok(`Status → ${targetDisplay}  (${relOrAbs(cwd, taskFile)})`);
+        log.blank();
+    }
+    const ctx = await readGitContext(taskFile);
+    const parts = parseTaskFilename(taskFile);
+    const commitMsg = commitMessageFor(parts.id, meta.title, meta.mvpPhase);
+    log.info(bold("Suggested commit"));
+    log.info(`  ${cyan(`git add -A && git commit -m "${commitMsg}"`)}`);
+    if (ctx !== null) {
+        log.info(`  ${dim(`after commit on ${ctx.taskBranch}: open PR or run \`git switch ${ctx.baseBranch} && git merge --no-ff ${ctx.taskBranch}\``)}`);
+    }
+    else {
+        log.info(`  ${dim("(no Git Context section — skipping merge guidance)")}`);
+    }
+    log.blank();
+    log.info(bold("Notion"));
+    log.info(`  ${dim("TODO: run `vibeops notion sync` to push this TASK metadata.")}`);
+    log.blank();
+    const all = await scanTasks(paths.docsTasks);
+    const next = pickNextTask(all.filter((t) => t.id.toUpperCase() !== meta.id.toUpperCase()));
+    log.info(bold("Next TASK candidate"));
+    if (next) {
+        log.info(`  → ${cyan(next.id)} — ${next.title || dim("(no title)")}  ${dim(`[${statusDisplay(next.status)}]`)}`);
+        log.info(`    file: ${dim(relOrAbs(cwd, next.filePath))}`);
+        log.info(`    start: ${dim(`vibeops task start ${next.id}`)}`);
+    }
+    else {
+        log.info(`  ${dim("(no remaining planned / in-progress / review TASK)")}`);
+    }
+    log.blank();
+    if (target === "review") {
+        log.info(`Status moved to ${cyan("Review")}. After human or Reviewer Agent review, finalize with ${cyan(`vibeops task done ${meta.id} --finalize`)}.`);
+    }
+    else {
+        log.ok(`${meta.id} finalized → Done.`);
+    }
+}

package/dist/commands/task-generate.js

@@ -0,0 +1,206 @@
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { pathExists, writeText } from "../lib/filesystem.js";
+import { bold, cyan, dim, log, yellow } from "../lib/logger.js";
+import { projectPaths } from "../lib/paths.js";
+import { collectInputDocs, } from "../lib/project-docs.js";
+import { formatTaskId, nextTaskNumber } from "../lib/task.js";
+import { buildTaskGeneratePrompt, } from "../lib/task-generator.js";
+import { planScaffoldEntries, renderScaffoldMarkdown, writeScaffoldFiles, } from "../lib/task-scaffold.js";
+import { VERSION } from "../version.js";
+const DEFAULT_PROMPT_REL = ".vibeops/generated/task-generate-prompt.md";
+const DEFAULT_COUNT = 8;
+const COUNT_SOFT_CAP = 20;
+const BRIEF_REL = ".vibeops/brief/project-brief.md";
+function toAbsolute(root, candidate) {
+    return isAbsolute(candidate) ? candidate : resolve(root, candidate);
+}
+function relDisplay(root, abs) {
+    const r = relative(root, abs);
+    return r.length === 0 ? "." : r;
+}
+function parseCount(raw) {
+    if (raw === undefined)
+        return { count: DEFAULT_COUNT, warning: false };
+    const n = typeof raw === "number" ? raw : Number.parseInt(String(raw).trim(), 10);
+    if (!Number.isFinite(n) || n <= 0) {
+        return {
+            count: DEFAULT_COUNT,
+            warning: false,
+            error: `--count must be a positive integer (got: "${String(raw)}"). Falling back to default ${DEFAULT_COUNT}.`,
+        };
+    }
+    return { count: Math.floor(n), warning: n > COUNT_SOFT_CAP };
+}
+function presentInventory(docs) {
+    const present = [];
+    const missing = [];
+    if (docs.from)
+        (docs.from.content !== null ? present : missing).push(docs.from);
+    for (const slot of docs.slots)
+        (slot.content !== null ? present : missing).push(slot);
+    if (docs.brief.content !== null)
+        present.push(docs.brief);
+    else
+        missing.push(docs.brief);
+    return { present, missing };
+}
+export async function taskGenerateCommand(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const paths = projectPaths(cwd);
+    const dryRun = options.dryRun === true;
+    const scaffold = options.scaffold === true;
+    const briefAbs = join(cwd, BRIEF_REL);
+    const parsedCount = parseCount(options.count);
+    if (parsedCount.error)
+        log.warn(parsedCount.error);
+    const count = parsedCount.count;
+    const countWarning = parsedCount.warning;
+    if (countWarning) {
+        log.warn(`--count ${count} is large (soft cap ${COUNT_SOFT_CAP}). Continuing, but the Planner Agent may push back.`);
+    }
+    const fromAbs = options.from ? toAbsolute(cwd, options.from) : undefined;
+    if (typeof fromAbs === "string" && !(await pathExists(fromAbs))) {
+        log.error(`--from path not found: ${fromAbs}`);
+        log.info(`If you meant a relative path, run from the project root or pass --cwd <path>.`);
+        process.exitCode = 1;
+        return;
+    }
+    log.info(bold(scaffold ? "vibeops task generate --scaffold" : "vibeops task generate"));
+    log.info(`  ${dim("cwd")}        ${cwd}`);
+    log.info(`  ${dim("mode")}       ${scaffold ? "scaffold (write skeleton TASK files)" : "prompt (build Cursor prompt)"}`);
+    if (options.phase)
+        log.info(`  ${dim("phase")}      ${options.phase}`);
+    log.info(`  ${dim("count")}      ${count}${countWarning ? yellow("  (above soft cap)") : ""}`);
+    if (fromAbs)
+        log.info(`  ${dim("--from")}     ${relDisplay(cwd, fromAbs)}`);
+    if (dryRun)
+        log.info(`  ${dim("dry-run")}    on (no file writes)`);
+    log.blank();
+    if (scaffold) {
+        await runScaffold({
+            tasksDir: paths.docsTasks,
+            cwd,
+            count,
+            phase: options.phase,
+            dryRun,
+        });
+        return;
+    }
+    await runPromptMode({
+        cwd,
+        paths,
+        options,
+        fromAbs,
+        briefAbs,
+        count,
+        countWarning,
+        dryRun,
+    });
+}
+async function runPromptMode(inputs) {
+    const { cwd, paths, options, fromAbs, briefAbs, count, countWarning, dryRun } = inputs;
+    const promptAbs = typeof options.output === "string"
+        ? toAbsolute(cwd, options.output)
+        : join(cwd, DEFAULT_PROMPT_REL);
+    const docs = await collectInputDocs({ cwd, fromPath: options.from, fromAbs, briefAbs });
+    const { present, missing } = presentInventory(docs);
+    log.info(bold("Input documents"));
+    for (const s of present)
+        log.info(`  ${cyan("✓")} ${relDisplay(cwd, s.path)}  ${dim(`(${s.label})`)}`);
+    for (const s of missing)
+        log.info(`  ${dim("·")} ${relDisplay(cwd, s.path)}  ${dim(`(${s.label} — missing)`)}`);
+    log.blank();
+    const nextNum = await nextTaskNumber(paths.docsTasks);
+    const nextId = formatTaskId(nextNum);
+    log.info(bold("Plan"));
+    log.info(`  ${dim("next TASK id")}   ${nextId}`);
+    log.info(`  ${dim("prompt output")}  ${relDisplay(cwd, promptAbs)}`);
+    log.blank();
+    if (dryRun) {
+        log.info(bold("dry-run — would perform:"));
+        log.info(`  · read ${present.length} input doc(s) (skipped ${missing.length} missing slot${missing.length === 1 ? "" : "s"})`);
+        log.info(`  · build Cursor prompt for ~${count} TASK starting at ${nextId}`);
+        log.info(`  · write prompt to ${relDisplay(cwd, promptAbs)}`);
+        log.info(`  · no LLM / Cursor / Notion / GitHub / Git call`);
+        log.blank();
+        log.info(dim("no files were written."));
+        return;
+    }
+    const promptInputs = {
+        cwd,
+        vibeopsVersion: VERSION,
+        generatedAt: new Date().toISOString(),
+        nextTaskId: nextId,
+        count,
+        outputPath: promptAbs,
+        outputRelative: relDisplay(cwd, promptAbs),
+        docs,
+        countWarning,
+        ...(typeof options.phase === "string" && options.phase.length > 0
+            ? { phase: options.phase }
+            : {}),
+    };
+    const md = buildTaskGeneratePrompt(promptInputs);
+    await writeText(promptAbs, md);
+    log.ok(`Cursor task-generate prompt: ${relDisplay(cwd, promptAbs)}`);
+    log.blank();
+    log.info(bold("Next steps"));
+    log.info(`  1) Open a new Cursor chat and paste the full contents of ${cyan(relDisplay(cwd, promptAbs))}.`);
+    log.info(`  2) Review the Planner Agent's \`docs/tasks/TASK-NNN-*.md\` files with \`git diff\` and commit.`);
+    log.info(`  3) Start the first new TASK with ${cyan(`vibeops task start ${nextId}`)}.`);
+    if (missing.length > 0) {
+        log.blank();
+        log.info(`${yellow("!")} ${missing.length} input slot(s) are missing on disk. The Planner Agent will see them as "missing"; decide whether to fill them this round.`);
+    }
+}
+async function runScaffold(inputs) {
+    const plan = await planScaffoldEntries({
+        tasksDir: inputs.tasksDir,
+        count: inputs.count,
+        ...(typeof inputs.phase === "string" && inputs.phase.length > 0
+            ? { phase: inputs.phase }
+            : {}),
+    });
+    log.info(bold("Scaffold plan"));
+    log.info(`  ${dim("start at")}  ${formatTaskId(plan.startNumber)}`);
+    log.info(`  ${dim("count")}     ${plan.entries.length}`);
+    log.blank();
+    log.info(bold("Files to create"));
+    for (const e of plan.entries) {
+        log.info(`  · ${relDisplay(inputs.cwd, e.absPath)}  ${dim(`(${e.phase})`)}`);
+    }
+    log.blank();
+    if (inputs.dryRun) {
+        log.info(dim("dry-run — no files were written."));
+        log.info(`Skeleton preview (first entry, ${plan.entries[0]?.id ?? "TASK-???"}):`);
+        log.blank();
+        log.info(dim("─".repeat(60)));
+        log.raw(renderScaffoldMarkdown(plan.entries[0] ?? fallbackPreviewEntry(plan.startNumber, inputs.phase)));
+        log.info(dim("─".repeat(60)));
+        return;
+    }
+    const written = await writeScaffoldFiles(plan);
+    for (const abs of written)
+        log.ok(`created   ${relDisplay(inputs.cwd, abs)}`);
+    if (written.length < plan.entries.length) {
+        const skipped = plan.entries.length - written.length;
+        log.warn(`${skipped} planned file(s) already existed and were skipped (won't overwrite).`);
+    }
+    log.blank();
+    log.info(bold("Next steps"));
+    log.info(`  1) Fill the empty sections of each scaffolded TASK file (in Cursor, via the Planner or Architect Agent).`);
+    log.info(`  2) After filling, run \`git add docs/tasks/ && git commit\`.`);
+    log.info(`  3) Start the first TASK with ${cyan(`vibeops task start ${plan.entries[0]?.id ?? "TASK-???"}`)}.`);
+}
+function fallbackPreviewEntry(start, phase) {
+    const id = formatTaskId(start);
+    return {
+        id,
+        number: start,
+        slug: "planned-task",
+        title: "(scaffolded TASK — fill in)",
+        fileName: `${id}-planned-task.md`,
+        absPath: `${id}-planned-task.md`,
+        phase: phase ?? "(unassigned)",
+    };
+}