@workser/cli 0.2.7 → 0.3.1

package/dist/index.js

@@ -4404,6 +4404,89 @@ workser storage get <key> [dest]    # download an object (or print its URL)
 infrastructure on the project's own Neon branch, available only on dedicated tenancy
 in a supported region. They are different stores \u2014 a file put in one is not visible
 in the other. See \`reference/neon-backend.md\`.
+`
+  },
+  {
+    topic: "tasks",
+    title: "Project tasks & subtasks",
+    summary: "The ticket you are working inside: read it, break it into steps, and ask before starting.",
+    commands: ["task"],
+    source: "skills/workser/reference/tasks.md",
+    body: `# Project tasks & subtasks
+
+A **project task** is a ticket the owner filed. You are usually running inside
+one \u2014 Orbit sets \`WORKSER_PROJECT_TASK_ID\` on your process, so every command
+below defaults to it and you rarely pass an id at all.
+
+\`\`\`
+workser task list [--status <value>] [--label <value>] [--limit <n>]
+workser task show [id]                  # the task you are in, with its steps
+
+workser task subtask add <title> [--role <value>] [--kind <value>]
+                                 [--note <text>] [--app <id...>]
+                                 [--infra <ref...>] [--scope <path...>]
+                                 [--depends-on <key...>]
+workser task subtask list [taskId]
+workser task subtask update <id> [--title|--note|--role|--kind|--scope]
+workser task subtask remove <id>
+
+workser task can-start [id]             # may work begin? refuses until approved
+workser task approval request           # tell the owner the plan is ready
+workser task move <id> <status>
+workser task done [id] --summary <text>
+\`\`\`
+
+## This is not \`workser board\`
+
+\`board\` is the Orbit Board \u2014 a human's list of work items. \`task\` is the AI Tech
+Team's own table. Filing your plan on the Board puts it somewhere the owner's
+task page never reads: they see "created work item" and an empty plan. Use
+\`task subtask add\`.
+
+## Planning a task
+
+Read the project first, then propose. One \`subtask add\` per step:
+
+\`\`\`
+workser task subtask add "Build the upload endpoint" \\
+  --role api --kind service \\
+  --note "Accept a file, work out its type, hand it to the right analyzer." \\
+  --scope src/app/api/analyze/route.ts
+
+workser task subtask add "Check every supported file type end to end" \\
+  --role qa --depends-on RIZZ-15
+\`\`\`
+
+\`--role\` is one of: pm, architect, web, api, automation, qa.
+\`--kind\` is what the step produces: data_reports, web, mobile, service,
+automation, docs. It is not the same fact as the role \u2014 the same engineer
+writing a screen, the docs for it and the service behind it is three kinds of
+work.
+
+\`--scope\` is what that step OWNS. Two steps naming the same file cannot run at
+the same time, so keeping scopes apart is what lets the team work in parallel.
+\`--depends-on\` takes the keys you read off \`task show\`.
+
+Between three and six steps. If it needs more, say the task is too big instead.
+The step that CHECKS work must not be the same role as the one that built it.
+
+## Nothing runs until the owner approves
+
+\`\`\`
+workser task can-start
+\`\`\`
+
+This exits non-zero, with the reason, until they have approved the plan \u2014 that
+refusal is the product working, not an error to route around. Ask with
+\`workser task approval request\`; only a person can answer.
+
+## Finishing a step
+
+\`\`\`
+workser task done --summary "The report now shows cost per KOL, with six months of history."
+\`\`\`
+
+Write the summary for someone who runs a business and does not read code.
 `
   },
   {
@@ -4632,7 +4715,18 @@ function buildContext(opts) {
   const projectId = opts.project || process.env.WORKSER_PROJECT_ID || link?.projectId || session.defaultProjectId;
   const runId = process.env.WORKSER_RUN_ID || void 0;
   const conversationId = process.env.WORKSER_CONVERSATION_ID || void 0;
-  return { endpoint, socketPath, token, mode: mode2, cwd, projectId, runId, conversationId };
+  const projectTaskId = process.env.WORKSER_PROJECT_TASK_ID || void 0;
+  return {
+    endpoint,
+    socketPath,
+    token,
+    mode: mode2,
+    cwd,
+    projectId,
+    runId,
+    conversationId,
+    projectTaskId
+  };
 }
 function runTarget(ctx) {
   return ctx.runId || "current";
@@ -6941,8 +7035,353 @@ function collect2(value, previous) {
   return [...previous, value];
 }
 
-// src/commands/decision.ts
+// src/commands/task.ts
 var import_picocolors27 = __toESM(require_picocolors(), 1);
+var STATUSES2 = ["todo", "working", "checking", "ready", "accepted", "archived"];
+var ROLES = ["pm", "architect", "web", "api", "automation", "qa"];
+var KINDS2 = ["data_reports", "web", "mobile", "service", "automation", "docs"];
+function registerTask(program3) {
+  const task = program3.command("task").description("The project's tasks and their subtasks (AI Tech Team)");
+  task.command("list").description("List the board's tasks \u2014 run this before starting anything").option("--status <value>", `only tasks in this status (${STATUSES2.join(" | ")})`).option("--label <value>", "only tasks carrying this label").option("--limit <n>", "cap the number of tasks returned").action(
+    action(async ({ ctx, opts }) => {
+      requireProject(ctx);
+      if (opts.status !== void 0) assertOneOf("--status", opts.status, STATUSES2);
+      const rows = await api(ctx, "/v1/project-tasks", {
+        query: {
+          status: opts.status,
+          label: opts.label,
+          limit: opts.limit
+        }
+      }) ?? [];
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors27.default.dim("No tasks on the board yet."));
+          return;
+        }
+        for (const r of rows) line(formatRow2(r));
+      });
+    })
+  );
+  task.command("show [id]").description(
+    "Show one task with its subtasks. Defaults to the task this run is inside."
+  ).action(
+    action(async ({ ctx, args }) => {
+      const id = resolveTaskId(ctx, args[0]);
+      const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
+      ok(row, () => printTask(row));
+    })
+  );
+  const subtask = task.command("subtask").description("The steps a task is broken into");
+  subtask.command("add <title>").description(
+    'Add one step, e.g. `workser task subtask add "Build the upload screen" --role web`'
+  ).option("--task <id>", "the parent task (defaults to the task this run is inside)").option("--role <value>", `who does it (${ROLES.join(" | ")})`).option("--kind <value>", `what it produces (${KINDS2.join(" | ")})`).option("--note <text>", "one sentence on what this step does").option("--app <id...>", "app ids this step touches").option("--infra <ref...>", "shared setup it touches (database | storage | auth | hosting | jobs)").option("--scope <path...>", "files or folders THIS step owns").option("--depends-on <id...>", "steps that must finish first (key or id)").action(
+    action(async ({ ctx, args, opts }) => {
+      const parent = resolveTaskId(ctx, opts.task);
+      if (opts.role !== void 0) assertOneOf("--role", opts.role, ROLES);
+      if (opts.kind !== void 0) assertOneOf("--kind", opts.kind, KINDS2);
+      const dependsOn = await resolveDeps(ctx, parent, opts.dependsOn ?? []);
+      const row = await api(ctx, "/v1/project-tasks", {
+        body: {
+          parentTaskId: parent,
+          title: args[0],
+          summary: opts.note,
+          role: opts.role,
+          category: opts.kind,
+          scopePaths: opts.scope,
+          dependsOn,
+          targets: [
+            ...(opts.app ?? []).map((appId) => ({ kind: "app", appId })),
+            ...(opts.infra ?? []).map((ref) => ({ kind: "infra", ref }))
+          ]
+        }
+      });
+      ok(row, () => {
+        line(`${import_picocolors27.default.green("added")} ${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.key ?? row.id)}`);
+        if (row.role) line(import_picocolors27.default.dim(`role: ${row.role}`));
+      });
+    })
+  );
+  subtask.command("list [taskId]").description("The steps of a task, in order").action(
+    action(async ({ ctx, args }) => {
+      const id = resolveTaskId(ctx, args[0]);
+      const row = await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`);
+      const rows = row.subtasks ?? [];
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors27.default.dim("No steps yet."));
+          return;
+        }
+        rows.forEach((r, i) => line(formatSubtask(r, i + 1)));
+      });
+    })
+  );
+  subtask.command("update <id>").description("Change a step \u2014 its title, its role, what it touches").option("--title <text>").option("--note <text>").option("--role <value>", ROLES.join(" | ")).option("--kind <value>", KINDS2.join(" | ")).option("--scope <path...>", "replaces the step's scope entirely").action(
+    action(async ({ ctx, args, opts }) => {
+      if (opts.role !== void 0) assertOneOf("--role", opts.role, ROLES);
+      if (opts.kind !== void 0) assertOneOf("--kind", opts.kind, KINDS2);
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(args[0])}`,
+        {
+          method: "PATCH",
+          body: {
+            title: opts.title,
+            summary: opts.note,
+            role: opts.role,
+            category: opts.kind,
+            scopePaths: opts.scope
+          }
+        }
+      );
+      ok(row, () => line(`${import_picocolors27.default.green("updated")} ${import_picocolors27.default.bold(row.title)}`));
+    })
+  );
+  subtask.command("remove <id>").description("Drop a step from the plan (only before the work starts)").action(
+    action(async ({ ctx, args }) => {
+      await api(ctx, `/v1/project-tasks/${encodeURIComponent(args[0])}`, {
+        method: "DELETE"
+      });
+      ok({ removed: args[0] }, () => line(import_picocolors27.default.green("removed")));
+    })
+  );
+  task.command("move <id> <status>").description(`Move a task or step along the board (${STATUSES2.join(" | ")})`).action(
+    action(async ({ ctx, args }) => {
+      assertOneOf("<status>", args[1], STATUSES2);
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(args[0])}/move`,
+        { body: { status: args[1] } }
+      );
+      ok(row, () => line(`${import_picocolors27.default.green("moved")} ${import_picocolors27.default.bold(row.title)} \u2192 ${args[1]}`));
+    })
+  );
+  task.command("can-start [id]").description("Ask whether work on this task may begin. Refuses until the owner approves.").action(
+    action(async ({ ctx, args }) => {
+      const id = resolveTaskId(ctx, args[0]);
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(id)}/dispatch-check`,
+        { method: "POST" }
+      );
+      ok(row, () => line(import_picocolors27.default.green("approved \u2014 you may start")));
+    })
+  );
+  task.command("approval").description("Ask the owner to approve the plan, or record their decision").argument("<request|approve|decline>").option("--task <id>", "defaults to the task this run is inside").option("--note <text>", "why").action(
+    action(async ({ ctx, args, opts }) => {
+      const id = resolveTaskId(ctx, opts.task);
+      const what = args[0];
+      if (what === "request") {
+        const row2 = await api(
+          ctx,
+          `/v1/project-tasks/${encodeURIComponent(id)}`
+        );
+        ok({ awaiting: row2.approval_state === "awaiting", task: row2 }, () => {
+          line(
+            row2.approval_state === "awaiting" ? import_picocolors27.default.yellow("The plan is waiting on the owner. They see it in the task.") : `Already ${row2.approval_state}.`
+          );
+        });
+        return;
+      }
+      if (what !== "approve" && what !== "decline") {
+        throw new WorkserError(
+          `Expected "request", "approve" or "decline", got "${what}".`,
+          { code: "bad_request" }
+        );
+      }
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(id)}/approval`,
+        {
+          body: {
+            decision: what === "approve" ? "approved" : "declined",
+            note: opts.note
+          }
+        }
+      );
+      ok(row, () => line(`${import_picocolors27.default.green(row.approval_state)} ${import_picocolors27.default.bold(row.title)}`));
+    })
+  );
+  task.command("done [id]").description("Record what a step produced, and move it to ready").option("--summary <text>", "what changed, in the owner's words").action(
+    action(async ({ ctx, args, opts }) => {
+      const id = resolveTaskId(ctx, args[0]);
+      await api(ctx, `/v1/project-tasks/${encodeURIComponent(id)}`, {
+        method: "PATCH",
+        body: { resultSummary: opts.summary }
+      });
+      const row = await api(
+        ctx,
+        `/v1/project-tasks/${encodeURIComponent(id)}/move`,
+        { body: { status: "ready" } }
+      );
+      ok(row, () => line(`${import_picocolors27.default.green("ready")} ${import_picocolors27.default.bold(row.title)}`));
+    })
+  );
+}
+function resolveTaskId(ctx, given) {
+  const id = given || ctx.projectTaskId;
+  if (!id) {
+    throw new WorkserError(
+      "No task. This run isn't inside one (WORKSER_PROJECT_TASK_ID is unset), so pass --task <id or key>.",
+      { code: "no_task" }
+    );
+  }
+  return id;
+}
+async function resolveDeps(ctx, parentId, given) {
+  if (!given.length) return void 0;
+  const parent = await api(
+    ctx,
+    `/v1/project-tasks/${encodeURIComponent(parentId)}`
+  );
+  const byKey = /* @__PURE__ */ new Map();
+  for (const s of parent.subtasks ?? []) {
+    byKey.set(s.id, s.id);
+    if (s.key) byKey.set(s.key, s.id);
+  }
+  return given.map((g) => {
+    const id = byKey.get(g);
+    if (!id) {
+      throw new WorkserError(
+        `"${g}" is not a step of this task. Run \`workser task subtask list\` to see them.`,
+        { code: "bad_request" }
+      );
+    }
+    return id;
+  });
+}
+function assertOneOf(flag, value, allowed) {
+  if (!allowed.includes(value)) {
+    throw new WorkserError(
+      `${flag} must be one of: ${allowed.join(", ")} \u2014 got "${value}".`,
+      { code: "bad_request" }
+    );
+  }
+}
+function formatRow2(r) {
+  const key = import_picocolors27.default.dim((r.key ?? r.id.slice(0, 8)).padEnd(10));
+  const steps = r.subtaskTotal ? import_picocolors27.default.dim(` ${r.subtaskDone}/${r.subtaskTotal}`) : "";
+  const gate = r.approval_state === "awaiting" ? import_picocolors27.default.yellow(" awaiting approval") : "";
+  return `${key} ${statusTag2(r.status)} ${r.title}${steps}${gate}`;
+}
+function formatSubtask(r, index) {
+  const n = import_picocolors27.default.dim(String(index).padStart(2, "0"));
+  const role = r.role ? import_picocolors27.default.dim(` [${r.role}]`) : "";
+  const scope = r.scope_paths?.length ? import_picocolors27.default.dim(`  owns: ${r.scope_paths.join(", ")}`) : "";
+  return `${n} ${statusTag2(r.status)} ${r.title}${role}${scope}`;
+}
+function printTask(row) {
+  line(`${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.key ?? row.id)}`);
+  line(`${statusTag2(row.status)}  approval: ${row.approval_state}`);
+  if (row.summary) line(`
+${row.summary}`);
+  if (row.targets?.length) {
+    line(
+      `
+touches: ${row.targets.map((t) => t.appName ?? t.ref ?? t.kind).join(", ")}`
+    );
+  }
+  if (row.subtasks?.length) {
+    line(`
+${import_picocolors27.default.bold("steps")}`);
+    row.subtasks.forEach((s, i) => line(formatSubtask(s, i + 1)));
+  } else {
+    line(import_picocolors27.default.dim("\nNo steps yet."));
+  }
+}
+function statusTag2(status) {
+  switch (status) {
+    case "ready":
+      return import_picocolors27.default.green("[ready]");
+    case "working":
+      return import_picocolors27.default.blue("[working]");
+    case "checking":
+      return import_picocolors27.default.cyan("[checking]");
+    case "accepted":
+      return import_picocolors27.default.green("[accepted]");
+    case "archived":
+      return import_picocolors27.default.dim("[archived]");
+    default:
+      return import_picocolors27.default.dim("[todo]");
+  }
+}
+
+// src/role-guard.ts
+var READS = [
+  "task",
+  "board",
+  "doc",
+  "decision",
+  "memory",
+  "search",
+  "verify",
+  "logs",
+  "status",
+  "help",
+  "whoami",
+  "login",
+  "auth",
+  "project",
+  "open",
+  "doctor"
+];
+var BUILDS = [
+  ...READS,
+  "app",
+  "env",
+  "db",
+  "storage",
+  "checkpoint",
+  "artifact",
+  "image",
+  "design",
+  "ask",
+  "sync",
+  "tool",
+  "workflow",
+  "neon",
+  "business"
+];
+var ROLE_VERBS = {
+  pm: [...READS, "ask", "app"],
+  architect: [...BUILDS, "versions"],
+  web: BUILDS,
+  api: BUILDS,
+  mobile: BUILDS,
+  python: BUILDS,
+  automation: BUILDS,
+  designer: BUILDS,
+  qa: READS,
+  security: READS,
+  analyst: READS,
+  sre: [...READS, "deploy", "domain", "versions"],
+  devops: [...BUILDS, "deploy", "domain", "versions"]
+};
+var NEVER = {
+  // Approving is the owner's, full stop. An agent that can approve the plan it
+  // proposed has removed the only gate this product has.
+  "task approval": "Only the owner can approve a plan."
+};
+function assertRoleMayRun(argv) {
+  const role = (process.env.WORKSER_ROLE ?? "").trim();
+  if (!role) return;
+  const verb = argv[0];
+  if (!verb) return;
+  const pair = `${argv[0]} ${argv[1] ?? ""}`.trim();
+  if (NEVER[pair] && !(pair === "task approval" && (argv[2] === "request" || !argv[2]))) {
+    throw new WorkserError(NEVER[pair], { code: "role_forbidden" });
+  }
+  const allowed = ROLE_VERBS[role];
+  const list = allowed ?? READS;
+  if (!list.includes(verb)) {
+    throw new WorkserError(
+      `The ${role} role can't run \`workser ${verb}\`. Report what you found instead, and the step that owns this will do it.`,
+      { code: "role_forbidden" }
+    );
+  }
+}
+
+// src/commands/decision.ts
+var import_picocolors28 = __toESM(require_picocolors(), 1);
 function registerDecision(program3) {
   const decision = program3.command("decision").description("Read and record the project's architecture decisions");
   decision.command("list").description("Every decision on record \u2014 read this before changing how something works").option("--limit <n>", "cap the number returned (newest first)").action(
@@ -6955,11 +7394,11 @@ function registerDecision(program3) {
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors27.default.dim("No decisions recorded yet."));
+          line(import_picocolors28.default.dim("No decisions recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors27.default.dim(r.id)}  ${import_picocolors27.default.dim(shortDate(r.createdAt))}  ${r.title}`);
+          line(`${import_picocolors28.default.dim(r.id)}  ${import_picocolors28.default.dim(shortDate(r.createdAt))}  ${r.title}`);
           line(`    ${truncate(r.decision, 100)}`);
         }
       });
@@ -6973,16 +7412,16 @@ function registerDecision(program3) {
         `/v1/projects/${projectId}/architecture-decisions/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.id)}`);
-        line(import_picocolors27.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
+        line(import_picocolors28.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
-${import_picocolors27.default.bold("Context")}
+${import_picocolors28.default.bold("Context")}
 ${row.context}`);
         line(`
-${import_picocolors27.default.bold("Decision")}
+${import_picocolors28.default.bold("Decision")}
 ${row.decision}`);
         if (row.consequences) line(`
-${import_picocolors27.default.bold("Consequences")}
+${import_picocolors28.default.bold("Consequences")}
 ${row.consequences}`);
       });
     })
@@ -7011,7 +7450,7 @@ ${row.consequences}`);
         refId: row?.id,
         output: { decision: row }
       });
