@pavel.sommer/agiter 0.8.0-alpha.0 → 0.27.0-alpha.0

package/README.md

@@ -3,15 +3,44 @@
 A client-agnostic harness for spec-driven agentic development. The design is in
 [docs/design-recap.md](docs/design-recap.md).
 
+## The key idea: diverse points of view
+
+Every step of a run is done by separate agents, each starting with a fresh context: the author
+writes, the reviewer judges what was written against the input and the criteria, without the
+author's reasoning in view, so it has nothing to anchor on and no decision of its own to
+defend. A next round's author gets its version and the review, not its earlier train of
+thought. One long prompting session cannot give this: there a model judges its own work with
+the whole path to it still in context, like a person proofreading what he wrote a minute ago.
+
+Context diversity works with the same model too. Model diversity adds a second layer: a
+model's blind spots come from its training, and a fresh context does not remove them, a
+different model does. That is why each role has its own model profile
+(`agiter/config/.models.<role>.json`): a cheap author and a stronger reviewer of another family
+make a good pair.
+
+## How it works
+
 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).
 
+The project's tech stack lives in `agiter/config/.stack.json` (blocks and presets, `agiter
+stack --help`); the harness puts into each model's prompt only what its role needs from it, then the owner's
+`agiter/config/project.md` (structure, naming, scaffolding, rules) for every role. `--includeFile
+<file>` (repeatable) gives any file to every model call of a run. `create-epics` breaks an initiative down into its functional areas and writes one epic file per
+epic (`<run>.create-epics.<round>.E1.md`, …) next to an overview. `--lang <tag>` (an ISO tag: `cs`, `en`,
+`cs-CZ`, `en-US`, …) sets the language of the output; without it the models write in the language
+of the input. The headings the harness reads stay in English, and so do established technical
+terms and common anglicisms.
+
 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.
+(`agiter/config/.models.<role>.json`, `agiter/config/.models.json`, and the agents in `agiter/config/.agents.json`, all copied from the package's defaults by `agiter init` or the first run). In a git repository
+a run works in the current checkout by default (no harness commits; the owner reviews and
+commits the changes), with `--isolation branch` on its own branch `agiter/<run>` with a commit
+per call, or with `--isolation worktree` in `agiter/.worktrees/<run>` on that branch with the
+project's `node_modules` linked in. The scope of a step is checked against what git sees, and
+`agiter finish [--merge]` ends a branch or worktree run.
 
 ## Layout
 
@@ -21,23 +50,57 @@ of a step is checked against what git sees, and `agiter finish [--merge]` ends t
 | `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 |
+| `defs/` | the package's artifact types, tasks, stack blocks and presets, default config |
 | `test/` | `npm test` (node:test, no dependencies) |
 
-A project keeps everything in `.agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
+The owner's documents stay his: any file a run did not write is an input in the owner's own form
+(with a frontmatter `type` it runs only with status `Active`; without one it runs as it is);
+the pipeline decides what it is (`create-epics`: an initiative), and its frontmatter, status and
+structure are not checked. A run is named after the input file without its leading timestamp and
+stamped in local time (`yyMMddHHmmss`); the titles of the outputs are the models' own.
+
+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
+agiter/docs/<run>/.<run>.md                   the input, copied as it is (never changed; a dot file)
+agiter/docs/<run>/.<run>.draft.1.md           round 1 of create-draft:3 (a dot file)
+agiter/docs/<run>/.<run>.draft.1.report.md    its review: Block or Done, cumulative (a dot file)
+agiter/docs/<run>/.<run>.draft.2.md           round 2: input + draft.1 + its report
+agiter/docs/<run>/<run>.create-work.1.md      the record of create-work
+docs/<run>.draft.md                           the result of a step, published
+docs/<run>.draft.report.md                    the step's last report, published
+docs/<run>.decisions.md                       the decisions report, for the owner to answer
+docs/<run>.epic.E1.md                         an epic of create-epics, published
 ...
 ```
 
