taskchef 0.0.1 → 1.0.1

package/skills/taskchef-bootstrap/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: taskchef-bootstrap
+description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, project configuration, managed AGENTS.md instructions, and TaskChef skill links. Use when creating a TaskChef workspace, adding, importing, listing, or removing configured projects, running TaskChef doctor, repairing dispatcher setup, or upgrading installed TaskChef skills. Do not dispatch user work or reconcile executor threads."
+---
+
+# TaskChef Bootstrap
+
+Initialize or refresh a data-only TaskChef dispatcher workspace.
+
+Resolve this linked skill with `realpath`. The TaskChef source root is two
+parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+all deterministic workspace operations.
+
+## Boundaries
+
+- Keep implementation, tests, and reports in the TaskChef source repository.
+- Keep only `AGENTS.md`, `taskchef.json`, `tasks/*/task.json`, and the three
+  TaskChef skill links in a dispatcher workspace.
+- Do not dispatch tasks or reconcile executor threads during bootstrap unless
+  the user separately requests those actions.
+- Never use collaboration agents, hooks, schedules, polling, or daemons.
+
+## Initialize and repair
+
+1. Run `workspace init --json`. It takes no stdin, creates an empty
+   configuration when missing, and idempotently creates or refreshes the task
+   directory, managed instructions, and all three skill links.
+2. Run `doctor --json` after setup or when the user asks to diagnose the
+   workspace. Doctor is read-only; rerun `workspace init --json` to repair the
+   managed scaffold.
+3. Report the actions or failed checks. End without dispatching unless the user
+   separately requested work.
+
+## Configure projects
+
+1. List native Codex projects once when discovery is necessary. Configure only
+   projects local to the TaskChef workspace's execution host. Remote connection
+   projects are outside the v1 contract.
+2. Add one project with `project add <path>`, normally supplying `--name` and a
+   curated `--description`. The CLI detects Git status, exact Git root, and a
+   canonical GitHub `origin`; use `--no-github` or `--github-repo` only to
+   override detection.
+3. Bulk import with `project import <file|-> --json`. Input is a JSON array of
+   objects containing `path` plus optional `name`, `description`, and
+   `githubRepo`. Import merges by canonical path and preserves an existing name
+   or description when omitted. Use `--replace` only when the user explicitly
+   requests replacement.
+4. Inspect configured projects with `project list --json`. Remove by name with
+   `project remove`; require explicit user intent before `--force` when task
+   records reference the project.

package/skills/taskchef-bootstrap/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Bootstrap"
+  short_description: "Bootstrap TaskChef dispatcher workspaces"
+  default_prompt: "Use $taskchef-bootstrap to initialize or refresh this TaskChef dispatcher workspace."

package/skills/taskchef-delegate/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: taskchef-delegate
+description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, splitting work across projects, or retrying pending executor creation. Dispatch must return immediately and must never use subagents, hooks, schedules, or foreground waiting. Use taskchef-bootstrap instead for workspace setup or configuration changes."
+---
+
+# TaskChef Delegate
+
+Create real Codex tasks from a TaskChef data workspace and return immediately.
+Use `taskchef-reconcile` first when the current prompt has active recorded tasks.
+
+Resolve this linked skill with `realpath`. The TaskChef source root is two
+parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+all deterministic workspace and task-record operations.
+
+## Boundaries
+
+- Keep implementation, tests, and reports in the TaskChef source repository.
+- Keep only `AGENTS.md`, `taskchef.json`, `tasks/*/task.json`, and the three
+  TaskChef skill links in a dispatcher workspace.
+- Use real Codex tasks, never collaboration or subagent tools.
+- Never use hooks, callbacks, schedules, polling, daemons, or event logs.
+- Never wait for delegated work after executor creation.
+- Never collect transcripts or hidden reasoning.
+
+## Dispatch
+
+1. Run `project list --json` to load and validate the configured routing
+   targets. Use `taskchef-bootstrap` if the workspace is missing or unhealthy.
+2. Split the request into the smallest independently useful outcomes. Include
+   constraints, expected testing, and reporting in every instruction.
+3. Classify against configured `name`, `githubRepo`, and `description`. Use
+   `path` only as checkout identity. Ask when metadata does not produce one
+   clear project match.
+4. Resolve native projects once and require the exact configured path.
+5. Reuse a matching pending record for an explicit retry; otherwise create one
+   pending record before executor creation.
+6. Create one real Codex task per record using the exact saved project and a
+   local environment on its executor host.
+7. Immediately record every returned `threadId` with status `running`. Never
+   persist `hostId`.
+8. Leave a failed creation pending. Do not invent an ID or delete the record.
+9. Return immediately with a created-thread directive for every success. Do
+   not read or wait for a newly created executor.

