@pavel.sommer/agiter 0.0.0-stage → 0.8.0-alpha.0

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# agiter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A client-agnostic harness for spec-driven agentic development. The design is in
+[docs/design-recap.md](docs/design-recap.md).
+
+A run's pipeline is always given explicitly: a comma list of tokens, or a pipeline file
+(`*.json`, `{ "steps": [...] }`). A token is `task` (one round, no review) or `task:N` (at most
+N rounds; each round is a version and its review report).
+
+Status: step 1 (inputs, artifacts, tasks, pipelines, the run engine, simulation) and a first
+real executor: `agiter run` calls the agent CLI of each role's model profile
+(`.agiter/config/.models.<role>.json`, `.agiter/config/.models.json`, copied from the package's defaults on the first run; agents in `defs/agents.json`). In a git repository
+every run works on its own branch `agiter/<run>`, the harness commits every call, the scope
+of a step is checked against what git sees, and `agiter finish [--merge]` ends the run.
+
+## Layout
+
+| Path | Content |
+| --- | --- |
+| `index.mjs` | the public API |
+| `bin/agiter.mjs` | the CLI on commander (`agiter --help`, `agiter <command> --help`) |
+| `sidecar.mjs` | JSON-RPC over stdio for long-lived clients (Far Manager) |
+| `src/` | the modules: definitions, pipelines, artifacts, engine, tools, log |
+| `defs/` | the package's artifact types and tasks |
+| `test/` | `npm test` (node:test, no dependencies) |
+
+A project keeps everything in `.agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
+`logs/`, its own definitions (`artifacts/`, `tasks/`, merged over the package's) and
+`checks.json` (the required checks).
+
+## A run's files
+
+```text
+.agiter/docs/<run>/<run>.md                    the input, copied as it is (never changed)
+.agiter/docs/<run>/<run>.draft.1.md            round 1 of create-draft:3
+.agiter/docs/<run>/<run>.draft.1.report.md     its review: Block or Done, cumulative
+.agiter/docs/<run>/<run>.draft.2.md            round 2: input + draft.1 + its report
+...
+```
+
+A version is Active when another step follows and it has no review or its report is Done;
+otherwise Draft. A step takes only prose or an Active artifact whose latest report is not
+Block. The state of a run is its files: `agiter continue` walks the steps again and repeats
+nothing done.
+
+## Try it
+
+```text
+agiter list tasks
+agiter plan --pipeline "create-draft:3,create-spec:2,create-work,checks" --text "Add a login form"
+agiter simulate --pipeline "create-draft:3,create-spec:2,create-work" --text "Add a login form" --script script.json
+agiter continue --root <project printed by simulate>
+```
+
+A simulation script says what the fake model returns, per task, role and attempt:
+
+```json
+{
+	"steps": {
+		"create-draft#1/review": { "findings": [{ "text": "Problem unclear" }] },
+		"create-draft#2": { "responses": { "F-1": "fixed: Problem rewritten" } },
+		"create-work": { "changes": ["src/login.js"] }
+	}
+}
+```

package/bin/agiter.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * agiter: the command line, a thin layer over the API (index.mjs), parsed with commander.
+ * `agiter --help` and `agiter <command> --help` list the commands and their options.
+ * Exit codes: 0 done (or planned), 1 blocked, failed or invalid, 2 usage.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Command, CommanderError, Option } from "commander";
+import * as api from "../index.mjs";
+import { logCli } from "../src/log.mjs";
+
+const USAGE = 2;
+
+function tokenOf(s) { return s.rounds ? `${s.task}:${s.rounds}` : s.task; }
+
+function printRun(run) {
+	console.log(`run ${run.id}: ${run.status}${run.git ? `  (branch ${run.git.branch}${run.finished ? `, finished${run.finished.merged ? ", merged" : ""}` : ""})` : ""}`);
+	console.log(`  pipeline ${run.pipeline.steps.map(tokenOf).join(",")}, input ${run.input.type}`);
+	for (const s of run.steps) {
+		const what = s.outcome === "failed" ? `failed [${s.guard}] ${s.error}` : `${s.file ? path.posix.basename(s.file) : ""}${s.verdict ? ` ${s.verdict}` : ""}`;
+		console.log(`  ${String(s.step).padEnd(3)} ${s.task.padEnd(13)} ${(s.round ? `r${s.round}` : "").padEnd(4)}${s.role.padEnd(9)} ${what}`);
+	}
+	if (run.error) console.log(`  ${run.status} at step ${run.error.step} ${run.error.task}: ${run.error.message}\n  next: ${run.status === "blocked" ? "a new input with the answers, or " : ""}agiter continue ${run.id}`);
+	else if (run.status === "done" && run.git && !run.finished) console.log(`  next: agiter finish ${run.id} --merge (or without --merge to keep the branch)`);
+}
+
+const pad2 = (n) => String(n).padStart(2, "0");
+/** A time in the machine's zone: yyyy-MM-dd HH:mm. */
+const local = (iso) => { const d = new Date(iso); return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`; };
+const duration = (s) => (s < 60 ? `${Math.round(s)} s` : s < 3600 ? `${Math.floor(s / 60)} min ${pad2(Math.round(s % 60))} s` : `${Math.floor(s / 3600)} h ${pad2(Math.floor((s % 3600) / 60))} min`);
+
+/** The RegExp of a --list or --delete value (true: no pattern), or a usage error. */
+function patternOf(value, option, cmd) {
+	if (typeof value !== "string") return null;
+	try { return new RegExp(value, "i"); } catch (e) { cmd.error(`error: --${option}: ${e.message}`, { exitCode: USAGE, code: "agiter.pattern" }); }
+}
+
+const runLine = (r) => `${local(r.created)}  ${r.status.padEnd(8)} ${duration(r.seconds).padStart(12)}  ${String(r.calls).padStart(3)} calls  ${r.id}  ${r.pipeline}${r.name ? `  "${r.name}"` : ""}${r.finished ? (r.finished.merged ? "  merged" : "  finished") : ""}${r.error ? `  [${r.error}]` : ""}`;
+
+/** run --list [pattern]: the runs, one per line. */
+function listRunsOf(opts, cmd) {
+	if (opts.failed || opts.done || opts.all || opts.yes) cmd.error(`error: options '--failed', '--done', '--all' and '--yes' belong to --delete`, { exitCode: USAGE, code: "agiter.delete" });
+	const pattern = patternOf(opts.list, "list", cmd);
+	const runs = api.listRuns(rootOf(opts), pattern, { order: opts.asc ? "asc" : "desc" });
+	print(opts, runs, () => {
+		for (const r of runs) console.log(runLine(r));
+		if (!runs.length) console.log(pattern ? `no run matches /${opts.list}/` : "no runs");
+	});
+}
+
+/** Ask a yes/no question on the terminal. */
+async function confirm(question) {
+	const { createInterface } = await import("node:readline/promises");
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try { return /^y(es)?$/i.test((await rl.question(question)).trim()); } finally { rl.close(); }
+}
+
+/** run --delete --all [--yes]: every run and last.json, after two warnings. */
+async function deleteAllOf(opts, cmd, root) {
+	if (typeof opts.delete === "string" || opts.failed || opts.done) cmd.error("error: --all stands alone: no pattern, --failed or --done with it", { exitCode: USAGE, code: "agiter.all" });
+	const runs = api.listRuns(root);
+	const folders = fs.existsSync(path.join(root, ".agiter", "runs")) ? fs.readdirSync(path.join(root, ".agiter", "runs"), { withFileTypes: true }).filter((d) => d.isDirectory()).length : 0;
+	if (!folders) { print(opts, { deleted: [] }, () => console.log("no run to delete")); return; }
+	if (!opts.yes) {
+		if (!process.stdin.isTTY) cmd.error(`error: --delete --all would delete all ${folders} run(s); confirm with --yes when the input is not a terminal`, { exitCode: USAGE, code: "agiter.confirm" });
+		for (const r of runs) console.log(runLine(r));
+		if (folders > runs.length) console.log(`and ${folders - runs.length} broken run folder(s)`);
+		console.log(`\nWARNING: this deletes ALL ${folders} run(s) of ${root}: their records, audits, logs of calls and every artifact they made. It cannot be undone.`);
+		if (!(await confirm("Delete all runs? [y/N] "))) { console.log("nothing deleted"); process.exitCode = 1; return; }
+		const { createInterface } = await import("node:readline/promises");
+		const rl = createInterface({ input: process.stdin, output: process.stdout });
+		let typed;
+		try { typed = (await rl.question(`SECOND WARNING: type "delete all" to delete all ${folders} run(s): `)).trim(); } finally { rl.close(); }
+		if (typed !== "delete all") { console.log("nothing deleted"); process.exitCode = 1; return; }
+	}
+	logCli(root, process.argv.slice(2));
+	const { deleted } = api.deleteRuns(root, { all: true });
+	print(opts, { deleted }, () => console.log(`deleted all ${deleted.length} run(s); last.json cleared`));
+}
+
+/** run --delete [pattern] [--failed] [--done] [--yes]: delete runs, after showing them. */
+async function deleteRunsOf(opts, cmd) {
+	if (opts.asc || opts.desc) cmd.error(`error: options '--asc' and '--desc' belong to --list`, { exitCode: USAGE, code: "agiter.order" });
+	const root = rootOf(opts);
+	if (opts.all) return deleteAllOf(opts, cmd, root);
+	const pattern = patternOf(opts.delete, "delete", cmd);
+	const statuses = [...(opts.failed ? ["failed"] : []), ...(opts.done ? ["done"] : [])];
+	if (!pattern && !statuses.length) {
+		const all = api.listRuns(root);
+		const message = "--delete needs a restriction: a pattern, --failed or --done (a pattern \".\" selects every run)";
+		print(opts, { deleted: [], problems: [message], runs: all }, () => {
+			console.log(`${message}. The runs:`);
+			for (const r of all) console.log(`  ${runLine(r)}`);
+			if (!all.length) console.log("  no runs");
+		});
+		process.exitCode = USAGE;
+		return;
+	}
+	const runs = api.listRuns(root, pattern).filter((r) => !statuses.length || statuses.includes(r.status));
+	if (!runs.length) { print(opts, { deleted: [] }, () => console.log("no run to delete")); return; }
+	if (!opts.yes) {
+		if (!process.stdin.isTTY) cmd.error(`error: --delete would delete ${runs.length} run(s); confirm with --yes when the input is not a terminal`, { exitCode: USAGE, code: "agiter.confirm" });
+		for (const r of runs) console.log(runLine(r));
+		if (!(await confirm(`Delete these ${runs.length} run(s) with their artifacts? This cannot be undone. [y/N] `))) { console.log("nothing deleted"); process.exitCode = 1; return; }
+	}
+	logCli(root, process.argv.slice(2));
+	const { deleted } = api.deleteRuns(root, { pattern, statuses });
+	print(opts, { deleted }, () => console.log(`deleted ${deleted.length} run(s)${opts.yes ? `: ${deleted.map((r) => r.id).join(", ")}` : ""}`));
+}
+
+const clockOf = (iso) => { const d = new Date(iso); return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`; };
+
+/**
+ * The live view of a run for the terminal: every event as it happens, and (unless quiet) the
+ * agents' output as it comes, indented under the call. None with --json (the result is JSON).
+ */
+function live(opts) {
+	if (opts.json) return {};
+	let pending = "";
+	const flush = () => { if (pending) { process.stdout.write(`    | ${pending}\n`); pending = ""; } };
+	const onEvent = (e) => {
+		flush();
+		console.log(`${clockOf(e.at)}  ${e.event.padEnd(13)} ${e.detail}`);
+	};
+	const onOutput = opts.quiet ? undefined : ({ text }) => {
+		const lines = (pending + text.replace(/\r\n?/g, "\n")).split("\n");
+		pending = lines.pop();
+		for (const l of lines) process.stdout.write(`    | ${l}\n`);
+	};
+	return { onEvent, onOutput, done: flush };
+}
+
+/** The --pipeline value: the shell may split an unquoted list ("a:2, b") into several items. */
+const pipelineOf = (items) => [].concat(items).join(" ");
+
+const rootOf = (opts) => path.resolve(opts.root ?? ".");
+const print = (opts, data, text) => { if (opts.json) console.log(JSON.stringify(data, null, "\t")); else text(); };
+const problems = (opts, r) => { print(opts, r, () => r.problems.forEach((p) => console.log(`problem: ${p}`))); return 1; };
+
+/** The options of a command that takes a scenario (`required`: --pipeline must be given). */
+function scenario(cmd, required = true) {
+	const pipeline = ["--pipeline <steps...>", "a pipeline file (*.json) or a comma list of task (one round, no review) and task:N (at most N rounds with review)"];
+	return (required ? cmd.requiredOption(...pipeline) : cmd.option(...pipeline))
+		.addOption(new Option("--input <file>", "the input file: prose, or an Active artifact").conflicts("text"))
+		.addOption(new Option("--text <text>", "the input as text").conflicts("input"))
+		.option("--name <name>", "the request's name (default: the input file's name; for text, each step's own heading)");
+}
+
+const common = (cmd) => cmd.option("--root <dir>", "the project (default: the current folder)").option("--json", "the result as JSON");
+
+export function program() {
+	const prog = new Command("agiter")
+		.description("A harness for spec-driven agentic development.")
+		.showHelpAfterError("(agiter --help, or agiter <command> --help)")
+		.exitOverride();
+
+	common(prog.command("init").description("make the folder an agiter project: .agiter/ with the default model config in .agiter/config/")).action((opts) => {
+		const r = api.initProject({ root: rootOf(opts) });
+		print(opts, r, () => {
+			for (const f of r.created) console.log(`created ${f}`);
+			for (const f of r.existed) console.log(`kept    ${f} (exists)`);
+		});
+	});
+
+	common(scenario(prog.command("plan").description("plan a scenario without running it"))).action((opts) => {
+		const r = api.planScenario({ root: rootOf(opts), pipeline: pipelineOf(opts.pipeline), input: opts.input, text: opts.text, name: opts.name });
+		print(opts, { ok: r.ok, problems: r.problems, name: r.name, plan: r.plan }, () => {
+			if (r.ok) console.log(`name: ${r.name ?? "(each step's own heading)"}`);
+			for (const s of r.plan ?? []) console.log(`  ${String(s.n).padEnd(3)} ${tokenOf(s).padEnd(16)} ${(s.input ?? "-").padEnd(6)} -> ${s.output.padEnd(7)} <run>.${s.name}.<round>.md${s.rounds ? " + .report.md" : ""}`);
+			for (const p of r.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = r.ok ? 0 : 1;
+	});
+
+	const runner = (simulate) => async (opts) => {
+		let root = rootOf(opts);
+		let simulation = null;
+		if (simulate) {
+			let script = {};
+			if (opts.script) { try { script = JSON.parse(fs.readFileSync(path.resolve(opts.script), "utf8")); } catch (e) { throw new CommanderError(USAGE, "agiter.script", `--script: ${e.message}`); } }
+			simulation = { script };
+			if (!opts.root) { root = fs.mkdtempSync(path.join(os.tmpdir(), "agiter-sim-")); fs.mkdirSync(path.join(root, ".agiter")); }
+		}
+		logCli(root, process.argv.slice(2));
+		const view = live(opts);
+		if (simulate && !opts.json) console.log(`project: ${root}`);
+		const r = await api.startRun({ root, pipeline: pipelineOf(opts.pipeline), input: opts.input, text: opts.text, name: opts.name, simulation, fresh: Boolean(opts.new), audit: Boolean(opts.audit), onEvent: view.onEvent, onOutput: view.onOutput });
+		view.done?.();
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		print(opts, { root, resumed: r.resumed, run: r.run }, () => {
+			if (r.resumed) console.log("resumed the unfinished run of the same scenario (--new starts a new one)");
+			console.log("");
+			printRun(r.run);
+		});
+		process.exitCode = r.run.status === "done" ? 0 : 1;
+	};
+	const runOptions = (cmd) => cmd
+		.option("--new", "start a new run even when an unfinished run of the same scenario exists")
+		.option("--audit", "record every executor call in .agiter/runs/<run>/audit.jsonl")
+		.option("--quiet", "show only the harness's events, not the agents' output");
+
+	const run = runOptions(scenario(prog.command("run").description("run a scenario (an unfinished run of the same scenario is resumed), or list the runs with --list"), false))
+		.addOption(new Option("--list [pattern]", "list the runs (newest first; --asc for oldest first); a regular expression keeps those whose id, name or pipeline it matches (case-insensitive)")
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet"]))
+		.addOption(new Option("--delete [pattern]", "delete runs (their records and artifacts) whose id, name or pipeline the regular expression matches, narrowed by --failed and --done; one restriction at least (\".\" for every run)")
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet", "list"]))
+		.option("--failed", "with --delete: only failed runs (with --done: failed or done ones)")
+		.option("--done", "with --delete: only done runs (with --failed: failed or done ones)")
+		.option("--all", "with --delete: delete every run and clear last.json (asks twice)")
+		.option("--yes", "with --delete: do not ask (needed when the input is not a terminal)")
+		.addOption(new Option("--asc", "with --list: oldest first").conflicts(["desc"]))
+		.addOption(new Option("--desc", "with --list: newest first (the default)").conflicts(["asc"]));
+	common(run).action(async (opts, cmd) => {
+		if (opts.list !== undefined) return listRunsOf(opts, cmd);
+		if (opts.delete !== undefined) return deleteRunsOf(opts, cmd);
+		for (const o of ["failed", "done", "all", "yes"]) if (opts[o]) cmd.error(`error: option '--${o}' belongs to --delete`, { exitCode: USAGE, code: "agiter.delete" });
+		if (opts.asc || opts.desc) cmd.error(`error: option '--${opts.asc ? "asc" : "desc"}' belongs to --list`, { exitCode: USAGE, code: "agiter.order" });
+		if (!opts.pipeline) cmd.error("error: required option '--pipeline <steps...>' not specified (or --list)", { exitCode: USAGE, code: "agiter.pipeline" });
+		return runner(false)(opts);
+	});
+	common(runOptions(scenario(prog.command("simulate").description("run a scenario with a scripted fake model (a new temporary project without --root)")))
+		.option("--script <file>", "what the fake model returns, per task, role and attempt")).action(runner(true));
+
+	common(prog.command("continue").argument("[run]", "the run id", "last").description("walk a run's steps again from its files")
+		.option("--audit", "turn the run's audit on from now")
+		.option("--quiet", "show only the harness's events, not the agents' output")).action(async (id, opts) => {
+		const root = rootOf(opts);
+		logCli(root, process.argv.slice(2));
+		const view = live(opts);
+		const r = await api.continueRun({ root, run: id, audit: Boolean(opts.audit), onEvent: view.onEvent, onOutput: view.onOutput });
+		view.done?.();
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		print(opts, { run: r.run }, () => { console.log(""); printRun(r.run); });
+		process.exitCode = r.run.status === "done" ? 0 : 1;
+	});
+
+	common(prog.command("finish").argument("[run]", "the run id", "last").description("end a git run: back to the branch it started from, with --merge of its branch (a done run) or without")
+		.option("--merge", "merge the run's branch into the branch it started from (no fast-forward)")).action((id, opts) => {
+		const root = rootOf(opts);
+		logCli(root, process.argv.slice(2));
+		const r = api.finishRun({ root, run: id, merge: Boolean(opts.merge) });
+		if (!r.ok) { process.exitCode = problems(opts, r); return; }
+		const back = r.run.git.baseBranch ?? `detached ${r.run.git.base.slice(0, 10)}`;
+		print(opts, { run: r.run, merged: r.merged }, () => console.log(r.merged ? `merged ${r.run.git.branch} into ${back}` : `back on ${back}; ${r.run.git.branch} is kept (finish --merge later, or delete it)`));
+	});
+
+	common(prog.command("status").argument("[run]", "the run id", "last").description("show a run")).action((id, opts) => {
+		const root = rootOf(opts);
+		const run = api.loadRun(root, id);
+		if (!run) { console.error(`agiter: no run ${id} in ${root}`); process.exitCode = 1; return; }
+		print(opts, run, () => printRun(run));
+	});
+
+	common(prog.command("runs").description("list the runs, newest first")).action((opts) => {
+		const runs = api.listRuns(rootOf(opts));
+		print(opts, runs, () => runs.forEach((r) => console.log(`${r.id}  ${r.status.padEnd(8)} ${r.pipeline}`)));
+	});
+
+	common(prog.command("audit").argument("[run]", "the run id", "last").description("show a run's audit")).action((id, opts) => {
+		const root = rootOf(opts);
+		const run = api.loadRun(root, id);
+		if (!run) { console.error(`agiter: no run ${id} in ${root}`); process.exitCode = 1; return; }
+		const lines = api.readAudit(root, run.id);
+		if (!run.audit && !lines.length) { console.error(`agiter: run ${run.id} has no audit (it ran without --audit)`); process.exitCode = 1; return; }
+		print(opts, lines, () => {
+			console.log(`audit of ${run.id} (${run.status}): ${lines.length} call(s), ${lines.reduce((t, a) => t + a.seconds, 0).toFixed(1)} s`);
+			for (const a of lines) {
+				const who = a.agent ? `${a.agent}${a.model ? ` ${a.model}` : ""}` : a.executor;
+				const end = a.outcome === "ok" ? (a.verdict ? `${a.verdict} (${a.blocking} blocking)` : "ok") : `${a.outcome} [${a.guard}]`;
+				console.log(`  ${String(a.step).padEnd(3)} ${a.task.padEnd(13)} ${(a.round ? `r${a.round}` : "").padEnd(4)}${a.role.padEnd(9)} ${who.padEnd(46)} ${a.seconds.toFixed(1).padStart(7)} s  ${end}`);
+			}
+		});
+	});
+
+	common(prog.command("list").addArgument(new Command().createArgument("<kind>", "what to list").choices(["artifacts", "tasks"])).description("list the definitions")).action((kind, opts) => {
+		const defs = api.loadDefs(rootOf(opts));
+		const items = [...defs[kind].values()];
+		print(opts, { problems: defs.problems, items }, () => {
+			for (const d of items) {
+				const detail = kind === "tasks" ? `${[].concat(d.input).join("|")} -> ${d.output} [${d.executor}]${d.rounds ? ` rounds ${d.rounds}` : ""}` : d.statuses.join(" / ");
+				console.log(`${d.id.padEnd(17)} ${detail}${d.layer === "project" ? "  (project)" : ""}`);
+			}
+			for (const p of defs.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = defs.problems.length ? 1 : 0;
+	});
+
+	common(prog.command("roles").description("the roles (for now only --list)").option("--list", "list the roles and their tasks")).action((opts, cmd) => {
+		if (!opts.list) cmd.error("error: roles: only --list is supported for now", { exitCode: USAGE, code: "agiter.roles" });
+		const defs = api.loadDefs(rootOf(opts));
+		const roles = api.listRoles(defs);
+		print(opts, { problems: defs.problems, roles }, () => {
+			for (const r of roles) console.log(`${r.role.padEnd(10)} ${[...r.tasks, ...(r.reviewsRounds ? ["every round of a step with :N"] : [])].join(", ")}`);
+			for (const p of defs.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = defs.problems.length ? 1 : 0;
+	});
+
+	prog.command("sidecar").description("serve the API as JSON-RPC over stdio (for Far Manager)").action(async () => {
+		const { serve } = await import("../sidecar.mjs");
+		await serve();
+	});
+
+	return prog;
+}
+
+/** Run the command line `argv` (without node and the script); the exit code. */
+export async function main(argv) {
+	const prog = program();
+	if (!argv.length) { prog.outputHelp(); return 0; }
+	try {
+		await prog.parseAsync(argv, { from: "user" });
+		return process.exitCode ?? 0;
+	} catch (e) {
+		if (!(e instanceof CommanderError)) throw e;
+		if (["commander.helpDisplayed", "commander.help", "commander.version"].includes(e.code)) return 0;
+		if (e.code === "agiter.script") console.error(`agiter: ${e.message}`);
+		return USAGE;
+	}
+}
+
+const self = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(new URL(import.meta.url));
+if (self) process.exitCode = await main(process.argv.slice(2));

package/defs/.models.architect.json

@@ -0,0 +1,9 @@
+{
+	"default": {
+		"agent": "claude",
+		"models": [],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.author.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.drafter.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.reviewer.json

@@ -0,0 +1,9 @@
+{
+	"default": {
+		"agent": "claude",
+		"models": [],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 30
+	}
+}

package/defs/.models.worker.json

@@ -0,0 +1,11 @@
+{
+	"default": {
+		"agent": "opencode",
+		"models": [
+			"openrouter/deepseek/deepseek-v4.1-flash"
+		],
+		"select": "availableFirst",
+		"effort": "high",
+		"timeoutMinutes": 60
+	}
+}

package/defs/agents.json

@@ -0,0 +1,48 @@
+{
+	"opencode": {
+		"title": "opencode run (as in Methodology's default profile)",
+		"command": [
+			"opencode",
+			"run",
+			"--auto",
+			"--thinking"
+		],
+		"model": [
+			"-m",
+			"{model}"
+		],
+		"message": [
+			"{message}"
+		]
+	},
+	"claude": {
+		"title": "Claude Code, print mode; the prompt comes right after -p (the tool options take several values); the reviewer reads only",
+		"command": [
+			"claude",
+			"-p",
+			"{message}"
+		],
+		"model": [
+			"--model",
+			"{model}"
+		],
+		"roles": {
+			"reviewer": [
+				"--allowedTools",
+				"Read,Grep,Glob",
+				"--disallowedTools",
+				"Write,Edit,NotebookEdit"
+			],
+			"*": [
+				"--allowedTools",
+				"Read,Grep,Glob,Write,Edit"
+			]
+		},
+		"dropEnv": [
+			"ANTHROPIC_BASE_URL",
+			"ANTHROPIC_AUTH_TOKEN",
+			"ANTHROPIC_API_KEY",
+			"ANTHROPIC_MODEL"
+		]
+	}
+}

package/defs/artifacts/checks.json

@@ -0,0 +1,12 @@
+{
+	"title": "Checks",
+	"summary": "The results of the project's required checks.",
+	"sections": [
+		"Results"
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/draft.json

@@ -0,0 +1,18 @@
+{
+	"title": "Draft",
+	"summary": "A worked-out proposal of what to build and why.",
+	"sections": [
+		"Problem",
+		"Proposal"
+	],
+	"criteria": [
+		"The problem is stated from the user's side.",
+		"The proposal is concrete enough to be split into specs.",
+		"Nothing is guessed: every unclear point is a finding."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/epic.json

@@ -0,0 +1,17 @@
+{
+	"title": "Epic",
+	"summary": "A larger goal split into specs.",
+	"sections": [
+		"Goal",
+		"Scope"
+	],
+	"criteria": [
+		"The goal is measurable.",
+		"The scope names what is out of it."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/idea.json

@@ -0,0 +1,10 @@
+{
+	"title": "Idea",
+	"summary": "The owner's request as prose; usually a file without frontmatter.",
+	"sections": [],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/initiative.json

@@ -0,0 +1,18 @@
+{
+	"title": "Initiative",
+	"summary": "The whole goal of a larger change and its functional areas.",
+	"sections": [
+		"Goal",
+		"Functional areas"
+	],
+	"criteria": [
+		"The goal says what changes for the users.",
+		"Every functional area has an id and a short scope.",
+		"Nothing is guessed: every unclear point is a finding."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/report.json

@@ -0,0 +1,12 @@
+{
+	"title": "Report",
+	"summary": "The review of one version: its findings, cumulative over the rounds.",
+	"statuses": [
+		"Block",
+		"Done"
+	],
+	"sections": [
+		"Findings",
+		"Closed"
+	]
+}

package/defs/artifacts/spec.json

@@ -0,0 +1,18 @@
+{
+	"title": "Spec",
+	"summary": "One implementable change with its acceptance criteria.",
+	"sections": [
+		"Goal",
+		"Acceptance"
+	],
+	"criteria": [
+		"Every acceptance criterion is testable.",
+		"The spec names the files or areas it changes.",
+		"Nothing is left for the Worker to decide."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/work.json

@@ -0,0 +1,17 @@
+{
+	"title": "Work",
+	"summary": "The record of a change made to the code, tests included.",
+	"sections": [
+		"Changes"
+	],
+	"criteria": [
+		"The changes meet the spec's acceptance criteria.",
+		"Nothing outside the spec's scope changed.",
+		"Tests cover the acceptance criteria."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/tasks/checks.json

@@ -0,0 +1,7 @@
+{
+	"title": "Run the project's required checks",
+	"executor": "tool",
+	"tool": "checks",
+	"input": "*",
+	"output": "checks"
+}