+Two kinds of output. Methodical artifacts (initiative, epic, draft, spec) are the documents a
+next run builds on: the result of each step (no review, or its report Done) is published to
+`docs/` (`agiter/config/.settings.json` `{ "docs": "<folder>" }` changes it), never over a
+file there, and agents never change them. Task records (`create-epics`, `create-work`,
+`create-tests`, `checks`) and the reports stay in `agiter/docs/<run>/` with every round; the versions of methodical
+artifacts there are dot files, so a client like Tolaria shows each document once (in `docs/`).
+Where the input does not say something, the models decide on their own and record it under
+"Decisions" (`[owner]` or `[author]`); at the end of a run the harness collects them into
+`docs/<run>.decisions.md` (beside the owner's documents), the owner's first, each with an `Answer:` line, so the
+answered file can be the input of a next run.
+A run on a document an earlier run wrote (an epic, a spec) gets that run's answered decisions in
+its prompt by itself: they override the document where they differ.
+Each document's frontmatter has the `model` that wrote it and the `cost` of that call.
+Every model call's cost and tokens come from the agent's JSON output (opencode `--format json`,
+claude `--output-format json`): `status` shows them per call and for the run, `run --list` per run.
+At the end of a run the file names in its documents become wikilinks (`[[name]]`, as Tolaria
+resolves them), to the notes in view: a version of the chain links to its published document.
+Their frontmatter gets Tolaria's relationships too: `belongs_to` and `related_to` as wikilinks.
+The owner's input file gets `has` (wikilinks to what runs made from it and keep), `model` (the
+models they used) and `cost` (their total).
+Frontmatter types are TitleCase and singular (`Spec`, `Epic`, `Report`, `Decision`); every task's
+record is `Pipeline`, its `task` (`create-epics`, `create-work`, …) tells which.
+
 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

package/bin/agiter.mjs

@@ -6,8 +6,10 @@
  */
 
 import fs from "node:fs";
+import { money, tokens } from "../src/usage.mjs";
 import os from "node:os";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { Command, CommanderError, Option } from "commander";
 import * as api from "../index.mjs";
 import { logCli } from "../src/log.mjs";
@@ -17,14 +19,25 @@ 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}`);
+	const where = !run.git ? "" : (run.git.mode ?? "branch") === "none" ? "  (no isolation: the checkout itself)" : `  (${run.git.mode === "worktree" ? `worktree ${run.git.worktree}, ` : ""}branch ${run.git.branch}${run.finished ? `, finished${run.finished.merged ? ", merged" : ""}` : ""})`;
+	console.log(`run ${run.id}: ${run.status}${where}`);
+	console.log(`  pipeline ${run.pipeline.steps.map(tokenOf).join(",")}, input ${run.input.type}${run.lang ? `, output in ${run.lang}` : ""}`);
 	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}`);
+		console.log(`  ${String(s.step).padEnd(3)} ${s.task.padEnd(13)} ${(s.round ? `r${s.round}` : "").padEnd(4)}${s.role.padEnd(9)} ${what}${s.usage ? `  ${money(s.usage)}` : ""}`);
+	}
+	if (run.steps.some((s) => s.executor === "model" || s.executor === "fake")) {
+		const calls = run.steps.filter((s) => s.executor === "model");
+		const missing = calls.filter((s) => !s.usage).length;
+		console.log(`  cost: ${run.usage ? `${money(run.usage)} (${tokens(run.usage)})` : "no usage data"}${missing && run.usage ? `; ${missing} call(s) without usage data` : ""}`);
+	}
+	if (run.decisions) {
+		const d = run.decisions;
+		console.log(`  decisions: ${d.owner ?? 0} for you${d.review ? `, ${d.review} open from the review` : ""}, ${(d.owner ?? 0) + (d.review ?? 0) + (d.unmarked ?? 0) + (d.author ?? 0)} in all -> ${d.file}`);
 	}
 	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)`);
+	else if (run.status === "done" && run.git && (run.git.mode ?? "branch") !== "none" && !run.finished) console.log(`  next: agiter finish ${run.id} --merge (or without --merge to keep the branch)`);
+	else if (run.status === "done" && run.git?.mode === "none") console.log("  next: review the changes (git status, git diff) and commit them");
 }
 
 const pad2 = (n) => String(n).padStart(2, "0");
@@ -38,7 +51,7 @@ function patternOf(value, option, cmd) {
 	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}]` : ""}`;
+const runLine = (r) => `${local(r.created)}  ${r.status.padEnd(8)} ${duration(r.seconds).padStart(12)}  ${String(r.calls).padStart(3)} calls ${money(r.usage).padStart(9)}  ${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) {
@@ -62,7 +75,7 @@ async function confirm(question) {
 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;
+	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" });
@@ -136,7 +149,14 @@ function live(opts) {
 /** 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 ?? ".");
+/** The git work tree's top of the current folder, or null. */
+function gitTop() {
+	const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true });
+	return r.status === 0 ? path.resolve(r.stdout.trim()) : null;
+}
+
+/** The project: --root, else found from the current folder (src/init.mjs findProjectRoot). */
+const rootOf = (opts) => (opts.root ? path.resolve(opts.root) : api.findProjectRoot(process.cwd(), gitTop()));
 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; };
 