package/skills/taskchef-delegate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Delegate"
+  short_description: "Dispatch work into visible Codex tasks"
+  default_prompt: "Use $taskchef-delegate to route this request into independently openable Codex tasks."

package/skills/taskchef-reconcile/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: taskchef-reconcile
+description: "Reconcile active TaskChef task records with their visible Codex executor threads. Use at the start of ordinary prompts in a TaskChef workspace, for TaskChef status or progress requests, after delegated work may have completed or blocked, or for an explicitly requested full refresh. Performs one bounded snapshot pass and never polls or waits for future activity."
+---
+
+# TaskChef Reconcile
+
+Refresh TaskChef's recorded task state from native Codex threads exactly once.
+
+Resolve this linked skill with `realpath`. The TaskChef source root is two
+parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+all deterministic record operations.
+
+## Reconcile
+
+1. Run `task reconcile-candidates --json` once. It returns only `running` and
+   `blocked` tasks with thread IDs. Do not scan pending or finished records.
+2. Query every returned thread exactly once using immediate native snapshots,
+   with no more than eight targets per call.
+3. Do not wait for future activity and do not poll.
+4. Map an active attempt to `running`, a user-input or external dependency to
+   `blocked`, and any concluded attempt to `finished`, including failed or
+   partial attempts.
+5. Preserve an existing result unless the thread provides a meaningful newer
+   report. Results contain exactly `message`, `githubPRs`, and `githubIssues`.
+6. Update each changed record once with `task update`.
+7. Report a concise snapshot and continue with the user's request. If there
+   were no candidates or changes, say so briefly.
+
+Use `task reconcile-candidates --include-finished --json` only when the user
+explicitly requests a full refresh or says a finished executor received new
+work. A finished task with a new active attempt becomes `running` again.
+
+The native thread is authoritative between reconciliations. Executor reports
+are evidence, not independently verified completion guarantees.

package/skills/taskchef-reconcile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Reconcile"
+  short_description: "Reconcile visible TaskChef task state"
+  default_prompt: "Use $taskchef-reconcile to refresh active TaskChef task statuses and results once."

package/src/cli.js

