agentplane 0.1.8 → 0.2.0

package/dist/commands/task/scaffold.command.d.ts

@@ -0,0 +1,12 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import type { CommandContext } from "../shared/task-backend.js";
+export type TaskScaffoldParsed = {
+    taskId: string;
+    title?: string;
+    overwrite: boolean;
+    force: boolean;
+    quiet: boolean;
+};
+export declare const taskScaffoldSpec: CommandSpec<TaskScaffoldParsed>;
+export declare function makeRunTaskScaffoldHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskScaffoldParsed) => Promise<number>;
+//# sourceMappingURL=scaffold.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scaffold.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,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAwD5D,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC3E,KAAK,UAAU,EAAE,GAAG,kBAAkB,KAAG,OAAO,CAAC,MAAM,CAAC,CAYvE"}

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

@@ -0,0 +1,73 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { cmdTaskScaffold } from "./scaffold.js";
+export const taskScaffoldSpec = {
+    id: ["task", "scaffold"],
+    group: "Task",
+    summary: "Write a task README file scaffold (for the current doc template).",
+    args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
+    options: [
+        {
+            kind: "string",
+            name: "title",
+            valueHint: "<text>",
+            description: "Optional. Title used when scaffolding a missing task with --force.",
+        },
+        {
+            kind: "boolean",
+            name: "overwrite",
+            default: false,
+            description: "Overwrite an existing README.md if it already exists.",
+        },
+        {
+            kind: "boolean",
+            name: "force",
+            default: false,
+            description: "Allow scaffolding even if the task is missing from the backend.",
+        },
+        {
+            kind: "boolean",
+            name: "quiet",
+            default: false,
+            description: "Suppress normal output (still prints errors).",
+        },
+    ],
+    examples: [
+        {
+            cmd: "agentplane task scaffold 202602030608-F1Q8AB",
+            why: "Write README.md from the existing task data.",
+        },
+        {
+            cmd: 'agentplane task scaffold 202602030608-F1Q8AB --overwrite --title "My task" --force',
+            why: "Overwrite README.md and allow missing task (uses --title).",
+        },
+    ],
+    validateRaw: (raw) => {
+        const title = raw.opts.title;
+        if (typeof title === "string" && title.trim() === "") {
+            throw usageError({ spec: taskScaffoldSpec, message: "Invalid value for --title: empty." });
+        }
+    },
+    parse: (raw) => {
+        return {
+            taskId: String(raw.args["task-id"]),
+            title: typeof raw.opts.title === "string" ? raw.opts.title : undefined,
+            overwrite: raw.opts.overwrite === true,
+            force: raw.opts.force === true,
+            quiet: raw.opts.quiet === true,
+        };
+    },
+};
+export function makeRunTaskScaffoldHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdTaskScaffold({
+            ctx: await getCtx("task scaffold"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            taskId: p.taskId,
+            title: p.title,
+            overwrite: p.overwrite,
+            force: p.force,
+            quiet: p.quiet,
+        });
+    };
+}

package/dist/commands/task/scaffold.d.ts

@@ -1,8 +1,12 @@
-export declare const TASK_SCAFFOLD_USAGE = "Usage: agentplane task scaffold <task-id> [--title <text>] [--overwrite] [--force]";
-export declare const TASK_SCAFFOLD_USAGE_EXAMPLE = "agentplane task scaffold 202602030608-F1Q8AB";
+import { type CommandContext } from "../shared/task-backend.js";
 export declare function cmdTaskScaffold(opts: {
+    ctx?: CommandContext;
     cwd: string;
     rootOverride?: string;
-    args: string[];
+    taskId: string;
+    title?: string;
+    overwrite: boolean;
+    force: boolean;
+    quiet: boolean;
 }): Promise<number>;
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/commands/task/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scaffold.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,mBAAmB,uFACsD,CAAC;AACvF,eAAO,MAAM,2BAA2B,iDAAiD,CAAC;AAyD1F,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwFlB"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scaffold.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AA6BnC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+GlB"}