@@ -146,10 +166,13 @@ function scenario(cmd, required = true) {
 	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)");
+		.option("--name <name>", "the request's name (default: the input file's name; for text, each step's own heading)")
+		.option("--lang <tag>", "the language of the output, an ISO tag: cs, en, cs-CZ, en-US, … (default: the language of the input); the headings the harness reads stay in English")
+		.addOption(new Option("--isolation <mode>", "branch: a new branch agiter/<run> in this checkout; worktree: a separate checkout in agiter/.worktrees/<run> (node_modules linked). Without it: the checkout itself, no harness commits").choices(["branch", "worktree"]))
+		.option("--includeFile <file>", "a file every model call of the run gets whole in its prompt (repeat for more files); relative to the current folder, /<path> from the project's root", (v, prev) => [...prev, v], []);
 }
 
-const common = (cmd) => cmd.option("--root <dir>", "the project (default: the current folder)").option("--json", "the result as JSON");
+const common = (cmd) => cmd.option("--root <dir>", "the project (default: found from the current folder: the project it is in)").option("--json", "the result as JSON");
 
 export function program() {
 	const prog = new Command("agiter")
@@ -157,8 +180,12 @@ export function program() {
 		.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) });
+	common(prog.command("init").description("make the current folder (or --root) an agiter project: agiter/ with the default config in agiter/config/")).action((opts) => {
+		// The current folder, unless it is already inside a project (then that project).
+		const found = api.findProjectRoot(process.cwd());
+		const root = opts.root ? path.resolve(opts.root) : api.isProject(found) ? found : process.cwd();
+		const r = api.initProject({ root });
+		if (!opts.json && root !== process.cwd()) console.log(`project: ${root}`);
 		print(opts, r, () => {
 			for (const f of r.created) console.log(`created ${f}`);
 			for (const f of r.existed) console.log(`kept    ${f} (exists)`);
@@ -166,9 +193,11 @@ export function program() {
 	});
 
 	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 }, () => {
+		const r = api.planScenario({ root: rootOf(opts), pipeline: pipelineOf(opts.pipeline), input: opts.input, text: opts.text, name: opts.name, include: opts.includeFile, lang: opts.lang, isolation: opts.isolation ?? "none" });
+		print(opts, { ok: r.ok, problems: r.problems, name: r.name, lang: r.lang ?? null, include: r.include, plan: r.plan }, () => {
 			if (r.ok) console.log(`name: ${r.name ?? "(each step's own heading)"}`);
+			if (r.ok) console.log(`output language: ${r.lang ?? "(the input's)"}`);
+			if (r.include?.length) console.log(`files for every call: ${r.include.join(", ")}`);
 			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}`);
 		});
@@ -182,12 +211,13 @@ export function program() {
 			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")); }
+			// Without --root: the project the current folder is in, else a new temporary project.
+			if (!opts.root && !api.isProject(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 });
+		if ((simulate || root !== process.cwd()) && !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, include: opts.includeFile, lang: opts.lang, isolation: opts.isolation ?? "none", 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 }, () => {
@@ -199,14 +229,14 @@ export function program() {
 	};
 	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("--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"]))
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet", "includeFile", "isolation", "lang"]))
 		.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"]))
+			.conflicts(["pipeline", "input", "text", "name", "new", "audit", "quiet", "includeFile", "isolation", "lang", "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)")
@@ -221,7 +251,7 @@ export function program() {
 		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)")))
+	common(runOptions(scenario(prog.command("simulate").description("run a scenario with a scripted fake model (in the project the current folder is in, or --root; outside a project in a new temporary one)")))
 		.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")
@@ -230,6 +260,7 @@ export function program() {
 		const root = rootOf(opts);
 		logCli(root, process.argv.slice(2));
 		const view = live(opts);
+		if (root !== process.cwd() && !opts.json) console.log(`project: ${root}`);
 		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; }
@@ -238,7 +269,7 @@ export function program() {
 	});
 
 	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) => {
+		.option("--merge", "merge the run's branch into the branch it started from (no fast-forward); a worktree is removed after")).action((id, opts) => {
 		const root = rootOf(opts);
 		logCli(root, process.argv.slice(2));
 		const r = api.finishRun({ root, run: id, merge: Boolean(opts.merge) });
@@ -299,6 +330,76 @@ export function program() {
 		process.exitCode = defs.problems.length ? 1 : 0;
 	});
 
+	const stackCmd = prog.command("stack").description("the project's tech stack (agiter/config/.stack.json): list blocks, show what a role gets, change the selection")
+		.addOption(new Option("--list", "the blocks and presets of the package and the project").conflicts(["show", "add", "remove", "preset", "detect"]))
+		.addOption(new Option("--show [role]", "what the models get about the project (stack and project.md): everything, or only what a role gets").conflicts(["add", "remove", "preset", "detect"]))
+		.addOption(new Option("--add <blocks...>", "add blocks (id or id@version)").conflicts(["remove", "preset", "detect"]))
+		.addOption(new Option("--remove <blocks...>", "remove blocks").conflicts(["preset", "detect"]))
+		.addOption(new Option("--preset <id>", "start the selection from a preset (only when the project has none)").conflicts(["detect"]))
+		.option("--detect", "start the selection from the blocks the project's files show (only when the project has none)");
+	common(stackCmd).action((opts, cmd) => {
+		const root = rootOf(opts);
+		const { blocks, presets, problems: loadProblems } = api.loadBlocks(root);
+		if (opts.list) {
+			print(opts, { blocks: [...blocks.values()].map(({ id, title, kind, summary, layer }) => ({ id, title, kind, summary, layer })), presets: [...presets.values()].map(({ id, title, blocks: b }) => ({ id, title, blocks: b })), problems: loadProblems }, () => {
+				for (const b of [...blocks.values()].sort((a, c) => a.kind.localeCompare(c.kind) || a.id.localeCompare(c.id))) console.log(`${b.kind.padEnd(12)} ${b.id.padEnd(20)} ${b.summary ?? b.title}${b.layer === "project" ? "  (project)" : ""}`);
+				console.log("\npresets:");
+				for (const p of presets.values()) console.log(`  ${p.id.padEnd(18)} ${p.blocks.map((x) => (typeof x === "string" ? x : x.id)).join(", ")}`);
+			});
+			return;
+		}
+		const current = api.readStack(root);
+		if (current?.error) { process.exitCode = problems(opts, { problems: [current.error] }); return; }
+		const save = (stack, what) => {
+			const r = api.resolveSelection(blocks, stack.blocks);
+			if (r.problems.length) { process.exitCode = problems(opts, { problems: r.problems.map((p) => `stack: ${p}`) }); return; }
+			api.writeStack(root, stack);
+			print(opts, { stack, added: r.added, suggestions: r.suggestions }, () => {
+				console.log(`${what}: agiter/config/.stack.json`);
+				console.log(`blocks: ${[...r.chosen.values()].map((e) => (e.block.versions ? `${e.block.id}@${e.version}` : e.block.id)).join(", ")}`);
+				for (const a of r.added) console.log(`  ${a.id} added as required by ${a.by}`);
+				if (r.suggestions.length) console.log(`suggested: ${r.suggestions.map((x) => `${x.id} (by ${x.by})`).join(", ")}`);
+			});
+		};
+		if (opts.preset || opts.detect) {
+			if (current) cmd.error("error: the project has a stack already (agiter/config/.stack.json): change it with --add and --remove", { exitCode: USAGE, code: "agiter.stack" });
+			if (opts.preset) {
+				const p = presets.get(opts.preset);
+				if (!p) cmd.error(`error: no preset ${opts.preset} (agiter stack --list)`, { exitCode: USAGE, code: "agiter.stack" });
+				return save({ preset: p.id, blocks: [...p.blocks] }, `created from the preset ${p.id}`);
+			}
+			const found = api.detectBlocks(blocks, root);
+			if (!found.length) { print(opts, { detected: [] }, () => console.log("no block detected: start with --preset or --add")); process.exitCode = 1; return; }
+			if (!opts.json) for (const f of found) console.log(`detected ${f.id}: ${f.evidence.join("; ")}`);
+			return save({ blocks: found.map((f) => f.id) }, "created from the project's files");
+		}
+		if (opts.add || opts.remove) {
+			const stack = current ?? { blocks: [] };
+			const id = (e) => (typeof e === "string" ? e : e.id);
+			for (const x of opts.add ?? []) {
+				const [bid, version] = x.split("@");
+				stack.blocks = stack.blocks.filter((e) => id(e) !== bid);
+				stack.blocks.push(version ? { id: bid, version } : bid);
+			}
+			for (const x of opts.remove ?? []) {
+				if (!stack.blocks.some((e) => id(e) === x)) cmd.error(`error: ${x} is not in the selection`, { exitCode: USAGE, code: "agiter.stack" });
+				stack.blocks = stack.blocks.filter((e) => id(e) !== x);
+			}
+			return save(stack, current ? "updated" : "created");
+		}
+		const role = typeof opts.show === "string" ? opts.show : null;
+		const composed = api.composeProject(root, role);
+		if (!composed) { print(opts, { stack: null }, () => console.log("the project has no stack yet (agiter stack --preset <id>, --detect or --add <blocks...>) and no agiter/config/project.md")); return; }
+		print(opts, { role, ...composed }, () => {
+			console.log(role ? `# What the ${role} gets` : "# The project's stack (every section)");
+			console.log("");
+			console.log(composed.text);
+			console.log(`\n(${Buffer.byteLength(composed.text)} bytes in every ${role ? `${role} ` : ""}prompt)`);
+			for (const p of composed.problems) console.log(`problem: ${p}`);
+		});
+		process.exitCode = composed.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();

package/defs/{agents.json → .agents.json}

@@ -13,7 +13,12 @@
 		],
 		"message": [
 			"{message}"
-		]
+		],
+		"format": [
+			"--format",
+			"json"
+		],
+		"output": "opencode-json"
 	},
 	"claude": {
 		"title": "Claude Code, print mode; the prompt comes right after -p (the tool options take several values); the reviewer reads only",
@@ -43,6 +48,11 @@
 			"ANTHROPIC_AUTH_TOKEN",
 			"ANTHROPIC_API_KEY",
 			"ANTHROPIC_MODEL"
-		]
+		],
+		"format": [
+			"--output-format",
+			"json"
+		],
+		"output": "claude-json"
 	}
 }