@@ -0,0 +1,303 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  addProject,
+  buildReconciliationCandidates,
+  buildTaskSummary,
+  createTask,
+  doctorWorkspace,
+  filterTasks,
+  importProjects,
+  initializeWorkspace,
+  listProjects,
+  readTask,
+  removeProject,
+  updateTask,
+} from "./workspace.js";
+
+async function readStdin() {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) input += chunk;
+  return input;
+}
+
+async function readJsonStdin() {
+  const input = await readStdin();
+  if (input.trim().length === 0) throw new Error("expected JSON on standard input");
+  return JSON.parse(input);
+}
+
+function option(args, name, fallback) {
+  const index = args.indexOf(name);
+  if (index === -1) return fallback;
+  if (!args[index + 1] || args[index + 1].startsWith("--")) {
+    throw new Error(`${name} requires a value`);
+  }
+  return args[index + 1];
+}
+
+function options(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== name) continue;
+    if (!args[index + 1] || args[index + 1].startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
+    values.push(args[index + 1]);
+    index += 1;
+  }
+  return values;
+}
+
+function validateCommandArgs(
+  args,
+  startIndex,
+  { values = [], switches = [], repeatable = [] } = {},
+) {
+  const valueOptions = new Set(values);
+  const booleanOptions = new Set(switches);
+  const repeatableOptions = new Set(repeatable);
+  const seen = new Set();
+  for (let index = startIndex; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--") || token.includes("=")) {
+      throw new Error(`unexpected argument: ${token}`);
+    }
+    if (!valueOptions.has(token) && !booleanOptions.has(token)) {
+      throw new Error(`unsupported option: ${token}`);
+    }
+    if (seen.has(token) && !repeatableOptions.has(token)) {
+      throw new Error(`duplicate option: ${token}`);
+    }
+    seen.add(token);
+    if (valueOptions.has(token)) {
+      if (!args[index + 1] || args[index + 1].startsWith("--")) {
+        throw new Error(`${token} requires a value`);
+      }
+      index += 1;
+    }
+  }
+}
+
+function workspaceRoot(args) {
+  return path.resolve(option(args, "--workspace", process.cwd()));
+}
+
+function print(value, args, human) {
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    return;
+  }
+  process.stdout.write(`${human ? human(value) : JSON.stringify(value, null, 2)}\n`);
+}
+
+function table(headers, rows) {
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => String(row[index]).length)));
+  const format = (row) => row.map((value, index) => String(value).padEnd(widths[index])).join("  ");
+  return [format(headers), ...rows.map(format)].join("\n");
+}
+
+async function initialize(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const result = await initializeWorkspace(workspaceRoot(args));
+  print(result, args, (value) => [
+    `Workspace: ${value.workspace}`,
+    `Configuration: ${value.config.action}`,
+    `Instructions: ${value.instructions.action}`,
+    `Skills: ${value.skills.skills.map((skill) => `${skill.name}=${skill.action}`).join(", ")}`,
+  ].join("\n"));
+  return 0;
+}
+
+async function doctor(args) {
+  validateCommandArgs(args, 1, { values: ["--workspace"], switches: ["--json"] });
+  const result = await doctorWorkspace(workspaceRoot(args));
+  print(result, args, (value) => value.checks
+    .map((check) => `${check.status === "pass" ? "✓" : "✗"} ${check.name}: ${check.message}`)
+    .join("\n"));
+  return result.ok ? 0 : 1;
+}
+
+async function projectAdd(args) {
+  if (!args[2] || args[2].startsWith("--")) throw new Error("project add requires a path");
+  validateCommandArgs(args, 3, {
+    values: ["--workspace", "--name", "--description", "--github-repo"],
+    switches: ["--json", "--no-github"],
+  });
+  if (args.includes("--no-github") && args.includes("--github-repo")) {
+    throw new Error("--no-github and --github-repo cannot be used together");
+  }
+  const input = { path: args[2] };
+  const name = option(args, "--name", null);
+  const description = option(args, "--description", null);
+  if (name !== null) input.name = name;
+  if (description !== null) input.description = description;
+  if (args.includes("--no-github")) input.githubRepo = null;
+  else if (args.includes("--github-repo")) input.githubRepo = option(args, "--github-repo");
+  const project = await addProject(workspaceRoot(args), input);
+  print(project, args, (value) => `Added ${value.name}: ${value.path}`);
+  return 0;
+}
+
+async function projectImport(args) {
+  const hasSource = Boolean(args[2] && !args[2].startsWith("--"));
+  const source = hasSource ? args[2] : "-";
+  validateCommandArgs(args, hasSource ? 3 : 2, {
+    values: ["--workspace"],
+    switches: ["--json", "--replace"],
+  });
+  const content = source === "-"
+    ? await readStdin()
+    : await readFile(path.resolve(source), "utf8");
+  if (content.trim().length === 0) throw new Error("project import input is empty");
+  const result = await importProjects(workspaceRoot(args), JSON.parse(content), {
+    replace: args.includes("--replace"),
+  });
+  print(result, args, (value) =>
+    `Imported ${value.importedCount} project(s); ${value.projectCount} configured (${value.mode}).`);
+  return 0;
+}
+
+async function projectList(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const projects = await listProjects(workspaceRoot(args));
+  print({ projectCount: projects.length, projects }, args, (value) => table(
+    ["NAME", "KIND", "PATH"],
+    value.projects.map((project) => [
+      project.name,
+      project.isGitRepository ? "git" : "folder",
+      project.path,
+    ]),
+  ));
+  return 0;
+}
+
+async function projectRemove(args) {
+  if (!args[2] || args[2].startsWith("--")) throw new Error("project remove requires a name");
+  validateCommandArgs(args, 3, {
+    values: ["--workspace"],
+    switches: ["--json", "--force"],
+  });
+  const result = await removeProject(workspaceRoot(args), args[2], {
+    force: args.includes("--force"),
+  });
+  print(result, args, (value) => `Removed ${value.project.name}: ${value.project.path}`);
+  return 0;
+}
+
+async function create(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const task = await createTask(workspaceRoot(args), await readJsonStdin());
+  print(task, args, (value) => `Created ${value.id}: ${value.title} (${value.status})`);
+  return 0;
+}
+
+async function update(args) {
+  validateCommandArgs(args, 3, { values: ["--workspace"], switches: ["--json"] });
+  const task = await updateTask(workspaceRoot(args), args[2], await readJsonStdin());
+  print(task, args, (value) => `Updated ${value.id}: ${value.status}`);
+  return 0;
+}
+
+async function show(args) {
+  validateCommandArgs(args, 3, { values: ["--workspace"], switches: ["--json"] });
+  print(await readTask(workspaceRoot(args), args[2]), args);
+  return 0;
+}
+
+async function taskList(args) {
+  validateCommandArgs(args, 2, {
+    values: ["--workspace", "--status", "--project"],
+    switches: ["--json"],
+    repeatable: ["--status"],
+  });
+  const tasks = await filterTasks(workspaceRoot(args), {
+    statuses: options(args, "--status"),
+    project: option(args, "--project", null),
+  });
+  const projects = await listProjects(workspaceRoot(args));
+  const projectNames = new Map(projects.map((project) => [project.path, project.name]));
+  const result = { taskCount: tasks.length, tasks };
+  print(result, args, (value) => table(
+    ["ID", "STATUS", "PROJECT", "TITLE"],
+    value.tasks.map((task) => [
+      task.id,
+      task.status,
+      projectNames.get(task.project) ?? path.basename(task.project),
+      task.title,
+    ]),
+  ));
+  return 0;
+}
+
+async function taskSummary(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const summary = await buildTaskSummary(workspaceRoot(args));
+  print(summary, args, (value) => [
+    `Tasks: ${value.taskCount}`,
+    ...Object.entries(value.statusCounts).map(([status, count]) => `${status}: ${count}`),
+  ].join("\n"));
+  return 0;
+}
+
+async function reconciliationCandidates(args) {
+  validateCommandArgs(args, 2, {
+    values: ["--workspace"],
+    switches: ["--json", "--include-finished"],
+  });
+  const result = await buildReconciliationCandidates(workspaceRoot(args), {
+    includeFinished: args.includes("--include-finished"),
+  });
+  print(result, args);
+  return 0;
+}
+
+function usage() {
+  process.stdout.write(`TaskChef workspace utility
+
+Usage:
+  taskchef help
+  taskchef doctor [--json] [--workspace <path>]
+  taskchef workspace init [--json] [--workspace <path>]
+  taskchef project add <path> [--name <name>] [--description <text>] [--github-repo <url> | --no-github] [--json] [--workspace <path>]
+  taskchef project import [<file> | -] [--replace] [--json] [--workspace <path>]
+  taskchef project list [--json] [--workspace <path>]
+  taskchef project remove <name> [--force] [--json] [--workspace <path>]
+  taskchef task create [--json] [--workspace <path>]
+  taskchef task update <task-id> [--json] [--workspace <path>]
+  taskchef task show <task-id> [--json] [--workspace <path>]
+  taskchef task list [--status <status>]... [--project <name-or-path>] [--json] [--workspace <path>]
+  taskchef task summary [--json] [--workspace <path>]
+  taskchef task reconcile-candidates [--include-finished] [--json] [--workspace <path>]
+
+Task create and update read JSON from standard input. Project import reads a
+JSON array from a file, or from standard input when the source is '-' or omitted.
+`);
+}
+
+export async function runCli(args) {
+  if (args.length === 0 || args[0] === "help" || args[0] === "--help") {
+    usage();
+    return 0;
+  }
+  if (args[0] === "doctor") return doctor(args);
+  if (args[0] === "workspace" && args[1] === "init") return initialize(args);
+  if (args[0] === "project" && args[1] === "add") return projectAdd(args);
+  if (args[0] === "project" && args[1] === "import") return projectImport(args);
+  if (args[0] === "project" && args[1] === "list") return projectList(args);
+  if (args[0] === "project" && args[1] === "remove") return projectRemove(args);
+  if (args[0] === "task" && args[1] === "create") return create(args);
+  if (args[0] === "task" && args[1] === "update" && args[2]) return update(args);
+  if (args[0] === "task" && args[1] === "show" && args[2]) return show(args);
+  if (args[0] === "task" && args[1] === "list") return taskList(args);
+  if (args[0] === "task" && args[1] === "summary") return taskSummary(args);
+  if (args[0] === "task" && args[1] === "reconcile-candidates") {
+    return reconciliationCandidates(args);
+  }
+  process.stderr.write(`Unknown command: ${args.join(" ")}\n`);
+  usage();
+  return 2;
+}