-      ok(row, () => line(`Recorded decision ${import_picocolors27.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded decision ${import_picocolors28.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   const requirement = program3.command("requirement").description("Read and record the project's requirements");
@@ -7023,11 +7462,11 @@ ${row.consequences}`);
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors27.default.dim("No requirements recorded yet."));
+          line(import_picocolors28.default.dim("No requirements recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors27.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
+          line(`${import_picocolors28.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
         }
       });
     })
@@ -7040,8 +7479,8 @@ ${row.consequences}`);
         `/v1/projects/${projectId}/requirements/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.id)}`);
-        line(import_picocolors27.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
+        line(import_picocolors28.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
 ${row.body}`);
       });
@@ -7067,7 +7506,7 @@ ${row.body}`);
         refId: row?.id,
         output: { requirement: row }
       });
-      ok(row, () => line(`Recorded requirement ${import_picocolors27.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded requirement ${import_picocolors28.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   requirement.command("update <id>").description(
@@ -7096,7 +7535,7 @@ ${row.body}`);
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated requirement ${import_picocolors27.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
+      ok(row, () => line(`Updated requirement ${import_picocolors28.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
     })
   );
 }
@@ -7119,7 +7558,7 @@ function shortDate(iso) {
 }
 
 // src/commands/doc.ts
-var import_picocolors28 = __toESM(require_picocolors(), 1);
+var import_picocolors29 = __toESM(require_picocolors(), 1);
 function registerDoc(program3) {
   const doc = program3.command("doc").description("Read and write project documents");
   doc.command("list").description("List the project's documents \u2014 check here before writing a new one").option("--work-item <id>", "the document linked to this card, if there is one").action(
@@ -7130,13 +7569,13 @@ function registerDoc(program3) {
       }) ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors28.default.dim("No documents yet."));
+          line(import_picocolors29.default.dim("No documents yet."));
           return;
         }
         for (const r of rows) {
-          const link = r.workItemId ? import_picocolors28.default.dim(` \u21B3 ${r.workItemId}`) : "";
-          const file = r.filePath ? import_picocolors28.default.dim(`  ${r.filePath}`) : "";
-          line(`${import_picocolors28.default.dim(r.id)}  ${r.title}${link}${file}`);
+          const link = r.workItemId ? import_picocolors29.default.dim(` \u21B3 ${r.workItemId}`) : "";
+          const file = r.filePath ? import_picocolors29.default.dim(`  ${r.filePath}`) : "";
+          line(`${import_picocolors29.default.dim(r.id)}  ${r.title}${link}${file}`);
         }
       });
     })
@@ -7150,17 +7589,17 @@ function registerDoc(program3) {
       );
       if (opts.markdown) {
         ok({ id: row.id, title: row.title, filePath: row.filePath }, () => {
-          line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
+          line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
           line(
-            row.filePath ? `Read it at ${import_picocolors28.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors28.default.dim("This document has no markdown mirror on disk yet.")
+            row.filePath ? `Read it at ${import_picocolors29.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors29.default.dim("This document has no markdown mirror on disk yet.")
           );
         });
         return;
       }
       ok(row, () => {
-        line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
-        if (row.workItemId) line(import_picocolors28.default.dim(`linked to work item ${row.workItemId}`));
-        if (row.filePath) line(import_picocolors28.default.dim(`markdown mirror: ${row.filePath}`));
+        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
+        if (row.workItemId) line(import_picocolors29.default.dim(`linked to work item ${row.workItemId}`));
+        if (row.filePath) line(import_picocolors29.default.dim(`markdown mirror: ${row.filePath}`));
         line("");
         line(row.contentJson);
       });
@@ -7189,7 +7628,7 @@ function registerDoc(program3) {
         refId: row?.id,
         output: { document: row }
       });
-      ok(row, () => line(`Created document ${import_picocolors28.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Created document ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   doc.command("update <id>").description("Revise an existing document rather than creating a second copy of it").option("--title <text>", "new title").option("--markdown <text>", "replace the body with this markdown").option("--content-json <json>", "replace the body with this rich-text content JSON").action(
@@ -7216,13 +7655,13 @@ function registerDoc(program3) {
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated document ${import_picocolors28.default.bold(row.id)} \u2014 ${row.title}`));
+      ok(row, () => line(`Updated document ${import_picocolors29.default.bold(row.id)} \u2014 ${row.title}`));
     })
   );
 }
 
 // src/commands/design.ts
-var import_picocolors29 = __toESM(require_picocolors(), 1);
+var import_picocolors30 = __toESM(require_picocolors(), 1);
 function registerDesign(program3) {
   const design = program3.command("design").description("Read the project's brand (colours, fonts, logo)");
   design.command("show").description("Show this project's brand \u2014 read it before writing any UI").option("--raw", "print the generated token files verbatim instead of a summary").action(
@@ -7236,11 +7675,11 @@ function registerDesign(program3) {
       if (opts.raw) {
         ok(files, () => {
           if (!files.length) {
-            line(import_picocolors29.default.dim("No brand set for this project."));
+            line(import_picocolors30.default.dim("No brand set for this project."));
             return;
           }
           for (const f of files) {
-            line(import_picocolors29.default.bold(f.path));
+            line(import_picocolors30.default.bold(f.path));
             line(f.contents);
             line("");
           }
@@ -7257,21 +7696,21 @@ function registerDesign(program3) {
       } : { hasBrand: false, colors: {}, fonts: {}, brand: {}, files: [] };
       ok(summary, () => {
         if (!tokens) {
-          line(import_picocolors29.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
+          line(import_picocolors30.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
           return;
         }
         for (const [name, value] of Object.entries(tokens.brand)) {
-          line(`${import_picocolors29.default.dim(name.padEnd(12))} ${value}`);
+          line(`${import_picocolors30.default.dim(name.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.color)) {
-          line(`${import_picocolors29.default.dim(`color.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors30.default.dim(`color.${name}`.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.font)) {
-          line(`${import_picocolors29.default.dim(`font.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors30.default.dim(`font.${name}`.padEnd(12))} ${value}`);
         }
         line("");
         line(
-          import_picocolors29.default.dim(
+          import_picocolors30.default.dim(
             `Generated into the working tree as ${files.map((f) => f.path).join(", ")} \u2014 wire those in, never edit them.`
           )
         );
@@ -7303,7 +7742,7 @@ function unwrap(group) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.2.7" : "0.0.0-dev"
+  version: true ? "0.3.1" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -7348,7 +7787,13 @@ registerImage(program2);
 registerAsk(program2);
 registerSearch(program2);
 registerBoard(program2);
+registerTask(program2);
 registerDecision(program2);
 registerDoc(program2);
 registerDesign(program2);
+try {
+  assertRoleMayRun(process.argv.slice(2));
+} catch (e) {
+  fail(e);
+}
 program2.parseAsync(process.argv).catch((e) => fail(e));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/reference/tasks.md

@@ -0,0 +1,82 @@
+---
+topic: tasks
+title: Project tasks & subtasks
+summary: The ticket you are working inside: read it, break it into steps, and ask before starting.
+commands: [task]
+---
+
+# Project tasks & subtasks
+
+A **project task** is a ticket the owner filed. You are usually running inside
+one — Orbit sets `WORKSER_PROJECT_TASK_ID` on your process, so every command
+below defaults to it and you rarely pass an id at all.
+
+```
+workser task list [--status <value>] [--label <value>] [--limit <n>]
+workser task show [id]                  # the task you are in, with its steps
+
+workser task subtask add <title> [--role <value>] [--kind <value>]
+                                 [--note <text>] [--app <id...>]
+                                 [--infra <ref...>] [--scope <path...>]
+                                 [--depends-on <key...>]
+workser task subtask list [taskId]
+workser task subtask update <id> [--title|--note|--role|--kind|--scope]
+workser task subtask remove <id>
+
+workser task can-start [id]             # may work begin? refuses until approved
+workser task approval request           # tell the owner the plan is ready
+workser task move <id> <status>
+workser task done [id] --summary <text>
+```
+
+## This is not `workser board`
+
+`board` is the Orbit Board — a human's list of work items. `task` is the AI Tech
+Team's own table. Filing your plan on the Board puts it somewhere the owner's
+task page never reads: they see "created work item" and an empty plan. Use
+`task subtask add`.
+
+## Planning a task
+
+Read the project first, then propose. One `subtask add` per step:
+
+```
+workser task subtask add "Build the upload endpoint" \
+  --role api --kind service \
+  --note "Accept a file, work out its type, hand it to the right analyzer." \
+  --scope src/app/api/analyze/route.ts
+
+workser task subtask add "Check every supported file type end to end" \
+  --role qa --depends-on RIZZ-15
+```
+
+`--role` is one of: pm, architect, web, api, automation, qa.
+`--kind` is what the step produces: data_reports, web, mobile, service,
+automation, docs. It is not the same fact as the role — the same engineer
+writing a screen, the docs for it and the service behind it is three kinds of
+work.
+
+`--scope` is what that step OWNS. Two steps naming the same file cannot run at
+the same time, so keeping scopes apart is what lets the team work in parallel.
+`--depends-on` takes the keys you read off `task show`.
+
+Between three and six steps. If it needs more, say the task is too big instead.
+The step that CHECKS work must not be the same role as the one that built it.
+
+## Nothing runs until the owner approves
+
+```
+workser task can-start
+```
+
+This exits non-zero, with the reason, until they have approved the plan — that
+refusal is the product working, not an error to route around. Ask with
+`workser task approval request`; only a person can answer.
+
+## Finishing a step
+
+```
+workser task done --summary "The report now shows cost per KOL, with six months of history."
+```
+
+Write the summary for someone who runs a business and does not read code.