@dreki-gg/taskman 0.2.1 → 0.3.1

package/README.md

@@ -46,6 +46,15 @@ taskman <command> --help  # flags + arguments for one command
 duplicate it (so it cannot drift). Every command prints human text by default
 and accepts `--json` for machine consumption.
 
+Create a plan from any harness (handoff/tasks accept an inline value, a
+`--*-file <path>`, or piped stdin):
+
+```bash
+echo "$MARKDOWN" | taskman create-plan --name my-plan --title "My Plan" \
+  --handoff-file - --tasks '[{"description":"do it"}]'
+taskman create-handoff --plan my-plan --file HANDOFF.md   # write/replace prose
+```
+
 A typical execution loop:
 
 ```bash

package/dist/cli.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-import { N as readInitiativesManifest, P as upsertInitiativeEntry, S as initiativeRollup, T as reconcileInitiativeForPlan, V as upsertPlanEntry, X as makePlanRuntime, _ as applyInitiativeReconcile, a as filterPlans, b as collectPlanDrift, d as setTaskStatus, g as resolvePlanByName, i as loadInitiativeListItems, l as sortPlans, m as loadPlanData, n as formatInitiativeList, o as formatPlanList, s as loadPlanListItems, t as filterInitiatives, u as appendDeferredTask, v as applyReconcile, y as collectInitiativeDrift, z as readPlansManifest } from "./initiatives-Ij_teFl_.mjs";
+import { J as writeTasksJsonl, N as readInitiativesManifest, P as upsertInitiativeEntry, S as initiativeRollup, T as reconcileInitiativeForPlan, V as upsertPlanEntry, W as saveHandoff, X as makePlanRuntime, _ as applyInitiativeReconcile, a as filterPlans, b as collectPlanDrift, d as setTaskStatus, f as nextTaskId, g as resolvePlanByName, i as loadInitiativeListItems, l as sortPlans, m as loadPlanData, n as formatInitiativeList, o as formatPlanList, p as toKebabCase, s as loadPlanListItems, t as filterInitiatives, u as appendDeferredTask, v as applyReconcile, y as collectInitiativeDrift, z as readPlansManifest } from "./initiatives-Ij_teFl_.mjs";
 import { Effect } from "effect";
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { Command } from "commander";
 //#region src/cli/runtime.ts
 /**
@@ -252,6 +254,143 @@ async function closeInitiativeCommand(status, name, opts) {
 	}, `Initiative ${name} → ${s}${opts.reason ? ` (${opts.reason})` : ""}.`);
 }
 //#endregion
+//#region src/cli/input.ts
+/**
+* Content resolution for CLI commands that accept markdown / JSON payloads from
+* a foreign harness: an inline string, a file path, or piped stdin.
+*/
+/** Read all of stdin as a UTF-8 string (used when neither inline nor file is given). */
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/**
+* Resolve payload content from, in priority order: an inline value, a `--file`
+* path (or `-` for stdin), else piped stdin. Throws `CliError` when nothing is
+* provided and stdin is a TTY (no piped input).
+*/
+async function resolveContent(inline, file, label) {
+	if (inline !== void 0) return inline;
+	if (file !== void 0 && file !== "-") try {
+		return await readFile(file, "utf8");
+	} catch {
+		throw new CliError(`Could not read ${label} file: ${file}`);
+	}
+	if (process.stdin.isTTY) throw new CliError(`No ${label} provided. Pass it inline, via --${label}-file, or on stdin.`);
+	return readStdin();
+}
+//#endregion
+//#region src/cli/commands/create-plan.ts
+/**
+* `taskman create-plan` — create a plan from a foreign harness.
+*
+* The CLI sibling of plan-mode's `submit_plan` tool: writes tasks.jsonl,
+* HANDOFF.md, and a plans.jsonl registry entry in one transaction, then
+* re-projects the parent initiative (when linked). Handoff/tasks payloads come
+* from inline values, files, or stdin so any harness can drive it.
+*/
+/** Parse and validate the `--tasks` JSON payload into TaskInput[]. */
+function parseTasks(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError("--tasks must be a JSON array of { description, ... } objects.");
+	}
+	if (!Array.isArray(parsed) || parsed.length === 0) throw new CliError("--tasks must be a non-empty JSON array.");
+	return parsed.map((entry, i) => {
+		if (typeof entry !== "object" || entry === null) throw new CliError(`Task at index ${i} is not an object.`);
+		const { description } = entry;
+		if (typeof description !== "string" || description.trim() === "") throw new CliError(`Task at index ${i} is missing a "description".`);
+		const t = entry;
+		return {
+			id: t.id,
+			description: t.description,
+			details: t.details,
+			depends_on: t.depends_on
+		};
+	});
+}
+/** Assign explicit IDs where given, generate t-NNN for the rest. */
+function assignIds(inputs, now) {
+	const ids = inputs.map((t) => t.id).filter((id) => Boolean(id));
+	const records = [];
+	for (const input of inputs) {
+		const id = input.id ?? nextTaskId(ids);
+		if (!input.id) ids.push(id);
+		records.push({
+			_type: "task",
+			id,
+			description: input.description.slice(0, 60),
+			details: input.details ?? "",
+			status: "pending",
+			depends_on: input.depends_on,
+			created_at: now,
+			updated_at: now
+		});
+	}
+	return records;
+}
+async function createPlanCommand(opts) {
+	if (!opts.name) throw new CliError("--name is required.");
+	if (!opts.title) throw new CliError("--title is required.");
+	const planName = toKebabCase(opts.name);
+	const planDir = `.plans/${planName}`;
+	const initiative = opts.initiative ? toKebabCase(opts.initiative) : void 0;
+	const dependsOnPlans = opts.dependsOn ? opts.dependsOn.split(",").map((s) => toKebabCase(s.trim())).filter(Boolean) : void 0;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const handoff = await resolveContent(opts.handoff, opts.handoffFile, "handoff");
+	const tasks = assignIds(parseTasks(await resolveContent(opts.tasks, opts.tasksFile, "tasks")), now);
+	const meta = {
+		_type: "meta",
+		title: opts.title,
+		plan_name: planName,
+		created_at: now
+	};
+	const unknownInitiative = await runPlanIO(Effect.gen(function* () {
+		yield* writeTasksJsonl(planDir, meta, tasks);
+		yield* saveHandoff(planDir, handoff);
+		yield* upsertPlanEntry(planName, {
+			status: "in-progress",
+			title: opts.title,
+			initiative,
+			depends_on: dependsOnPlans
+		});
+		yield* reconcileInitiativeForPlan(planName);
+		if (!initiative) return false;
+		return !(yield* readInitiativesManifest()).some((entry) => entry.name === initiative);
+	}));
+	const linkSuffix = initiative ? ` Linked to initiative "${initiative}"${unknownInitiative ? " (no initiatives.jsonl entry yet — create it with submit_initiative)" : ""}.` : "";
+	emit(Boolean(opts.json), {
+		plan_name: planName,
+		plan_dir: planDir,
+		task_count: tasks.length,
+		task_ids: tasks.map((t) => t.id),
+		initiative: initiative ?? null,
+		depends_on: dependsOnPlans ?? null,
+		unknown_initiative: unknownInitiative
+	}, `Plan "${opts.title}" saved with ${tasks.length} tasks in ${planDir}.${linkSuffix}`);
+}
+//#endregion
+//#region src/cli/commands/create-handoff.ts
+/**
+* `taskman create-handoff [content]` — write/replace HANDOFF.md for a plan.
+*
+* Lets a foreign harness hand off markdown without going through the plan-mode
+* extension: content comes from an inline argument, `--file <path>`, or stdin.
+*/
+async function createHandoffCommand(content, opts) {
+	const { planName, planDir } = await resolvePlanDir(opts.plan);
+	const markdown = await resolveContent(content, opts.file, "handoff");
+	await runPlanIO(saveHandoff(planDir, markdown));
+	emit(Boolean(opts.json), {
+		plan_name: planName,
+		path: `${planDir}/HANDOFF.md`,
+		bytes: Buffer.byteLength(markdown)
+	}, `Wrote HANDOFF.md (${Buffer.byteLength(markdown)} bytes) for ${planName}.`);
+}
+//#endregion
 //#region src/cli.ts
 /**
 * `taskman` CLI — drive the `.plans/` task ledger from any Node harness.
@@ -259,9 +398,18 @@ async function closeInitiativeCommand(status, name, opts) {
 * Thin Commander wiring over the engine: each subcommand delegates to an action
 * module under `cli/commands/`. Human text by default; `--json` for machines.
 */
+/** Read the shipped package version (dist/cli.mjs → ../package.json). */
+function packageVersion() {
+	try {
+		const pkgUrl = new URL("../package.json", import.meta.url);
+		return JSON.parse(readFileSync(pkgUrl, "utf-8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
 function buildProgram() {
 	const program = new Command();
-	program.name("taskman").description("Task-management engine over a .plans/ JSONL ledger").version("0.1.0");
+	program.name("taskman").description("Task-management engine over a .plans/ JSONL ledger").version(packageVersion());
 	program.command("status").description("Progress + task ids/statuses for the active plan").option("--plan <name>", "plan name (or .plans/<name>) to inspect").option("--json", "machine-readable JSON output").action((opts) => statusCommand(opts));
 	program.command("list").description("List plans").option("--status <status>", "all|in-progress|done|superseded|abandoned").option("--sort <field>", "name|date-asc|date-desc|tasks").option("--json", "machine-readable JSON output").action((opts) => listPlansCommand(opts));
 	program.command("initiatives").description("List initiatives").option("--status <status>", "all|in-progress|done|superseded|abandoned").option("--json", "machine-readable JSON output").action((opts) => listInitiativesCommand(opts));
@@ -269,6 +417,8 @@ function buildProgram() {
 	program.command("update-task").description("Set a task status (done|skipped|blocked|pending)").argument("<id>", "task id, e.g. t-001").argument("<status>", "done|skipped|blocked|pending").option("--plan <name>", "plan to target").option("--notes <text>", "notes recorded on the task").option("--json", "machine-readable JSON output").action((id, status, opts) => updateTaskCommand(id, status, opts));
 	program.command("add-task").description("Append a deferred follow-up task").argument("<description>", "short task label").requiredOption("--reason <text>", "why this follow-up matters").option("--plan <name>", "plan to target").option("--details <text>", "fuller implementation notes").option("--json", "machine-readable JSON output").action((description, opts) => addTaskCommand(description, opts));
 	program.command("reconcile").description("Detect (and with --apply, repair) status drift").option("--apply", "repair safe in-progress→done drift").option("--json", "machine-readable JSON output").action((opts) => reconcileCommand(opts));
+	program.command("create-plan").description("Create a plan (tasks.jsonl + HANDOFF.md + registry entry) from any harness").requiredOption("--name <name>", "short kebab-case plan name").requiredOption("--title <title>", "human-readable plan title").option("--handoff <text>", "HANDOFF.md markdown (inline)").option("--handoff-file <path>", "read HANDOFF.md markdown from a file (\"-\" for stdin)").option("--tasks <json>", "tasks as an inline JSON array of { description, ... }").option("--tasks-file <path>", "read the tasks JSON array from a file (\"-\" for stdin)").option("--initiative <name>", "parent initiative name to link this plan to").option("--depends-on <names>", "comma-separated plan names this plan depends on").option("--json", "machine-readable JSON output").action((opts) => createPlanCommand(opts));
+	program.command("create-handoff").description("Write/replace HANDOFF.md for a plan from any harness").argument("[content]", "HANDOFF.md markdown (inline); else use --file or stdin").option("--plan <name>", "plan to target").option("--file <path>", "read markdown from a file (\"-\" for stdin)").option("--json", "machine-readable JSON output").action((content, opts) => createHandoffCommand(content, opts));
 	program.command("close").description("Set a plan lifecycle status").argument("<status>", "done|superseded|abandoned|in-progress").option("--plan <name>", "plan to target").option("--reason <text>", "why (recorded in the registry)").option("--json", "machine-readable JSON output").action((status, opts) => closePlanCommand(status, opts));
 	program.command("close-initiative").description("Set an initiative lifecycle status").argument("<status>", "done|superseded|abandoned|in-progress").argument("<name>", "initiative name").option("--reason <text>", "why (recorded in the registry)").option("--json", "machine-readable JSON output").action((status, name, opts) => closeInitiativeCommand(status, name, opts));
 	return program;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/taskman",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Standalone task-management engine + CLI over a .plans/ JSONL ledger — the plan-mode core, usable from any Node harness",
   "keywords": [
     "tasks",

package/skills/taskman/core/SKILL.md

@@ -2,13 +2,14 @@
 name: taskman/core
 description: >
   Drive the taskman CLI and engine over a .plans/ JSONL ledger — plans,
-  initiatives, and tasks. Load when running `taskman` commands (status, list,
-  update-task, add-task, reconcile, close), tracking plan/task progress across
-  sessions or harnesses, or calling @dreki-gg/taskman as a library. Covers the
-  status-is-a-projection model, stateless plan resolution, and reconcile.
+  initiatives, and tasks. Load when running `taskman` commands (create-plan,
+  create-handoff, status, list, update-task, add-task, reconcile, close),
+  tracking plan/task progress across sessions or harnesses, or calling
+  @dreki-gg/taskman as a library. Covers the status-is-a-projection model,
+  stateless plan resolution, and reconcile.
 type: core
 library: "@dreki-gg/taskman"
-library_version: "0.2.1"
+library_version: "0.3.1"
 sources:
   - "dreki-gg/pi-extensions:packages/taskman/README.md"
   - "dreki-gg/pi-extensions:packages/taskman/src/cli.ts"
@@ -65,6 +66,23 @@ taskman add-task "handle empty input" --reason "found gap while implementing"
 taskman reconcile --apply       # repair safe (in-progress→done) drift
 ```
 
+### Creating plans from any harness
+
+Plans don't have to originate in plan-mode's `submit_plan` tool. The CLI creates
+the same durable artifacts (tasks.jsonl + HANDOFF.md + registry entry) so a
+foreign harness can seed the ledger directly. Handoff/task payloads accept an
+inline value, a `--*-file <path>`, or piped stdin.
+
+```bash
+echo "$MARKDOWN" | taskman create-plan --name my-plan --title "My Plan" \
+  --handoff-file - --tasks '[{"description":"do it"}]'   # tasks get t-NNN ids
+taskman create-handoff --plan my-plan --file HANDOFF.md   # write/replace prose
+```
+
+Use `--initiative <name>` to link the plan (create the initiative first) and
+`--depends-on a,b` for plan-level ordering. Task creation here is plan setup —
+distinct from `add-task`, which records a *deferred* follow-up (see below).
+
 ### Machine-readable output
 
 Every command prints human text by default and accepts `--json`: