oh-my-opencode 4.11.1 → 4.12.0

package/packages/omo-codex/plugin/components/start-work-continuation/src/boulder-reader.ts

@@ -1,14 +1,30 @@
-import { join } from "node:path";
-import type { BoulderWorkStatus, PlanChecklist } from "@oh-my-opencode/boulder-state";
-import {
-	getBoulderFilePath,
-	getPlanChecklist,
-	getWorkForSession,
-	normalizeSessionId,
-	resolveBoulderPlanPathForWork,
-} from "@oh-my-opencode/boulder-state";
-
-export type { PlanChecklist };
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+export type PlanChecklist = {
+	readonly completed: number;
+	readonly remaining: number;
+	readonly total: number;
+	readonly nextTaskLabel: string | null;
+};
+
+type BoulderWorkStatus = "active" | "paused" | "completed" | "abandoned";
+
+type BoulderWork = {
+	readonly activePlan: string;
+	readonly planName: string;
+	readonly status?: BoulderWorkStatus;
+	readonly startedAt?: string;
+	readonly updatedAt?: string;
+	readonly sessionIds: readonly string[];
+	readonly worktreePath?: string;
+};
+
+type BoulderState = {
+	readonly works: readonly BoulderWork[];
+	readonly mirrorWork: BoulderWork | null;
+	readonly hasWorksMap: boolean;
+};
 
 export type ContinuationState = {
 	readonly planName: string;
@@ -19,22 +35,218 @@ export type ContinuationState = {
 	readonly checklist: PlanChecklist;
 };
 
+const TODO_HEADING = "TODOs";
+const FINAL_VERIFICATION_HEADING = "Final Verification Wave";
+const CHECKBOX_PREFIX_LENGTH = "- [ ] ".length;
+const SESSION_ID_PREFIX_PATTERN = /^(codex|opencode):/;
+
 export function readContinuationState(cwd: string, sessionId: string): ContinuationState | null {
-	const work = getWorkForSession(cwd, normalizeSessionId(sessionId, "codex"));
+	const boulderPath = getBoulderFilePath(cwd);
+	const boulderState = readBoulderState(boulderPath);
+	if (boulderState === null) return null;
+
+	const work = getWorkForSession(boulderState, normalizeSessionId(sessionId, "codex"));
 	if (work === null || !isContinuableStatus(work.status)) return null;
+
 	const planPath = resolveBoulderPlanPathForWork(cwd, work);
 	const checklist = getPlanChecklist(planPath);
 	if (checklist.remaining === 0) return null;
+
 	return {
-		planName: work.plan_name,
+		planName: work.planName,
 		planPath,
-		boulderPath: getBoulderFilePath(cwd),
+		boulderPath,
 		ledgerPath: join(cwd, ".omo", "start-work", "ledger.jsonl"),
-		worktreePath: work.worktree_path ?? null,
+		worktreePath: work.worktreePath ?? null,
 		checklist,
 	};
 }
 
+export function getPlanChecklist(planPath: string): PlanChecklist {
+	if (!existsSync(planPath)) return emptyChecklist();
+
+	try {
+		return parsePlanChecklist(readFileSync(planPath, "utf8"));
+	} catch (error) {
+		if (error instanceof Error) return emptyChecklist();
+		throw error;
+	}
+}
+
+function parsePlanChecklist(markdown: string): PlanChecklist {
+	const lines = markdown.split(/\r?\n/);
+	const hasCountedSections = lines.some((line) => isCountedHeading(parseLevelTwoHeading(line)));
+	let completed = 0;
+	let remaining = 0;
+	let nextTaskLabel: string | null = null;
+	let isCountedSection = !hasCountedSections;
+
+	for (const line of lines) {
+		const heading = parseLevelTwoHeading(line);
+		if (heading !== null) {
+			isCountedSection = isCountedHeading(heading);
+			continue;
+		}
+		if (!isCountedSection) continue;
+
+		const checkbox = parseTopLevelCheckbox(line);
+		if (checkbox === null) continue;
+
+		if (checkbox.checked) {
+			completed += 1;
+		} else {
+			remaining += 1;
+			nextTaskLabel = nextTaskLabel ?? checkbox.label;
+		}
+	}
+
+	return { completed, remaining, total: completed + remaining, nextTaskLabel };
+}
+
+function readBoulderState(path: string): BoulderState | null {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		return parseBoulderState(parsed);
+	} catch (error) {
+		if (error instanceof Error) return null;
+		throw error;
+	}
+}
+
+function parseBoulderState(value: unknown): BoulderState | null {
+	if (!isRecord(value)) return null;
+
+	const works: BoulderWork[] = [];
+	const worksValue = value["works"];
+	const hasWorksMap = isRecord(worksValue);
+	if (hasWorksMap) {
+		for (const workValue of Object.values(worksValue)) {
+			const work = parseBoulderWork(workValue);
+			if (work !== null) works.push(work);
+		}
+	}
+
+	const mirrorWork = parseBoulderWork(value);
+	if (works.length === 0 && mirrorWork === null) return null;
+	return { works, mirrorWork, hasWorksMap };
+}
+
+function parseBoulderWork(value: unknown): BoulderWork | null {
+	if (!isRecord(value)) return null;
+
+	const activePlan = value["active_plan"];
+	const planName = value["plan_name"];
+	if (typeof activePlan !== "string") return null;
+
+	const status = parseBoulderWorkStatus(value["status"]);
+	const sessionIds = parseSessionIds(value["session_ids"]);
+	const worktreePath = value["worktree_path"];
+	const startedAt = value["started_at"];
+	const updatedAt = value["updated_at"];
+
+	return {
+		activePlan,
+		planName: typeof planName === "string" ? planName : activePlan,
+		sessionIds,
+		...(status === undefined ? {} : { status }),
+		...(typeof startedAt === "string" ? { startedAt } : {}),
+		...(typeof updatedAt === "string" ? { updatedAt } : {}),
+		...(typeof worktreePath === "string" ? { worktreePath } : {}),
+	};
+}
+
+function getWorkForSession(state: BoulderState, normalizedSessionId: string): BoulderWork | null {
+	let newestWork: BoulderWork | null = null;
+	let newestWorkMs = 0;
+
+	for (const work of state.works) {
+		if (!work.sessionIds.includes(normalizedSessionId)) continue;
+
+		const workMs = parseIsoToMs(work.updatedAt ?? work.startedAt) ?? 0;
+		if (newestWork === null || workMs > newestWorkMs) {
+			newestWork = work;
+			newestWorkMs = workMs;
+		}
+	}
+
+	if (newestWork !== null) return newestWork;
+	if (state.hasWorksMap) return null;
+	if (state.mirrorWork?.sessionIds.includes(normalizedSessionId) === true) return state.mirrorWork;
+	return null;
+}
+
+function resolveBoulderPlanPathForWork(cwd: string, work: BoulderWork): string {
+	const absolutePlanPath = resolveTrackedPath(cwd, work.activePlan);
+	const worktreePath = work.worktreePath?.trim();
+	if (worktreePath === undefined || worktreePath.length === 0) return absolutePlanPath;
+
+	const relativePlanPath = relative(resolve(cwd), absolutePlanPath);
+	if (relativePlanPath.length === 0 || relativePlanPath.startsWith("..") || isAbsolute(relativePlanPath)) {
+		return absolutePlanPath;
+	}
+
+	const worktreePlanPath = resolve(resolveTrackedPath(cwd, worktreePath), relativePlanPath);
+	return existsSync(worktreePlanPath) ? worktreePlanPath : absolutePlanPath;
+}
+
+function resolveTrackedPath(baseDirectory: string, trackedPath: string): string {
+	return isAbsolute(trackedPath) ? resolve(trackedPath) : resolve(baseDirectory, trackedPath);
+}
+
+function parseTopLevelCheckbox(line: string): { readonly checked: boolean; readonly label: string } | null {
+	if (line.startsWith("- [ ] ")) return { checked: false, label: line.slice(CHECKBOX_PREFIX_LENGTH) };
+	if (line.startsWith("- [x] ") || line.startsWith("- [X] ")) {
+		return { checked: true, label: line.slice(CHECKBOX_PREFIX_LENGTH) };
+	}
+	return null;
+}
+
+function parseLevelTwoHeading(line: string): string | null {
+	if (!line.startsWith("## ")) return null;
+	return line.slice("## ".length).trim();
+}
+
+function isCountedHeading(heading: string | null): boolean {
+	return heading === TODO_HEADING || heading === FINAL_VERIFICATION_HEADING;
+}
+
+function parseBoulderWorkStatus(value: unknown): BoulderWorkStatus | undefined {
+	if (value === "active" || value === "paused" || value === "completed" || value === "abandoned") return value;
+	return undefined;
+}
+
+function parseSessionIds(value: unknown): readonly string[] {
+	if (!Array.isArray(value)) return [];
+	const sessionIds: string[] = [];
+	for (const item of value) {
+		if (typeof item === "string") sessionIds.push(normalizeSessionId(item));
+	}
+	return sessionIds;
+}
+
+function normalizeSessionId(sessionId: string, platform: "codex" | "opencode" = "opencode"): string {
+	if (SESSION_ID_PREFIX_PATTERN.test(sessionId)) return sessionId;
+	return `${platform}:${sessionId}`;
+}
+
+function parseIsoToMs(value: string | undefined): number | null {
+	if (value === undefined) return null;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+
 function isContinuableStatus(status: BoulderWorkStatus | undefined): boolean {
 	return status === "active" || status === "paused";
 }
+
+function getBoulderFilePath(cwd: string): string {
+	return join(cwd, ".omo", "boulder.json");
+}
+
+function emptyChecklist(): PlanChecklist {
+	return { completed: 0, remaining: 0, total: 0, nextTaskLabel: null };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/omo-codex/plugin/components/start-work-continuation/test/boulder-reader.test.ts

@@ -1,9 +1,8 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { getPlanChecklist } from "@oh-my-opencode/boulder-state";
 import { afterEach, describe, expect, it } from "vitest";
-import { readContinuationState } from "../src/boulder-reader.js";
+import { getPlanChecklist, readContinuationState } from "../src/boulder-reader.js";
 
 const cleanupRoots: string[] = [];
 
@@ -109,6 +108,21 @@ describe("start-work boulder state reader", () => {
 		expect(state).toBeNull();
 	});
 
+	it("#given paused codex work with remaining checklist #when state is read #then continuation is present", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: createBoulderJson({ status: "paused", sessionIds: ["codex:sess_abc"] }),
+			planMarkdown: "# Plan\n\n## TODOs\n- [ ] First\n",
+		});
+
+		// when
+		const state = readContinuationState(workspace, "sess_abc");
+
+		// then
+		expect(state?.planName).toBe("launch-plan");
+		expect(state?.checklist).toEqual({ completed: 0, remaining: 1, total: 1, nextTaskLabel: "First" });
+	});
+
 	it("#given no remaining top-level checklist items #when state is read #then continuation is absent", () => {
 		// given
 		const workspace = createWorkspace({
@@ -136,6 +150,52 @@ describe("start-work boulder state reader", () => {
 		// then
 		expect(state).toBeNull();
 	});
+
+	it("#given bare boulder session id #when codex state is read #then continuation is absent", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: createBoulderJson({ status: "active", sessionIds: ["sess_abc"] }),
+			planMarkdown: "# Plan\n\n## TODOs\n- [ ] First\n",
+		});
+
+		// when
+		const state = readContinuationState(workspace, "sess_abc");
+
+		// then
+		expect(state).toBeNull();
+	});
+
+	it("#given works omit the codex session but stale mirror matches #when state is read #then continuation is absent", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: JSON.stringify({
+				schema_version: 2,
+				active_work_id: "work_1",
+				works: {
+					work_1: {
+						work_id: "work_1",
+						active_plan: ".omo/plans/plan.md",
+						plan_name: "current-work",
+						status: "active",
+						started_at: "2026-06-13T00:00:00.000Z",
+						session_ids: ["opencode:sess_other"],
+					},
+				},
+				active_plan: ".omo/plans/plan.md",
+				plan_name: "stale-mirror",
+				status: "active",
+				started_at: "2026-06-12T00:00:00.000Z",
+				session_ids: ["codex:sess_abc"],
+			}),
+			planMarkdown: "# Plan\n\n## TODOs\n- [ ] First\n",
+		});
+
+		// when
+		const state = readContinuationState(workspace, "sess_abc");
+
+		// then
+		expect(state).toBeNull();
+	});
 });
 
 type WorkspaceInput = {

package/packages/omo-codex/plugin/components/start-work-continuation/test/cli.test.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execPath } from "node:process";
@@ -23,7 +23,11 @@ describe("start-work continuation CLI", () => {
 		// then
 		if (result.error !== undefined) throw result.error;
 		expect(result.status).toBe(0);
-		expect(result.stdout).toContain('"decision":"block"');
+		const output = parseStopHookOutput(result.stdout);
+		expect(output.decision).toBe("block");
+		expect(output.reason).toContain("Remaining top-level checkboxes: `2` of `3`");
+		expect(output.reason).toContain("Next incomplete task: `Task one`");
+		expect(output.reason).toContain("Your session id in boulder.json: `codex:s1`");
 	});
 
 	it("#given valid SubagentStop stdin #when CLI runs #then stdout contains block JSON", () => {
@@ -80,6 +84,18 @@ describe("start-work continuation CLI", () => {
 		expect(result.status).toBe(0);
 		expect(result.stdout).toBe("");
 	});
+
+	it("#given built CLI bundle #when inspected #then it does not depend on the monorepo boulder package", () => {
+		// given
+		const cliPath = join(process.cwd(), "dist", "cli.js");
+
+		// when
+		const source = readFileSync(cliPath, "utf8");
+
+		// then
+		expect(source).not.toContain("@oh-my-opencode/boulder-state");
+		expect(source).not.toContain("../../boulder-state");
+	});
 });
 
 function runCli(subcommand: "stop" | "subagent-stop", input: string) {
@@ -90,7 +106,7 @@ function createWorkspace(sessionIds: readonly string[]): string {
 	const root = mkdtempSync(join(tmpdir(), "codex-continuation-cli-"));
 	cleanupRoots.push(root);
 	mkdirSync(join(root, ".omo", "plans"), { recursive: true });
-	writeFileSync(join(root, ".omo", "plans", "plan.md"), "## TODOs\n\n- [ ] Task one\n");
+	writeFileSync(join(root, ".omo", "plans", "plan.md"), "## TODOs\n\n- [ ] Task one\n- [x] Done\n- [ ] Task two\n");
 	const work = {
 		work_id: "w1",
 		active_plan: ".omo/plans/plan.md",
@@ -122,3 +138,18 @@ function makePayload(
 		last_assistant_message: "done",
 	};
 }
+
+type ParsedStopHookOutput = {
+	readonly decision: unknown;
+	readonly reason: string;
+};
+
+function parseStopHookOutput(stdout: string): ParsedStopHookOutput {
+	const parsed: unknown = JSON.parse(stdout);
+	if (!isRecord(parsed) || typeof parsed["reason"] !== "string") throw new Error("CLI did not emit Stop hook JSON");
+	return { decision: parsed["decision"], reason: parsed["reason"] };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,139 @@
+---
+name: teammode
+description: "Codex-only team orchestration: run a named team of cooperating Codex threads with durable, script-managed state. MUST USE when the user asks Codex to create, run, coordinate, inspect, archive, or delete a team of threads/sessions, or to work on something as a team in parallel. The main session is always the leader; members are defined by a concrete part, ownership area, or perspective - never a vague job role; a bundled cross-platform script writes the .omo/teams state plus an auto-generated member field manual. Use a team when the work is not perfectly isolated but parallelizing helps, or when a task still needs exploration under a clear goal; use plain subagents when scope is perfectly isolated or the goal is ambiguous. Triggers: team mode, teammode, make a team, run as a team, team of agents, coordinate threads, parallel Codex threads, archive the team, delete the team."
+---
+
+# Teammode
+
+Run a named team of cooperating Codex threads under one leader, with durable state on disk.
+This is a Codex-only workflow. It is inspired by the lifecycle concerns in the
+Yeachan-Heo/oh-my-codex team skill, but it does not copy that runtime model and never depends
+on an external terminal runner - it coordinates through Codex's own thread tools plus a bundled
+state script.
+
+## When to use a team (and when to use plain subagents instead)
+
+Use a TEAM when EITHER holds:
+- the work does NOT split into perfectly isolated pieces, but doing it in parallel is clearly
+  more convenient - members will need to see and react to each other's findings; or
+- one task still needs exploration, yet its GOAL is already clear - parallel investigation under
+  a fixed objective.
+
+Use plain subagents (`$ulw` / `multi_agent_v1.spawn_agent`) - NOT a team - when EITHER holds:
+- the work IS perfectly isolated, so there is no coordination cost worth paying; or
+- the GOAL is still ambiguous, where one mind should resolve direction before any fan-out.
+
+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
+
+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.
+
+## Compose by part, ownership, or perspective - not by job title
+
+A team is ALWAYS two or more members - never a single-member team. One worker on an isolated
+job is a subagent (`multi_agent_v1.spawn_agent`), not a team; if you end up with a single member,
+either split off a second distinct slice or drop the team and use a subagent.
+
+Compose the team from what you actually KNOW about the work. Ground the split in real knowledge
+of the problem, then divide it into clear, non-overlapping responsibilities - one per aspect of
+the work - and give each member exactly one. No two members may own the same thing. Define each
+member by a concrete slice: a specific part of the codebase, an ownership area, or a distinct
+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`.
+
+## Run the script - never hand-write team state
+
+A bundled, dependency-free Node script owns all team state so you never author `team.json` or
+the member manual by hand. Run it with `node` (or `bun`); it works on macOS, Linux, and Windows.
+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" 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" 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>
+```
+
+`init` creates `.omo/teams/{session_id}/` containing `team.json` (the single durable state file:
+team id, the main-session leader, the member roster, status, worktree config, and a lifecycle
+log), `guide.md` (the auto-generated member field manual), and `artifacts/` (a shared exchange
+space). `{session_id}` is the leader's Codex session id when you can pass it via `--session`;
+otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
+subcommand rewrites `guide.md`, so the manual always matches the current team.
+
+## Create the team and its threads
+
+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.
+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
+   carrying the whole protocol inline.
+
+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
+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
+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.
+
+## Archive, delete, and cleanup
+
+DISBAND the team the moment it is no longer needed. A team exists only to do its work; once that
+work is done, or the user no longer wants it, do not leave it lying around - archive every member,
+then delete the team state. A finished team that is never disbanded is a leak.
+
+- `archive` closes the team: notify each active member, copy anything useful into `artifacts/`,
+  archive each member thread with `codex_app.set_thread_archived`, then `archive` flips the team
+  and all members to archived. If a thread-archive tool is unavailable, record that in the team log
+  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.
+
+## Stop rules
+
+- Stop and ask before deleting an unarchived team while any member is still active.
+- Member communication stays English unless the user explicitly requests otherwise; user-facing
+  replies follow the user's language.
+- Stop if the requested operation needs Codex thread tools (create/read/send/title/archive) and
+  they are unavailable; say so instead of faking it.

package/packages/omo-codex/plugin/components/teammode/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.`;
+}