oh-my-opencode 4.12.0 → 4.13.0

package/packages/omo-codex/plugin/components/codegraph/test/session-start-worker-flow.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodegraphCommandInvocation, runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart worker flow", () => {
+	it("#given Windows install_dir has codegraph.cmd #when worker resolves provisioned CodeGraph #then it uses the cmd shim", async () => {
+		await withProcessPlatform("win32", async () => {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-home-"));
+			const installDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-install-"));
+			const binPath = join(installDir, "bin", "codegraph.cmd");
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				mkdirSync(join(installDir, "bin"), { recursive: true });
+				writeFileSync(binPath, "");
+
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], trustedCodegraphInstallDir: installDir, warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => {
+							throw new Error("provisioning should not run when install_dir binary exists");
+						},
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: (options) => {
+							const provisioned = options?.provisioned?.() ?? null;
+							return { argsPrefix: [], command: provisioned ?? "missing-codegraph", exists: provisioned !== null, source: provisioned === null ? "path" : "provisioned" };
+						},
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? '{"initialized":false}' : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: "initialized" });
+				expect(calls.map((call) => ({ args: [...call.args], command: call.command }))).toEqual([
+					{ args: ["status", "--json"], command: binPath },
+					{ args: ["init"], command: binPath },
+				]);
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe(installDir);
+				expect(outcomes).toEqual([{ action: "initialized", exitCode: 0, projectRoot: workspace, source: "provisioned", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+				rmSync(installDir, { recursive: true, force: true });
+			}
+		});
+	});
+
+	it("#given Windows codegraph.cmd #when default worker runner builds invocation #then it runs through cmd.exe", () => {
+		// given
+		const command = "C:\\Users\\test\\.omo\\codegraph\\bin\\codegraph.cmd";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["status", "--json"], "win32");
+
+		// then
+		expect(invocation).toEqual({
+			args: ["/d", "/s", "/c", command, "status", "--json"],
+			command: "cmd.exe",
+		});
+	});
+
+	it("#given non-Windows codegraph command #when default worker runner builds invocation #then it executes directly", () => {
+		// given
+		const command = "/home/test/.omo/codegraph/bin/codegraph";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["sync"], "linux");
+
+		// then
+		expect(invocation).toEqual({ args: ["sync"], command });
+	});
+
+	it("#given resolved CodeGraph status #when worker runs #then it runs status before init or sync", async () => {
+		for (const scenario of [
+			{ action: "initialized", args: [["status", "--json"], ["init"]], stdout: '{"initialized":false}' },
+			{ action: "synced", args: [["status", "--json"], ["sync"]], stdout: '{"initialized":true}' },
+		] as const) {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-status-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-status-home-"));
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: "/tmp/codegraph-install" }, sources: [], trustedCodegraphInstallDir: "/tmp/codegraph-install", warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => Promise.resolve({ binPath: "/tmp/codegraph", provisioned: true }),
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: () => ({ argsPrefix: [], command: "/tmp/codegraph", exists: true, source: "path" }),
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? scenario.stdout : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: scenario.action });
+				expect(calls.map((call) => [...call.args])).toEqual(scenario.args.map((args) => [...args]));
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe("/tmp/codegraph-install");
+				expect(outcomes).toEqual([{ action: scenario.action, exitCode: 0, projectRoot: workspace, source: "path", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+			}
+		}
+	});
+});
+
+async function withProcessPlatform(platform: NodeJS.Platform, run: () => Promise<void>): Promise<void> {
+	const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
+	Object.defineProperty(process, "platform", { configurable: true, enumerable: true, value: platform });
+	try {
+		await run();
+	} finally {
+		if (descriptor !== undefined) Object.defineProperty(process, "platform", descriptor);
+	}
+}

package/packages/omo-codex/plugin/components/comment-checker/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-comment-checker",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex plugin that runs comment-checker after edit-like PostToolUse hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/git-bash/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-git-bash-hook",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex hook component that reminds Windows sessions to prefer the OMO git_bash MCP.",
 	"type": "module",
 	"private": true,

package/packages/omo-codex/plugin/components/lazycodex-executor-verify/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lazycodex-executor-verify",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex SubagentStop evidence verifier for LazyCodex executor completions.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/lsp/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lsp",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex plugin that exposes Language Server Protocol tools and post-edit diagnostics.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/dist/cli.js