package/defs/artifacts/checks.json

@@ -1,4 +1,10 @@
 {
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"Check"
+	],
 	"title": "Checks",
 	"summary": "The results of the project's required checks.",
 	"sections": [

package/defs/artifacts/create-epics.json

@@ -0,0 +1,32 @@
+{
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"epics",
+		"CreateEpic"
+	],
+	"title": "Breakdown into epics",
+	"summary": "The result of create-epics, not a methodical artifact: the input's functional areas and the epics that deliver them; each epic is in its own file (type epic).",
+	"sections": [
+		"Functional areas",
+		"Epics"
+	],
+	"criteria": [
+		"Every functional area of the input is listed, and every one is covered by exactly one epic.",
+		"The epics do not overlap: nothing is in the scope of two epics.",
+		"Each epic can be delivered and checked on its own; where one needs another, its scope says which.",
+		"There are as many epics as the input needs: no epic for a trivial part, no epic that bundles unrelated areas.",
+		"Nothing outside the input is added."
+	],
+	"items": {
+		"type": "epic",
+		"prefix": "E",
+		"section": "Epics"
+	},
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/create-tests.json

@@ -0,0 +1,22 @@
+{
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"CreateTest"
+	],
+	"title": "Tests record",
+	"summary": "The record of create-tests, not a methodical artifact: the tests written for a spec.",
+	"sections": [
+		"Changes"
+	],
+	"criteria": [
+		"The tests cover every acceptance criterion of the spec.",
+		"Nothing outside the spec's scope changed."
+	],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/{work.json → create-work.json}

@@ -1,6 +1,13 @@
 {
-	"title": "Work",
-	"summary": "The record of a change made to the code, tests included.",
+	"name": "Pipeline",
+	"shared": true,
+	"record": true,
+	"aliases": [
+		"work",
+		"CreateWork"
+	],
+	"title": "Work record",
+	"summary": "The record of create-work, not a methodical artifact: the change made to the code, tests included.",
 	"sections": [
 		"Changes"
 	],

package/defs/artifacts/decisions.json

@@ -0,0 +1,12 @@
+{
+	"name": "Decision",
+	"record": true,
+	"title": "Decisions",
+	"summary": "The record of a run's autonomous decisions: what the models decided that the input did not say, those that belong to the owner first, for him to answer.",
+	"sections": [],
+	"statuses": [
+		"Draft",
+		"Active",
+		"Done"
+	]
+}

package/defs/artifacts/report.json

@@ -1,4 +1,5 @@
 {
+	"record": true,
 	"title": "Report",
 	"summary": "The review of one version: its findings, cumulative over the rounds.",
 	"statuses": [

package/defs/blocks/ado-net.json

@@ -0,0 +1,130 @@
+{
+	"id": "ado-net",
+	"title": "ADO.NET (Microsoft.Data.SqlClient)",
+	"kind": "library",
+	"slot": "dotnet-data-access",
+	"detect": {
+		"text": [
+			{
+				"files": "**/*.csproj",
+				"match": "Microsoft\\.Data\\.SqlClient"
+			},
+			{
+				"files": "**/packages.config",
+				"match": "id=\"Microsoft\\.Data\\.SqlClient\""
+			}
+		]
+	},
+	"summary": "explicit SQL and row mapping, no ORM",
+	"requires": [
+		{
+			"anyOf": [
+				"dotnet",
+				"dotnet-framework"
+			]
+		},
+		"sql-server"
+	],
+	"fragments": {
+		"stack": [
+			{
+				"id": "ado.stack",
+				"text": "Direct ADO.NET through `Microsoft.Data.SqlClient`. No EF Core, Dapper or reflection-based object mappers.",
+				"unless": [
+					"dotnet-framework"
+				]
+			},
+			{
+				"id": "ado.stack-framework",
+				"text": "Direct ADO.NET through the SqlClient the project references (`System.Data.SqlClient` or `Microsoft.Data.SqlClient`). No Entity Framework, Dapper or reflection-based object mappers.",
+				"when": [
+					"dotnet-framework"
+				]
+			}
+		],
+		"rules": [
+			{
+				"id": "ado.explicit",
+				"group": "ADO.NET and SQL Server",
+				"text": "Keep SQL and row mapping explicit. Parameterize values; set `SqlDbType` and relevant size, precision and scale deliberately."
+			},
+			{
+				"id": "ado.async",
+				"group": "ADO.NET and SQL Server",
+				"text": "Use `OpenAsync`, `ExecuteReaderAsync`/`ExecuteNonQueryAsync` and `ReadAsync` where available, propagating the request's `CancellationToken`."
+			},
+			{
+				"id": "ado.dispose",
+				"group": "ADO.NET and SQL Server",
+				"text": "Dispose connections, commands and readers deterministically; use asynchronous disposal where supported. Use connection pooling rather than a shared mutable `SqlConnection` singleton."
+			},
+			{
+				"id": "ado.typed",
+				"group": "ADO.NET and SQL Server",
+				"text": "Use typed reader access and handle `DBNull` explicitly. Select required columns; avoid `DataSet`/`DataTable` unless the named spec requires them."
+			},
+			{
+				"id": "ado.transactions",
+				"group": "ADO.NET and SQL Server",
+				"text": "Define transaction boundaries, isolation, timeout and concurrency behavior in the spec. Pass the transaction to every participating command."
+			},
+			{
+				"id": "ado.retry",
+				"group": "ADO.NET and SQL Server",
+				"text": "Do not retry non-idempotent writes without an explicit idempotency strategy. Cancellation does not prove a transaction was rolled back; test the chosen behavior."
+			},
+			{
+				"id": "ado.scripts",
+				"group": "ADO.NET and SQL Server",
+				"text": "Store schema changes as ordered SQL scripts with verification."
+			},
+			{
+				"id": "ado.aot",
+				"group": "Native AOT",
+				"text": "Validate the exact SqlClient version, native dependencies and database authentication mode in the published artifact. Do not infer full compatibility from target framework support alone.",
+				"when": [
+					"native-aot"
+				]
+			}
+		],
+		"paths": [
+			{
+				"id": "ado.database",
+				"path": "`database/`",
+				"content": "Ordered SQL scripts and schema documentation"
+			}
+		],
+		"scopes": [
+			{
+				"id": "ado.schema",
+				"scope": "schema-only change",
+				"folder": "`docs/spec/database/`"
+			}
+		],
+		"commands": [
+			{
+				"id": "ado.integration",
+				"purpose": "SQL integration tests",
+				"command": "`{{option.integration}}`",
+				"after": "unit tests"
+			}
+		],
+		"environment": [
+			{
+				"id": "ado.sqlclient",
+				"setting": "SqlClient",
+				"value": "`<pinned version and required native/authentication dependencies>`"
+			}
+		],
+		"notes": {
+			"commands": "SQL integration and native acceptance commands are mandatory for changes exercising those paths; do not report them as passed when credentials, SQL Server or the native toolchain are absent."
+		}
+	},
+	"options": {
+		"integration": {
+			"title": "the isolated-SQL-Server test command",
+			"type": "text",
+			"default": "<existing isolated-SQL-Server test command>"
+		}
+	}
+}