package/dist/commands/task/scaffold.js

@@ -1,80 +1,48 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { atomicWriteFile, ensureDocSections, renderTaskReadme, setMarkdownSection, taskReadmePath, } from "@agentplaneorg/core";
-import { loadTaskBackend } from "../../backends/task-backend.js";
+import { ensureDocSections, renderTaskReadme, setMarkdownSection, taskReadmePath, } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
-import { missingValueMessage, successMessage, unknownEntityMessage, usageMessage, } from "../../cli/output.js";
+import { successMessage, unknownEntityMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
-import { taskDataToFrontmatter } from "../shared/task-backend.js";
+import { loadCommandContext, taskDataToFrontmatter, } from "../shared/task-backend.js";
+import { writeTextIfChanged } from "../../shared/write-if-changed.js";
 import { nowIso } from "./shared.js";
-export const TASK_SCAFFOLD_USAGE = "Usage: agentplane task scaffold <task-id> [--title <text>] [--overwrite] [--force]";
-export const TASK_SCAFFOLD_USAGE_EXAMPLE = "agentplane task scaffold 202602030608-F1Q8AB";
-function parseTaskScaffoldFlags(args) {
-    const [taskId, ...rest] = args;
-    if (!taskId) {
-        throw new CliError({
-            exitCode: 2,
-            code: "E_USAGE",
-            message: usageMessage(TASK_SCAFFOLD_USAGE, TASK_SCAFFOLD_USAGE_EXAMPLE),
-        });
+function insertMarkdownSectionBefore(opts) {
+    const normalized = opts.body.replaceAll("\r\n", "\n");
+    if (normalized.includes(`## ${opts.section}`)) {
+        return setMarkdownSection(normalized, opts.section, opts.text);
     }
-    const out = { taskId, overwrite: false, force: false, quiet: false };
-    for (let i = 0; i < rest.length; i++) {
-        const arg = rest[i];
-        if (!arg)
-            continue;
-        if (arg === "--overwrite") {
-            out.overwrite = true;
-            continue;
-        }
-        if (arg === "--force") {
-            out.force = true;
-            continue;
-        }
-        if (arg === "--quiet") {
-            out.quiet = true;
-            continue;
-        }
-        if (arg === "--title") {
-            const next = rest[i + 1];
-            if (!next) {
-                throw new CliError({
-                    exitCode: 2,
-                    code: "E_USAGE",
-                    message: missingValueMessage("--title"),
-                });
-            }
-            out.title = next;
-            i++;
-            continue;
-        }
-        throw new CliError({
-            exitCode: 2,
-            code: "E_USAGE",
-            message: `Unknown flag: ${arg}`,
-        });
+    const lines = normalized.split("\n");
+    const beforeHeading = `## ${opts.beforeSection}`;
+    const beforeIdx = lines.findIndex((line) => line.trim() === beforeHeading);
+    if (beforeIdx === -1) {
+        // Fallback: append at the end if we can't find the insertion anchor.
+        return setMarkdownSection(normalized, opts.section, opts.text);
     }
-    return out;
+    const textLines = opts.text.replaceAll("\r\n", "\n").split("\n");
+    const sectionLines = [`## ${opts.section}`, "", ...textLines, "", ""];
+    const out = [...lines.slice(0, beforeIdx), ...sectionLines, ...lines.slice(beforeIdx)];
+    return `${out.join("\n").trimEnd()}\n`;
 }
 export async function cmdTaskScaffold(opts) {
-    const flags = parseTaskScaffoldFlags(opts.args);
     try {
-        const { backend, resolved, config } = await loadTaskBackend({
-            cwd: opts.cwd,
-            rootOverride: opts.rootOverride ?? null,
-        });
-        const task = await backend.getTask(flags.taskId);
-        if (!task && !flags.force) {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const backend = ctx.taskBackend;
+        const resolved = ctx.resolvedProject;
+        const config = ctx.config;
+        const task = await backend.getTask(opts.taskId);
+        if (!task && !opts.force) {
             throw new CliError({
                 exitCode: 2,
                 code: "E_USAGE",
-                message: unknownEntityMessage("task id", flags.taskId),
+                message: unknownEntityMessage("task id", opts.taskId),
             });
         }
-        const readmePath = taskReadmePath(path.join(resolved.gitRoot, config.paths.workflow_dir), flags.taskId);
+        const readmePath = taskReadmePath(path.join(resolved.gitRoot, config.paths.workflow_dir), opts.taskId);
         try {
             await readFile(readmePath, "utf8");
-            if (!flags.overwrite) {
+            if (!opts.overwrite) {
                 throw new CliError({
                     exitCode: 2,
                     code: "E_USAGE",
@@ -92,8 +60,8 @@ export async function cmdTaskScaffold(opts) {
         }
         const baseTask = task ??
             {
-                id: flags.taskId,
-                title: flags.title ?? "",
+                id: opts.taskId,
+                title: opts.title ?? "",
                 description: "",
                 status: "TODO",
                 priority: "med",
@@ -106,14 +74,30 @@ export async function cmdTaskScaffold(opts) {
                 doc_updated_at: nowIso(),
                 doc_updated_by: "UNKNOWN",
             };
-        if (flags.title)
-            baseTask.title = flags.title;
+        if (opts.title)
+            baseTask.title = opts.title;
         if (typeof baseTask.doc_updated_by !== "string" ||
             baseTask.doc_updated_by.trim().length === 0 ||
             baseTask.doc_updated_by.trim().toLowerCase() === "agentplane") {
             baseTask.doc_updated_by = baseTask.owner?.trim() ? baseTask.owner : "UNKNOWN";
         }
         const frontmatter = taskDataToFrontmatter(baseTask);
+        const verifyStepsTemplate = [
+            "<!-- TODO: FILL VERIFY STEPS -->",
+            "",
+            "### Scope",
+            "",
+            "",
+            "### Checks",
+            "",
+            "",
+            "### Evidence / Commands",
+            "",
+            "",
+            "### Pass criteria",
+            "",
+            "",
+        ].join("\n");
         const verificationTemplate = [
             "### Plan",
             "",
@@ -125,11 +109,17 @@ export async function cmdTaskScaffold(opts) {
             "<!-- END VERIFICATION RESULTS -->",
         ].join("\n");
         const baseDoc = ensureDocSections("", config.tasks.doc.required_sections);
-        const body = setMarkdownSection(baseDoc, "Verification", verificationTemplate);
+        const withVerifySteps = insertMarkdownSectionBefore({
+            body: baseDoc,
+            section: "Verify Steps",
+            text: verifyStepsTemplate,
+            beforeSection: "Verification",
+        });
+        const body = setMarkdownSection(withVerifySteps, "Verification", verificationTemplate);
         const text = renderTaskReadme(frontmatter, body);
         await mkdir(path.dirname(readmePath), { recursive: true });
-        await atomicWriteFile(readmePath, text.endsWith("\n") ? text : `${text}\n`);
-        if (!flags.quiet) {
+        await writeTextIfChanged(readmePath, text.endsWith("\n") ? text : `${text}\n`);
+        if (!opts.quiet) {
             process.stdout.write(`${successMessage("wrote", path.relative(resolved.gitRoot, readmePath))}\n`);
         }
         return 0;

package/dist/commands/task/scrub.command.d.ts

@@ -0,0 +1,11 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import type { CommandContext } from "../shared/task-backend.js";
+export type TaskScrubParsed = {
+    find: string;
+    replace: string;
+    dryRun: boolean;
+    quiet: boolean;
+};
+export declare const taskScrubSpec: CommandSpec<TaskScrubParsed>;
+export declare function makeRunTaskScrubHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskScrubParsed) => Promise<number>;
+//# sourceMappingURL=scrub.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrub.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scrub.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,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAwDtD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IACxE,KAAK,UAAU,EAAE,GAAG,eAAe,KAAG,OAAO,CAAC,MAAM,CAAC,CAWpE"}

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

@@ -0,0 +1,72 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { cmdTaskScrub } from "./scrub.js";
+export const taskScrubSpec = {
+    id: ["task", "scrub"],
+    group: "Task",
+    summary: "Replace a string across all tasks (frontmatter + docs).",
+    options: [
+        {
+            kind: "string",
+            name: "find",
+            valueHint: "<text>",
+            required: true,
+            description: "The string to search for.",
+        },
+        {
+            kind: "string",
+            name: "replace",
+            valueHint: "<text>",
+            required: true,
+            description: "The replacement string.",
+        },
+        {
+            kind: "boolean",
+            name: "dry-run",
+            default: false,
+            description: "Print affected task ids without writing changes.",
+        },
+        {
+            kind: "boolean",
+            name: "quiet",
+            default: false,
+            description: "Suppress normal output (still prints errors).",
+        },
+    ],
+    examples: [
+        {
+            cmd: 'agentplane task scrub --find "agentctl" --replace "agentplane" --dry-run',
+            why: "Preview which tasks would change.",
+        },
+    ],
+    validateRaw: (raw) => {
+        const find = raw.opts.find;
+        const replace = raw.opts.replace;
+        if (typeof find === "string" && find.trim() === "") {
+            throw usageError({ spec: taskScrubSpec, message: "Invalid value for --find: empty." });
+        }
+        if (typeof replace === "string" && replace.trim() === "") {
+            throw usageError({ spec: taskScrubSpec, message: "Invalid value for --replace: empty." });
+        }
+    },
+    parse: (raw) => {
+        return {
+            find: String(raw.opts.find),
+            replace: String(raw.opts.replace),
+            dryRun: raw.opts["dry-run"] === true,
+            quiet: raw.opts.quiet === true,
+        };
+    },
+};
+export function makeRunTaskScrubHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdTaskScrub({
+            ctx: await getCtx("task scrub"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            find: p.find,
+            replace: p.replace,
+            dryRun: p.dryRun,
+            quiet: p.quiet,
+        });
+    };
+}

package/dist/commands/task/scrub.d.ts

@@ -1,8 +1,11 @@
-export declare const TASK_SCRUB_USAGE = "Usage: agentplane task scrub --find <text> --replace <text> [flags]";
-export declare const TASK_SCRUB_USAGE_EXAMPLE = "agentplane task scrub --find \"agentctl\" --replace \"agentplane\" --dry-run";
+import { type CommandContext } from "../shared/task-backend.js";
 export declare function cmdTaskScrub(opts: {
+    ctx?: CommandContext;
     cwd: string;
     rootOverride?: string;
-    args: string[];
+    find: string;
+    replace: string;
+    dryRun: boolean;
+    quiet: boolean;
 }): Promise<number>;
 //# sourceMappingURL=scrub.d.ts.map

package/dist/commands/task/scrub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scrub.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,gBAAgB,wEAC0C,CAAC;AACxE,eAAO,MAAM,wBAAwB,iFACuC,CAAC;AAgE7E,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDlB"}
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../../../src/commands/task/scrub.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAgBpF,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+ClB"}

package/dist/commands/task/scrub.js

@@ -1,52 +1,6 @@
-import { loadTaskBackend } from "../../backends/task-backend.js";
 import { mapBackendError } from "../../cli/error-map.js";
-import { infoMessage, missingValueMessage, successMessage, usageMessage, } from "../../cli/output.js";
-import { CliError } from "../../shared/errors.js";
-export const TASK_SCRUB_USAGE = "Usage: agentplane task scrub --find <text> --replace <text> [flags]";
-export const TASK_SCRUB_USAGE_EXAMPLE = 'agentplane task scrub --find "agentctl" --replace "agentplane" --dry-run';
-function parseTaskScrubFlags(args) {
-    const out = {
-        find: "",
-        replace: "",
-        dryRun: false,
-        quiet: false,
-    };
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (!arg)
-            continue;
-        if (arg === "--dry-run") {
-            out.dryRun = true;
-            continue;
-        }
-        if (arg === "--quiet") {
-            out.quiet = true;
-            continue;
-        }
-        if (!arg.startsWith("--")) {
-            throw new CliError({
-                exitCode: 2,
-                code: "E_USAGE",
-                message: usageMessage(TASK_SCRUB_USAGE, TASK_SCRUB_USAGE_EXAMPLE),
-            });
-        }
-        const next = args[i + 1];
-        if (!next) {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: missingValueMessage(arg) });
-        }
-        if (arg === "--find") {
-            out.find = next;
-        }
-        else if (arg === "--replace") {
-            out.replace = next;
-        }
-        else {
-            throw new CliError({ exitCode: 2, code: "E_USAGE", message: `Unknown flag: ${arg}` });
-        }
-        i++;
-    }
-    return out;
-}
+import { infoMessage, successMessage } from "../../cli/output.js";
+import { loadCommandContext } from "../shared/task-backend.js";
 function scrubValue(value, find, replace) {
     if (typeof value === "string")
         return value.replaceAll(find, replace);
@@ -63,25 +17,15 @@ function scrubValue(value, find, replace) {
     return value;
 }
 export async function cmdTaskScrub(opts) {
-    const flags = parseTaskScrubFlags(opts.args);
-    if (!flags.find) {
-        throw new CliError({
-            exitCode: 2,
-            code: "E_USAGE",
-            message: usageMessage(TASK_SCRUB_USAGE, TASK_SCRUB_USAGE_EXAMPLE),
-        });
-    }
     try {
-        const { backend } = await loadTaskBackend({
-            cwd: opts.cwd,
-            rootOverride: opts.rootOverride ?? null,
-        });
-        const tasks = await backend.listTasks();
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const tasks = await ctx.taskBackend.listTasks();
         const updated = [];
         const changedIds = new Set();
         for (const task of tasks) {
             const before = JSON.stringify(task);
-            const scrubbed = scrubValue(task, flags.find, flags.replace);
+            const scrubbed = scrubValue(task, opts.find, opts.replace);
             if (scrubbed && typeof scrubbed === "object") {
                 const next = scrubbed;
                 updated.push(next);
@@ -93,8 +37,8 @@ export async function cmdTaskScrub(opts) {
                 updated.push(task);
             }
         }
-        if (flags.dryRun) {
-            if (!flags.quiet) {
+        if (opts.dryRun) {
+            if (!opts.quiet) {
                 process.stdout.write(`${infoMessage(`dry-run: would update ${changedIds.size} task(s)`)}` + "\n");
                 for (const id of [...changedIds].toSorted()) {
                     process.stdout.write(`${id}\n`);
@@ -102,15 +46,15 @@ export async function cmdTaskScrub(opts) {
             }
             return 0;
         }
-        if (backend.writeTasks) {
-            await backend.writeTasks(updated);
+        if (ctx.taskBackend.writeTasks) {
+            await ctx.taskBackend.writeTasks(updated);
         }
         else {
             for (const task of updated) {
-                await backend.writeTask(task);
+                await ctx.taskBackend.writeTask(task);
             }
         }
-        if (!flags.quiet) {
+        if (!opts.quiet) {
             process.stdout.write(`${successMessage("updated tasks", undefined, `count=${changedIds.size}`)}` + "\n");
         }
         return 0;

package/dist/commands/task/search.command.d.ts

@@ -0,0 +1,11 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import type { CommandContext } from "../shared/task-backend.js";
+import type { TaskListFilters } from "./shared.js";
+export type TaskSearchParsed = {
+    query: string;
+    regex: boolean;
+    filters: TaskListFilters;
+};
+export declare const taskSearchSpec: CommandSpec<TaskSearchParsed>;
+export declare function makeRunTaskSearchHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: TaskSearchParsed) => Promise<number>;
+//# sourceMappingURL=search.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/search.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC;AAQF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CA8ExD,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,CAUrE"}

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

@@ -0,0 +1,101 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { cmdTaskSearch } from "./search.js";
+function toStringList(v) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    return [];
+}
+export const taskSearchSpec = {
+    id: ["task", "search"],
+    group: "Task",
+    summary: "Search tasks by text or regex with optional filters.",
+    args: [{ name: "query", required: true, valueHint: "<query>" }],
+    options: [
+        { kind: "boolean", name: "regex", default: false, description: "Treat query as a regex." },
+        {
+            kind: "string",
+            name: "status",
+            valueHint: "<status>",
+            repeatable: true,
+            description: "Repeatable. Filter by status.",
+        },
+        {
+            kind: "string",
+            name: "owner",
+            valueHint: "<owner>",
+            repeatable: true,
+            description: "Repeatable. Filter by owner id.",
+        },
+        {
+            kind: "string",
+            name: "tag",
+            valueHint: "<tag>",
+            repeatable: true,
+            description: "Repeatable. Filter by tag.",
+        },
+        { kind: "string", name: "limit", valueHint: "<n>", description: "Max rows to print." },
+    ],
+    examples: [
+        { cmd: "agentplane task search cli", why: "Search tasks by substring." },
+        { cmd: "agentplane task search 'CLI.*' --regex", why: "Search tasks by regex." },
+    ],
+    validateRaw: (raw) => {
+        const q = String(raw.args.query ?? "").trim();
+        if (!q) {
+            throw usageError({
+                spec: taskSearchSpec,
+                message: "Missing query (expected non-empty text)",
+            });
+        }
+        for (const key of ["status", "owner", "tag"]) {
+            const list = toStringList(raw.opts[key]);
+            if (list.some((s) => s.trim() === "")) {
+                throw usageError({ spec: taskSearchSpec, message: `Invalid value for --${key}: empty.` });
+            }
+        }
+        if (raw.opts.limit !== undefined) {
+            const limitRaw = raw.opts.limit;
+            if (typeof limitRaw !== "string") {
+                throw usageError({
+                    spec: taskSearchSpec,
+                    message: `Invalid value for --limit: ${JSON.stringify(limitRaw)} (expected integer)`,
+                });
+            }
+            const parsed = Number.parseInt(limitRaw, 10);
+            if (Number.isFinite(parsed)) {
+                // ok
+            }
+            else {
+                throw usageError({
+                    spec: taskSearchSpec,
+                    message: `Invalid value for --limit: ${limitRaw} (expected integer)`,
+                });
+            }
+        }
+    },
+    parse: (raw) => ({
+        query: String(raw.args.query),
+        regex: raw.opts.regex === true,
+        filters: {
+            status: toStringList(raw.opts.status),
+            owner: toStringList(raw.opts.owner),
+            tag: toStringList(raw.opts.tag),
+            limit: typeof raw.opts.limit === "string" ? Number.parseInt(raw.opts.limit, 10) : undefined,
+            quiet: true,
+        },
+    }),
+};
+export function makeRunTaskSearchHandler(getCtx) {
+    return async (ctx, p) => {
+        return await cmdTaskSearch({
+            ctx: await getCtx("task search"),
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            query: p.query,
+            regex: p.regex,
+            filters: p.filters,
+        });
+    };
+}

package/dist/commands/task/search.d.ts

@@ -1,7 +1,11 @@
+import { type CommandContext } from "../shared/task-backend.js";
+import { type TaskListFilters } from "./shared.js";
 export declare function cmdTaskSearch(opts: {
+    ctx?: CommandContext;
     cwd: string;
     rootOverride?: string;
     query: string;
-    args: string[];
+    regex: boolean;
+    filters: TaskListFilters;
 }): Promise<number>;
 //# sourceMappingURL=search.d.ts.map

package/dist/commands/task/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/commands/task/search.ts"],"names":[],"mappings":"AAcA,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqElB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/commands/task/search.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEpF,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DlB"}