@stacknyu/pi-flow 0.0.0-stage → 1.5.0

package/setup.mjs

@@ -0,0 +1,310 @@
+// pi-flow setup: detect the repo's stack, verify check commands by running them once,
+// apply your saved plugin profile, and keep a short managed block in AGENTS.md.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { LOGIN_SHELL, cleanEnv, git, loadJson, resolvePi, run, tail } from "./runner.mjs";
+
+export const FLOW_DIR = ".pi-flow";
+export const TASKS_DIR = ".tasks";
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || "", ".pi", "agent");
+export const PROFILE = join(AGENT_DIR, "pi-flow", "profile.json");
+const SKIP = new Set(["node_modules", ".git", ".pi-queue", ".pi-flow", "dist", "build", ".next", ".turbo", "vendor", "target"]);
+
+/** Keep a path out of git without touching .gitignore (uses .git/info/exclude). */
+export async function exclude(repo, path) {
+	const rel = (await git(repo, "rev-parse", "--git-path", "info/exclude")).out.trim();
+	if (!rel) return;
+	const file = isAbsolute(rel) ? rel : join(repo, rel);
+	mkdirSync(dirname(file), { recursive: true });
+	const cur = existsSync(file) ? readFileSync(file, "utf8") : "";
+	if (!cur.split("\n").includes(path)) appendFileSync(file, `${cur && !cur.endsWith("\n") ? "\n" : ""}${path}\n`);
+}
+
+// ---------- stack detection ----------
+
+function readJson(p) {
+	try {
+		return JSON.parse(readFileSync(p, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+function dirsMatching(repo, pattern) {
+	const clean = pattern.replace(/^["']|["']$/g, "").replace(/^\.\//, "").replace(/\/$/, "");
+	if (!clean || clean.startsWith("!")) return [];
+	const parts = clean.split("/");
+	const out = [];
+	const walk = (base, i) => {
+		if (i === parts.length) return out.push(base);
+		const part = parts[i];
+		const abs = join(repo, base);
+		if (part === "**") {
+			walk(base, i + 1);
+			for (const d of subdirs(abs)) walk(join(base, d), i);
+			return;
+		}
+		if (part.includes("*")) {
+			const re = new RegExp(`^${part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
+			for (const d of subdirs(abs)) if (re.test(d)) walk(join(base, d), i + 1);
+			return;
+		}
+		if (existsSync(join(abs, part))) walk(join(base, part), i + 1);
+	};
+	walk("", 0);
+	return out.filter((d) => existsSync(join(repo, d, "package.json")));
+}
+
+function subdirs(abs) {
+	try {
+		return readdirSync(abs).filter((d) => !SKIP.has(d) && !d.startsWith(".") && statSync(join(abs, d)).isDirectory());
+	} catch {
+		return [];
+	}
+}
+
+function findFiles(repo, name, depth = 3, base = "") {
+	const out = [];
+	if (existsSync(join(repo, base, name))) out.push(base || ".");
+	if (depth === 0) return out;
+	for (const d of subdirs(join(repo, base))) out.push(...findFiles(repo, name, depth - 1, join(base, d)));
+	return out;
+}
+
+export function detect(repo) {
+	const has = (f) => existsSync(join(repo, f));
+	const pm = has("pnpm-lock.yaml") ? "pnpm" : has("bun.lock") || has("bun.lockb") ? "bun" : has("yarn.lock") ? "yarn" : has("package-lock.json") ? "npm" : has("package.json") ? "npm" : "";
+	const install = {
+		pnpm: "pnpm install --frozen-lockfile --prefer-offline",
+		bun: "bun install --frozen-lockfile",
+		yarn: "yarn install --frozen-lockfile",
+		npm: "npm ci --prefer-offline --no-audit --no-fund",
+	}[pm] ?? "";
+
+	// workspace packages
+	let patterns = [];
+	if (has("pnpm-workspace.yaml")) {
+		let inPackages = false;
+		for (const line of readFileSync(join(repo, "pnpm-workspace.yaml"), "utf8").split("\n")) {
+			if (/^packages\s*:/.test(line)) inPackages = true;
+			else if (/^\S/.test(line)) inPackages = false;
+			else if (inPackages) {
+				const m = line.match(/^\s*-\s*(.+?)\s*$/);
+				if (m) patterns.push(m[1]);
+			}
+		}
+	}
+	const rootPkg = readJson(join(repo, "package.json"));
+	const ws = rootPkg?.workspaces;
+	if (Array.isArray(ws)) patterns.push(...ws);
+	else if (Array.isArray(ws?.packages)) patterns.push(...ws.packages);
+	const dirs = [...new Set(patterns.flatMap((p) => dirsMatching(repo, p)))].sort();
+	if (dirs.length === 0 && rootPkg) dirs.push(".");
+
+	const packages = dirs.map((dir) => {
+		const pkg = readJson(join(repo, dir, "package.json")) ?? {};
+		return { dir, name: pkg.name ?? dir, scripts: pkg.scripts ?? {}, tsconfig: existsSync(join(repo, dir, "tsconfig.json")) };
+	});
+	const go = findFiles(repo, "go.mod");
+	const cargo = findFiles(repo, "Cargo.toml", 2).filter((d) => d === "." || !existsSync(join(repo, "Cargo.toml")));
+	return { pm, install, packages, go, cargo };
+}
+
+/** Check commands worth trying, per package. Tests are listed but not run (they can be slow or need services). */
+export function candidates(repo, det) {
+	const runS = { pnpm: "pnpm run", bun: "bun run", yarn: "yarn run", npm: "npm run" }[det.pm] ?? "npm run";
+	const execTsc = { pnpm: "pnpm exec tsc --noEmit", bun: "bunx tsc --noEmit", yarn: "yarn tsc --noEmit", npm: "npx --no-install tsc --noEmit" }[det.pm] ?? "npx --no-install tsc --noEmit";
+	const at = (dir, cmd) => (dir === "." ? cmd : `cd ${dir} && ${cmd}`);
+	const out = [];
+	const tscAvailable = (dir) => existsSync(join(repo, dir, "node_modules", ".bin", "tsc")) || existsSync(join(repo, "node_modules", ".bin", "tsc"));
+	for (const p of det.packages) {
+		const s = p.scripts;
+		const tc = ["typecheck", "type-check", "check-types", "types", "tsc"].find((k) => s[k]);
+		if (tc) out.push({ dir: p.dir, kind: "typecheck", cmd: at(p.dir, `${runS} ${tc}`) });
+		else if (p.tsconfig && tscAvailable(p.dir)) out.push({ dir: p.dir, kind: "typecheck", cmd: at(p.dir, execTsc) });
+		if (s.lint) out.push({ dir: p.dir, kind: "lint", cmd: at(p.dir, `${runS} lint`) });
+		if (s.check && !tc) out.push({ dir: p.dir, kind: "check", cmd: at(p.dir, `${runS} check`) });
+		if (s.test) out.push({ dir: p.dir, kind: "test", cmd: at(p.dir, `${runS} test`), notRun: true });
+	}
+	for (const d of det.go) {
+		out.push({ dir: d, kind: "build", cmd: at(d, "go build ./...") });
+		out.push({ dir: d, kind: "vet", cmd: at(d, "go vet ./...") });
+		out.push({ dir: d, kind: "test", cmd: at(d, "go test ./..."), notRun: true });
+	}
+	for (const d of det.cargo) out.push({ dir: d, kind: "build", cmd: at(d, "cargo check") });
+	return out;
+}
+
+/** Run each candidate once on the current code. Only commands that pass can become a task's checks. */
+export async function verify(repo, cands, onProgress = () => {}, minutes = 10) {
+	const results = [];
+	let i = 0;
+	for (const c of cands) {
+		i++;
+		if (c.notRun) {
+			results.push({ ...c, ok: null });
+			continue;
+		}
+		onProgress(`checking ${i}/${cands.length}: ${c.cmd}`);
+		const t0 = Date.now();
+		const r = await run(repo, LOGIN_SHELL, ["-lc", c.cmd], { timeoutMs: minutes * 60_000, env: cleanEnv() });
+		results.push({ ...c, ok: r.code === 0, seconds: Math.round((Date.now() - t0) / 1000), ...(r.code === 0 ? {} : { output: tail(r.out, 15) }) });
+	}
+	return results;
+}
+
+// ---------- AGENTS.md ----------
+
+const START = "<!-- pi-flow:start -->";
+const END = "<!-- pi-flow:end -->";
+export const AGENTS_BLOCK = `${START}
+## How large work runs here (pi-flow)
+
+- Large tasks start with \`/task <request>\`: a planning session researches and writes \`${TASKS_DIR}/<task>/\` (brief, inventory, maps, rules, questions, items), asks the user its open questions, then hands the item list to the queue.
+- Queue items run unattended, each in a fresh session: never ask the user questions; stay inside the item and the task's allowed paths; do not commit; run the task's checks before stopping. Reply \`NEEDS: <files> files, <lines> lines\` if the item needs more than its size limits, or \`BLOCKED: <reason>\` if it cannot be done without a decision.
+- Subagents may read, search and research; only the main agent edits files.
+- A task's \`brief.md\`, \`rules.md\` and answered \`questions.md\` narrow the scope for that task; they never loosen the rules in this file.
+${END}`;
+
+/** Insert or refresh the managed block; drop stale harness blocks from earlier setups. Returns notes. */
+export function updateAgents(repo) {
+	const file = join(repo, "AGENTS.md");
+	const notes = [];
+	let text = existsSync(file) ? readFileSync(file, "utf8") : "# Agent rules\n";
+	const stale = /<!-- harness:long-running:start -->[\s\S]*?<!-- harness:long-running:end -->\n?/g;
+	if (stale.test(text)) {
+		text = text.replace(stale, "");
+		notes.push("removed the old long-running harness block (GLLA) from AGENTS.md");
+	}
+	if (text.includes(START) && text.includes(END)) {
+		const before = text;
+		text = text.replace(new RegExp(`${START}[\\s\\S]*?${END}`), AGENTS_BLOCK);
+		if (before !== text) notes.push("refreshed the pi-flow block in AGENTS.md");
+	} else {
+		text = `${text.trimEnd()}\n\n${AGENTS_BLOCK}\n`;
+		notes.push(existsSync(file) ? "added the pi-flow block to AGENTS.md" : "created AGENTS.md with the pi-flow block");
+	}
+	const leftovers = text.split("\n").filter((l) => /\bGLLA\b|\/goal\b|pi-goal/i.test(l) && !l.includes("pi-flow"));
+	if (leftovers.length) notes.push(`AGENTS.md still mentions the old loop in ${leftovers.length} line(s), e.g. "${leftovers[0].trim().slice(0, 80)}" — review it`);
+	writeFileSync(file, text);
+	return notes;
+}
+
+// ---------- plugin profile ----------
+
+function packagesOf(settingsFile) {
+	return (readJson(settingsFile)?.packages ?? []).map((p) => (typeof p === "string" ? p : p?.source)).filter(Boolean);
+}
+
+/** Save this repo's project plugins (.pi/settings.json) as your profile for other repos. */
+export function saveProfile(repo) {
+	const settings = readJson(join(repo, ".pi", "settings.json")) ?? {};
+	const packages = (settings.packages ?? []).filter((p) => {
+		const src = typeof p === "string" ? p : p?.source;
+		return src && !/^\.{1,2}\//.test(src); // repo-relative local packages cannot move to another repo
+	});
+	const { packages: _p, ...rest } = settings;
+	mkdirSync(dirname(PROFILE), { recursive: true });
+	writeFileSync(PROFILE, `${JSON.stringify({ savedFrom: repo, savedAt: new Date().toISOString(), packages, settings: rest }, null, 2)}\n`);
+	return { file: PROFILE, count: packages.length };
+}
+
+/** Install the profile's plugins into this repo (pi install -l) and copy its other project settings where unset. */
+export async function applyProfile(repo, onProgress = () => {}) {
+	const profile = loadJson(PROFILE, null);
+	if (!profile) return { notes: ["no plugin profile yet: run /task save-profile in a repo whose plugins you like"], installed: [] };
+	const settingsFile = join(repo, ".pi", "settings.json");
+	const have = new Set([...packagesOf(settingsFile), ...packagesOf(join(AGENT_DIR, "settings.json"))]);
+	const pi = await resolvePi({});
+	const installed = [];
+	const notes = [];
+	for (const p of profile.packages ?? []) {
+		const src = typeof p === "string" ? p : p.source;
+		if (have.has(src)) continue;
+		onProgress(`installing ${src}`);
+		const r = await run(repo, LOGIN_SHELL, ["-lc", `"${pi}" install -l "$0"`, src], { timeoutMs: 10 * 60_000, env: cleanEnv() });
+		if (r.code === 0) installed.push(src);
+		else notes.push(`could not install ${src}: ${tail(r.out, 2).replace(/\n/g, " ")}`);
+	}
+	// object-form package filters and other project settings: merge where this repo has nothing
+	const cur = readJson(settingsFile) ?? {};
+	let changed = false;
+	for (const [k, v] of Object.entries(profile.settings ?? {})) {
+		if (cur[k] === undefined) {
+			cur[k] = v;
+			changed = true;
+		}
+	}
+	const objs = (profile.packages ?? []).filter((p) => typeof p === "object");
+	if (objs.length) {
+		cur.packages = (cur.packages ?? []).map((p) => {
+			const src = typeof p === "string" ? p : p.source;
+			return objs.find((o) => o.source === src) ?? p;
+		});
+		changed = true;
+	}
+	if (changed) {
+		mkdirSync(dirname(settingsFile), { recursive: true });
+		writeFileSync(settingsFile, `${JSON.stringify(cur, null, 2)}\n`);
+	}
+	return { notes, installed };
+}
+
+// ---------- the whole setup ----------
+
+export async function setupRepo(repo, onProgress = () => {}) {
+	const notes = [];
+	if ((await git(repo, "rev-parse", "--is-inside-work-tree")).out.trim() !== "true") throw new Error("not a git repository");
+	mkdirSync(join(repo, FLOW_DIR), { recursive: true });
+	await exclude(repo, `${FLOW_DIR}/`);
+	await exclude(repo, ".pi-queue/");
+
+	const dirtyBefore = (await git(repo, "status", "--porcelain", "--", "AGENTS.md", ".pi/settings.json")).out.trim();
+
+	onProgress("plugins");
+	const prof = await applyProfile(repo, onProgress);
+	notes.push(...prof.notes);
+	if (prof.installed.length) notes.push(`installed ${prof.installed.length} plugin(s): ${prof.installed.join(", ")}`);
+
+	notes.push(...updateAgents(repo));
+
+	onProgress("detecting the stack");
+	const det = detect(repo);
+	const cands = candidates(repo, det);
+	const checks = await verify(repo, cands, onProgress);
+	const info = { updatedAt: new Date().toISOString(), pm: det.pm, install: det.install, packages: det.packages.map(({ dir, name }) => ({ dir, name })), go: det.go, cargo: det.cargo, checks };
+	writeFileSync(join(repo, FLOW_DIR, "repo.json"), `${JSON.stringify(info, null, 2)}\n`);
+
+	// commit setup's own files, only if they were clean before (never sweep up your edits)
+	if (!dirtyBefore) {
+		const changed = (await git(repo, "status", "--porcelain", "--", "AGENTS.md", ".pi/settings.json")).out.trim();
+		if (changed) {
+			await git(repo, "add", "--", "AGENTS.md", ...(existsSync(join(repo, ".pi", "settings.json")) ? [".pi/settings.json"] : []));
+			const c = await git(repo, "commit", "-m", "pi-flow setup", "--", "AGENTS.md", ...(existsSync(join(repo, ".pi", "settings.json")) ? [".pi/settings.json"] : []));
+			notes.push(c.code === 0 ? "committed AGENTS.md / .pi/settings.json as \"pi-flow setup\"" : `could not commit setup changes: ${tail(c.out, 2)}`);
+		}
+	} else notes.push("AGENTS.md or .pi/settings.json had your own uncommitted edits, so setup did not commit; commit them yourself before /task");
+
+	const ok = checks.filter((c) => c.ok === true);
+	const bad = checks.filter((c) => c.ok === false);
+	const report = [
+		`# pi-flow setup — ${info.updatedAt}`,
+		"",
+		`Package manager: ${det.pm || "none"}${det.install ? ` (worktree install: \`${det.install}\`)` : ""}`,
+		`Packages: ${det.packages.map((p) => p.dir).join(", ") || "none"}${det.go.length ? ` · Go: ${det.go.join(", ")}` : ""}${det.cargo.length ? ` · Rust: ${det.cargo.join(", ")}` : ""}`,
+		"",
+		"## Checks that pass today (usable as task checks)",
+		...ok.map((c) => `- \`${c.cmd}\` (${c.kind}, ${c.seconds}s)`),
+		"",
+		"## Checks that fail today (not used until fixed)",
+		...bad.map((c) => `- \`${c.cmd}\` (${c.kind})\n\n  \`\`\`\n${(c.output ?? "").split("\n").map((l) => `  ${l}`).join("\n")}\n  \`\`\``),
+		"",
+		"## Available but not run (tests)",
+		...checks.filter((c) => c.ok === null).map((c) => `- \`${c.cmd}\``),
+		"",
+		"## Notes",
+		...notes.map((n) => `- ${n}`),
+	].join("\n");
+	writeFileSync(join(repo, FLOW_DIR, "setup-report.md"), `${report}\n`);
+	return { info, notes, ok: ok.length, bad: bad.length, report };
+}

package/skills/pi-flow/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: pi-flow
+description: How pi-flow plans and runs large tasks with a queue of fresh Pi sessions (/task, /task manage, /queue, items.md format, [check]/[areas]/[after] tags, limits, re-queuing, cleanup, troubleshooting). Use when planning a /task, managing or explaining the queue, answering how pi-flow works, or diagnosing a queue problem.
+---
+
+# pi-flow
+
+pi-flow turns a large request into a planned work list that a queue of fresh, unattended Pi sessions implements item by item. A script judges every item; each passing item becomes one commit.
+
+Read the reference that fits the question:
+
+- `references/guide.md`: the whole workflow (setup → plan → questions → handoff → queue → cleanup), the terminal app versus Pi Web, and the files involved. Start here when explaining pi-flow.
+- `references/items.md`: the items.md line format, every tag (`[areas]`, `[after]`, `[check]`, `[big]`, size tags), the size limits and how they rise, splitting, gap fixing, deferral, rechecks. Read it before writing or changing a plan.
+- `references/manager.md`: what the manager chat does, its tools and actions (retry, recheck, rerun, unpark, next, add, parallel, stop, start), how to diagnose a run, and the rules it follows. Read it when acting as the manager.
+- `references/troubleshooting.md`: known problems and their fixes (failed baseline, dirty tree, items blocked by missing prerequisites, parked items running one by one, stray Pi Web projects, and more). Read it when something went wrong.
+
+Rules that always hold:
+- The runner, not an agent, decides whether an item passes: scope (allowed paths), size limits, checks.
+- Queue items never ask questions, never commit, and never use the queue tools.
+- The manual manager acts only when asked. The isolated automatic manager may propose bounded recovery of approved existing work; see references/manager.md. Neither manager edits code, reverts commits or deletes branches.

package/skills/pi-flow/references/guide.md

@@ -0,0 +1,80 @@
+# pi-flow guide
+
+## The idea
+
+Large work (hours) fails in one long agent session: context fills up, the agent drifts, and nothing checks its claims. pi-flow splits the work into a written plan and a list of small items. A queue gives every item a fresh session and has a script judge the result. You answer the plan's questions once, then watch or walk away.
+
+## One-time install
+
+- `pi install npm:@stacknyu/pi-flow` installs pi-flow personally for every repo. Optionally install the independent check plugin with `pi install npm:@stacknyu/pi-check`. Reload Pi / Pi Web.
+- In a repo whose plugins you like: `/task save-profile`. That set becomes your profile.
+
+## Per repo, once: `/task setup`
+
+- Installs your profile's plugins into the repo (`pi install -l`).
+- Detects the stack: pnpm/npm/yarn/bun workspaces, Go modules, Rust.
+- Runs every typecheck, lint and build command **once on today's code**. Only commands that pass can become a task's checks. Failing ones are listed with their output in `.pi-flow/setup-report.md`.
+- Adds a short managed block to `AGENTS.md` and removes stale harness blocks (old GLLA). It commits only `AGENTS.md` and `.pi/settings.json`, and only if you had no edits there.
+
+## Per task
+
+1. **`/task <request>`.** This chat becomes the planning session. It researches the code (subagents may search in parallel, read-only) and writes `.tasks/<slug>/`:
+
+   | File | Content |
+   |---|---|
+   | `brief.md` | goal, what "done" means, out of scope, risks |
+   | `inventory.md` | facts from the code, with paths |
+   | `map/<area>.md` | what changes per area, and what must not |
+   | `rules.md` | task-specific rules |
+   | `questions.md` | decisions only you can make |
+   | `items.md` | the work list (see items.md) |
+   | `task.json` | `allowedPaths`, `checks`, suggested `parallel` |
+
+2. **Questions.** It asks them all in one message, each with a recommended answer. Reply in plain words.
+3. **Handoff.** The planner calls `task_handoff`. It refuses until:
+   - every question is answered
+   - every item has an id, a "Done when" and `[areas]`
+   - every `[after]` id exists and dependencies are acyclic
+   - the checks pass on today's code
+   - the tree is clean apart from the plan
+
+   Then it commits `.tasks/<slug>/` and starts the queue. In Pi Web it pins this chat as the control room.
+4. **The queue runs.** Up to `parallel` items at once, each in its own git worktree (`.pi-queue/worktrees/wN`) and its own fresh session. Each passing item is rebased onto the branch and fast-forwarded: one commit `ID: title`.
+5. **Automatic supervision.** Once the baseline passes, a detached supervisor creates a chat-only manager. Healthy 60-second ticks make no model calls. Bounded recovery and human-only blockers are defined in manager.md. `/task manage` and `/queue …` remain available for manual intervention.
+6. **Clean up.** Finished item sessions are removed when the run ends. `/task cleanup` removes failed items' sessions and the planning chat. `--all` also removes worktrees and `queue-failed/*` branches.
+
+## Terminal app versus Pi Web
+
+Everything works in the plain terminal app. Pi Web is optional and found automatically.
+
+| | Terminal | Pi Web |
+|---|---|---|
+| Items run as | background `pi --mode json` processes | real Pi Web sessions, live in the sidebar |
+| Watch an item | `/queue log <id>`, the live panel | open `queue <id>: …` in the sidebar |
+| Open a finished item | `/queue open <id>` (switches this chat to it) | sidebar |
+| Sessions stored | `.pi-queue/sessions/` | Pi Web's store |
+| Cleanup | deletes the files | Pi Web API (delete or archive) |
+| Planning chat | — | pinned while the queue runs |
+
+## Files
+
+| Path | In git | What |
+|---|---|---|
+| `.tasks/<slug>/` | yes | the plan, which is what every item reads |
+| `.pi-flow/` | no | `repo.json` (verified checks), `setup-report.md`, `status.json` |
+| `.pi-queue/config.json` | no | queue settings (your edits survive across tasks) |
+| `.pi-queue/log.md` | no | one line per event: PASS, FAIL, SPLIT, GAPS, DEFERRED, RECHECK, REDO, WIDTH, CONTROL, END |
+| `.pi-queue/state.json` | no | done, failed, parked, splits, fixes, sessions; a restart continues from here |
+| `.pi-queue/manager.json` | no | manager session, approval identity, incident and recovery budgets |
+| `.pi-queue/control/` | no | atomic control inbox; one file per request |
+| `.pi-queue/notes/<id>.md` | no | each item's result and the agent's last reply |
+| `.pi-queue/live/<id>.log` | no | each item's activity |
+| `.pi-queue/archive/` | no | earlier runs' records |
+
+## While it runs
+
+- `/queue pause` stops new dispatch and lets running items finish normally. `/queue start` resumes. `/queue stop` still aborts running items and preserves their work; use pause for upgrades.
+- Agent parallelism and pi-check's CPU/job budgets are independent. Planning and manager controls accept more than eight agents; choose based on independent work and available memory/provider capacity, not test-process count.
+- Don't commit to the task's branch or edit files in the repo folder. The queue fast-forwards that branch.
+- Keep the machine awake (`caffeinate -dims` on a Mac). In Pi Web mode, keep the Pi Web server running.
+- One queue per repo at a time. You can discuss the next task meanwhile, but keep draft files outside the active checkout. Its handoff must wait until the queue is free.

package/skills/pi-flow/references/items.md

@@ -0,0 +1,68 @@
+# Work items
+
+## Line format
+
+```
+- [ ] A01 — <what to do, naming files/functions>. Done when: <observable result>. [areas: <folders/files it changes>] [after: <ids>]
+```
+
+- **Id:** capital letters plus a number (`A01`, `P03`, `V04`), unique. File order breaks ties, not dependencies. Ids made by the queue: `A01a…` (split parts), `V01-fix1…` (gap fixes).
+- **Done when:** what a reviewer can verify. Every item needs one.
+- **Context:** each item runs in a fresh session that has never seen the planning chat. It reads `AGENTS.md`, `brief.md`, `rules.md`, the answers in `questions.md`, and the map and inventory parts it names. Anything it needs must be there or in its line.
+
+## Tags
+
+| Tag | Meaning |
+|---|---|
+| `[areas: a, b]` | folders/files the item changes. Items with overlapping areas never run at the same time; disjoint ones run in parallel. Required. |
+| `[after: A01, A02]` | wait until these pass. If one fails, this item fails without running. `[after: *]` waits for everything else. |
+| `[check]` | a verification item (see below) |
+| `[big]` | start at the `big` limits (15 files / 600 lines / 90 min) |
+| `[files=12 lines=400 min=60]` | start at these limits |
+| `[model: provider/model-id]` | exact model selected during planning; otherwise queue default |
+| `[thinking: medium]` | supported thinking level selected during planning; otherwise queue default |
+
+## Plan session choices upfront
+
+The planner receives the authenticated model catalog, supported thinking levels and advertised costs. Choose a sufficient model/effort for each item according to complexity and risk, honoring user preferences; explain the choices briefly in `rules.md`. Routine localized edits need not use the strongest model. Security, migrations, cross-cutting changes and final verification deserve stronger reasoning. Price is not a speed benchmark.
+
+`task.json` may set default `model` and `thinking`; item tags override those defaults. Handoff rejects unavailable models and unsupported thinking levels before running checks or committing. Legacy untagged items retain queue defaults. Both CLI and Pi Web session creation use the resolved pair; automatically generated split/fix items inherit their parent's selection. No mid-run model guessing or automatic fallback.
+
+## What the runner judges
+
+An item passes only if:
+- it changed files only under `allowedPaths`
+- it stays within its size limits: net added lines (`maxNetLines`, 150) and files gaining lines (`maxFilesGrowing`, 5)
+- every check command passes
+
+If a check fails, the agent gets `fixRounds` (1) chances in the same session. Failed work is kept on `queue-failed/<id>`.
+
+## Sizes adjust themselves
+
+1. An agent that sees the item is bigger replies `NEEDS: 20 files, 900 lines`. The runner jumps to the first `escalate` level that fits (15/600 → 40/1500 → 200/5000) and the same agent carries on.
+2. An agent that stops on size, or whose change overflows, gets the next level.
+3. Typing "bypass limits" in a running item's session lifts size limits for that item.
+4. Past the last level, the same agent **splits** the item into 3–8 parts (`A01a…`), with their own areas and `[after]` order. They run next. Parts are not split again.
+
+## Re-queuing
+
+- **Deferred:** an item that says `BLOCKED` while other work is still pending is retried after that work. This catches the most common case, a prerequisite that hasn't run yet. A second BLOCKED with nothing left that could help is a failure for you (a missing decision, contract or environment).
+- **Conflict:** an item whose change no longer fits the moved branch is redone at once on the latest code, in the same session (`REDO`). If it conflicts again it is parked and retried at the end.
+- **Parked items** (conflicts, deferred) run only when nothing else is running, one at a time. `unpark` or `next` lets them run normally (see manager.md).
+
+## [check] items
+
+- Verify instead of build. Give them `[after: <items they verify>]`.
+- Pass **without changes** when everything holds. The log reads `PASS V01 · checked, nothing to change`.
+- May fix tests, fixtures and docs inside the allowed paths.
+- Report production gaps as lines: `GAP: <what is wrong and what to change>. Done when: … [areas: …]`. The queue adds fix items `V01-fix1…` before the check and checks again after them, up to `gapRounds` (2) rounds.
+- **Recheck:** a passed check runs again automatically when an item it covers changes later, meaning its `[after]` names that item or their `[areas]` overlap (`RECHECK` in the log).
+- `BLOCKED` when it cannot check at all, for example with no test environment.
+
+## Good plans
+
+- Use `[after]` only for real prerequisites, not blanket stage barriers. Ready prerequisites on longer chains get preference; independent work stays parallel. Cycles and duplicate tags are rejected.
+- Narrow, accurate `[areas]`. They decide parallelism and prevent conflicts.
+- One coherent change per item. Splitting artificially is worse than one `[big]` item.
+- No items that only investigate or review: every item builds something or is a `[check]`.
+- No item may depend on an unanswered question.

package/skills/pi-flow/references/manager.md

@@ -0,0 +1,59 @@
+# The manager
+
+## Automatic manager
+
+After an approved handoff passes its baseline, a detached supervisor creates a dedicated manager session. It survives closing the planning terminal/chat. In Pi Web the manager is pinned; in terminal mode its session is in `.pi-queue/sessions/`, with its ID/reply in `.pi-queue/manager.json`.
+
+- A 60-second filesystem/process health tick makes **no model calls** while work is healthy. Runner readiness/exit also wakes the supervisor.
+- After the initial manager turn, a new terminal failure can trigger a diagnostic turn; subsequent interventions are spaced at least 10 minutes apart. An unchanged incident is not prompted repeatedly.
+- The manager is chat-only, with no tools or extension capabilities. It proposes exact existing-item retries with repair guidance, or a clean runner restart. Code validates proposals. Workers make repairs under the original scope, checks and model selection.
+- At most two automatic retries per item and two clean runner restarts per task, persisted across supervisor restarts. Manual pause/stop, changed approval/configuration, missing decisions/credentials and uncertain worker ownership prevent automatic recovery. Exhausted or rejected interventions stop supervision and leave evidence for the user.
+- A crash with recorded workers quarantines their worktrees: no reset, cleanup or automatic orphan reclamation. Quiet tests/provider retries are not treated as hangs.
+- Set `manager: false` in `.pi-queue/config.json` to disable automatic management. A direct `node runner.mjs` invocation is unsupervised; normal handoff and `/queue start` launch the supervisor.
+- Models requiring a custom provider extension cannot run in the isolated chat-only manager; configure an available built-in/configured provider. No model fallback is guessed.
+
+## Manual manager
+
+`/task manage` makes the current chat a separate interactive manager. In Pi Web it is pinned. This chat acts **only on what the user asks in each message**; the automatic supervisor does not prompt it.
+
+## Tools
+
+| Tool | What |
+|---|---|
+| `queue_overview` | counts, running items, failed items with reasons, parked and open items, recent log |
+| `queue_item` | one item: its line, status, commit (files changed), last result, activity |
+| `queue_control` | `stop`, `start`, `retry`, `recheck`, `rerun`, `unpark`, `next`, `add`, `parallel` |
+
+`ids` are item ids or prefixes: `V04` matches `V04a…V04h`. Empty ids means all.
+
+| Action | Effect |
+|---|---|
+| `retry` | failed or parked items run again |
+| `recheck` | passed `[check]` items run again |
+| `rerun` | passed items run again (their commits stay; the new run builds on top) |
+| `unpark` | parked/deferred items run normally, in parallel, without waiting for the end |
+| `next` | these items run next: un-parked and moved to the front; dependencies and overlapping areas still apply |
+| `add` | new work-list lines, only lines the user agreed to (kept in state; the plan file is not edited) |
+| `parallel` | how many run at once. Works while running; the number becomes the ceiling and is saved for the next start |
+| `stop` / `start` | stop the run (running items' work kept on branches) / start it |
+
+Controls go through atomic files in `.pi-queue/control/`. The runner alone applies them, within seconds while running or on the next start otherwise; applied actions are logged. `/queue pause` lets current workers finish; `/queue stop` aborts them and preserves work. Only an explicit `/queue start` clears those markers. Wait for the old runner/supervisor to exit before starting.
+
+The same actions exist as commands: `/queue retry [id]`, `/queue recheck [id]`, `/queue rerun <id>`, `/queue unpark`, `/queue next <ids>`, `/queue parallel <n>`.
+
+## Diagnosing
+
+1. `queue_overview` first. Group failures by cause; many failures often share one.
+2. Typical causes:
+   - **A check or consumer ran before what it depends on.** The reasons say "not built yet", "absent", "still uses the old …". Fix: `retry` once the prerequisites pass, or `next` the prerequisites. Plans should tag `[after]`.
+   - **A real gap the plan missed.** Propose items, and `add` them after the user agrees.
+   - **A decision or contract question.** Tell the user plainly what must be decided.
+   - **Environment** (no test endpoint, credentials, a broken test suite). The user must provide it, or the item should be dropped.
+   - **The size limit.** That handles itself. If it keeps failing, suggest splitting the item.
+3. Explain in a few lines: what is wrong, why, and what you would do. Act only when asked.
+
+## Rules
+
+- Never edit code, revert commits or delete branches. If that is needed, say so.
+- Never add items the user did not agree to.
+- Queue items cannot use these tools (they refuse inside `.pi-queue/worktrees/` and in sessions named `queue …`).

package/skills/pi-flow/references/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting
+
+Each of these was hit in real use.
+
+**The queue stops right away: "checks fail before any change".**
+The checks fail on today's code, so every item would fail. `/queue problem` shows the output and a diagnosis.
+- **"Missing script" / "pnpm recursive exec failed":** the check names a script that doesn't exist. `/task setup` only offers commands that ran successfully; re-run it after scripts change.
+- **Passes in your folder but fails in a fresh worktree:** git-ignored files are missing (`.env`, generated types, another package's build output). List env files in `copyFromRepo`, or add the build to `setup`.
+- **Fails everywhere:** the code itself is broken. Fix that first, or drop the command from `checks`.
+
+**Checks behave differently when started from Pi Web.** Pi Web is a Node/pnpm process and leaks `npm_*`/`PNPM_*`/`NODE_ENV` variables. pi-flow strips them before setup and checks; if a tool needs one of them, set it inside the check command.
+
+**"Working tree is not clean".** The queue fast-forwards your branch, so it needs a clean tree. Commit or stash your edits. The handoff commits only the plan folder.
+
+**Interrupted workers / quarantined worktrees.** The runner refuses to reset dirty or unintegrated worktrees and retains worker ownership after an uncertain exit. Stop/confirm termination of those exact CLI/Web workers, preserve their changes/commits, and reconcile the recorded slots before restarting. Do not delete `state.running` or force-clean a worktree merely to bypass this protection. The automatic manager will not do that for you.
+
+**Many items are BLOCKED with "not built yet / absent / still uses the old …".** They ran before their prerequisites. pi-flow defers such items and retries them after the rest. If the run ended anyway, ask the manager: "retry everything that was blocked by missing prerequisites". For future plans, tag `[after: …]`.
+
+**A check fails with "no changes were made".** Only in old plans without `[check]`. Tag verification items `[check]` and they pass when nothing needs changing.
+
+**Parked items run one at a time at the end.** Parked items (after a conflict or a deferral) wait for quiet so they don't conflict again. To speed up: `unpark`, or `next <ids>`.
+
+**The run stopped with "5 failures in a row".** That's the safety stop. The automatic manager may diagnose it and propose bounded retries within the approved task; unresolved blockers or exhausted budgets remain stopped. Read the reasons, address the cause, then explicitly `retry` and `start`. Manual stops do not count as real failures.
+
+**You continued a failed item by hand and another item clashed with it.** When an item fails, its worktree goes to the next item. Don't keep working in a failed item's session; `retry` it, or raise its limits through the queue.
+
+**Size limits keep blocking an item.** Limits rise by themselves (`NEEDS`, escalation, split). "bypass limits" in its session lifts them for that item, and `[big]` or `[files= lines= min=]` in its line starts it higher.
+
+**`/queue` exists twice, or behaves oddly.** The old pi-queue package is still installed next to pi-flow. Remove it (`pi remove -l ./.pi/pi-queue` or the personal entry) and reload.
+
+**Pi Web shows a stray "w0" project.** Sessions of a removed worktree lose their grouping. `/task cleanup --all` keeps worktrees while item sessions exist. Delete those sessions (`/task cleanup`) before removing worktrees.
+
+**Pi Web asks for a password / "401".** Start Pi Web with `PI_WEB_PASSWORD` set in the environment the queue sees, or put `piWebPassword` in `.pi-queue/config.json`.
+
+**Pi Web isn't used although it runs.** The runner looks for Pi Web's run records and port 30141. Set `piWebUrl` in `.pi-queue/config.json` if yours differs. `runIn: "web"` refuses to start without it, and `"cli"` never uses it.
+
+**Nothing happens overnight.** Keep the machine awake (`caffeinate -dims`) and Pi Web running for Web workers. The detached supervisor survives closing the planning chat, not a machine shutdown or killed supervisor. Explicit start resumes saved state only when no interrupted worker ownership remains. Grant project trust before starting unattended CLI workers; saved trust denials are not overridden.
+
+**Parallel items rerun the same tests and the machine crawls.** Install pi-check (a separate plugin). The queue then sends every check through one shared broker per repo. Results are cached by file content and shared by all worktrees, identical runs in progress are joined, and heavy runs are throttled. Go failures that already fail on the base branch stop blocking items. See `/check status` for what runs and how much time was saved.