@@ -4032,9 +4032,9 @@ function getSparkShellRuntimeAwareness(env = process.env, deps = {}) {
   return [
     SPARKSHELL_AWARENESS_MARKER,
     "",
-    `- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-    `- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+    `- Use \`${command} sparkshell <command>\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+    `- Use \`${command} sparkshell --shell '<command>'\` only for shell metacharacters or pipelines.`,
+    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
     "- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
     "- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
     `- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

package/packages/omo-codex/plugin/components/rules/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-rules",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex plugin that injects project rule files into model context through lifecycle hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/src/sparkshell-awareness.ts

@@ -81,9 +81,9 @@ export function getSparkShellRuntimeAwareness(env: RuntimeEnv = process.env, dep
 	return [
 		SPARKSHELL_AWARENESS_MARKER,
 		"",
-		`- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-		`- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+		`- Use \`${command} sparkshell <command>\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+		`- Use \`${command} sparkshell --shell '<command>'\` only for shell metacharacters or pipelines.`,
+		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
 		"- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
 		"- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
 		`- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

package/packages/omo-codex/plugin/components/rules/test/sparkshell-awareness.test.ts

@@ -19,6 +19,29 @@ function parseAdditionalContext(output: string): string {
 	return parsed.hookSpecificOutput?.additionalContext ?? "";
 }
 
+function normalizeGuidance(value: string): string {
+	return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function expectSparkshellFirstContract(value: string): void {
+	const guidance = normalizeGuidance(value);
+
+	expect(guidance).toMatch(/`omo sparkshell <command>`[^.]*\bfirst\b/);
+	expect(guidance).toMatch(/\brepo inspection\b/);
+	expect(guidance).toMatch(/\bcli smoke tests\b/);
+	expect(guidance).toMatch(/\bgit\/history checks\b/);
+	expect(guidance).toMatch(/\bbounded command output\b/);
+	expect(guidance).toMatch(/\braw\b[^.]*`rg`\/`grep`\/`cat`\/`git`[^.]*\bfallbacks?\b/);
+	expect(guidance).toMatch(/\bsparkshell is unavailable\b/);
+	expect(guidance).toMatch(/\btoo narrow\b/);
+	expect(guidance).toMatch(/`omo sparkshell --shell '<command>'`[^.]*\bmetacharacters\b[^.]*\bpipelines\b/);
+	expect(guidance).toMatch(
+		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bonly\b[^.]*\binspect\b[^.]*\bexisting pane\b/,
+	);
+	expect(guidance).toMatch(/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bnever\b[^.]*\blaunch ordinary commands\b/);
+	expect(guidance).not.toMatch(/\bprefer\b[^.]*\bbefore raw shell commands\b/);
+}
+
 function parseHookOutput(value: unknown): HookOutput {
 	if (typeof value !== "object" || value === null) {
 		return {};
@@ -85,15 +108,16 @@ describe("Codex Sparkshell awareness", () => {
 		);
 
 		// then
-		expect(parseAdditionalContext(output)).toContain("omo sparkshell <command>");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_CONDENSE");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SPARK");
-		expect(parseAdditionalContext(output)).toContain("[sparkshell caption]");
-		expect(parseAdditionalContext(output)).toContain("never appends that context to command output");
-		expect(parseAdditionalContext(output)).toContain("what the full output contained");
-		expect(parseAdditionalContext(output)).not.toContain("[REDACTED]");
-		expect(parseAdditionalContext(output)).not.toContain("appends recent session context");
+		const context = parseAdditionalContext(output);
+		expectSparkshellFirstContract(context);
+		expect(context).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
+		expect(context).toContain("OMO_SPARKSHELL_CONDENSE");
+		expect(context).toContain("OMO_SPARKSHELL_SPARK");
+		expect(context).toContain("[sparkshell caption]");
+		expect(context).toContain("never appends that context to command output");
+		expect(context).toContain("what the full output contained");
+		expect(context).not.toContain("[REDACTED]");
+		expect(context).not.toContain("appends recent session context");
 	});
 
 	it("#given inactive env #when SessionStart runs #then emits no Sparkshell guidance", async () => {

package/packages/omo-codex/plugin/components/start-work-continuation/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-start-work-continuation",
-	"version": "4.12.0",
+	"version": "4.13.0",
 	"description": "Codex Stop hook continuation injector for omo-codex start-work plans.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/teammode/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+// components/teammode/src/codex-hook.ts
+var CREATE_THREAD_TOOL_NAMES = new Set(["create_thread", "codex_app.create_thread"]);
+function parsePostToolUsePayload(raw) {
+  if (raw.trim().length === 0)
+    return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return isPostToolUsePayload(parsed) ? parsed : null;
+  } catch (error) {
+    if (error instanceof SyntaxError)
+      return null;
+    return null;
+  }
+}
+function runPostToolUseHook(payload) {
+  if (payload.hook_event_name !== "PostToolUse")
+    return "";
+  if (!CREATE_THREAD_TOOL_NAMES.has(payload.tool_name))
+    return "";
+  const threadReference = extractThreadCreationReference(payload.tool_response);
+  if (threadReference === null)
+    return "";
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: threadTitleReminder(threadReference)
+    }
+  };
+  return `${JSON.stringify(output)}
+`;
+}
+async function runTeammodeHookCli(stdin, stdout) {
+  const payload = parsePostToolUsePayload(await readAll(stdin));
+  if (payload === null)
+    return;
+  const output = runPostToolUseHook(payload);
+  if (output.length > 0)
+    stdout.write(output);
+}
+function threadTitleReminder(threadReference) {
+  const id = formatIdentifier(threadReference.id);
+  return threadReference.kind === "thread" ? `THREAD ID ${id}: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.` : `PENDING WORKTREE ID ${id}: CALL codex_app.set_thread_title AS SOON AS THREAD ID EXISTS. USE THE REAL TASK/ROLE.`;
+}
+function formatIdentifier(value) {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized.length <= 200 ? normalized : `${normalized.slice(0, 197)}...`;
+}
+function extractThreadCreationReference(toolResponse) {
+  if (!isRecord(toolResponse))
+    return null;
+  const threadId = toolResponse["threadId"];
+  if (typeof threadId === "string" && threadId.trim().length > 0) {
+    return { kind: "thread", id: threadId };
+  }
+  const pendingWorktreeId = toolResponse["pendingWorktreeId"];
+  if (typeof pendingWorktreeId === "string" && pendingWorktreeId.trim().length > 0) {
+    return { kind: "pendingWorktree", id: pendingWorktreeId };
+  }
+  return null;
+}
+function isPostToolUsePayload(value) {
+  if (!isRecord(value))
+    return false;
+  return value["hook_event_name"] === "PostToolUse" && typeof value["session_id"] === "string" && typeof value["tool_name"] === "string" && Object.hasOwn(value, "tool_input") && Object.hasOwn(value, "tool_response") && optionalString(value["turn_id"]) && optionalString(value["cwd"]) && optionalString(value["model"]) && optionalString(value["permission_mode"]) && optionalString(value["tool_use_id"]) && (value["transcript_path"] === undefined || value["transcript_path"] === null || typeof value["transcript_path"] === "string");
+}
+function optionalString(value) {
+  return value === undefined || typeof value === "string";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readAll(stdin) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => {
+      data += chunk instanceof Buffer ? chunk.toString() : String(chunk);
+    });
+    stdin.once("error", reject);
+    stdin.once("end", () => resolve(data));
+  });
+}
+
+// components/teammode/src/cli.ts
+var [command, subcommand] = process.argv.slice(2);
+if (command === "hook" && subcommand === "post-tool-use") {
+  await runTeammodeHookCli(process.stdin, process.stdout);
+} else {
+  process.stderr.write(`Usage: omo-teammode hook post-tool-use
+`);
+  process.exitCode = 2;
+}

package/packages/omo-codex/plugin/components/teammode/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+	"hooks": {
+		"PostToolUse": [
+			{
+				"matcher": "^(create_thread|codex_app\\.create_thread)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use",
+						"timeout": 10,
+						"statusMessage": "(OmO) Checking Thread Title Hygiene"
+					}
+				]
+			}
+		]
+	}
+}

package/packages/omo-codex/plugin/components/teammode/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@sisyphuslabs/codex-teammode",
+	"version": "4.13.0",
+	"description": "Codex team-mode hook component that keeps background thread titles descriptive after create_thread.",
+	"type": "module",
+	"private": true,
+	"files": [
+		"dist",
+		"hooks",
+		"skills"
+	],
+	"scripts": {
+		"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build src/cli.ts --target node --format esm --outfile dist/cli.js",
+		"test": "bun test test/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.3",
+		"bun-types": "^1.3.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.8"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}

package/packages/omo-codex/plugin/components/teammode/skills/teammode/SKILL.md

@@ -26,11 +26,15 @@ Use plain subagents (`$ulw` / `multi_agent_v1.spawn_agent`) - NOT a team - when
 A team buys cross-member coordination at a real overhead cost; only spend it when coordination
 is the thing you actually need.
 
-## You are the leader
+## You are the leader - orchestrate, do not implement
 
-The main session is ALWAYS the team leader. Do NOT create a separate leader thread - you
-orchestrate directly. Members are the threads you create; they report to you, and you own the
-final synthesis and any integration.
+The main session is ALWAYS the team leader; you orchestrate directly and never spin up a separate
+leader thread. Your job is orchestration, NOT writing product code: split the work and assign each
+slice, hold live situational awareness of every member, verify and QA what they deliver, relay
+findings between members, instruct and unblock, and synthesize the result. DELEGATE every code edit
+to a member - if you catch yourself editing product files while the team runs, that work was a
+member's slice you should have handed off. You own direction, verification, and integration (the
+merge), not the keystrokes.
 
 ## Compose by part, ownership, or perspective - not by job title
 
@@ -45,6 +49,9 @@ member by a concrete slice: a specific part of the codebase, an ownership area,
 perspective/lens. Assigning a vague role ("backend dev", "release analyst", "the tester") is an
 anti-pattern - it gives the member no real boundary and invites overlap. Each member's `focus`
 names what they own concretely; the `lens` is one of `area`, `ownership`, or `perspective`.
+Give each member a short, distinct `--name` too - its role or what it watches (e.g.
+`app-server-lifecycle`, `mailbox-delivery`) - because that name titles its thread; never reuse
+one name for two members.
 
 ## Run the script - never hand-write team state
 
@@ -54,10 +61,13 @@ Replace `<skill-root>` with this skill's own directory.
 
 ```
 node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<session>" [--session <leader_session_id>] [--worktree] [--base-branch dev]
-node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
+node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
 node "<skill-root>/scripts/team.mjs" bind-thread  --team <session_id> --id A --thread <thread_id> [--cwd <path>]
 node "<skill-root>/scripts/team.mjs" member-prompt --team <session_id> --id A
 node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --status reported|blocked|active|archived [--note "<...>"]
+node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
+node "<skill-root>/scripts/team.mjs" worktree-remove --team <session_id> --id A [--force]
+node "<skill-root>/scripts/team.mjs" integrate       --team <session_id> [--id A]
 node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A]
 node "<skill-root>/scripts/team.mjs" delete       --team <session_id> [--force]
 node "<skill-root>/scripts/team.mjs" status       --team <session_id>
@@ -74,11 +84,11 @@ subcommand rewrites `guide.md`, so the manual always matches the current team.
 
 1. `init` the team, then `add-member` once per member.
 2. Create a durable thread per member with `codex_app.create_thread` - ALWAYS this tool for every
-   member, never a spawned agent - titled EXACTLY
-   `[team name] {session name}` (keep this convention strictly). If `codex_app.create_thread`
-   accepts a working directory / cwd argument, set it to that member's worktree; otherwise the
-   member's manual tells it to `cd` there first. Use `codex_app.set_thread_title` if the title
-   did not land at creation.
+   member, never a spawned agent - titled `[team name] <member name>`, using THAT member's own
+   name (its role / what it watches), so no two threads share a title. `add-member` prints the
+   exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
+   set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
+   Use `codex_app.set_thread_title` if the title did not land at creation.
 3. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
    trigger (printed by `add-member` / `member-prompt`) as the thread's first message. The trigger
    is short on purpose: it tells the new thread to READ its `guide.md` and `team.json` rather than
@@ -87,7 +97,7 @@ subcommand rewrites `guide.md`, so the manual always matches the current team.
 Every team member is a real Codex thread created with `codex_app.create_thread` - this is strict,
 not a preference. NEVER substitute `multi_agent_v1.spawn_agent`, or any other in-process subagent,
 for a team member: a spawned agent is an ephemeral helper that does not show up as a team thread,
-cannot carry the `[team name] {session name}` title, and cannot be inspected, titled, archived, or
+cannot carry the `[team name] <member name>` title, and cannot be inspected, titled, archived, or
 re-opened with the `codex_app.*` thread tools - which defeats the entire point of a durable team.
 A member only counts once you have `bind-thread`-ed it to a real `codex_app.create_thread` thread
 id. If the thread-creation tool is unavailable, STOP and say so (see Stop rules); do not quietly
@@ -95,24 +105,41 @@ fall back to a spawned agent.
 
 ## Communication
 
-Coordinate with `codex_app.send_message_to_thread` (leader-to-member and peer digests) and inspect
-status with `codex_app.read_thread`. The generated manual already binds members to the hard rules,
-so you mostly enforce them: all member-to-member and member-to-leader communication is in English;
-when the END user addresses a member, that member replies in the user's own language. Members
-over-communicate relentlessly - constant, small, lean updates that report every finding, hand-off,
-and even the smallest or most trivial step as it happens rather than one final dump - and send
-`WORKING:`/`BLOCKED:` markers so the leader always knows their state; stale, stuck, or
-silently-blocked members are not acceptable, and a finished
-member reports to the leader immediately. Members hand off files and
-memos through the team `artifacts/` directory and reference them by path instead of pasting large
-content. Wait for every required member's final report before you declare the team done.
-
-## Worktrees (optional isolation)
-
-When parallel members would edit overlapping files, enable isolation with `init --worktree`. Create
-one git worktree per member off the base branch, `bind-thread --cwd <worktree>` so each member's
-worktree is recorded in `team.json`, and rely on the manual to direct each member into its own
-worktree. Each member commits inside its worktree so you can integrate.
+Members push to you and to one another with `codex_app.send_message_to_thread`; you inspect their
+state with `codex_app.read_thread`. So members can actually reach you, run `init` with
+`--session <your own thread id>` - that makes `leader.sessionId` in team.json a real, messageable
+thread; without it members cannot report to you and you are stuck polling. The generated manual binds
+members to the hard rules, so you mainly keep the channel open: expect frequent small inbound updates
+from each member - findings, `WORKING:`/`BLOCKED:` markers, peer digests - rather than one final
+dump, and act on them as they arrive. All member-to-member and member-to-leader traffic is in English;
+when the END user addresses a member, that member replies in the user's own language. Members hand off
+files and memos through the team `artifacts/` directory and reference them by path. Wait for every
+required member's final report before you declare the team done.
+
+## Worktrees - isolate members who would touch the same files
+
+The moment two members' slices would edit the same files, give each its own git worktree so they
+cannot clobber each other. Decide this whenever you see the collision - at team creation OR mid-run,
+not only up front. For each colliding member run `worktree-add --team <id> --id <member>`: it creates
+the worktree off the base branch on a derived branch, flips the team into worktree mode, records it in
+`team.json`, and prints the `cd` path to hand that member. The member works and commits only inside
+its own worktree. To land the work, `integrate --team <id>` merges every member branch into your
+current branch with a merge commit (never a squash or rebase); resolve any conflict it reports, then
+`worktree-remove` each worktree at cleanup.
+
+## Run a ulw-plan in parallel
+
+When a decision-complete plan already exists at `.omo/plans/<slug>.md` (from ulw-plan), execute its
+parallel waves as a team instead of one todo at a time. Map it directly:
+- one wave's independent todos -> one member each; the todo's scope/files become that member's `focus`,
+  and its acceptance criteria + QA become the member's `deliverable`.
+- the plan's dependency matrix sets the shape: todos with no unmet dependency inside a wave run as
+  concurrent members; a todo that depends on another waits, so launch the next wave only after the
+  blocking members report.
+- todos in the same wave that touch overlapping files -> give those members worktrees (see above).
+
+Keep the plan file as the shared spec: point each member at its todo by path, and verify the member's
+result against that todo's acceptance criteria before you integrate.
 
 ## Archive, delete, and cleanup
 
@@ -126,9 +153,9 @@ then delete the team state. A finished team that is never disbanded is a leak.
   and tell the user - never pretend a member was archived.
 - `delete` removes `.omo/teams/{session_id}` and refuses while the team is unarchived or any member
   is still active unless `--force`.
-- When the work wraps up, integrate each member's worktree the way the user asked - merge directly,
-  or open a fresh PR and merge it - then archive and delete. Cleanup is real work; respect the
-  user's instruction on how to land it.
+- When the work wraps up, land it the way the user asked: `integrate --team <id>` for a direct merge
+  commit, or push each member branch and open a PR. Then `worktree-remove` each worktree, archive, and
+  delete. Cleanup is real work; respect the user's instruction on how to land it.
 
 ## Stop rules