oh-my-opencode 4.11.1 → 4.12.1

package/packages/omo-codex/plugin/skills/teammode/scripts/team-guide.mjs

@@ -0,0 +1,111 @@
+// team-guide.mjs - render the member-facing field manual (guide.md) and the short
+// bootstrap trigger a new thread reads on startup. Pure string builders, no I/O.
+//
+// The manual is the durable, two-channel replacement for per-prompt guidance: the leader
+// writes it once at team creation, and every member thread is told to READ it instead of
+// receiving the rules inline each turn.
+
+function memberLine(member) {
+	const thread = member.threadId ? ` | thread ${member.threadId}` : " | thread not created yet";
+	const wt = member.worktree?.path ? ` | worktree ${member.worktree.path}` : "";
+	return `- **${member.id}** (${member.lens}) - ${member.focus}${member.deliverable ? ` -> ${member.deliverable}` : ""}${thread}${wt} [${member.status}]`;
+}
+
+function worktreeSection(team) {
+	if (!team.worktree?.enabled) {
+		return `## Worktrees
+
+This team does not use isolated git worktrees. Work in the shared repository checkout
+the leader is running from. If your changes would collide with another member's files,
+that is a coordination signal: mark yourself \`blocked\` and tell the leader at once.`;
+	}
+	const lines = team.members
+		.filter((m) => m.worktree?.path || m.worktree?.branch)
+		.map((m) => `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\``);
+	return `## Worktrees (ISOLATION IS ON - this is not optional for you)
+
+This team runs each member in its own git worktree branched off \`${team.worktree.baseBranch}\`.
+**You MUST work only inside your own worktree.** The very first thing you do is \`cd\` into it;
+every edit, command, and commit happens there. Never touch another member's worktree, and
+never edit files outside your assigned scope. Commit your work so the leader can integrate it.
+
+${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
+}
+
+export function buildGuide(team) {
+	const artifacts = team.paths?.artifacts ?? ".omo/teams/<session_id>/artifacts";
+	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
+	const roster = team.members.length ? team.members.map(memberLine).join("\n") : "- (no members yet)";
+	return `# Team ${team.teamName} - Member Field Manual
+
+> Auto-generated by the teammode script. This file is the single source of truth for how
+> this team works. Re-read it whenever you are unsure - do not improvise the protocol.
+
+- Team: **${team.teamName}** (id \`${team.teamId}\`)
+- Team state: \`${teamJson}\`
+- Thread/session title convention (use it EXACTLY): \`${team.threadTitleConvention}\`
+
+## Who you are (your identity is fixed)
+
+**You are a member of team ${team.teamName}, not a generic assistant.** You own exactly one
+slice of this team's work - the focus and deliverable assigned to your id below - and you are
+accountable for it end to end. Read your row, internalize it, and act as that owner for the
+whole session. Do not drift into other members' scope.
+
+${roster}
+
+## Leader
+
+**The main session is the leader. There is no other leader, and you are not it.** You report
+to the leader, take direction from the leader, and send your results to the leader. Peers
+coordinate with each other, but the leader owns the final decision and integration.
+
+## Communication rules (hard rules)
+
+- **All communication between team members, and from you to the leader, is in English.** This
+  is mandatory regardless of the language the task was given in.
+- **Exception: when the END USER addresses you directly, reply in the user's own language.**
+  Team-internal traffic stays English; user-facing replies match the user.
+- **Report to the leader the moment your work is complete.** A finished task that was never
+  reported does not count as done.
+- **Over-communicate relentlessly - report even the trivial.** Message constantly and
+  proactively: every finding, decision, hand-off, and even the smallest or most trivial step, the
+  moment it happens, in short lean notes. Never save it up for one final report. When in doubt,
+  send the message - far more and far smaller updates always beats going quiet. The instant
+  anything changes a peer's assumption, push it to them. Too many messages is correct here; the
+  only failure is going quiet.
+- **Stale, stuck, and silently-blocked states are NOT acceptable.** During long work send
+  \`WORKING: <your focus> - <phase>\` so the leader can see you are alive. If you truly cannot
+  proceed, send \`BLOCKED: <reason>\` immediately and propose the smallest unblock - never sit
+  idle and never disappear. Being quiet is a failure, not a pause.
+
+## Artifacts (how you hand work off)
+
+Exchange files and memos through the team artifacts directory:
+
+\`${artifacts}\`
+
+Drop deliverables, notes, diffs, and findings there as files, and reference them by path in
+your messages instead of pasting large content into a thread. Treat it as the team's shared
+desk: if a peer or the leader needs something from you, leave it in artifacts and point them to it.
+
+${worktreeSection(team)}
+
+## Done means reported and verified
+
+Your slice is done only when (1) the deliverable exists, (2) you have evidence it works, and
+(3) you have reported it to the leader. Until all three are true, keep going.`;
+}
+
+export function buildMemberPrompt(team, id) {
+	const member = team.members.find((m) => m.id === id);
+	if (!member) throw new Error(`no member with id "${id}"`);
+	const guide = team.paths?.guide ?? ".omo/teams/<session_id>/guide.md";
+	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
+	const where = member.cwd ? `Work inside \`${member.cwd}\`.` : "Work from the repository root unless your manual assigns a worktree.";
+	return `You are member ${member.id} of team ${team.teamName} - owner of: ${member.focus}.
+FIRST read your field manual at \`${guide}\`, then the team state at \`${teamJson}\`; they define your scope, deliverable, the leader, the artifacts directory, and the communication rules.
+${where}
+Communicate with the team and leader in English; reply to the end user in the user's own language.
+Start now, send WORKING/BLOCKED updates so you never look stale, and report to the leader the moment you are done.`;
+}

package/packages/omo-codex/plugin/skills/teammode/scripts/team-state.mjs

@@ -0,0 +1,250 @@
+// team-state.mjs - the teammode state model + atomic, symlink-guarded persistence.
+//
+// Zero external dependencies (node builtins only) so it runs byte-identically under
+// `node` and `bun` on macOS, Linux, and Windows with no install step, no POSIX shell,
+// and no python3 precondition. This is the SINGLE source of the team-state shape: the
+// model never hand-writes team.json - it calls these helpers through scripts/team.mjs.
+//
+// Rendering (the member field manual + bootstrap trigger) lives in team-guide.mjs so
+// this file stays the state concern only.
+
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export const LENSES = ["area", "ownership", "perspective"];
+export const MEMBER_STATUSES = ["pending", "active", "reported", "blocked", "archived"];
+// A team is never a single member: two or more distinct slices is the minimum. One isolated
+// job is a subagent, not a team.
+export const MIN_MEMBERS = 2;
+
+export function isUnderstaffed(team) {
+	return team.members.length < MIN_MEMBERS;
+}
+// A team dir is a single child of .omo/teams. This pattern alone blocks "/", "\", and a
+// leading "." so ".." and "a/b" can never name a team dir (the escape guard).
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isoNow(now) {
+	return now ?? new Date().toISOString();
+}
+
+export function buildTeam({ teamName, sessionName, sessionId = null, dir = null, worktreeEnabled = false, baseBranch = "dev", now }) {
+	if (!teamName?.trim()) throw new Error("team name is required");
+	if (!sessionName?.trim()) throw new Error("session name is required");
+	const ts = isoNow(now);
+	return {
+		schemaVersion: 2,
+		teamId: randomUUID(),
+		teamName: teamName.trim(),
+		sessionName: sessionName.trim(),
+		sessionId,
+		threadTitleConvention: `[${teamName.trim()}] ${sessionName.trim()}`,
+		status: "active",
+		createdAt: ts,
+		updatedAt: ts,
+		archivedAt: null,
+		leader: { kind: "main-session", sessionId },
+		communication: { memberLanguage: "english", replyToUserInUserLanguage: true },
+		worktree: { enabled: Boolean(worktreeEnabled), baseBranch, root: dir ? join(dir, "worktrees") : null },
+		paths: dir
+			? { dir, team: join(dir, "team.json"), guide: join(dir, "guide.md"), artifacts: join(dir, "artifacts") }
+			: null,
+		members: [],
+		log: [{ ts, event: "created", detail: `team ${teamName.trim()}` }],
+	};
+}
+
+function touch(team, event, detail) {
+	const ts = isoNow();
+	team.updatedAt = ts;
+	team.log.push({ ts, event, detail });
+	return team;
+}
+
+function memberById(team, id) {
+	const found = team.members.find((m) => m.id === id);
+	if (!found) throw new Error(`no member with id "${id}"`);
+	return found;
+}
+
+function normalizedFocus(focus) {
+	return focus.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function assertUniqueMemberFocus(team) {
+	const seen = new Map();
+	for (const member of team.members) {
+		const key = normalizedFocus(member.focus ?? "");
+		const previous = seen.get(key);
+		if (previous) {
+			throw new Error(`member focus "${member.focus}" duplicates "${previous.focus}" (no two members may own the same thing)`);
+		}
+		seen.set(key, member);
+	}
+}
+
+function assertTeamReadyForThreadBinding(team) {
+	if (isUnderstaffed(team)) {
+		throw new Error(
+			`cannot bind member threads until the team has at least ${MIN_MEMBERS} distinct members; current count is ${team.members.length}`,
+		);
+	}
+	assertUniqueMemberFocus(team);
+}
+
+export function addMember(team, { id, focus, lens, deliverable = "", branch = null }) {
+	if (!id?.trim()) throw new Error("member id is required");
+	if (!focus?.trim()) throw new Error("member focus is required - a concrete part, ownership area, or perspective");
+	if (!LENSES.includes(lens)) throw new Error(`invalid lens "${lens}" - use one of: ${LENSES.join(", ")}`);
+	const memberId = id.trim();
+	const memberFocus = focus.trim();
+	if (team.members.some((m) => m.id === memberId)) throw new Error(`member id "${memberId}" already exists (duplicate)`);
+	const duplicate = team.members.find((m) => normalizedFocus(m.focus) === normalizedFocus(memberFocus));
+	if (duplicate) throw new Error(`member focus "${memberFocus}" duplicates "${duplicate.focus}" (no two members may own the same thing)`);
+	team.members.push({
+		id: memberId,
+		focus: memberFocus,
+		lens,
+		deliverable: deliverable.trim(),
+		threadId: null,
+		threadTitle: team.threadTitleConvention,
+		cwd: null,
+		worktree: { path: null, branch: branch ?? null },
+		status: "pending",
+	});
+	return touch(team, "add-member", `member ${memberId} (${lens}): ${memberFocus}`);
+}
+
+export function bindThread(team, { id, threadId, cwd = null, worktreePath = null }) {
+	if (!threadId?.trim()) throw new Error("thread id is required");
+	assertTeamReadyForThreadBinding(team);
+	const m = memberById(team, id);
+	m.threadId = threadId.trim();
+	m.status = "active";
+	if (cwd) m.cwd = cwd;
+	if (team.worktree.enabled) m.worktree.path = worktreePath ?? cwd ?? m.worktree.path;
+	return touch(team, "bind-thread", `member ${id} -> thread ${threadId.trim()}`);
+}
+
+export function setMemberStatus(team, { id, status, note = "" }) {
+	if (!MEMBER_STATUSES.includes(status)) throw new Error(`invalid status "${status}" - use one of: ${MEMBER_STATUSES.join(", ")}`);
+	memberById(team, id).status = status;
+	return touch(team, "set-status", `member ${id} -> ${status}${note ? `: ${note}` : ""}`);
+}
+
+export function archive(team, { id = null, note = "" } = {}) {
+	if (id) {
+		memberById(team, id).status = "archived";
+		return touch(team, "archive-member", `member ${id}${note ? `: ${note}` : ""}`);
+	}
+	for (const m of team.members) m.status = "archived";
+	team.status = "archived";
+	team.archivedAt = isoNow();
+	return touch(team, "archive", note || "team archived; all members closed");
+}
+
+export function validateTeam(team) {
+	if (team?.schemaVersion !== 2) throw new Error("invalid team: schemaVersion must be 2");
+	if (!team.teamId || !team.teamName) throw new Error("invalid team: teamId and teamName are required");
+	if (team.leader?.kind !== "main-session") throw new Error("invalid team: leader.kind must be main-session");
+	if (!Array.isArray(team.members)) throw new Error("invalid team: members must be an array");
+	assertUniqueMemberFocus(team);
+	return team;
+}
+
+// Resolve (and confine) a team dir to a single child of <cwd>/.omo/teams.
+export function resolveTeamDir(cwd, sessionId) {
+	if (!SESSION_ID_PATTERN.test(sessionId ?? "")) throw new Error(`invalid or unsafe session id "${sessionId}"`);
+	return resolve(cwd, ".omo", "teams", sessionId);
+}
+
+async function lstatOrNull(p) {
+	return lstat(p).catch((error) => {
+		if (error && error.code === "ENOENT") return null;
+		throw error;
+	});
+}
+
+// Create a directory chain refusing any symlinked component, so team state can never be
+// written through a symlink that escapes the workspace.
+async function mkdirNoSymlink(dir, stopAt) {
+	if (dir === stopAt) return;
+	const rel = relative(stopAt, dir);
+	if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: path escapes ${stopAt}: ${dir}`);
+	await mkdirNoSymlink(dirname(dir), stopAt);
+	const st = await lstatOrNull(dir);
+	if (st) {
+		if (st.isSymbolicLink()) throw new Error(`refused: path component is a symlink: ${dir}`);
+		if (!st.isDirectory()) throw new Error(`refused: path component is not a directory: ${dir}`);
+		return;
+	}
+	await mkdir(dir);
+}
+
+async function assertNoSymlinkComponents(dir, stopAt) {
+	if (dir === stopAt) return;
+	const rel = relative(stopAt, dir);
+	if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: path escapes ${stopAt}: ${dir}`);
+	await assertNoSymlinkComponents(dirname(dir), stopAt);
+	const st = await lstatOrNull(dir);
+	if (st?.isSymbolicLink()) throw new Error(`refused: path component is a symlink: ${dir}`);
+}
+
+export async function ensureTeamDir(cwd, sessionId) {
+	const workspaceRoot = resolve(cwd);
+	const teamsRoot = resolve(cwd, ".omo", "teams");
+	const dir = resolveTeamDir(cwd, sessionId);
+	await mkdirNoSymlink(teamsRoot, workspaceRoot);
+	await mkdirNoSymlink(dir, teamsRoot);
+	await mkdirNoSymlink(join(dir, "artifacts"), dir);
+	return dir;
+}
+
+export async function assertSafeTeamDir(cwd, sessionId) {
+	const workspaceRoot = resolve(cwd);
+	const teamsRoot = resolve(cwd, ".omo", "teams");
+	const dir = resolveTeamDir(cwd, sessionId);
+	await assertNoSymlinkComponents(teamsRoot, workspaceRoot);
+	await assertNoSymlinkComponents(dir, teamsRoot);
+	return dir;
+}
+
+export async function readTeam(dir) {
+	return validateTeam(JSON.parse(await readFile(join(dir, "team.json"), "utf8")));
+}
+
+export async function teamExists(dir) {
+	return (await lstatOrNull(join(dir, "team.json"))) !== null;
+}
+
+async function persistedFileTarget(team, pathKey, fileName, expectedDir) {
+	validateTeam(team);
+	if (!team.paths?.dir || !team.paths?.[pathKey]) throw new Error(`invalid team: paths.${pathKey} is required`);
+	const dir = resolve(expectedDir);
+	if (resolve(team.paths.dir) !== dir) throw new Error(`refused: persisted team dir does not match trusted team dir: ${team.paths.dir}`);
+	const target = resolve(team.paths[pathKey]);
+	if (target !== resolve(dir, fileName)) throw new Error(`refused: ${fileName} persist target escapes team dir: ${team.paths[pathKey]}`);
+	const dirStat = await lstatOrNull(dir);
+	if (dirStat?.isSymbolicLink()) throw new Error(`refused: team dir is a symlink: ${dir}`);
+	const st = await lstatOrNull(target);
+	if (st?.isSymbolicLink()) throw new Error(`refused: ${fileName} is a symlink: ${target}`);
+	if (st && !st.isFile()) throw new Error(`refused: ${fileName} is not a file: ${target}`);
+	return target;
+}
+
+async function writePersistedFileAtomic(team, pathKey, fileName, content, expectedDir) {
+	const target = await persistedFileTarget(team, pathKey, fileName, expectedDir);
+	const tmp = `${target}.tmp-${process.pid}-${randomUUID()}`;
+	await writeFile(tmp, content, { encoding: "utf8", flag: "wx" });
+	await rename(tmp, target);
+	return team;
+}
+
+export async function writeTeamAtomic(team, expectedDir) {
+	return writePersistedFileAtomic(team, "team", "team.json", `${JSON.stringify(team, null, 2)}\n`, expectedDir);
+}
+
+export async function writeGuideAtomic(team, content, expectedDir) {
+	return writePersistedFileAtomic(team, "guide", "guide.md", content, expectedDir);
+}

package/packages/omo-codex/plugin/skills/teammode/scripts/team.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// team.mjs - the teammode controller CLI. Thin argv dispatch over team-state.mjs (the
+// state model) and team-guide.mjs (the member field manual). It replaces hand-written
+// team.json / guide.md so the model never has to author those files by hand.
+//
+// Zero external dependencies (node builtins only): runs identically under node and bun on
+// macOS, Linux, and Windows.
+//
+//   node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<sess>" [--session <id>] [--worktree] [--base-branch dev]
+//   node "<skill-root>/scripts/team.mjs" add-member  --team <id> --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <b>]
+//   node "<skill-root>/scripts/team.mjs" bind-thread  --team <id> --id A --thread <thread-id> [--cwd <path>]
+//   node "<skill-root>/scripts/team.mjs" member-prompt --team <id> --id A
+//   node "<skill-root>/scripts/team.mjs" set-status   --team <id> --id A --status reported|blocked|active|archived [--note "<...>"]
+//   node "<skill-root>/scripts/team.mjs" archive      --team <id> [--id A] [--note "<...>"]
+//   node "<skill-root>/scripts/team.mjs" delete       --team <id> [--force]
+//   node "<skill-root>/scripts/team.mjs" status       --team <id>
+//   node "<skill-root>/scripts/team.mjs" guide        --team <id>
+
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { buildGuide, buildMemberPrompt } from "./team-guide.mjs";
+import {
+	addMember,
+	archive,
+	assertSafeTeamDir,
+	bindThread,
+	buildTeam,
+	ensureTeamDir,
+	isUnderstaffed,
+	MIN_MEMBERS,
+	readTeam,
+	resolveTeamDir,
+	setMemberStatus,
+	teamExists,
+	writeGuideAtomic,
+	writeTeamAtomic,
+} from "./team-state.mjs";
+
+function parseFlags(args) {
+	const flags = { _: [] };
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (!arg.startsWith("--")) {
+			flags._.push(arg);
+			continue;
+		}
+		const key = arg.slice(2);
+		const next = args[i + 1];
+		if (next === undefined || next.startsWith("--")) {
+			flags[key] = true;
+		} else {
+			flags[key] = next;
+			i++;
+		}
+	}
+	return flags;
+}
+
+function requireFlag(flags, name) {
+	const value = flags[name];
+	if (value === undefined || value === true) throw new Error(`missing required flag --${name}`);
+	return value;
+}
+
+async function loadTeam(cwd, sessionId) {
+	const dir = await assertSafeTeamDir(cwd, sessionId);
+	return { dir, team: await readTeam(dir) };
+}
+
+async function persist(team, dir) {
+	await writeTeamAtomic(team, dir);
+	await writeGuideAtomic(team, buildGuide(team), dir);
+}
+
+const handlers = {
+	async init(cwd, flags) {
+		const teamName = requireFlag(flags, "name");
+		const sessionName = requireFlag(flags, "session-name");
+		const sessionId = typeof flags.session === "string" ? flags.session : `team-${randomUUID().slice(0, 8)}`;
+		const dir = await ensureTeamDir(cwd, sessionId);
+		if (await teamExists(dir)) {
+			process.stdout.write(`exists: ${dir} (left untouched; re-init is a safe no-op)\n`);
+			return;
+		}
+		const team = buildTeam({
+			teamName,
+			sessionName,
+			sessionId,
+			dir,
+			worktreeEnabled: flags.worktree === true,
+			baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : "dev",
+		});
+		await persist(team, dir);
+		process.stdout.write(`created: ${dir}\n`);
+		process.stdout.write(`team.json + guide.md written; artifacts/ ready. session id: ${sessionId}\n`);
+		process.stdout.write(`next: add-member --team ${sessionId} --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
+	},
+
+	async "add-member"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		const memberId = requireFlag(flags, "id").trim();
+		addMember(team, {
+			id: memberId,
+			focus: requireFlag(flags, "focus"),
+			lens: requireFlag(flags, "lens"),
+			deliverable: typeof flags.deliverable === "string" ? flags.deliverable : "",
+			branch: typeof flags.branch === "string" ? flags.branch : null,
+		});
+		await persist(team, dir);
+		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\nSend this as the new thread's first message (title it "${team.threadTitleConvention}"):\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
+	},
+
+	async "bind-thread"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		bindThread(team, {
+			id: requireFlag(flags, "id"),
+			threadId: requireFlag(flags, "thread"),
+			cwd: typeof flags.cwd === "string" ? flags.cwd : null,
+			worktreePath: typeof flags["worktree-path"] === "string" ? flags["worktree-path"] : null,
+		});
+		await persist(team, dir);
+		process.stdout.write(`bound member ${flags.id} to thread ${flags.thread}.\n`);
+	},
+
+	async "member-prompt"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { team } = await loadTeam(cwd, sessionId);
+		process.stdout.write(`${buildMemberPrompt(team, requireFlag(flags, "id"))}\n`);
+	},
+
+	async "set-status"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		setMemberStatus(team, {
+			id: requireFlag(flags, "id"),
+			status: requireFlag(flags, "status"),
+			note: typeof flags.note === "string" ? flags.note : "",
+		});
+		await persist(team, dir);
+		process.stdout.write(`member ${flags.id} -> ${flags.status}\n`);
+	},
+
+	async archive(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		archive(team, {
+			id: typeof flags.id === "string" ? flags.id : null,
+			note: typeof flags.note === "string" ? flags.note : "",
+		});
+		await persist(team, dir);
+		process.stdout.write(flags.id ? `archived member ${flags.id}\n` : `archived team ${sessionId} and closed all members\n`);
+	},
+
+	async delete(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		const active = team.members.filter((m) => m.status !== "archived");
+		if (flags.force !== true && (team.status !== "archived" || active.length > 0)) {
+			throw new Error(
+				`refused: team "${sessionId}" is not archived or still has ${active.length} active member(s). Archive first, or pass --force to delete anyway.`,
+			);
+		}
+		await rm(dir, { recursive: true, force: true });
+		process.stdout.write(`deleted team state: ${dir}\n`);
+	},
+
+	async status(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { team } = await loadTeam(cwd, sessionId);
+		process.stdout.write(`Team ${team.teamName} [${team.status}] - leader: main session - ${team.members.length} member(s)\n`);
+		for (const m of team.members) {
+			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${m.threadId ? ` thread=${m.threadId}` : ""}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
+		}
+		if (isUnderstaffed(team)) {
+			process.stdout.write(
+				`WARNING: a team needs at least ${MIN_MEMBERS} members; this team has ${team.members.length}. A single-member team is not a team - add another distinct slice or use a subagent.\n`,
+			);
+		}
+	},
+
+	async guide(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		await writeGuideAtomic(team, buildGuide(team), dir);
+		process.stdout.write(`${team.paths.guide}\n`);
+	},
+};
+
+async function main() {
+	const [subcommand, ...rest] = process.argv.slice(2);
+	const handler = handlers[subcommand];
+	if (!handler) {
+		throw new Error(`unknown subcommand "${subcommand ?? ""}" - expected one of: ${Object.keys(handlers).join(", ")}`);
+	}
+	await handler(process.cwd(), parseFlags(rest));
+}
+
+// Symlink-robust main-module check: a symlinked install invokes this file through a symlink
+// path while node resolves import.meta.url to the realpath, so compare the resolved real paths
+// (falling back to the literal url comparison if a path cannot be resolved).
+function isInvokedAsScript() {
+	const entry = process.argv[1];
+	if (!entry) return false;
+	try {
+		return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(entry);
+	} catch {
+		return import.meta.url === pathToFileURL(entry).href;
+	}
+}
+
+if (isInvokedAsScript()) {
+	await main().catch((error) => {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		process.exit(1);
+	});
+}

package/packages/omo-codex/plugin/skills/ultraresearch/SKILL.md

@@ -49,6 +49,14 @@ The research is done when all of these hold:
 - Every claim in the deliverable cites a source or a verification artifact.
 - The session journal reconstructs what was searched, found, and expanded, wave by wave.
 
+## Run the swarm as a cooperating team
+
+Saturation research is the textbook case for a cooperating team, not isolated fire-and-forget workers: a lead one worker surfaces almost always reshapes what another should search next. So when your harness gives you real cooperating members — Codex: the `teammode` skill (`codex_app` threads); OpenCode: `team_mode` — run this swarm as a team. Fall back to the background-worker swarm below only when team mode is unavailable, or the axes are genuinely independent with no cross-pollination expected.
+
+- **One member per axis — by part, ownership, or perspective, never a job title.** Each Phase 0 axis is one member owning one concrete slice: a codebase part, a source territory, or a question lens. No two members share an angle. "Backend researcher" or "the web person" gives no real boundary and invites overlap — name what the member owns.
+- **The raise law — broadcast every lead the instant it surfaces.** Members over-communicate relentlessly: every new lead, finding, contradiction, and dead end is raised to you the moment it surfaces, never hoarded for a final dump. Through long passes they send `WORKING: <axis> - <phase>`, and `BLOCKED: <reason>` the moment progress stops, so you always know a member is alive. Too many small updates is correct here; going quiet is the only failure.
+- **You lead; expand on each raised lead.** Members raise via message text, never write session files. Journal each lead and spawn its expansion the instant it lands (Phase 2), not only when a member's final reply arrives.
+
 ## Worker ground rules
 
 Research workers (explore, librarian, browsing) differ by harness, but assume:
@@ -104,7 +112,7 @@ Append each digest the moment its worker returns, not in a batch at the end —
 
 ## Phase 1 — Saturation wave
 
-Launch every first-wave worker in a single turn, all in background. Sequential launches and "start with one and see" defeat the mode.
+Launch the entire first wave in one turn — every axis at once, as team members if you formed a team, else as background workers. Sequential launches and "start with one and see" defeat the mode.
 
 Scaling floor — more angles always justify more workers:
 
@@ -135,7 +143,7 @@ End your reply with the ## EXPAND tail: '- LEAD: <discovery> — WHY: <why> —
 
 ## Phase 2 — Expand until convergence
 
-This loop is what makes the mode research rather than search. Collect workers as they finish — never wait for the full wave:
+This loop is what makes the mode research rather than search. Collect returns as they land — and in team mode, act on each lead the moment a member raises it, never waiting for the full wave or a member's final reply:
 
 1. Journal the return: digest plus verbatim EXPAND markers into `wave-<N>-<kind>-<axis>.md`.
 2. Deduplicate new markers against `expansion-log.md` — every lead ever seen, not just confirmed ones, or rejected leads resurface each wave.
@@ -219,6 +227,7 @@ High-yield combinations: official docs (`site:<docs domain>`), GitHub implementa
 | Failure | Correction |
 |---|---|
 | Sequential spawning, or trimming the first wave | All first-wave workers in one turn, background, scaling floor respected |
+| A team member hoards leads for one final dump | Raise law — every lead, finding, and dead end broadcast the moment it surfaces |
 | Worker reply without the EXPAND tail | One follow-up demanding it; the lane stays open until it lands |
 | Stopping after wave 1 because "enough was found" | Convergence rules only: 2+ expansion waves, leads run dry |
 | Obeying a surrounding "stop exploring" rule mid-research | Authority section — those rules do not bind this mode |

package/packages/omo-codex/plugin/skills/ultraresearch/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "(OmO) ultraresearch"

package/packages/omo-codex/plugin/skills/ulw-loop/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
-  display_name: "ulw-loop (omo)"
+  display_name: "(OmO) ulw-loop"
   short_description: "Goal-like ultrawork loop for systematic decomposition"
   search_terms:
     - "ulw-loop"

package/packages/omo-codex/plugin/skills/ulw-plan/SKILL.md

@@ -17,6 +17,7 @@ Outcome-first: explore a lot, ask few sharp questions - or none, when the intent
 
 After grounding, make ONE judgment and load ONE intent reference (you ALSO read `references/full-workflow.md` for the shared mechanics - see below). The test keys on whether the desired **OUTCOME** is clear, NOT on request length.
 
+- **OVERRIDE - explicit ask wins:** if the user explicitly asks to be questioned or interviewed ("ask me", "interview me", "why aren't you asking me" - in any language), route **CLEAR**, run the interview, and turn the adopt-default filter OFF: the user has claimed the forks, so every surviving one is ASKED, not defaulted. This beats the OUTCOME test below, even on a fuzzy brief.
 - **CLEAR** - the user knows the outcome; the only open items are preferences/tradeoffs the repo cannot answer (genuine owner-decisions). Read **`references/intent-clear.md`**: ask the surviving forks with WHY, run the normal approval gate, high-accuracy review is OPTIONAL (offered as one question).
 - **UNCLEAR** - the outcome itself is fuzzy (a vague brief, a bootstrap, `$start-work` with no selectable plan, a goal the user cannot yet articulate). Asking would offload your own job onto the user. Read **`references/intent-unclear.md`**: research maximally, adopt and ANNOUNCE best-practice defaults, do NOT ask the user extra questions, and run high-accuracy review AUTOMATICALLY (unless Classify sized the work Trivial).
 - **ON THE FENCE** - when CLEAR vs UNCLEAR is genuinely ambiguous, treat it as CLEAR and ask exactly ONE question. A user wrongly silenced is worse than one extra question. The dominant failure to guard against is mis-routing a CLEAR request to UNCLEAR, which silently applies defaults and overrides forks the user wanted to own.
@@ -42,7 +43,7 @@ Run it ONCE at plan generation. A plain re-run on an existing plan is a safe no-
 - **Decision-complete is the north star.** The executor has NO interview context - spell out exact paths, "every X in Y", and an explicit Must-NOT-Have. Leave the implementer ZERO judgment calls.
 - **Explore before asking.** Discoverable facts (repo/system/docs truth) -> research and cite, never ask. Preferences/tradeoffs -> the only things you bring to the user. When unsure which, treat it as a user-decision.
 - **CodeGraph first when present.** Use `codegraph_explore` for repo how/where/what/flow questions before wider reads; if codegraph_* tools are absent, inactive/uninitialized, or cold-start unavailable, continue with Read/Grep/Glob/LSP and the ast-grep skill.
-- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask. Only a real fork survives.
+- **Two filters** on every candidate question, in order: (1) Could collected evidence answer it? -> explore instead. (2) Could the user's stated intent plus a defensible default answer it? -> adopt the default, record it, do not ask - UNLESS it is an owner-decision, which always survives as a question even when a default exists: anything irreversible / destructive / safety-critical, or a cross-cutting product choice the user lives with (public config surface, distribution / packaging, external dependency or pinned SHA, data / schema shape). Default the reversible internals; surface the owner-decisions.
 - **Explore to sufficiency, then STOP.** One research wave per open question; stop when the clearance check is answerable; never re-explore to double-check.
 - **Parallel-dispatch** independent research in ONE turn and keep working while it runs. Subagent outputs are CLAIMS until you independently verify them.
 - **Approval is not execution.** Approval authorizes writing the plan ONLY, never implementation. ONE request -> ONE plan, however large.

package/packages/omo-codex/plugin/skills/ulw-plan/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
-  display_name: "ulw-plan (omo)"
+  display_name: "(OmO) ulw-plan"
   short_description: "Explore-first planning consultant that waits for your okay"
   search_terms:
     - "ulw-plan"