agentplane 0.2.6 → 0.2.12

package/dist/commands/release/plan.command.js

@@ -0,0 +1,206 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveProject } from "@agentplaneorg/core";
+import { usageError } from "../../cli/spec/errors.js";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { CliError } from "../../shared/errors.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+function parseSemver(version) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
+    if (!m)
+        return null;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const patch = Number(m[3]);
+    if (![major, minor, patch].every((n) => Number.isInteger(n) && n >= 0))
+        return null;
+    return { major, minor, patch };
+}
+function bumpVersion(version, bump) {
+    const parsed = parseSemver(version);
+    if (!parsed) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Invalid version (expected X.Y.Z): ${version}`,
+        });
+    }
+    if (bump === "patch")
+        return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+    if (bump === "minor")
+        return `${parsed.major}.${parsed.minor + 1}.0`;
+    return `${parsed.major + 1}.0.0`;
+}
+async function readPackageVersion(pkgJsonPath) {
+    const raw = JSON.parse(await readFile(pkgJsonPath, "utf8"));
+    const version = typeof raw.version === "string" ? raw.version.trim() : "";
+    if (!version) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Missing package.json version: ${pkgJsonPath}`,
+        });
+    }
+    return version;
+}
+async function getLatestSemverTag(gitRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["describe", "--tags", "--abbrev=0", "--match", "v[0-9]*.[0-9]*.[0-9]*"], { cwd: gitRoot, env: gitEnv() });
+        const tag = String(stdout ?? "").trim();
+        return tag || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function listChanges(gitRoot, sinceRef) {
+    const range = sinceRef ? `${sinceRef}..HEAD` : "HEAD";
+    const { stdout } = await execFileAsync("git", ["log", "--no-merges", "--pretty=format:%H%x00%aI%x00%s", range], { cwd: gitRoot, env: gitEnv(), maxBuffer: 10 * 1024 * 1024 });
+    const text = String(stdout ?? "");
+    const lines = text.split("\n").filter((l) => l.length > 0);
+    const out = [];
+    for (const line of lines) {
+        const parts = line.split("\0");
+        const hash = (parts[0] ?? "").trim();
+        const authorDateIso = (parts[1] ?? "").trim();
+        const subject = (parts[2] ?? "").trim();
+        if (!hash || !authorDateIso || !subject)
+            continue;
+        out.push({ hash, authorDateIso, subject });
+    }
+    return out;
+}
+function changesMarkdown(changes) {
+    if (changes.length === 0)
+        return "_No commits found in the selected range._\n";
+    return (changes
+        .map((c) => `- ${c.subject} (${c.hash.slice(0, 7)})`)
+        .join("\n")
+        .trim() + "\n");
+}
+function releaseInstructions(opts) {
+    return (`# Release plan\n\n` +
+        `## Target\n\n` +
+        `- Tag: \`${opts.nextTag}\`\n` +
+        (opts.prevTag
+            ? `- Since: \`${opts.prevTag}\`\n`
+            : "- Since: (no previous semver tag found)\n") +
+        `- Bump: \`${opts.bump}\`\n\n` +
+        `## Agent task: write release notes\n\n` +
+        `Write English release notes as \`docs/releases/${opts.nextTag}.md\`.\n\n` +
+        `Rules:\n` +
+        `- Use human-readable bullets focused on outcomes and user-facing improvements.\n` +
+        `- Minimum: 3 bullet points.\n` +
+        `- Do not include Cyrillic.\n` +
+        `- Use \`docs/releases/TEMPLATE.md\` as the structure.\n\n` +
+        `Inputs:\n` +
+        `- \`changes.md\` and \`changes.json\` in this directory.\n`);
+}
+export const releasePlanSpec = {
+    id: ["release", "plan"],
+    group: "Release",
+    summary: "Generate an agent-assisted release plan (changes list + next patch version).",
+    description: "Generates a structured changes list since the last semver tag and writes a plan directory under .agentplane/.release/. This plan is intended for a DOCS agent to author release notes. By default, only patch bumps are allowed without explicit approval.",
+    options: [
+        {
+            kind: "boolean",
+            name: "patch",
+            default: false,
+            description: "Bump patch version (default).",
+        },
+        {
+            kind: "boolean",
+            name: "minor",
+            default: false,
+            description: "Bump minor version (requires --yes).",
+        },
+        {
+            kind: "boolean",
+            name: "major",
+            default: false,
+            description: "Bump major version (requires --yes).",
+        },
+        {
+            kind: "string",
+            name: "since",
+            valueHint: "<tag>",
+            description: "Override the starting tag/ref (defaults to the latest vX.Y.Z tag).",
+        },
+        {
+            kind: "boolean",
+            name: "yes",
+            default: false,
+            description: "Approve minor/major version bumps (required for --minor/--major).",
+        },
+    ],
+    validateRaw: (raw) => {
+        const count = [
+            raw.opts.patch === true,
+            raw.opts.minor === true,
+            raw.opts.major === true,
+        ].filter(Boolean).length;
+        if (count > 1) {
+            throw usageError({
+                spec: releasePlanSpec,
+                command: "release plan",
+                message: "Options --patch/--minor/--major are mutually exclusive.",
+            });
+        }
+    },
+    parse: (raw) => {
+        const bump = raw.opts.major === true ? "major" : raw.opts.minor === true ? "minor" : "patch";
+        return { bump, since: raw.opts.since, yes: raw.opts.yes === true };
+    },
+    validate: (p) => {
+        if ((p.bump === "minor" || p.bump === "major") && p.yes !== true) {
+            throw usageError({
+                spec: releasePlanSpec,
+                command: "release plan",
+                message: `Bump '${p.bump}' requires explicit approval. Re-run with --yes.`,
+            });
+        }
+    },
+    examples: [
+        {
+            cmd: "agentplane release plan",
+            why: "Generate a plan for the next patch release and hand it to a DOCS agent to write release notes.",
+        },
+        {
+            cmd: "agentplane release plan --minor --yes",
+            why: "Generate a plan for the next minor release (explicit approval required).",
+        },
+    ],
+};
+export const runReleasePlan = async (ctx, flags) => {
+    const resolved = await resolveProject({ cwd: ctx.cwd, rootOverride: ctx.rootOverride ?? null });
+    const gitRoot = resolved.gitRoot;
+    const corePkgPath = path.join(gitRoot, "packages", "core", "package.json");
+    const agentplanePkgPath = path.join(gitRoot, "packages", "agentplane", "package.json");
+    const [coreVersion, agentplaneVersion] = await Promise.all([
+        readPackageVersion(corePkgPath),
+        readPackageVersion(agentplanePkgPath),
+    ]);
+    if (coreVersion !== agentplaneVersion) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Package versions must match before release planning. ` +
+                `packages/core=${coreVersion} packages/agentplane=${agentplaneVersion}`,
+        });
+    }
+    const prevTag = flags.since ?? (await getLatestSemverTag(gitRoot));
+    const nextVersion = bumpVersion(coreVersion, flags.bump);
+    const nextTag = `v${nextVersion}`;
+    const changes = await listChanges(gitRoot, prevTag);
+    const runId = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    const baseDir = path.join(gitRoot, ".agentplane", ".release", "plan", runId);
+    await mkdir(baseDir, { recursive: true });
+    await writeFile(path.join(baseDir, "version.json"), JSON.stringify({ prevTag, prevVersion: coreVersion, nextTag, nextVersion, bump: flags.bump }, null, 2) + "\n", "utf8");
+    await writeFile(path.join(baseDir, "changes.json"), JSON.stringify(changes, null, 2) + "\n", "utf8");
+    await writeFile(path.join(baseDir, "changes.md"), changesMarkdown(changes), "utf8");
+    await writeFile(path.join(baseDir, "instructions.md"), releaseInstructions({ nextTag, prevTag, bump: flags.bump }), "utf8");
+    process.stdout.write(`Release plan written: ${path.relative(gitRoot, baseDir)}\n`);
+    process.stdout.write(`Next tag: ${nextTag}\n`);
+    process.stdout.write(`Hint: Create a DOCS task to write docs/releases/${nextTag}.md based on this plan.\n`);
+    return 0;
+};

package/dist/commands/release/release.command.d.ts

@@ -0,0 +1,5 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type ReleaseGroupParsed = Record<string, never>;
+export declare const releaseSpec: CommandSpec<ReleaseGroupParsed>;
+export declare const runRelease: CommandHandler<ReleaseGroupParsed>;
+//# sourceMappingURL=release.command.d.ts.map

package/dist/commands/release/release.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/release.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEvD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAYvD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAGzD,CAAC"}

package/dist/commands/release/release.command.js

@@ -0,0 +1,18 @@
+import { usageError } from "../../cli/spec/errors.js";
+export const releaseSpec = {
+    id: ["release"],
+    group: "Release",
+    summary: "Prepare a release (agent-assisted notes + version bump workflow).",
+    synopsis: ["agentplane release <command> [args] [options]"],
+    validateRaw: (raw) => {
+        if (raw.extra.length > 0) {
+            throw usageError({ spec: releaseSpec, message: `Unknown subcommand: ${raw.extra[0]}` });
+        }
+        throw usageError({ spec: releaseSpec, message: "Missing subcommand." });
+    },
+    parse: () => ({}),
+};
+export const runRelease = () => {
+    // Unreachable (validateRaw always throws).
+    return Promise.resolve(2);
+};

package/dist/commands/shared/task-backend.d.ts

@@ -4,6 +4,7 @@ export type CommandMemo = {
     taskList?: Promise<TaskData[]>;
     changedPaths?: Promise<string[]>;
     headCommit?: Promise<string>;
+    agentIds?: Promise<string[]>;
 };
 export type CommandContext = {
     resolvedProject: Awaited<ReturnType<typeof loadTaskBackend>>["resolved"];

package/dist/commands/shared/task-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACzE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9D,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,UAAU,CAAC;IAEhB,IAAI,EAAE,WAAW,CAAC;IAGlB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;CACxC,CAAC;AASF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+B7E;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAepB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC,CAaD;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAG5E"}
+{"version":3,"file":"task-backend.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACzE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9D,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,UAAU,CAAC;IAEhB,IAAI,EAAE,WAAW,CAAC;IAGlB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;CACxC,CAAC;AASF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+B7E;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAepB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC,CAaD;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAG5E"}

package/dist/commands/start.command.d.ts

@@ -1,19 +1,4 @@
-import type { CommandCtx, CommandSpec } from "../cli/spec/spec.js";
-import type { CommandContext } from "./shared/task-backend.js";
-export type StartParsed = {
-    taskId: string;
-    author: string;
-    body: string;
-    commitFromComment: boolean;
-    commitEmoji?: string;
-    commitAllow: string[];
-    commitAutoAllow: boolean;
-    commitAllowTasks: boolean;
-    commitRequireClean: boolean;
-    confirmStatusCommit: boolean;
-    force: boolean;
-    quiet: boolean;
-};
-export declare const startSpec: CommandSpec<StartParsed>;
-export declare function makeRunStartHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: StartParsed) => Promise<number>;
+export { startSpec } from "./start.spec.js";
+export type { StartParsed } from "./start.spec.js";
+export { makeRunStartHandler } from "./start.run.js";
 //# sourceMappingURL=start.command.d.ts.map

package/dist/commands/start.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.command.d.ts","sourceRoot":"","sources":["../../src/commands/start.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAQF,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,WAAW,CAmH9C,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACpE,KAAK,UAAU,EAAE,GAAG,WAAW,KAAG,OAAO,CAAC,MAAM,CAAC,CAmBhE"}
+{"version":3,"file":"start.command.d.ts","sourceRoot":"","sources":["../../src/commands/start.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/commands/start.command.js

@@ -1,143 +1,2 @@
-import { usageError } from "../cli/spec/errors.js";
-import { cmdStart } from "./task/start.js";
-function toStringList(v) {
-    if (typeof v === "string")
-        return [v];
-    if (Array.isArray(v))
-        return v.filter((x) => typeof x === "string");
-    return [];
-}
-export const startSpec = {
-    id: ["start"],
-    group: "Lifecycle",
-    summary: "Transition a task to DOING and record a structured Start comment.",
-    args: [
-        {
-            name: "task-id",
-            required: true,
-            valueHint: "<task-id>",
-            description: "Existing task id.",
-        },
-    ],
-    options: [
-        {
-            kind: "string",
-            name: "author",
-            valueHint: "<id>",
-            required: true,
-            description: "Comment author id (e.g. CODER).",
-        },
-        {
-            kind: "string",
-            name: "body",
-            valueHint: "<text>",
-            required: true,
-            description: "Structured comment body (must match the configured Start: prefix).",
-        },
-        {
-            kind: "boolean",
-            name: "commit-from-comment",
-            default: false,
-            description: "Create a status commit using the comment body.",
-        },
-        {
-            kind: "string",
-            name: "commit-emoji",
-            valueHint: "<emoji>",
-            description: "Override the status commit emoji (used with --commit-from-comment).",
-        },
-        {
-            kind: "string",
-            name: "commit-allow",
-            valueHint: "<path-prefix>",
-            repeatable: true,
-            description: "Repeatable. Allowlist path prefixes to stage for the status commit (used with --commit-from-comment).",
-        },
-        {
-            kind: "boolean",
-            name: "commit-auto-allow",
-            default: false,
-            description: "Auto-allow inferred allowlist paths if none are provided (used with --commit-from-comment).",
-        },
-        {
-            kind: "boolean",
-            name: "commit-allow-tasks",
-            default: true,
-            hidden: true,
-            description: "Deprecated. Tasks are always allowed for status commits.",
-            deprecated: "no-op",
-        },
-        {
-            kind: "boolean",
-            name: "commit-require-clean",
-            default: false,
-            description: "Require a clean working tree for the status commit (used with --commit-from-comment).",
-        },
-        {
-            kind: "boolean",
-            name: "confirm-status-commit",
-            default: false,
-            description: "Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment).",
-        },
-        {
-            kind: "boolean",
-            name: "force",
-            default: false,
-            description: "Override readiness checks and status transition restrictions.",
-        },
-        { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
-    ],
-    examples: [
-        {
-            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI"',
-            why: "Start work on a task.",
-        },
-        {
-            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI" --commit-from-comment --commit-allow packages/agentplane/src',
-            why: "Start work and create a status commit from the comment.",
-        },
-    ],
-    validateRaw: (raw) => {
-        const author = typeof raw.opts.author === "string" ? raw.opts.author.trim() : "";
-        const body = typeof raw.opts.body === "string" ? raw.opts.body.trim() : "";
-        if (!author)
-            throw usageError({ spec: startSpec, message: "Invalid value for --author: empty." });
-        if (!body)
-            throw usageError({ spec: startSpec, message: "Invalid value for --body: empty." });
-    },
-    parse: (raw) => ({
-        taskId: typeof raw.args["task-id"] === "string" ? raw.args["task-id"] : "",
-        author: raw.opts.author,
-        body: raw.opts.body,
-        commitFromComment: raw.opts["commit-from-comment"] === true,
-        commitEmoji: raw.opts["commit-emoji"],
-        commitAllow: toStringList(raw.opts["commit-allow"]),
-        commitAutoAllow: raw.opts["commit-auto-allow"] === true,
-        commitAllowTasks: raw.opts["commit-allow-tasks"] !== false,
-        commitRequireClean: raw.opts["commit-require-clean"] === true,
-        confirmStatusCommit: raw.opts["confirm-status-commit"] === true,
-        force: raw.opts.force === true,
-        quiet: raw.opts.quiet === true,
-    }),
-};
-export function makeRunStartHandler(getCtx) {
-    return async (ctx, p) => {
-        return await cmdStart({
-            ctx: await getCtx("start"),
-            cwd: ctx.cwd,
-            rootOverride: ctx.rootOverride,
-            taskId: p.taskId,
-            author: p.author,
-            body: p.body,
-            commitFromComment: p.commitFromComment,
-            commitEmoji: p.commitEmoji,
-            commitAllow: p.commitAllow,
-            commitAutoAllow: p.commitAutoAllow,
-            commitAllowTasks: p.commitAllowTasks,
-            commitRequireClean: p.commitRequireClean,
-            confirmStatusCommit: p.confirmStatusCommit,
-            force: p.force,
-            quiet: p.quiet,
-        });
-    };
-}
+export { startSpec } from "./start.spec.js";
+export { makeRunStartHandler } from "./start.run.js";

package/dist/commands/start.run.d.ts

@@ -0,0 +1,5 @@
+import type { CommandCtx } from "../cli/spec/spec.js";
+import type { CommandContext } from "./shared/task-backend.js";
+import type { StartParsed } from "./start.spec.js";
+export declare function makeRunStartHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: StartParsed) => Promise<number>;
+//# sourceMappingURL=start.run.d.ts.map

package/dist/commands/start.run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.run.d.ts","sourceRoot":"","sources":["../../src/commands/start.run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACpE,KAAK,UAAU,EAAE,GAAG,WAAW,KAAG,OAAO,CAAC,MAAM,CAAC,CAmBhE"}

package/dist/commands/start.run.js

@@ -0,0 +1,22 @@
+import { cmdStart } from "./task/start.js";
+export function makeRunStartHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdStart({
+            ctx: await getCtx("start"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            taskId: p.taskId,
+            author: p.author,
+            body: p.body,
+            commitFromComment: p.commitFromComment,
+            commitEmoji: p.commitEmoji,
+            commitAllow: p.commitAllow,
+            commitAutoAllow: p.commitAutoAllow,
+            commitAllowTasks: p.commitAllowTasks,
+            commitRequireClean: p.commitRequireClean,
+            confirmStatusCommit: p.confirmStatusCommit,
+            force: p.force,
+            quiet: p.quiet,
+        });
+    };
+}

package/dist/commands/start.spec.d.ts

@@ -0,0 +1,17 @@
+import type { CommandSpec } from "../cli/spec/spec.js";
+export type StartParsed = {
+    taskId: string;
+    author: string;
+    body: string;
+    commitFromComment: boolean;
+    commitEmoji?: string;
+    commitAllow: string[];
+    commitAutoAllow: boolean;
+    commitAllowTasks: boolean;
+    commitRequireClean: boolean;
+    confirmStatusCommit: boolean;
+    force: boolean;
+    quiet: boolean;
+};
+export declare const startSpec: CommandSpec<StartParsed>;
+//# sourceMappingURL=start.spec.d.ts.map

package/dist/commands/start.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.spec.d.ts","sourceRoot":"","sources":["../../src/commands/start.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,WAAW,CAmH9C,CAAC"}

package/dist/commands/start.spec.js

@@ -0,0 +1,115 @@
+import { usageError } from "../cli/spec/errors.js";
+import { toStringList } from "../cli/spec/parse-utils.js";
+export const startSpec = {
+    id: ["start"],
+    group: "Lifecycle",
+    summary: "Transition a task to DOING and record a structured Start comment.",
+    args: [
+        {
+            name: "task-id",
+            required: true,
+            valueHint: "<task-id>",
+            description: "Existing task id.",
+        },
+    ],
+    options: [
+        {
+            kind: "string",
+            name: "author",
+            valueHint: "<id>",
+            required: true,
+            description: "Comment author id (e.g. CODER).",
+        },
+        {
+            kind: "string",
+            name: "body",
+            valueHint: "<text>",
+            required: true,
+            description: "Structured comment body (must match the configured Start: prefix).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-from-comment",
+            default: false,
+            description: "Create a status commit using the comment body.",
+        },
+        {
+            kind: "string",
+            name: "commit-emoji",
+            valueHint: "<emoji>",
+            description: "Override the status commit emoji (used with --commit-from-comment).",
+        },
+        {
+            kind: "string",
+            name: "commit-allow",
+            valueHint: "<path-prefix>",
+            repeatable: true,
+            description: "Repeatable. Allowlist path prefixes to stage for the status commit (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-auto-allow",
+            default: false,
+            description: "Auto-allow inferred allowlist paths if none are provided (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "commit-allow-tasks",
+            default: true,
+            hidden: true,
+            description: "Deprecated. Tasks are always allowed for status commits.",
+            deprecated: "no-op",
+        },
+        {
+            kind: "boolean",
+            name: "commit-require-clean",
+            default: false,
+            description: "Require a clean working tree for the status commit (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "confirm-status-commit",
+            default: false,
+            description: "Confirm status commit creation when status_commit_policy=confirm (used with --commit-from-comment).",
+        },
+        {
+            kind: "boolean",
+            name: "force",
+            default: false,
+            description: "Override readiness checks and status transition restrictions.",
+        },
+        { kind: "boolean", name: "quiet", default: false, description: "Suppress output." },
+    ],
+    examples: [
+        {
+            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI"',
+            why: "Start work on a task.",
+        },
+        {
+            cmd: 'agentplane start 202602030608-F1Q8AB --author CODER --body "Start: implement spec-driven CLI" --commit-from-comment --commit-allow packages/agentplane/src',
+            why: "Start work and create a status commit from the comment.",
+        },
+    ],
+    validateRaw: (raw) => {
+        const author = typeof raw.opts.author === "string" ? raw.opts.author.trim() : "";
+        const body = typeof raw.opts.body === "string" ? raw.opts.body.trim() : "";
+        if (!author)
+            throw usageError({ spec: startSpec, message: "Invalid value for --author: empty." });
+        if (!body)
+            throw usageError({ spec: startSpec, message: "Invalid value for --body: empty." });
+    },
+    parse: (raw) => ({
+        taskId: typeof raw.args["task-id"] === "string" ? raw.args["task-id"] : "",
+        author: raw.opts.author,
+        body: raw.opts.body,
+        commitFromComment: raw.opts["commit-from-comment"] === true,
+        commitEmoji: raw.opts["commit-emoji"],
+        commitAllow: toStringList(raw.opts["commit-allow"]),
+        commitAutoAllow: raw.opts["commit-auto-allow"] === true,
+        commitAllowTasks: raw.opts["commit-allow-tasks"] !== false,
+        commitRequireClean: raw.opts["commit-require-clean"] === true,
+        confirmStatusCommit: raw.opts["confirm-status-commit"] === true,
+        force: raw.opts.force === true,
+        quiet: raw.opts.quiet === true,
+    }),
+};

package/dist/commands/task/add.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/add.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAQF,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAmIlD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACtE,KAAK,UAAU,EAAE,GAAG,aAAa,KAAG,OAAO,CAAC,MAAM,CAAC,CAkBlE"}
+{"version":3,"file":"add.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/add.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAmIlD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACtE,KAAK,UAAU,EAAE,GAAG,aAAa,KAAG,OAAO,CAAC,MAAM,CAAC,CAkBlE"}

package/dist/commands/task/add.command.js

@@ -1,13 +1,7 @@
 import { usageError } from "../../cli/spec/errors.js";
+import { toStringList } from "../../cli/spec/parse-utils.js";
 import { cmdTaskAdd } from "./add.js";
 import { normalizeDependsOnInput } from "./shared.js";
-function toStringList(v) {
-    if (typeof v === "string")
-        return [v];
-    if (Array.isArray(v))
-        return v.filter((x) => typeof x === "string");
-    return [];
-}
 export const taskAddSpec = {
     id: ["task", "add"],
     group: "Task",

package/dist/commands/task/derive.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAQF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAqExD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAarE"}
+{"version":3,"file":"derive.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/derive.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAqExD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACzE,KAAK,UAAU,EAAE,GAAG,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAAC,CAarE"}

package/dist/commands/task/derive.command.js

@@ -1,12 +1,6 @@
 import { usageError } from "../../cli/spec/errors.js";
+import { toStringList } from "../../cli/spec/parse-utils.js";
 import { cmdTaskDerive } from "./derive.js";
-function toStringList(v) {
-    if (typeof v === "string")
-        return [v];
-    if (Array.isArray(v))
-        return v.filter((x) => typeof x === "string");
-    return [];
-}
 export const taskDeriveSpec = {
     id: ["task", "derive"],
     group: "Task",