Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

chore: sync Codex marketplace v4.8.0

github-actions[bot]2dd6ff8d841c
diff --git a/plugins/omo/.codex-plugin/plugin.json b/plugins/omo/.codex-plugin/plugin.json
index f2d2e469..bce798b6 100644
--- a/plugins/omo/.codex-plugin/plugin.json
+++ b/plugins/omo/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "omo",
- "version": "0.1.0",
+ "version": "4.8.0",
"description": "One Codex plugin namespace for Yeongyu's local Codex components.",
"author": {
"name": "Yeongyu Kim",
@@ -10,17 +10,30 @@
"homepage": "https://github.com/sisyphuslabs/omo",
"repository": "https://github.com/sisyphuslabs/omo",
"license": "MIT",
- "keywords": ["codex", "codex-plugin", "omo", "hooks", "mcp", "skills"],
+ "keywords": [
+ "codex",
+ "codex-plugin",
+ "omo",
+ "hooks",
+ "mcp",
+ "skills"
+ ],
"skills": "./skills/",
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json",
"interface": {
"displayName": "OMO",
"shortDescription": "Unified local Codex components",
- "longDescription": "OMO exposes the local Codex Rules, Comment Checker, LSP, Ultrawork, and ulw-loop components as one plugin namespace while keeping each component isolated under components/ for maintenance.",
+ "longDescription": "OMO exposes local Codex Rules, Comment Checker, Git Bash, LSP, Ultrawork, ulw-loop, start-work continuation, and telemetry components as one plugin namespace while keeping each component isolated under components/ for maintenance.",
"developerName": "Yeongyu Kim",
"category": "Developer Tools",
- "capabilities": ["Hooks", "MCP Tools", "Code Intelligence", "Workflow", "Context Injection"],
+ "capabilities": [
+ "Hooks",
+ "MCP Tools",
+ "Code Intelligence",
+ "Workflow",
+ "Context Injection"
+ ],
"websiteURL": "https://github.com/sisyphuslabs/omo",
"privacyPolicyURL": "https://github.com/sisyphuslabs/omo#privacy",
"termsOfServiceURL": "https://github.com/sisyphuslabs/omo#license",
diff --git a/plugins/omo/README.md b/plugins/omo/README.md
index 57801707..c2d306d0 100644
--- a/plugins/omo/README.md
+++ b/plugins/omo/README.md
@@ -7,11 +7,13 @@ Internally each component remains isolated under `components/`:
- `components/comment-checker`
- `components/rules`
- `components/lsp`
+- `components/git-bash`
+- `components/start-work-continuation`
- `components/ultrawork`
- `components/ulw-loop`
- `components/telemetry`
-The root plugin manifest exports one Codex plugin named `omo`, with aggregate hooks, skills, and the LSP MCP server.
+The root plugin manifest exports one Codex plugin named `omo`, with aggregate hooks, skills, and plugin-scoped MCP servers for `ast_grep`, `grep_app`, `context7`, `git_bash`, and `lsp`.
## Telemetry
diff --git a/plugins/omo/components/comment-checker/hooks/hooks.json b/plugins/omo/components/comment-checker/hooks/hooks.json
index 2f8db801..bc777d2e 100644
--- a/plugins/omo/components/comment-checker/hooks/hooks.json
+++ b/plugins/omo/components/comment-checker/hooks/hooks.json
@@ -8,7 +8,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use",
"timeout": 30,
- "statusMessage": "LazyCodex(0.1.1): Checking Comments"
+ "statusMessage": "LazyCodex(4.8.0): Checking Comments"
}
]
}
diff --git a/plugins/omo/components/comment-checker/src/apply-patch.ts b/plugins/omo/components/comment-checker/src/apply-patch.ts
index 7da3af29..366691e6 100644
--- a/plugins/omo/components/comment-checker/src/apply-patch.ts
+++ b/plugins/omo/components/comment-checker/src/apply-patch.ts
@@ -1,5 +1,5 @@
-import type { CommentCheckRequest } from "./core.js";
-import { getString, isRecord } from "./core-values.js";
+import { getString, isRecord } from "./record.js";
+import type { CommentCheckRequest } from "./types.js";
type ApplyPatchAccumulator = {
operation: "add" | "delete" | "update";
diff --git a/plugins/omo/components/comment-checker/src/core-values.ts b/plugins/omo/components/comment-checker/src/core-values.ts
index ba8edf84..b7f0867e 100644
--- a/plugins/omo/components/comment-checker/src/core-values.ts
+++ b/plugins/omo/components/comment-checker/src/core-values.ts
@@ -1,11 +1 @@
-export function getString(input: Record<string, unknown>, keys: string[]): string | undefined {
- for (const key of keys) {
- const value = input[key];
- if (typeof value === "string") return value;
- }
- return undefined;
-}
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
- return typeof value === "object" && value !== null;
-}
+export { getString, isRecord } from "./record.js";
diff --git a/plugins/omo/components/comment-checker/src/core.ts b/plugins/omo/components/comment-checker/src/core.ts
index 70c5fd2b..87262940 100644
--- a/plugins/omo/components/comment-checker/src/core.ts
+++ b/plugins/omo/components/comment-checker/src/core.ts
@@ -1,177 +1,15 @@
-import { extractApplyPatchRequests as extractApplyPatchRequestsFromPatch } from "./apply-patch.js";
-import { getString, isRecord } from "./core-values.js";
-
export { parseApplyPatchRequests } from "./apply-patch.js";
-export { isRecord } from "./core-values.js";
-
-export type TextContent = {
- type: "text";
- text: string;
-};
-
-export type ImageContent = {
- type: "image";
- data: string;
- mimeType: string;
-};
-
-export type CheckerToolName = "Write" | "Edit" | "MultiEdit";
-
-export type CheckerEdit = {
- old_string: string;
- new_string: string;
-};
-
-export type CheckerToolInput = {
- file_path: string;
- content?: string;
- old_string?: string;
- new_string?: string;
- edits?: CheckerEdit[];
-};
-
-export type CommentCheckRequest = {
- sourceToolName: string;
- toolName: CheckerToolName;
- filePath: string;
- toolInput: CheckerToolInput;
-};
-
-export type CommentCheckerHookInput = {
- session_id: string;
- tool_name: CheckerToolName;
- transcript_path: string;
- cwd: string;
- hook_event_name: "PostToolUse";
- tool_input: CheckerToolInput;
-};
-
-export type ToolResultContent = TextContent | ImageContent;
-
-export type ToolResultLike = {
- toolName: string;
- input: Record<string, unknown>;
- content?: ToolResultContent[];
- isError?: boolean;
- details?: unknown;
-};
-
-export function extractCommentCheckRequests(event: ToolResultLike): CommentCheckRequest[] {
- if (event.isError) return [];
- if (isToolFailureOutput(getContentText(event.content))) return [];
-
- const toolName = event.toolName.toLowerCase();
- if (toolName === "write") return extractWriteRequest(event);
- if (toolName === "edit") return extractEditRequest(event);
- if (toolName === "multiedit" || toolName === "multi_edit") return extractMultiEditRequest(event);
- if (toolName === "apply_patch") return extractApplyPatchRequests(event);
- return [];
-}
-
-export function toHookInput(
- request: CommentCheckRequest,
- context: {
- sessionId: string;
- cwd: string;
- transcriptPath?: string;
- },
-): CommentCheckerHookInput {
- return {
- session_id: context.sessionId,
- tool_name: request.toolName,
- transcript_path: context.transcriptPath ?? "",
- cwd: context.cwd,
- hook_event_name: "PostToolUse",
- tool_input: request.toolInput,
- };
-}
-
-export function isToolFailureOutput(text: string): boolean {
- const lower = text.trim().toLowerCase();
- return (
- lower.startsWith("error") ||
- lower.includes("error:") ||
- lower.includes("failed to") ||
- lower.includes("could not")
- );
-}
-
-function extractWriteRequest(event: ToolResultLike): CommentCheckRequest[] {
- const filePath = getString(event.input, ["filePath", "file_path", "path"]);
- const content = getString(event.input, ["content"]);
- if (!filePath || content === undefined) return [];
- return [
- {
- sourceToolName: event.toolName,
- toolName: "Write",
- filePath,
- toolInput: {
- file_path: filePath,
- content,
- },
- },
- ];
-}
-
-function extractEditRequest(event: ToolResultLike): CommentCheckRequest[] {
- const filePath = getString(event.input, ["filePath", "file_path", "path"]);
- const oldString = getString(event.input, ["oldString", "old_string"]);
- const newString = getString(event.input, ["newString", "new_string"]);
- if (!filePath || oldString === undefined || newString === undefined) return [];
- const toolInput: CheckerToolInput = { file_path: filePath };
- toolInput.old_string = oldString;
- toolInput.new_string = newString;
- return [
- {
- sourceToolName: event.toolName,
- toolName: "Edit",
- filePath,
- toolInput,
- },
- ];
-}
-
-function extractMultiEditRequest(event: ToolResultLike): CommentCheckRequest[] {
- const filePath = getString(event.input, ["filePath", "file_path", "path"]);
- const edits = getEdits(event.input["edits"]);
- if (!filePath || edits.length === 0) return [];
- return [
- {
- sourceToolName: event.toolName,
- toolName: "MultiEdit",
- filePath,
- toolInput: {
- file_path: filePath,
- edits,
- },
- },
- ];
-}
-
-function extractApplyPatchRequests(event: ToolResultLike): CommentCheckRequest[] {
- return extractApplyPatchRequestsFromPatch(event);
-}
-
-function getEdits(value: unknown): CheckerEdit[] {
- if (!Array.isArray(value)) return [];
- const edits: CheckerEdit[] = [];
- for (const item of value) {
- if (!isRecord(item)) continue;
- const oldString = getString(item, ["oldString", "old_string"]);
- const newString = getString(item, ["newString", "new_string"]);
- if (oldString === undefined || newString === undefined) continue;
- edits.push({
- old_string: oldString,
- new_string: newString,
- });
- }
- return edits;
-}
-
-function getContentText(content: ToolResultContent[] | undefined): string {
- if (!content) return "";
- return content
- .filter((block): block is TextContent => block.type === "text")
- .map((block) => block.text)
- .join("\n");
-}
+export { toHookInput } from "./hook-input.js";
+export { isRecord } from "./record.js";
+export { extractCommentCheckRequests, isToolFailureOutput } from "./request-extractor.js";
+export type {
+ CheckerEdit,
+ CheckerToolInput,
+ CheckerToolName,
+ CommentCheckerHookInput,
+ CommentCheckRequest,
+ ImageContent,
+ TextContent,
+ ToolResultContent,
+ ToolResultLike,
+} from "./types.js";
diff --git a/plugins/omo/components/comment-checker/src/hook-input.ts b/plugins/omo/components/comment-checker/src/hook-input.ts
new file mode 100644
index 00000000..b02408f5
--- /dev/null
+++ b/plugins/omo/components/comment-checker/src/hook-input.ts
@@ -0,0 +1,19 @@
+import type { CommentCheckerHookInput, CommentCheckRequest } from "./types.js";
+
+export function toHookInput(
+ request: CommentCheckRequest,
+ context: {
+ readonly sessionId: string;
+ readonly cwd: string;
+ readonly transcriptPath?: string;
+ },
+): CommentCheckerHookInput {
+ return {
+ session_id: context.sessionId,
+ tool_name: request.toolName,
+ transcript_path: context.transcriptPath ?? "",
+ cwd: context.cwd,
+ hook_event_name: "PostToolUse",
+ tool_input: request.toolInput,
+ };
+}
diff --git a/plugins/omo/components/comment-checker/src/record.ts b/plugins/omo/components/comment-checker/src/record.ts
new file mode 100644
index 00000000..a29f12e0
--- /dev/null
+++ b/plugins/omo/components/comment-checker/src/record.ts
@@ -0,0 +1,11 @@
+export function getString(input: Record<string, unknown>, keys: readonly string[]): string | undefined {
+ for (const key of keys) {
+ const value = input[key];
+ if (typeof value === "string") return value;
+ }
+ return undefined;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null;
+}
diff --git a/plugins/omo/components/comment-checker/src/request-extractor.ts b/plugins/omo/components/comment-checker/src/request-extractor.ts
new file mode 100644
index 00000000..3aa9b89b
--- /dev/null
+++ b/plugins/omo/components/comment-checker/src/request-extractor.ts
@@ -0,0 +1,102 @@
+import { extractApplyPatchRequests } from "./apply-patch.js";
+import { getString, isRecord } from "./record.js";
+import type { CheckerEdit, CommentCheckRequest, TextContent, ToolResultContent, ToolResultLike } from "./types.js";
+
+export function extractCommentCheckRequests(event: ToolResultLike): CommentCheckRequest[] {
+ if (event.isError) return [];
+ if (isToolFailureOutput(getContentText(event.content))) return [];
+
+ const toolName = event.toolName.toLowerCase();
+ if (toolName === "write") return extractWriteRequest(event);
+ if (toolName === "edit") return extractEditRequest(event);
+ if (toolName === "multiedit" || toolName === "multi_edit") return extractMultiEditRequest(event);
+ if (toolName === "apply_patch") return extractApplyPatchRequests(event);
+ return [];
+}
+
+export function isToolFailureOutput(text: string): boolean {
+ const lower = text.trim().toLowerCase();
+ return (
+ lower.startsWith("error") ||
+ lower.includes("error:") ||
+ lower.includes("failed to") ||
+ lower.includes("could not")
+ );
+}
+
+function extractWriteRequest(event: ToolResultLike): CommentCheckRequest[] {
+ const filePath = getString(event.input, ["filePath", "file_path", "path"]);
+ const content = getString(event.input, ["content"]);
+ if (!filePath || content === undefined) return [];
+ return [
+ {
+ sourceToolName: event.toolName,
+ toolName: "Write",
+ filePath,
+ toolInput: {
+ file_path: filePath,
+ content,
+ },
+ },
+ ];
+}
+
+function extractEditRequest(event: ToolResultLike): CommentCheckRequest[] {
+ const filePath = getString(event.input, ["filePath", "file_path", "path"]);
+ const oldString = getString(event.input, ["oldString", "old_string"]);
+ const newString = getString(event.input, ["newString", "new_string"]);
+ if (!filePath || oldString === undefined || newString === undefined) return [];
+ return [
+ {
+ sourceToolName: event.toolName,
+ toolName: "Edit",
+ filePath,
+ toolInput: {
+ file_path: filePath,
+ old_string: oldString,
+ new_string: newString,
+ },
+ },
+ ];
+}
+
+function extractMultiEditRequest(event: ToolResultLike): CommentCheckRequest[] {
+ const filePath = getString(event.input, ["filePath", "file_path", "path"]);
+ const edits = getEdits(event.input["edits"]);
+ if (!filePath || edits.length === 0) return [];
+ return [
+ {
+ sourceToolName: event.toolName,
+ toolName: "MultiEdit",
+ filePath,
+ toolInput: {
+ file_path: filePath,
+ edits,
+ },
+ },
+ ];
+}
+
+function getEdits(value: unknown): CheckerEdit[] {
+ if (!Array.isArray(value)) return [];
+ const edits: CheckerEdit[] = [];
+ for (const item of value) {
+ if (!isRecord(item)) continue;
+ const oldString = getString(item, ["oldString", "old_string"]);
+ const newString = getString(item, ["newString", "new_string"]);
+ if (oldString === undefined || newString === undefined) continue;
+ edits.push({
+ old_string: oldString,
+ new_string: newString,
+ });
+ }
+ return edits;
+}
+
+function getContentText(content: readonly ToolResultContent[] | undefined): string {
+ if (!content) return "";
+ return content
+ .filter((block): block is TextContent => block.type === "text")
+ .map((block) => block.text)
+ .join("\n");
+}
diff --git a/plugins/omo/components/comment-checker/src/types.ts b/plugins/omo/components/comment-checker/src/types.ts
new file mode 100644
index 00000000..c4016923
--- /dev/null
+++ b/plugins/omo/components/comment-checker/src/types.ts
@@ -0,0 +1,51 @@
+export type TextContent = {
+ type: "text";
+ text: string;
+};
+
+export type ImageContent = {
+ type: "image";
+ data: string;
+ mimeType: string;
+};
+
+export type CheckerToolName = "Write" | "Edit" | "MultiEdit";
+
+export type CheckerEdit = {
+ old_string: string;
+ new_string: string;
+};
+
+export type CheckerToolInput = {
+ file_path: string;
+ content?: string;
+ old_string?: string;
+ new_string?: string;
+ edits?: CheckerEdit[];
+};
+
+export type CommentCheckRequest = {
+ sourceToolName: string;
+ toolName: CheckerToolName;
+ filePath: string;
+ toolInput: CheckerToolInput;
+};
+
+export type CommentCheckerHookInput = {
+ session_id: string;
+ tool_name: CheckerToolName;
+ transcript_path: string;
+ cwd: string;
+ hook_event_name: "PostToolUse";
+ tool_input: CheckerToolInput;
+};
+
+export type ToolResultContent = TextContent | ImageContent;
+
+export type ToolResultLike = {
+ toolName: string;
+ input: Record<string, unknown>;
+ content?: ToolResultContent[];
+ isError?: boolean;
+ details?: unknown;
+};
diff --git a/plugins/omo/components/comment-checker/test/core.test.ts b/plugins/omo/components/comment-checker/test/core.test.ts
new file mode 100644
index 00000000..db88f691
--- /dev/null
+++ b/plugins/omo/components/comment-checker/test/core.test.ts
@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+import type { CheckerEdit, CheckerToolInput, CommentCheckRequest, ToolResultLike } from "../src/core.ts";
+import { extractCommentCheckRequests, parseApplyPatchRequests, toHookInput } from "../src/core.ts";
+
+describe("extractCommentCheckRequests", () => {
+ it("#given apply_patch metadata files #when extracting #then supports direct result and metadata shapes", () => {
+ // given
+ const directEvent = applyPatchEvent({
+ files: [{ filePath: "src/direct.ts", before: "", after: "// explains direct\nconst direct = true;\n" }],
+ });
+ const resultEvent = applyPatchEvent({
+ result: {
+ files: [{ file_path: "src/result.ts", old: "const result = false;\n", new: "const result = true;\n" }],
+ },
+ });
+ const metadataEvent = applyPatchEvent({
+ metadata: {
+ files: [{ path: "src/metadata.ts", before: "", after: "// explains metadata\nconst metadata = true;\n" }],
+ },
+ });
+
+ // when
+ const directRequests = extractCommentCheckRequests(directEvent);
+ const resultRequests = extractCommentCheckRequests(resultEvent);
+ const metadataRequests = extractCommentCheckRequests(metadataEvent);
+
+ // then
+ expect(directRequests[0]?.filePath).toBe("src/direct.ts");
+ expect(resultRequests[0]).toEqual({
+ sourceToolName: "apply_patch",
+ toolName: "Edit",
+ filePath: "src/result.ts",
+ toolInput: {
+ file_path: "src/result.ts",
+ old_string: "const result = false;\n",
+ new_string: "const result = true;\n",
+ },
+ });
+ expect(metadataRequests[0]?.toolName).toBe("Write");
+ expect(metadataRequests[0]?.filePath).toBe("src/metadata.ts");
+ });
+
+ it("#given apply_patch add move and delete hunks #when extracting from raw patch #then add and move are checked while delete is ignored", () => {
+ // given
+ const patch = [
+ "*** Begin Patch",
+ "*** Add File: src/added.ts",
+ "+// explains add",
+ "+const added = true;",
+ "*** Update File: src/original.ts",
+ "*** Move to: src/renamed.ts",
+ "@@",
+ "-const original = true;",
+ "+// explains rename",
+ "+const renamed = true;",
+ "*** Delete File: src/deleted.ts",
+ "*** End Patch",
+ ].join("\n");
+
+ // when
+ const requests = parseApplyPatchRequests(patch, "apply_patch");
+
+ // then
+ expect(requests).toEqual([
+ {
+ sourceToolName: "apply_patch",
+ toolName: "Write",
+ filePath: "src/added.ts",
+ toolInput: {
+ file_path: "src/added.ts",
+ content: "// explains add\nconst added = true;\n",
+ },
+ },
+ {
+ sourceToolName: "apply_patch",
+ toolName: "Edit",
+ filePath: "src/renamed.ts",
+ toolInput: {
+ file_path: "src/renamed.ts",
+ old_string: "const original = true;\n",
+ new_string: "// explains rename\nconst renamed = true;\n",
+ },
+ },
+ ]);
+ });
+
+ it("#given failed tool output #when extracting #then text and isError failures emit no requests", () => {
+ // given
+ const textFailure = applyPatchEvent(undefined, {
+ content: [{ type: "text", text: "Error: failed to apply patch" }],
+ });
+ const structuredFailure = applyPatchEvent(undefined, {
+ content: [{ type: "text", text: "Success. Updated files." }],
+ isError: true,
+ });
+
+ // when
+ const textRequests = extractCommentCheckRequests(textFailure);
+ const structuredRequests = extractCommentCheckRequests(structuredFailure);
+
+ // then
+ expect(textRequests).toEqual([]);
+ expect(structuredRequests).toEqual([]);
+ });
+});
+
+describe("toHookInput", () => {
+ it("#given comment check request #when converting #then emits stable hook input contract", () => {
+ // given
+ const request: CommentCheckRequest = {
+ sourceToolName: "write",
+ toolName: "Write",
+ filePath: "src/example.ts",
+ toolInput: {
+ file_path: "src/example.ts",
+ content: "// explains value\nconst value = 1;\n",
+ },
+ };
+
+ // when
+ const input = toHookInput(request, {
+ sessionId: "session-1",
+ cwd: "/repo",
+ transcriptPath: "/tmp/transcript.jsonl",
+ });
+
+ // then
+ expect(input).toEqual({
+ session_id: "session-1",
+ tool_name: "Write",
+ transcript_path: "/tmp/transcript.jsonl",
+ cwd: "/repo",
+ hook_event_name: "PostToolUse",
+ tool_input: request.toolInput,
+ });
+ });
+});
+
+describe("public contract mutability", () => {
+ it("#given exported core types #when consumers mutate fields #then the compatibility contract is preserved", () => {
+ // given
+ const edit: CheckerEdit = {
+ old_string: "const value = 1;\n",
+ new_string: "const value = 2;\n",
+ };
+ const toolInput: CheckerToolInput = {
+ file_path: "src/example.ts",
+ edits: [edit],
+ };
+ const request: CommentCheckRequest = {
+ sourceToolName: "multi_edit",
+ toolName: "MultiEdit",
+ filePath: "src/example.ts",
+ toolInput,
+ };
+ const event: ToolResultLike = {
+ toolName: "write",
+ input: {},
+ content: [{ type: "text", text: "ok" }],
+ };
+
+ // when
+ edit.new_string = "const value = 3;\n";
+ toolInput.file_path = "src/renamed.ts";
+ toolInput.edits?.push({
+ old_string: "const other = 1;\n",
+ new_string: "const other = 2;\n",
+ });
+ request.filePath = "src/renamed.ts";
+ event.toolName = "edit";
+ event.content?.push({ type: "text", text: "still ok" });
+
+ // then
+ expect(request.filePath).toBe("src/renamed.ts");
+ expect(request.toolInput.edits).toHaveLength(2);
+ expect(event.toolName).toBe("edit");
+ expect(event.content).toEqual([
+ { type: "text", text: "ok" },
+ { type: "text", text: "still ok" },
+ ]);
+ });
+});
+
+function applyPatchEvent(details: unknown, overrides: Partial<ToolResultLike> = {}): ToolResultLike {
+ return {
+ toolName: "apply_patch",
+ input: {
+ command: [
+ "*** Begin Patch",
+ "*** Update File: src/raw.ts",
+ "@@",
+ "-const raw = false;",
+ "+const raw = true;",
+ "*** End Patch",
+ ].join("\n"),
+ },
+ ...(details === undefined ? {} : { details }),
+ ...overrides,
+ };
+}
diff --git a/plugins/omo/components/git-bash/hooks/hooks.json b/plugins/omo/components/git-bash/hooks/hooks.json
index 1224be0f..a16ed9c7 100644
--- a/plugins/omo/components/git-bash/hooks/hooks.json
+++ b/plugins/omo/components/git-bash/hooks/hooks.json
@@ -8,7 +8,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Recommending Git Bash Mcp"
+ "statusMessage": "LazyCodex(4.8.0): Recommending Git Bash Mcp"
}
]
}
@@ -20,7 +20,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-compact",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Resetting Git Bash Mcp Reminder"
+ "statusMessage": "LazyCodex(4.8.0): Resetting Git Bash Mcp Reminder"
}
]
}
diff --git a/plugins/omo/components/lsp/CHANGELOG.md b/plugins/omo/components/lsp/CHANGELOG.md
index 31941445..b2efa7e3 100644
--- a/plugins/omo/components/lsp/CHANGELOG.md
+++ b/plugins/omo/components/lsp/CHANGELOG.md
@@ -7,10 +7,10 @@
## 0.2.0
- Extracted the LSP runtime and MCP server into [`@code-yeongyu/lsp-tools-mcp`](https://github.com/code-yeongyu/lsp-tools-mcp).
-- codex-lsp now consumes that runtime as a git submodule at `packages/lsp-tools-mcp`.
+- codex-lsp now consumes that runtime from the repository-level `packages/lsp-tools-mcp` package.
- Kept the Codex-specific PostToolUse hook in this package and routed MCP serving through the upstream CLI.
-- Extract LSP runtime to `lsp-tools-mcp` upstream and consume it via git submodule at `packages/lsp-tools-mcp`.
+- Extract LSP runtime to `lsp-tools-mcp` upstream and consume it via the repository-level `packages/lsp-tools-mcp` package.
- Renamed the MCP server namespace to `lsp` and exposed shorter tool names such as `lsp.diagnostics`.
- Use portable Codex hook interpolation and add package smoke coverage for hook/MCP entrypoints.
- Spawn language servers without shell mode; Windows `.cmd` and `.bat` shims are routed through `cmd.exe` with explicit arguments.
diff --git a/plugins/omo/components/lsp/hooks/hooks.json b/plugins/omo/components/lsp/hooks/hooks.json
index 674c1223..20b617d7 100644
--- a/plugins/omo/components/lsp/hooks/hooks.json
+++ b/plugins/omo/components/lsp/hooks/hooks.json
@@ -8,7 +8,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use",
"timeout": 60,
- "statusMessage": "LazyCodex(0.2.0): Checking LSP Diagnostics"
+ "statusMessage": "LazyCodex(4.8.0): Checking LSP Diagnostics"
}
]
}
@@ -21,7 +21,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-compact",
"timeout": 5,
- "statusMessage": "LazyCodex(0.2.0): Resetting LSP Diagnostics Cache"
+ "statusMessage": "LazyCodex(4.8.0): Resetting LSP Diagnostics Cache"
}
]
}
diff --git a/plugins/omo/components/rules/bundled-rules/hephaestus.md b/plugins/omo/components/rules/bundled-rules/hephaestus.md
index 13f0d24a..cabb2836 100644
--- a/plugins/omo/components/rules/bundled-rules/hephaestus.md
+++ b/plugins/omo/components/rules/bundled-rules/hephaestus.md
@@ -79,10 +79,10 @@ omo-codex bundles three read-only Codex subagent roles in `CODEX_HOME/agents/`:
**Routing:**
-- "Where is X?" / "Find code that does Y" -> `spawn_agent(agent_type="explorer", fork_turns="none", ...)`
-- "How does library Z work?" / "What's the API contract?" -> `spawn_agent(agent_type="librarian", fork_turns="none", ...)`
-- 5+ interdependent steps, ambiguous scope, multi-module work -> `spawn_agent(agent_type="plan", fork_turns="none", ...)`
-- Heavy verification of a finished change -> `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)`
+- "Where is X?" / "Find code that does Y" -> `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})`
+- "How does library Z work?" / "What's the API contract?" -> `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})`
+- 5+ interdependent steps, ambiguous scope, multi-module work -> `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})`
+- Heavy verification of a finished change -> `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})`
**Don't duplicate.** Once a subagent is dispatched for a question, do not re-do the same search yourself. Once results return, do not re-verify by repeating their tool calls; integrate and move on.
@@ -110,6 +110,12 @@ LSP diagnostics catch type errors, not logic bugs; tests cover only what their a
Reading the source and concluding "this should work" does not pass this gate. If usage reveals a defect, that defect is yours to fix in this turn - same turn, not "follow-up".
+# Global Review and Debugging Gate
+
+For significant implementation work and every PR handoff, run `review-work` plus a `debugging` runtime audit before declaring completion. Timeout, missing deliverable, ack-only, `BLOCKED:`, and inconclusive review lanes fail the gate. Record at least three debugging hypotheses and the runtime evidence that confirms or refutes each one.
+
+Do not print completion, create a PR, produce a PR handoff, or produce a branch handoff until the gate passes. Always redact secrets, tokens, credentials, auth headers, cookies, env dumps, private logs, and PII from ledgers, PR bodies, and handoffs.
+
# Failure Recovery
If your first approach fails, try a materially different one - different algorithm, library, or pattern, not a small tweak. Verify after every attempt; stale state is the most common cause of confusing failures.
diff --git a/plugins/omo/components/rules/hooks/hooks.json b/plugins/omo/components/rules/hooks/hooks.json
index 46831e87..23ba6505 100644
--- a/plugins/omo/components/rules/hooks/hooks.json
+++ b/plugins/omo/components/rules/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook session-start",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Loading Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Loading Project Rules"
}
]
}
@@ -19,7 +19,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Loading Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Loading Project Rules"
}
]
}
@@ -32,7 +32,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-tool-use",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Matching Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Matching Project Rules"
}
]
}
@@ -45,7 +45,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook post-compact",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Resetting Project Rule Cache"
+ "statusMessage": "LazyCodex(4.8.0): Resetting Project Rule Cache"
}
]
}
diff --git a/plugins/omo/components/rules/src/hook-output.ts b/plugins/omo/components/rules/src/hook-output.ts
index b60a9488..cc07c7a9 100644
--- a/plugins/omo/components/rules/src/hook-output.ts
+++ b/plugins/omo/components/rules/src/hook-output.ts
@@ -1,10 +1,12 @@
export type ContextInjectionHookEventName = "SessionStart" | "UserPromptSubmit" | "PostToolUse";
+const MAX_ADDITIONAL_CONTEXT_CHARS = 32_000;
+
export function formatAdditionalContextOutput(
eventName: ContextInjectionHookEventName,
additionalContext: string,
): string {
- const normalizedContext = normalizeAdditionalContext(additionalContext);
+ const normalizedContext = limitAdditionalContext(normalizeAdditionalContext(additionalContext));
if (normalizedContext.length === 0) return "";
return `${JSON.stringify({
hookSpecificOutput: {
@@ -17,3 +19,11 @@ export function formatAdditionalContextOutput(
function normalizeAdditionalContext(additionalContext: string): string {
return additionalContext.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
}
+
+function limitAdditionalContext(additionalContext: string): string {
+ if (additionalContext.length <= MAX_ADDITIONAL_CONTEXT_CHARS) return additionalContext;
+ const marker = `\n\n[Truncated hook additional context to ${MAX_ADDITIONAL_CONTEXT_CHARS} chars to avoid Codex context overflow.]`;
+ if (marker.length >= MAX_ADDITIONAL_CONTEXT_CHARS) return marker.slice(0, MAX_ADDITIONAL_CONTEXT_CHARS);
+ const head = additionalContext.slice(0, MAX_ADDITIONAL_CONTEXT_CHARS - marker.length).replace(/[ \t\r\n]+$/, "");
+ return `${head}${marker}`;
+}
diff --git a/plugins/omo/components/rules/src/rules/formatter.ts b/plugins/omo/components/rules/src/rules/formatter.ts
index 779553ad..f4ac8a1a 100644
--- a/plugins/omo/components/rules/src/rules/formatter.ts
+++ b/plugins/omo/components/rules/src/rules/formatter.ts
@@ -74,12 +74,9 @@ export function formatStaticBlock(rules: ReadonlyArray<LoadedRule>, options: For
return "";
}
- return [
- "## Project Instructions",
- "",
- "must read project rules:",
- orderStaticRules(uniqueRulesByBody(rules)).map(formatStaticRuleReference).join("\n"),
- ].join("\n");
+ const orderedRules = orderStaticRules(uniqueRulesByBody(rules));
+
+ return ["## Project Instructions", "", truncateRules(orderedRules, options).map(formatRule).join("\n\n")].join("\n");
}
function orderStaticRules(rules: ReadonlyArray<LoadedRule>): LoadedRule[] {
@@ -99,10 +96,6 @@ function isHephaestusRule(rule: LoadedRule): boolean {
return displayFilename(rule).toLowerCase() === "hephaestus.md";
}
-function formatStaticRuleReference(rule: LoadedRule): string {
- return `- [${displayFilename(rule)}]{${rule.path}}`;
-}
-
function displayFilename(rule: LoadedRule): string {
const normalizedPath = rule.relativePath.length > 0 ? rule.relativePath : rule.path;
const segments = normalizedPath
diff --git a/plugins/omo/components/rules/src/rules/parser-frontmatter.ts b/plugins/omo/components/rules/src/rules/parser-frontmatter.ts
new file mode 100644
index 00000000..65b7eae2
--- /dev/null
+++ b/plugins/omo/components/rules/src/rules/parser-frontmatter.ts
@@ -0,0 +1,39 @@
+const FRONTMATTER_OPENING = "---\n";
+const FRONTMATTER_OPENING_CRLF = "---\r\n";
+
+export type ClosingDelimiter = {
+ readonly start: number;
+ readonly bodyStart: number;
+};
+
+export function stripBom(content: string): string {
+ return content.startsWith("\uFEFF") ? content.slice(1) : content;
+}
+
+export function getOpeningDelimiterLength(content: string): number {
+ if (content.startsWith(FRONTMATTER_OPENING_CRLF)) return FRONTMATTER_OPENING_CRLF.length;
+ if (content.startsWith(FRONTMATTER_OPENING)) return FRONTMATTER_OPENING.length;
+ return 0;
+}
+
+export function findClosingDelimiter(content: string, openingLength: number): ClosingDelimiter | null {
+ let lineStart = openingLength;
+
+ while (lineStart <= content.length) {
+ const nextNewline = content.indexOf("\n", lineStart);
+ const lineEnd = nextNewline === -1 ? content.length : nextNewline;
+ const line = content.slice(lineStart, lineEnd).replace(/\r$/, "");
+
+ if (line === "---") {
+ return {
+ start: lineStart,
+ bodyStart: nextNewline === -1 ? content.length : nextNewline + 1,
+ };
+ }
+
+ if (nextNewline === -1) break;
+ lineStart = nextNewline + 1;
+ }
+
+ return null;
+}
diff --git a/plugins/omo/components/rules/src/rules/parser-yaml.ts b/plugins/omo/components/rules/src/rules/parser-yaml.ts
new file mode 100644
index 00000000..47aa3383
--- /dev/null
+++ b/plugins/omo/components/rules/src/rules/parser-yaml.ts
@@ -0,0 +1,271 @@
+import { RuleFrontmatterParseError } from "./errors.js";
+import type { RuleFrontmatter } from "./types.js";
+
+type ParsedGlobValue = {
+ readonly values: readonly string[];
+ readonly consumed: number;
+};
+
+export function parseYamlFrontmatter(yamlContent: string): RuleFrontmatter {
+ const lines = yamlContent.replace(/\r\n/g, "\n").split("\n");
+ const frontmatter: RuleFrontmatter = {};
+ const globValues: string[] = [];
+ const seenGlobs = new Set<string>();
+ let lineIndex = 0;
+
+ while (lineIndex < lines.length) {
+ const rawLine = lines[lineIndex];
+ if (rawLine === undefined) break;
+
+ const line = stripComment(rawLine).trim();
+ if (line.length === 0) {
+ lineIndex += 1;
+ continue;
+ }
+
+ const colonIndex = line.indexOf(":");
+ if (colonIndex === -1) {
+ throw new RuleFrontmatterParseError(`Expected key-value pair on line ${lineIndex + 1}`);
+ }
+
+ const key = line.slice(0, colonIndex).trim();
+ const rawValue = line.slice(colonIndex + 1).trim();
+
+ if (key === "description") {
+ frontmatter.description = parseStringValue(rawValue);
+ lineIndex += 1;
+ continue;
+ }
+
+ if (key === "alwaysApply") {
+ frontmatter.alwaysApply = parseBooleanValue(rawValue, lineIndex + 1);
+ lineIndex += 1;
+ continue;
+ }
+
+ if (key === "globs" || key === "paths" || key === "applyTo") {
+ const parsed = parseGlobValue(rawValue, lines, lineIndex);
+ for (const glob of parsed.values) {
+ if (!seenGlobs.has(glob)) {
+ seenGlobs.add(glob);
+ globValues.push(glob);
+ }
+ }
+ lineIndex += parsed.consumed;
+ continue;
+ }
+
+ lineIndex += 1;
+ }
+
+ const singleGlob = globValues[0];
+ if (globValues.length === 1 && singleGlob !== undefined) {
+ frontmatter.globs = singleGlob;
+ } else if (globValues.length > 1) {
+ frontmatter.globs = globValues;
+ }
+
+ return frontmatter;
+}
+
+function parseBooleanValue(value: string, lineNumber: number): boolean {
+ if (value === "true") return true;
+ if (value === "false") return false;
+ throw new RuleFrontmatterParseError(`Expected boolean on line ${lineNumber}`);
+}
+
+function parseGlobValue(rawValue: string, lines: readonly string[], lineIndex: number): ParsedGlobValue {
+ if (rawValue.startsWith("[")) {
+ return { values: parseInlineArray(rawValue), consumed: 1 };
+ }
+
+ if (rawValue.length === 0) {
+ return parseMultilineArray(lines, lineIndex);
+ }
+
+ const quotedScalar = isQuotedScalar(rawValue);
+ const value = parseStringValue(rawValue);
+ if (!quotedScalar && value.includes(",")) {
+ return {
+ values: value
+ .split(",")
+ .map((item) => item.trim())
+ .filter(Boolean),
+ consumed: 1,
+ };
+ }
+
+ return { values: [value], consumed: 1 };
+}
+
+function isQuotedScalar(value: string): boolean {
+ return value.startsWith('"') || value.startsWith("'");
+}
+
+function parseMultilineArray(lines: readonly string[], lineIndex: number): ParsedGlobValue {
+ const values: string[] = [];
+ let consumed = 1;
+
+ for (let index = lineIndex + 1; index < lines.length; index += 1) {
+ const rawLine = lines[index];
+ if (rawLine === undefined) break;
+
+ const lineWithoutComment = stripComment(rawLine);
+ if (lineWithoutComment.trim().length === 0) {
+ consumed += 1;
+ continue;
+ }
+
+ const arrayItem = lineWithoutComment.match(/^\s+-\s*(.*)$/);
+ if (arrayItem === null) break;
+
+ values.push(parseStringValue(arrayItem[1] ?? ""));
+ consumed += 1;
+ }
+
+ return { values: values.filter(Boolean), consumed };
+}
+
+function parseInlineArray(value: string): string[] {
+ const closingBracketIndex = findClosingBracket(value);
+ if (closingBracketIndex === -1) {
+ throw new RuleFrontmatterParseError("Unclosed inline array");
+ }
+
+ const trailing = value.slice(closingBracketIndex + 1).trim();
+ if (trailing.length > 0) {
+ throw new RuleFrontmatterParseError("Unexpected content after inline array");
+ }
+
+ const content = value.slice(1, closingBracketIndex).trim();
+ if (content.length === 0) return [];
+
+ return splitCommaSeparated(content).map(parseStringValue).filter(Boolean);
+}
+
+function findClosingBracket(value: string): number {
+ let quote: string | null = null;
+ let escaped = false;
+
+ for (let index = 0; index < value.length; index += 1) {
+ const character = value[index];
+ if (character === undefined) continue;
+
+ if (escaped) {
+ escaped = false;
+ continue;
+ }
+
+ if (quote !== null && character === "\\") {
+ escaped = true;
+ continue;
+ }
+
+ if (character === '"' || character === "'") {
+ if (quote === null) quote = character;
+ else if (quote === character) quote = null;
+ continue;
+ }
+
+ if (quote === null && character === "]") return index;
+ }
+
+ return -1;
+}
+
+function splitCommaSeparated(value: string): string[] {
+ const values: string[] = [];
+ let current = "";
+ let quote: string | null = null;
+ let escaped = false;
+
+ for (let index = 0; index < value.length; index += 1) {
+ const character = value[index];
+ if (character === undefined) continue;
+
+ if (escaped) {
+ current += character;
+ escaped = false;
+ continue;
+ }
+
+ if (quote !== null && character === "\\") {
+ current += character;
+ escaped = true;
+ continue;
+ }
+
+ if (character === '"' || character === "'") {
+ if (quote === null) quote = character;
+ else if (quote === character) quote = null;
+ current += character;
+ continue;
+ }
+
+ if (quote === null && character === ",") {
+ values.push(current.trim());
+ current = "";
+ continue;
+ }
+
+ current += character;
+ }
+
+ if (quote !== null) {
+ throw new RuleFrontmatterParseError("Unclosed quoted value");
+ }
+
+ values.push(current.trim());
+ return values.filter(Boolean);
+}
+
+function parseStringValue(value: string): string {
+ if (value.length === 0) return "";
+ if (value.startsWith('"')) return parseJsonString(value);
+ if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+ if (value.startsWith("'")) throw new RuleFrontmatterParseError("Unclosed quoted value");
+ return value;
+}
+
+function parseJsonString(value: string): string {
+ try {
+ const parsedValue: unknown = JSON.parse(value);
+ if (typeof parsedValue !== "string") {
+ throw new RuleFrontmatterParseError("Expected JSON-quoted string");
+ }
+ return parsedValue;
+ } catch (error) {
+ if (error instanceof RuleFrontmatterParseError) throw error;
+ throw new RuleFrontmatterParseError("Invalid JSON-quoted string");
+ }
+}
+
+function stripComment(line: string): string {
+ let quote: string | null = null;
+ let escaped = false;
+
+ for (let index = 0; index < line.length; index += 1) {
+ const character = line[index];
+ if (character === undefined) continue;
+
+ if (escaped) {
+ escaped = false;
+ continue;
+ }
+
+ if (quote !== null && character === "\\") {
+ escaped = true;
+ continue;
+ }
+
+ if (character === '"' || character === "'") {
+ if (quote === null) quote = character;
+ else if (quote === character) quote = null;
+ continue;
+ }
+
+ if (quote === null && character === "#") return line.slice(0, index);
+ }
+
+ return line;
+}
diff --git a/plugins/omo/components/rules/src/rules/parser.ts b/plugins/omo/components/rules/src/rules/parser.ts
index 894f0da9..fd5ae367 100644
--- a/plugins/omo/components/rules/src/rules/parser.ts
+++ b/plugins/omo/components/rules/src/rules/parser.ts
@@ -1,8 +1,6 @@
-import { RuleFrontmatterParseError } from "./errors.js";
-import type { ParsedRule, RuleFrontmatter } from "./types.js";
-
-const FRONTMATTER_OPENING = "---\n";
-const FRONTMATTER_OPENING_CRLF = "---\r\n";
+import { findClosingDelimiter, getOpeningDelimiterLength, stripBom } from "./parser-frontmatter.js";
+import { parseYamlFrontmatter } from "./parser-yaml.js";
+import type { ParsedRule } from "./types.js";
/** Parse markdown rule content and extract the supported YAML frontmatter subset. */
export function parseRule(content: string): ParsedRule {
@@ -35,296 +33,3 @@ export function parseRule(content: string): ParsedRule {
};
}
}
-
-function stripBom(content: string): string {
- return content.startsWith("\uFEFF") ? content.slice(1) : content;
-}
-
-function getOpeningDelimiterLength(content: string): number {
- if (content.startsWith(FRONTMATTER_OPENING_CRLF)) return FRONTMATTER_OPENING_CRLF.length;
- if (content.startsWith(FRONTMATTER_OPENING)) return FRONTMATTER_OPENING.length;
- return 0;
-}
-
-function findClosingDelimiter(content: string, openingLength: number): { start: number; bodyStart: number } | null {
- let lineStart = openingLength;
-
- while (lineStart <= content.length) {
- const nextNewline = content.indexOf("\n", lineStart);
- const lineEnd = nextNewline === -1 ? content.length : nextNewline;
- const line = content.slice(lineStart, lineEnd).replace(/\r$/, "");
-
- if (line === "---") {
- return {
- start: lineStart,
- bodyStart: nextNewline === -1 ? content.length : nextNewline + 1,
- };
- }
-
- if (nextNewline === -1) break;
- lineStart = nextNewline + 1;
- }
-
- return null;
-}
-
-function parseYamlFrontmatter(yamlContent: string): RuleFrontmatter {
- const lines = yamlContent.replace(/\r\n/g, "\n").split("\n");
- const frontmatter: RuleFrontmatter = {};
- const globValues: string[] = [];
- const seenGlobs = new Set<string>();
- let lineIndex = 0;
-
- while (lineIndex < lines.length) {
- const rawLine = lines[lineIndex];
- if (rawLine === undefined) break;
-
- const line = stripComment(rawLine).trim();
- if (line.length === 0) {
- lineIndex += 1;
- continue;
- }
-
- const colonIndex = line.indexOf(":");
- if (colonIndex === -1) {
- throw new RuleFrontmatterParseError(`Expected key-value pair on line ${lineIndex + 1}`);
- }
-
- const key = line.slice(0, colonIndex).trim();
- const rawValue = line.slice(colonIndex + 1).trim();
-
- if (key === "description") {
- frontmatter.description = parseStringValue(rawValue);
- lineIndex += 1;
- continue;
- }
-
- if (key === "alwaysApply") {
- frontmatter.alwaysApply = parseBooleanValue(rawValue, lineIndex + 1);
- lineIndex += 1;
- continue;
- }
-
- if (key === "globs" || key === "paths" || key === "applyTo") {
- const parsed = parseGlobValue(rawValue, lines, lineIndex);
- for (const glob of parsed.values) {
- if (!seenGlobs.has(glob)) {
- seenGlobs.add(glob);
- globValues.push(glob);
- }
- }
- lineIndex += parsed.consumed;
- continue;
- }
-
- lineIndex += 1;
- }
-
- const singleGlob = globValues[0];
- if (globValues.length === 1 && singleGlob !== undefined) {
- frontmatter.globs = singleGlob;
- } else if (globValues.length > 1) {
- frontmatter.globs = globValues;
- }
-
- return frontmatter;
-}
-
-function parseBooleanValue(value: string, lineNumber: number): boolean {
- if (value === "true") return true;
- if (value === "false") return false;
- throw new RuleFrontmatterParseError(`Expected boolean on line ${lineNumber}`);
-}
-
-function parseGlobValue(rawValue: string, lines: string[], lineIndex: number): { values: string[]; consumed: number } {
- if (rawValue.startsWith("[")) {
- return { values: parseInlineArray(rawValue), consumed: 1 };
- }
-
- if (rawValue.length === 0) {
- return parseMultilineArray(lines, lineIndex);
- }
-
- const value = parseStringValue(rawValue);
- if (value.includes(",")) {
- return {
- values: value
- .split(",")
- .map((item) => item.trim())
- .filter(Boolean),
- consumed: 1,
- };
- }
-
- return { values: [value], consumed: 1 };
-}
-
-function parseMultilineArray(lines: string[], lineIndex: number): { values: string[]; consumed: number } {
- const values: string[] = [];
- let consumed = 1;
-
- for (let index = lineIndex + 1; index < lines.length; index += 1) {
- const rawLine = lines[index];
- if (rawLine === undefined) break;
-
- const lineWithoutComment = stripComment(rawLine);
- if (lineWithoutComment.trim().length === 0) {
- consumed += 1;
- continue;
- }
-
- const arrayItem = lineWithoutComment.match(/^\s+-\s*(.*)$/);
- if (arrayItem === null) break;
-
- values.push(parseStringValue(arrayItem[1] ?? ""));
- consumed += 1;
- }
-
- return { values: values.filter(Boolean), consumed };
-}
-
-function parseInlineArray(value: string): string[] {
- const closingBracketIndex = findClosingBracket(value);
- if (closingBracketIndex === -1) {
- throw new RuleFrontmatterParseError("Unclosed inline array");
- }
-
- const trailing = value.slice(closingBracketIndex + 1).trim();
- if (trailing.length > 0) {
- throw new RuleFrontmatterParseError("Unexpected content after inline array");
- }
-
- const content = value.slice(1, closingBracketIndex).trim();
- if (content.length === 0) return [];
-
- return splitCommaSeparated(content).map(parseStringValue).filter(Boolean);
-}
-
-function findClosingBracket(value: string): number {
- let quote: string | null = null;
- let escaped = false;
-
- for (let index = 0; index < value.length; index += 1) {
- const character = value[index];
- if (character === undefined) continue;
-
- if (escaped) {
- escaped = false;
- continue;
- }
-
- if (quote !== null && character === "\\") {
- escaped = true;
- continue;
- }
-
- if (character === '"' || character === "'") {
- if (quote === null) quote = character;
- else if (quote === character) quote = null;
- continue;
- }
-
- if (quote === null && character === "]") return index;
- }
-
- return -1;
-}
-
-function splitCommaSeparated(value: string): string[] {
- const values: string[] = [];
- let current = "";
- let quote: string | null = null;
- let escaped = false;
-
- for (let index = 0; index < value.length; index += 1) {
- const character = value[index];
- if (character === undefined) continue;
-
- if (escaped) {
- current += character;
- escaped = false;
- continue;
- }
-
- if (quote !== null && character === "\\") {
- current += character;
- escaped = true;
- continue;
- }
-
- if (character === '"' || character === "'") {
- if (quote === null) quote = character;
- else if (quote === character) quote = null;
- current += character;
- continue;
- }
-
- if (quote === null && character === ",") {
- values.push(current.trim());
- current = "";
- continue;
- }
-
- current += character;
- }
-
- if (quote !== null) {
- throw new RuleFrontmatterParseError("Unclosed quoted value");
- }
-
- values.push(current.trim());
- return values.filter(Boolean);
-}
-
-function parseStringValue(value: string): string {
- if (value.length === 0) return "";
- if (value.startsWith('"')) return parseJsonString(value);
- if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
- if (value.startsWith("'")) throw new RuleFrontmatterParseError("Unclosed quoted value");
- return value;
-}
-
-function parseJsonString(value: string): string {
- let parsedValue: unknown;
- try {
- parsedValue = JSON.parse(value);
- } catch {
- throw new RuleFrontmatterParseError("Invalid JSON-quoted string");
- }
-
- if (typeof parsedValue !== "string") {
- throw new RuleFrontmatterParseError("Expected JSON-quoted string");
- }
-
- return parsedValue;
-}
-
-function stripComment(line: string): string {
- let quote: string | null = null;
- let escaped = false;
-
- for (let index = 0; index < line.length; index += 1) {
- const character = line[index];
- if (character === undefined) continue;
-
- if (escaped) {
- escaped = false;
- continue;
- }
-
- if (quote !== null && character === "\\") {
- escaped = true;
- continue;
- }
-
- if (character === '"' || character === "'") {
- if (quote === null) quote = character;
- else if (quote === character) quote = null;
- continue;
- }
-
- if (quote === null && character === "#") return line.slice(0, index);
- }
-
- return line;
-}
diff --git a/plugins/omo/components/rules/src/sparkshell-awareness.ts b/plugins/omo/components/rules/src/sparkshell-awareness.ts
index fbefc9be..a4cc51f1 100644
--- a/plugins/omo/components/rules/src/sparkshell-awareness.ts
+++ b/plugins/omo/components/rules/src/sparkshell-awareness.ts
@@ -17,22 +17,28 @@ export function isCodexAppServerActive(env: RuntimeEnv = process.env): boolean {
);
}
+function isSparkShellAppServerConfigured(env: RuntimeEnv = process.env): boolean {
+ const codexSocketPath = env["CODEX_APP_SERVER_SOCKET"]?.trim() ?? "";
+ const omoSocketPath = env["OMO_SPARKSHELL_APP_SERVER_SOCKET"]?.trim() ?? "";
+ return codexSocketPath.length > 0 || omoSocketPath.length > 0;
+}
+
export function getSparkShellRuntimeAwareness(env: RuntimeEnv = process.env): string {
const override = env["OMO_SPARKSHELL_AWARENESS"] ?? env["LAZYCODEX_SPARKSHELL_AWARENESS"];
if (isFalsy(override)) {
return "";
}
- if (!isTruthy(override) && !isCodexAppServerActive(env)) {
+ if (!isTruthy(override) && !isCodexAppServerActive(env) && !isSparkShellAppServerConfigured(env)) {
return "";
}
return [
SPARKSHELL_AWARENESS_MARKER,
"",
- "- Codex app server context is active, so Sparkshell is available for shell-native inspection and bounded verification.",
- "- Use `omo sparkshell <command>` for direct argv execution. Use `omo sparkshell --shell '<command>'` only when shell metacharacters are required.",
- "- Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` to summarize a tmux pane. Tail lines must stay between 100 and 1000.",
- "- Fallback boundaries are visible in output. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
+ "- Prefer `omo sparkshell <command>` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.",
+ "- Use `omo sparkshell --shell '<command>'` only when shell metacharacters are required.",
+ "- Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` to inspect an existing tmux pane. 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.",
].join("\n");
}
diff --git a/plugins/omo/components/rules/test/bundled-rules-priority.test.ts b/plugins/omo/components/rules/test/bundled-rules-priority.test.ts
index 70c971d2..e353f87a 100644
--- a/plugins/omo/components/rules/test/bundled-rules-priority.test.ts
+++ b/plugins/omo/components/rules/test/bundled-rules-priority.test.ts
@@ -84,7 +84,8 @@ describe("plugin bundled rule priority", () => {
// then
expect(formatted).toContain(homePath);
- expect(formatted).not.toContain(homeBody);
+ expect(formatted).toContain(homeBody);
+ expect(formatted).not.toContain(`- [hephaestus.md]{${homePath}}`);
expect(formatted).not.toContain(bundledPath);
expect(formatted).not.toContain(bundledBody);
});
diff --git a/plugins/omo/components/rules/test/bundled-rules.test.ts b/plugins/omo/components/rules/test/bundled-rules.test.ts
index acba2406..c39846a4 100644
--- a/plugins/omo/components/rules/test/bundled-rules.test.ts
+++ b/plugins/omo/components/rules/test/bundled-rules.test.ts
@@ -26,14 +26,17 @@ interface Fixture {
const BUNDLED_ONLY_ENV = {
CODEX_RULES_ENABLED_SOURCES: "plugin-bundled",
+ CODEX_RULES_MAX_RESULT_CHARS: "40000",
};
const PROJECT_AND_BUNDLED_ENV = {
CODEX_RULES_ENABLED_SOURCES: ".omo/rules,plugin-bundled",
+ CODEX_RULES_MAX_RESULT_CHARS: "40000",
};
const DISABLED_BUNDLED_ENV = {
CODEX_RULES_ENABLED_SOURCES: "plugin-bundled",
+ CODEX_RULES_MAX_RESULT_CHARS: "40000",
CODEX_RULES_DISABLE_BUNDLED: "1",
};
@@ -147,7 +150,7 @@ describe("plugin bundled rules", () => {
expect(cache.scannedRuleFiles.has(join(pluginRoot, "bundled-rules"))).toBe(true);
});
- it("#given alwaysApply bundled rule #when SessionStart runs #then static context lists it", async () => {
+ it("#given alwaysApply bundled Hephaestus rule #when SessionStart runs #then static context expands it inline", async () => {
// given
const { root, pluginData, bundledRulePath } = makeFixture();
@@ -159,8 +162,11 @@ describe("plugin bundled rules", () => {
// then
expect(output).toContain('"hookEventName":"SessionStart"');
- expect(output).toContain(`- [hephaestus.md]{${bundledRulePath}}`);
- expect(output).not.toContain(BUNDLED_BODY);
+ expect(output).toContain(`Instructions from: ${bundledRulePath}`);
+ expect(output).toContain(BUNDLED_BODY);
+ expect(output).toContain("## Project Instructions");
+ expect(output).not.toContain("must read project rules:");
+ expect(output).not.toContain(`- [hephaestus.md]{${bundledRulePath}}`);
});
it("#given same project and bundled body #when SessionStart runs #then project rule file wins", async () => {
@@ -174,9 +180,9 @@ describe("plugin bundled rules", () => {
});
// then
- expect(occurrenceCount(output, "- [hephaestus.md]{")).toBe(1);
- expect(output).toContain(projectRulePath);
- expect(output).not.toContain(SHARED_BODY);
+ expect(occurrenceCount(output, "- [hephaestus.md]{")).toBe(0);
+ expect(output).toContain(`Instructions from: ${projectRulePath}`);
+ expect(output).toContain(SHARED_BODY);
expect(output).not.toContain(bundledRulePath);
});
@@ -196,13 +202,13 @@ describe("plugin bundled rules", () => {
it("#given bundled static context already injected #when UserPromptSubmit runs after PostCompact #then it emits no duplicate bundled context", async () => {
// given
- const { root, pluginData } = makeFixture();
+ const { root, pluginData, bundledRulePath } = makeFixture();
const firstOutput = await runSessionStartHook(sessionStartInput(root), {
pluginDataRoot: pluginData,
env: BUNDLED_ONLY_ENV,
});
- expect(firstOutput).toContain("must read project rules:");
- expect(firstOutput).not.toContain(BUNDLED_BODY);
+ expect(firstOutput).toContain(`Instructions from: ${bundledRulePath}`);
+ expect(firstOutput).toContain(BUNDLED_BODY);
// when
const compactOutput = await runPostCompactHook(postCompactInput(root), { pluginDataRoot: pluginData });
@@ -216,7 +222,7 @@ describe("plugin bundled rules", () => {
expect(output).toBe("");
});
- it("#given bundled rule body exceeds per-rule cap #when SessionStart runs #then static context lists the file without body", async () => {
+ it("#given bundled Hephaestus rule body exceeds per-rule cap #when SessionStart runs #then static context expands the body within result budget", async () => {
// given
const root = mkdtempSync(join(tmpdir(), "codex-rules-bundled-large-project-"));
const pluginRoot = mkdtempSync(join(tmpdir(), "codex-rules-bundled-large-plugin-"));
@@ -239,12 +245,13 @@ describe("plugin bundled rules", () => {
});
// then
- expect(output).toContain(`- [hephaestus.md]{${bundledRulePath}}`);
- expect(output).not.toContain(tailMarker);
+ expect(output).toContain(`Instructions from: ${bundledRulePath}`);
+ expect(output).toContain("The bundled craftsman discipline is non-negotiable.");
+ expect(output).toContain(tailMarker);
expect(output).not.toContain("[Truncated. Full:");
});
- it("#given project rule body exceeds per-rule cap #when SessionStart runs #then static context lists the file without body", async () => {
+ it("#given project rule body exceeds per-rule cap #when SessionStart runs #then static context injects a truncated body", async () => {
// given
const root = mkdtempSync(join(tmpdir(), "codex-rules-project-large-project-"));
const pluginRoot = mkdtempSync(join(tmpdir(), "codex-rules-project-large-plugin-"));
@@ -268,8 +275,9 @@ describe("plugin bundled rules", () => {
});
// then
- expect(output).toContain(`- [oversized.md]{${projectRulePath}}`);
+ expect(output).toContain(`Instructions from: ${projectRulePath}`);
+ expect(output).toContain("The project rule body is intentionally oversized for the cap test.");
+ expect(output).toContain("[Truncated. Full:");
expect(output).not.toContain(tailMarker);
- expect(output).not.toContain("[Truncated. Full:");
});
});
diff --git a/plugins/omo/components/rules/test/codex-hook-context-pressure.test.ts b/plugins/omo/components/rules/test/codex-hook-context-pressure.test.ts
index 6e7f81dd..0c0ed371 100644
--- a/plugins/omo/components/rules/test/codex-hook-context-pressure.test.ts
+++ b/plugins/omo/components/rules/test/codex-hook-context-pressure.test.ts
@@ -9,6 +9,35 @@ const tempDirectories: string[] = [];
const PROJECT_ONLY_ENV = {
CODEX_RULES_ENABLED_SOURCES: "AGENTS.md,.omo/rules",
};
+const PROMPT_CONTEXT_PRESSURE_CASES = [
+ [
+ "#given context-pressure recovery prompt and empty static cache #when UserPromptSubmit runs #then it emits no static context",
+ [
+ "Context compacted",
+ "error context_too_large: Your input exceeds the context window of this model.",
+ "Please adjust your input and try again.",
+ ].join("\n"),
+ ],
+ [
+ "#given Codex canonical context-window prompt and empty static cache #when UserPromptSubmit runs #then it emits no static context",
+ [
+ "error context_length_exceeded",
+ "Codex ran out of room in the model's context window. Start a new thread before retrying.",
+ ].join("\n"),
+ ],
+] as const;
+const TRANSCRIPT_CONTEXT_PRESSURE_CASES = [
+ [
+ "#given context-pressure transcript and empty static cache #when UserPromptSubmit runs #then it emits no static context",
+ "#given context-pressure transcript and empty dynamic cache #when PostToolUse runs #then it emits no dynamic context",
+ writeContextPressureTranscript,
+ ],
+ [
+ "#given Codex canonical context-window transcript and empty static cache #when UserPromptSubmit runs #then it emits no static context",
+ "#given Codex canonical context-window transcript and empty dynamic cache #when PostToolUse runs #then it emits no dynamic context",
+ writeCodexContextWindowTranscript,
+ ],
+] as const;
afterEach(() => {
for (const directory of tempDirectories.splice(0)) {
@@ -17,144 +46,54 @@ afterEach(() => {
});
describe("codex rules context-pressure recovery", () => {
- it("#given context-pressure recovery prompt and empty static cache #when UserPromptSubmit runs #then it emits no static context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
-
- // when
- const output = await runUserPromptSubmitHook(
- {
- ...userPromptSubmitInput(root),
- prompt: [
- "Context compacted",
- "error context_too_large: Your input exceeds the context window of this model.",
- "Please adjust your input and try again.",
- ].join("\n"),
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
-
- it("#given Codex canonical context-window prompt and empty static cache #when UserPromptSubmit runs #then it emits no static context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
-
- // when
- const output = await runUserPromptSubmitHook(
- {
- ...userPromptSubmitInput(root),
- prompt: [
- "error context_length_exceeded",
- "Codex ran out of room in the model's context window. Start a new thread before retrying.",
- ].join("\n"),
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
-
- it("#given context-pressure transcript and empty static cache #when UserPromptSubmit runs #then it emits no static context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
- const transcriptPath = writeContextPressureTranscript(root);
-
- // when
- const output = await runUserPromptSubmitHook(
- {
- ...userPromptSubmitInput(root),
- transcript_path: transcriptPath,
- prompt: "continue",
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
-
- it("#given Codex canonical context-window transcript and empty static cache #when UserPromptSubmit runs #then it emits no static context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
- const transcriptPath = writeCodexContextWindowTranscript(root);
-
- // when
- const output = await runUserPromptSubmitHook(
- {
- ...userPromptSubmitInput(root),
- transcript_path: transcriptPath,
- prompt: "continue",
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
-
- it("#given context-pressure transcript and empty dynamic cache #when PostToolUse runs #then it emits no dynamic context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
- const transcriptPath = writeContextPressureTranscript(root);
- const filePath = path.join(root, "src", "app.ts");
- mkdirSync(path.dirname(filePath), { recursive: true });
- writeFileSync(filePath, "export const answer = 42;\n");
-
- // when
- const output = await runPostToolUseHook(
- {
- session_id: "session-context-pressure",
- turn_id: "turn-1",
- transcript_path: transcriptPath,
- cwd: root,
- hook_event_name: "PostToolUse",
- model: "gpt-5.5",
- permission_mode: "default",
- tool_name: "mcp__filesystem__read_file",
- tool_input: { path: filePath },
- tool_response: { text: "export const answer = 42;" },
- tool_use_id: "call-1",
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
-
- it("#given Codex canonical context-window transcript and empty dynamic cache #when PostToolUse runs #then it emits no dynamic context", async () => {
- // given
- const { root, pluginData } = makeTempProject();
- const transcriptPath = writeCodexContextWindowTranscript(root);
- const filePath = path.join(root, "src", "app.ts");
- mkdirSync(path.dirname(filePath), { recursive: true });
- writeFileSync(filePath, "export const answer = 42;\n");
-
- // when
- const output = await runPostToolUseHook(
- {
- session_id: "session-context-pressure",
- turn_id: "turn-1",
- transcript_path: transcriptPath,
- cwd: root,
- hook_event_name: "PostToolUse",
- model: "gpt-5.5",
- permission_mode: "default",
- tool_name: "mcp__filesystem__read_file",
- tool_input: { path: filePath },
- tool_response: { text: "export const answer = 42;" },
- tool_use_id: "call-1",
- },
- { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
- );
-
- // then
- expect(output).toBe("");
- });
+ for (const [name, prompt] of PROMPT_CONTEXT_PRESSURE_CASES) {
+ it(name, async () => {
+ // given
+ const { root, pluginData } = makeTempProject();
+
+ // when
+ const output = await runUserPromptSubmitHook(
+ { ...userPromptSubmitInput(root), prompt },
+ { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
+ );
+
+ // then
+ expect(output).toBe("");
+ });
+ }
+
+ for (const [userPromptName, postToolName, writeTranscript] of TRANSCRIPT_CONTEXT_PRESSURE_CASES) {
+ it(userPromptName, async () => {
+ // given
+ const { root, pluginData } = makeTempProject();
+ const transcriptPath = writeTranscript(root);
+
+ // when
+ const output = await runUserPromptSubmitHook(
+ { ...userPromptSubmitInput(root), transcript_path: transcriptPath, prompt: "continue" },
+ { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV },
+ );
+
+ // then
+ expect(output).toBe("");
+ });
+
+ it(postToolName, async () => {
+ // given
+ const { root, pluginData } = makeTempProject();
+ const transcriptPath = writeTranscript(root);
+ const filePath = writeAppFile(root);
+
+ // when
+ const output = await runPostToolUseHook(postToolUseInput(root, transcriptPath, filePath), {
+ pluginDataRoot: pluginData,
+ env: PROJECT_ONLY_ENV,
+ });
+
+ // then
+ expect(output).toBe("");
+ });
+ }
});
function makeTempProject(): { readonly root: string; readonly pluginData: string } {
@@ -191,6 +130,33 @@ function userPromptSubmitInput(root: string): Parameters<typeof runUserPromptSub
};
}
+function postToolUseInput(
+ root: string,
+ transcriptPath: string,
+ filePath: string,
+): Parameters<typeof runPostToolUseHook>[0] {
+ return {
+ session_id: "session-context-pressure",
+ turn_id: "turn-1",
+ transcript_path: transcriptPath,
+ cwd: root,
+ hook_event_name: "PostToolUse",
+ model: "gpt-5.5",
+ permission_mode: "default",
+ tool_name: "mcp__filesystem__read_file",
+ tool_input: { path: filePath },
+ tool_response: { text: "export const answer = 42;" },
+ tool_use_id: "call-1",
+ };
+}
+
+function writeAppFile(root: string): string {
+ const filePath = path.join(root, "src", "app.ts");
+ mkdirSync(path.dirname(filePath), { recursive: true });
+ writeFileSync(filePath, "export const answer = 42;\n");
+ return filePath;
+}
+
function writeContextPressureTranscript(root: string): string {
const transcriptPath = path.join(root, "transcript-context-pressure.jsonl");
writeFileSync(
diff --git a/plugins/omo/components/rules/test/codex-hook-post-compact-budget.test.ts b/plugins/omo/components/rules/test/codex-hook-post-compact-budget.test.ts
index 83b0ca63..99391b50 100644
--- a/plugins/omo/components/rules/test/codex-hook-post-compact-budget.test.ts
+++ b/plugins/omo/components/rules/test/codex-hook-post-compact-budget.test.ts
@@ -25,7 +25,7 @@ afterEach(() => {
});
describe("codex rules post-compaction context budget", () => {
- it("#given oversized project rules already injected #when static recovery runs after compaction #then it emits no duplicate compact index", async () => {
+ it("#given oversized project rules already injected #when static recovery runs after compaction #then it emits no duplicate static injection", async () => {
// given
const { root, pluginData } = makeOversizedProject();
const firstOutput = await runSessionStartHook(sessionStartInput(root), {
@@ -46,10 +46,10 @@ describe("codex rules post-compaction context budget", () => {
});
// then
- expect(firstContext).toContain("must read project rules:");
- expect(firstContext).toContain(`- [CONTEXT.md]{${path.join(root, "CONTEXT.md")}}`);
- expect(firstContext).not.toContain("Project rule");
- expect(firstContext.length).toBeLessThan(1_000);
+ expect(firstContext).toContain(`Instructions from: ${path.join(root, "CONTEXT.md")}`);
+ expect(firstContext).toContain("Project rule");
+ expect(firstContext).toContain("[Truncated. Full:");
+ expect(firstContext.length).toBeLessThan(31_000);
expect(output).toBe("");
});
});
diff --git a/plugins/omo/components/rules/test/codex-hook-post-compact-context.test.ts b/plugins/omo/components/rules/test/codex-hook-post-compact-context.test.ts
index 8105e788..827f05dc 100644
--- a/plugins/omo/components/rules/test/codex-hook-post-compact-context.test.ts
+++ b/plugins/omo/components/rules/test/codex-hook-post-compact-context.test.ts
@@ -38,9 +38,9 @@ describe("codex rules compacted context recovery", () => {
// then
const postCompactContext = readAdditionalContext(output);
expect(postCompactContext.length).toBeLessThan(5_000);
- expect(postCompactContext).toContain("must read project rules:");
- expect(postCompactContext).toContain("- [CONTEXT.md]{");
- expect(postCompactContext).not.toContain("Project rule");
+ expect(postCompactContext).toContain("Instructions from:");
+ expect(postCompactContext).toContain("CONTEXT.md");
+ expect(postCompactContext).toContain("Project rule");
});
it("#given compacted context warning and near-full transcript #when compact source starts twice #then handles compacted context warning once", async () => {
@@ -65,8 +65,8 @@ describe("codex rules compacted context recovery", () => {
// then
const firstContext = readOptionalAdditionalContext(firstOutput);
expect(firstContext.length).toBeLessThan(1_000);
- expect(firstContext).toContain("must read project rules:");
- expect(firstContext).toContain("- [CONTEXT.md]{");
+ expect(firstContext).toContain("Instructions from:");
+ expect(firstContext).toContain("CONTEXT.md");
expect(secondOutput).toBe("");
});
@@ -88,8 +88,8 @@ describe("codex rules compacted context recovery", () => {
// then
const context = readOptionalAdditionalContext(output);
expect(context.length).toBeLessThan(1_000);
- expect(context).toContain("must read project rules:");
- expect(context).toContain("- [CONTEXT.md]{");
+ expect(context).toContain("Instructions from:");
+ expect(context).toContain("CONTEXT.md");
});
it("#given compact SessionStart without prior PostCompact state #when context-pressure transcript is present #then emits emergency-sized context", async () => {
@@ -106,8 +106,8 @@ describe("codex rules compacted context recovery", () => {
// then
const context = readOptionalAdditionalContext(output);
expect(context.length).toBeLessThan(1_000);
- expect(context).toContain("must read project rules:");
- expect(context).toContain("- [CONTEXT.md]{");
+ expect(context).toContain("Instructions from:");
+ expect(context).toContain("CONTEXT.md");
});
it("#given malformed context-too-large transcript and empty session data #when compact source starts #then ignores malformed oversize markers safely", async () => {
@@ -128,8 +128,8 @@ describe("codex rules compacted context recovery", () => {
// then
const context = readOptionalAdditionalContext(output);
expect(context.length).toBeLessThan(1_000);
- expect(context).toContain("must read project rules:");
- expect(context).toContain("- [CONTEXT.md]{");
+ expect(context).toContain("Instructions from:");
+ expect(context).toContain("CONTEXT.md");
});
it("#given concurrent compact SessionStart triggers #when both recover context-too-large state #then deduplicates concurrent context-too-large recovery", async () => {
@@ -157,7 +157,7 @@ describe("codex rules compacted context recovery", () => {
const contexts = outputs.map(readOptionalAdditionalContext);
expect(contexts.filter((context) => context.length > 0)).toHaveLength(1);
expect(contexts.join("").length).toBeLessThan(1_000);
- expect(contexts.join("")).toContain("must read project rules:");
- expect(contexts.join("")).toContain("- [CONTEXT.md]{");
+ expect(contexts.join("")).toContain("Instructions from:");
+ expect(contexts.join("")).toContain("CONTEXT.md");
});
});
diff --git a/plugins/omo/components/rules/test/codex-hook.test.ts b/plugins/omo/components/rules/test/codex-hook.test.ts
index 8081e488..1ae17345 100644
--- a/plugins/omo/components/rules/test/codex-hook.test.ts
+++ b/plugins/omo/components/rules/test/codex-hook.test.ts
@@ -218,11 +218,10 @@ describe("codex rules hooks", () => {
const parsed = parseHookOutput(output);
expect(parsed.hookSpecificOutput?.hookEventName).toBe("SessionStart");
expect(parsed.hookSpecificOutput?.additionalContext).toContain("## Project Instructions");
- expect(parsed.hookSpecificOutput?.additionalContext).toContain("must read project rules:");
expect(parsed.hookSpecificOutput?.additionalContext).toContain(
- `- [CONTEXT.md]{${path.join(root, "CONTEXT.md")}}`,
+ `Instructions from: ${path.join(root, "CONTEXT.md")}`,
);
- expect(parsed.hookSpecificOutput?.additionalContext).not.toContain("Always wear safety goggles");
+ expect(parsed.hookSpecificOutput?.additionalContext).toContain("Always wear safety goggles");
});
it("#given default auto sources #when SessionStart runs #then native Codex AGENTS.md is not duplicated", async () => {
@@ -314,9 +313,9 @@ describe("codex rules hooks", () => {
// then
expect(resumeOutput).toBe("");
const clearContext = parseHookOutput(clearOutput).hookSpecificOutput?.additionalContext ?? "";
- expect(clearContext).toContain("must read project rules:");
- expect(clearContext).toContain(`- [CONTEXT.md]{${path.join(root, "CONTEXT.md")}}`);
- expect(clearContext).not.toContain("Always wear safety goggles");
+ expect(clearContext).toContain("## Project Instructions");
+ expect(clearContext).toContain(`Instructions from: ${path.join(root, "CONTEXT.md")}`);
+ expect(clearContext).toContain("Always wear safety goggles");
});
it("#given static context remains in transcript but cache is missing #when SessionStart runs #then it emits no duplicate context", async () => {
diff --git a/plugins/omo/components/rules/test/formatter.test.ts b/plugins/omo/components/rules/test/formatter.test.ts
index 359363c4..a0227a94 100644
--- a/plugins/omo/components/rules/test/formatter.test.ts
+++ b/plugins/omo/components/rules/test/formatter.test.ts
@@ -42,7 +42,7 @@ describe("rules formatter hook context", () => {
);
});
- it("#given static rules #when formatting SessionStart context #then it lists files to read without rule bodies", () => {
+ it("#given static rules #when formatting SessionStart context #then it injects rule bodies inline", () => {
// given
const rule = loadedRule({
path: "/repo/CONTEXT.md",
@@ -55,9 +55,14 @@ describe("rules formatter hook context", () => {
// then
expect(block).toBe(
- ["## Project Instructions", "", "must read project rules:", "- [CONTEXT.md]{/repo/CONTEXT.md}"].join("\n"),
+ [
+ "## Project Instructions",
+ "",
+ "Instructions from: /repo/CONTEXT.md",
+ "",
+ "Keep generated hook context readable.",
+ ].join("\n"),
);
- expect(block).not.toContain("Keep generated hook context readable.");
});
it("#given CRLF and bare CR rule bodies #when formatting context #then it normalizes line endings", () => {
@@ -74,7 +79,7 @@ describe("rules formatter hook context", () => {
expect(block).not.toContain("\r");
});
- it("#given duplicate static rules with different line endings #when formatting context #then it lists one file to read", () => {
+ it("#given duplicate static rules with different line endings #when formatting context #then it injects one copy", () => {
// given
const lfRule = loadedRule({
path: "/repo/CONTEXT.md",
@@ -91,12 +96,12 @@ describe("rules formatter hook context", () => {
const block = formatStaticBlock([lfRule, crlfRule], FORMAT_OPTIONS);
// then
- expect(occurrenceCount(block, "- [CONTEXT.md]{/repo/CONTEXT.md}")).toBe(1);
- expect(block).not.toContain("Shared rule\nKeep one copy.");
+ expect(occurrenceCount(block, "Instructions from: /repo/CONTEXT.md")).toBe(1);
+ expect(occurrenceCount(block, "Shared rule\nKeep one copy.")).toBe(1);
expect(block).not.toContain("/repo/packages/CONTEXT.md");
});
- it("#given a Hephaestus static rule #when formatting SessionStart context #then it is listed before other rules", () => {
+ it("#given a Hephaestus static rule #when formatting SessionStart context #then it injects its body before other rule bodies", () => {
// given
const rules = [
loadedRule({ path: "/repo/alpha.md", relativePath: "alpha.md", body: "Alpha guidance." }),
@@ -112,12 +117,32 @@ describe("rules formatter hook context", () => {
const block = formatStaticBlock(rules, FORMAT_OPTIONS);
// then
- const ruleLines = block.split("\n").filter((line) => line.startsWith("- "));
- expect(ruleLines).toEqual([
- "- [hephaestus.md]{/repo/bundled-rules/hephaestus.md}",
- "- [alpha.md]{/repo/alpha.md}",
- "- [beta.md]{/repo/beta.md}",
- ]);
+ expect(block).toContain("Instructions from: /repo/bundled-rules/hephaestus.md");
+ expect(block).toContain("Hephaestus guidance.");
+ expect(block).toContain("Alpha guidance.");
+ expect(block).toContain("Beta guidance.");
+ expect(block.indexOf("Hephaestus guidance.")).toBeLessThan(block.indexOf("Alpha guidance."));
+ expect(block.indexOf("Alpha guidance.")).toBeLessThan(block.indexOf("Beta guidance."));
+ expect(block).not.toContain("must read project rules:");
+ expect(block).not.toContain("- [hephaestus.md]");
+ });
+
+ it("#given only a Hephaestus static rule #when formatting SessionStart context #then it emits no project rule link section", () => {
+ // given
+ const rule = loadedRule({
+ path: "/repo/bundled-rules/hephaestus.md",
+ relativePath: "bundled-rules/hephaestus.md",
+ body: "Hephaestus guidance.",
+ });
+
+ // when
+ const block = formatStaticBlock([rule], FORMAT_OPTIONS);
+
+ // then
+ expect(block).toContain("Instructions from: /repo/bundled-rules/hephaestus.md");
+ expect(block).toContain("Hephaestus guidance.");
+ expect(block).not.toContain("- [hephaestus.md]");
+ expect(block).not.toContain("must read project rules:");
});
it("#given multiple oversized rules #when formatting under a tight result budget #then every rule receives a fair truncated share with a read-full guide", () => {
diff --git a/plugins/omo/components/rules/test/hook-output.test.ts b/plugins/omo/components/rules/test/hook-output.test.ts
index aa022863..a454f4f6 100644
--- a/plugins/omo/components/rules/test/hook-output.test.ts
+++ b/plugins/omo/components/rules/test/hook-output.test.ts
@@ -26,6 +26,22 @@ describe("formatAdditionalContextOutput", () => {
// then
expect(output).toBe("");
});
+
+ it("#given oversized context #when serializing hook JSON #then it keeps additional context under the safety cap", () => {
+ // given
+ const context = `first\n${"x".repeat(50_000)}\nlast`;
+
+ // when
+ const output = formatAdditionalContextOutput("SessionStart", context);
+ const parsed: unknown = JSON.parse(output);
+ const additionalContext = readAdditionalContext(parsed);
+
+ // then
+ expect(additionalContext.length).toBeLessThanOrEqual(32_000);
+ expect(additionalContext).toContain("first");
+ expect(additionalContext).not.toContain("last");
+ expect(additionalContext).toContain("[Truncated hook additional context to 32000 chars");
+ });
});
function readAdditionalContext(value: unknown): string {
diff --git a/plugins/omo/components/rules/test/parser.test.ts b/plugins/omo/components/rules/test/parser.test.ts
index 39d5e4ce..152ceea0 100644
--- a/plugins/omo/components/rules/test/parser.test.ts
+++ b/plugins/omo/components/rules/test/parser.test.ts
@@ -3,6 +3,133 @@ import { describe, expect, it } from "vitest";
import { parseRule } from "../src/rules/parser.js";
describe("parseRule", () => {
+ it("#given content without frontmatter #when parsing #then body is preserved", () => {
+ // given
+ const content = "Prefer strict TypeScript.\n---\nThis is body content.";
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed).toEqual({
+ frontmatter: {},
+ body: content,
+ });
+ });
+
+ it("#given bom and crlf frontmatter #when parsing #then delimiters are removed", () => {
+ // given
+ const content = "\uFEFF---\r\ndescription: Windows rule\r\nalwaysApply: true\r\n---\r\nUse Git Bash.\r\n";
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed).toEqual({
+ frontmatter: {
+ description: "Windows rule",
+ alwaysApply: true,
+ },
+ body: "Use Git Bash.\r\n",
+ });
+ });
+
+ it("#given missing closing delimiter #when parsing #then original markdown is salvaged with diagnostic", () => {
+ // given
+ const content = ["---", "description: Missing close", "", "Keep this content."].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed).toEqual({
+ frontmatter: {},
+ body: content,
+ diagnostic: "Missing closing frontmatter delimiter",
+ });
+ });
+
+ it("#given malformed yaml subset #when parsing #then original markdown is salvaged with diagnostic", () => {
+ // given
+ const content = ["---", "alwaysApply: maybe", "---", "", "Keep this content."].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed.frontmatter).toEqual({});
+ expect(parsed.body).toBe(content);
+ expect(parsed.diagnostic).toBe("Malformed frontmatter: Expected boolean on line 1");
+ });
+
+ it("#given quoted hashes and inline quoted commas #when parsing #then comments and commas are handled by quote context", () => {
+ // given
+ const content = [
+ "---",
+ 'description: "Rule #1" # trailing comment',
+ 'globs: ["src/a,b.ts", "docs/#guide.md"] # trailing comment',
+ "---",
+ "",
+ "Use quote-aware parsing.",
+ ].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed.frontmatter).toEqual({
+ description: "Rule #1",
+ globs: ["src/a,b.ts", "docs/#guide.md"],
+ });
+ });
+
+ it("#given quoted scalar glob with comma #when parsing #then the comma remains part of one glob", () => {
+ // given
+ const content = ["---", 'globs: "src/foo,bar.ts"', "---", "", "Prefer precise glob parsing."].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed.frontmatter.globs).toBe("src/foo,bar.ts");
+ });
+
+ it("#given unquoted scalar glob list with comma #when parsing #then it remains split into multiple globs", () => {
+ // given
+ const content = ["---", "globs: src/foo.ts, src/bar.ts", "---", "", "Prefer precise glob parsing."].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed.frontmatter.globs).toEqual(["src/foo.ts", "src/bar.ts"]);
+ });
+
+ it("#given multiline array with comments and blanks #when parsing #then items are collected until next key", () => {
+ // given
+ const content = [
+ "---",
+ "globs:",
+ " # ignored comment",
+ "",
+ ' - "src/#hash.ts" # trailing comment',
+ " - docs/**/*.md",
+ "description: Multiline",
+ "---",
+ "",
+ "Prefer precise rules.",
+ ].join("\n");
+
+ // when
+ const parsed = parseRule(content);
+
+ // then
+ expect(parsed.frontmatter).toEqual({
+ description: "Multiline",
+ globs: ["src/#hash.ts", "docs/**/*.md"],
+ });
+ });
+
it("#given duplicate glob aliases #when parsing frontmatter #then first-seen order is preserved", () => {
// given
const content = [
diff --git a/plugins/omo/components/rules/test/sparkshell-awareness.test.ts b/plugins/omo/components/rules/test/sparkshell-awareness.test.ts
index de039e3e..b7059a36 100644
--- a/plugins/omo/components/rules/test/sparkshell-awareness.test.ts
+++ b/plugins/omo/components/rules/test/sparkshell-awareness.test.ts
@@ -96,6 +96,32 @@ describe("Codex Sparkshell awareness", () => {
expect(output).toBe("");
});
+ it("#given Codex CLI appserver socket env #when SessionStart runs #then emits Sparkshell guidance", async () => {
+ // given
+ const env = {
+ OMO_SPARKSHELL_APP_SERVER_SOCKET: "/tmp/app-server-control.sock",
+ CODEX_THREAD_ID: "thread-sparkshell-cli",
+ CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+ };
+
+ // when
+ const output = await runSessionStartHook(
+ {
+ session_id: "session-sparkshell-cli-wrapper",
+ transcript_path: null,
+ cwd: process.cwd(),
+ hook_event_name: "SessionStart",
+ model: "gpt-5.5",
+ permission_mode: "default",
+ source: "startup",
+ },
+ { env },
+ );
+
+ // then
+ expect(parseAdditionalContext(output)).toContain("omo sparkshell <command>");
+ });
+
it("#given explicit force-on env #when SessionStart runs #then emits Sparkshell guidance", async () => {
// given
const env = {
@@ -198,7 +224,7 @@ describe("Codex Sparkshell awareness", () => {
const context = [
"## Sparkshell Runtime",
"",
- "- Use `omo sparkshell <command>` for shell-native inspection.",
+ "- Prefer `omo sparkshell <command>` for shell-native inspection.",
].join("\n");
// when
diff --git a/plugins/omo/components/rules/test/tool-paths.test.ts b/plugins/omo/components/rules/test/tool-paths.test.ts
index 17be0944..b4cf6499 100644
--- a/plugins/omo/components/rules/test/tool-paths.test.ts
+++ b/plugins/omo/components/rules/test/tool-paths.test.ts
@@ -30,22 +30,34 @@ function postToolUse(input: { toolName: string; toolInput?: unknown; toolRespons
}
describe("extractCodexToolPaths", () => {
- it("#given filesystem read payload #when extracting #then returns resolved path", () => {
- // given
- const root = makeProject();
-
- // when
- const paths = extractCodexToolPaths(
- postToolUse({
- toolName: "mcp__filesystem__read_file",
- toolInput: { path: "src/app.ts" },
- }),
- root,
- );
-
- // then
- expect(paths).toEqual([path.join(root, "src", "app.ts")]);
- });
+ for (const [name, toolName, toolInput] of [
+ [
+ "#given filesystem read payload #when extracting #then returns resolved path",
+ "mcp__filesystem__read_file",
+ { path: "src/app.ts" },
+ ],
+ [
+ "#given mcp write-file payload #when extracting #then returns resolved path",
+ "mcp__filesystem__write_file",
+ { path: "src/app.ts", content: "export const app = true;\n" },
+ ],
+ [
+ "#given mcp edit-file payload #when extracting #then returns resolved path",
+ "mcp__filesystem__edit_file",
+ { path: "src/app.ts", edits: [] },
+ ],
+ ] as const) {
+ it(name, () => {
+ // given
+ const root = makeProject();
+
+ // when
+ const paths = extractCodexToolPaths(postToolUse({ toolName, toolInput }), root);
+
+ // then
+ expect(paths).toEqual([path.join(root, "src", "app.ts")]);
+ });
+ }
it("#given apply_patch payload #when extracting #then returns patched file paths", () => {
// given
@@ -109,40 +121,6 @@ describe("extractCodexToolPaths", () => {
]);
});
- it("#given mcp write-file payload #when extracting #then returns resolved path", () => {
- // given
- const root = makeProject();
-
- // when
- const paths = extractCodexToolPaths(
- postToolUse({
- toolName: "mcp__filesystem__write_file",
- toolInput: { path: "src/app.ts", content: "export const app = true;\n" },
- }),
- root,
- );
-
- // then
- expect(paths).toEqual([path.join(root, "src", "app.ts")]);
- });
-
- it("#given mcp edit-file payload #when extracting #then returns resolved path", () => {
- // given
- const root = makeProject();
-
- // when
- const paths = extractCodexToolPaths(
- postToolUse({
- toolName: "mcp__filesystem__edit_file",
- toolInput: { path: "src/app.ts", edits: [] },
- }),
- root,
- );
-
- // then
- expect(paths).toEqual([path.join(root, "src", "app.ts")]);
- });
-
it("#given mcp read-multiple-files payload #when extracting #then returns all resolved paths", () => {
// given
const root = makeProject();
diff --git a/plugins/omo/components/rules/test/windows-git-bash-bundled-rule.test.ts b/plugins/omo/components/rules/test/windows-git-bash-bundled-rule.test.ts
index 405a7d25..02997008 100644
--- a/plugins/omo/components/rules/test/windows-git-bash-bundled-rule.test.ts
+++ b/plugins/omo/components/rules/test/windows-git-bash-bundled-rule.test.ts
@@ -72,7 +72,7 @@ describe("Windows Git Bash bundled rule", () => {
expect(candidates.map((candidate) => candidate.relativePath)).not.toContain(WINDOWS_RULE_PATH);
});
- it("#given bundled rules enabled on Windows #when SessionStart runs #then Windows Git Bash guidance file is listed once", async () => {
+ it("#given bundled rules enabled on Windows #when SessionStart runs #then Windows Git Bash guidance is injected once", async () => {
const { root, pluginData } = makeProject();
const output = await runSessionStartHook(sessionStartInput(root), {
@@ -81,8 +81,8 @@ describe("Windows Git Bash bundled rule", () => {
platform: "win32",
});
- expect(occurrenceCount(output, `- [windows-git-bash.md]{${join(process.cwd(), WINDOWS_RULE_PATH)}}`)).toBe(1);
- expect(output).not.toContain(WINDOWS_GUIDANCE);
+ expect(occurrenceCount(output, `Instructions from: ${join(process.cwd(), WINDOWS_RULE_PATH)}`)).toBe(1);
+ expect(output).toContain(WINDOWS_GUIDANCE);
});
it("#given bundled rules enabled off Windows #when SessionStart runs #then Windows Git Bash guidance is not injected", async () => {
@@ -116,8 +116,8 @@ describe("Windows Git Bash bundled rule", () => {
platform: "win32",
});
- expect(output).toContain(`- [windows-git-bash.md]{${projectRulePath}}`);
- expect(output).not.toContain(projectGuidance);
+ expect(output).toContain(`Instructions from: ${projectRulePath}`);
+ expect(output).toContain(projectGuidance);
expect(output).not.toContain(WINDOWS_GUIDANCE);
});
});
diff --git a/plugins/omo/components/start-work-continuation/directive.md b/plugins/omo/components/start-work-continuation/directive.md
index 788d6e8b..904c8bec 100644
--- a/plugins/omo/components/start-work-continuation/directive.md
+++ b/plugins/omo/components/start-work-continuation/directive.md
@@ -18,7 +18,7 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
1. Read `{{PLAN_PATH}}` AND `{{LEDGER_PATH}}` first — ground truth for what remains and what evidence has already been recorded. The plan checkbox and the ledger are the only sources of truth; do not trust your own memory of prior turns.
2. Pick the FIRST unchecked top-level checkbox in `## TODOs` or `## Final Verification Wave`. Ignore nested checkboxes under Acceptance Criteria / Evidence / Definition of Done.
3. Follow the `start-work` skill in full. The skill is already loaded from your earlier turn — re-read its file at `packages/omo-codex/plugin/skills/start-work/SKILL.md` if you have lost context.
-4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Prefer `fork_turns: "none"` unless full history is truly required. Every dispatch sets `agent_type`; `model` + `reasoning_effort` alone creates a default agent, not the requested role.
+4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Prefer `fork_turns: "none"` unless full history is truly required. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`.
5. Every sub-task message MUST be self-contained and start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff. It must include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app. Tests are the floor; the channel artifact plus probed adversarial classes are the ceiling. All are required.
6. Treat every worker DoneClaim as untrusted input. Run independent AdversarialVerify before any checkbox can become FullyDone; `confirmed` is the only pass verdict, while `false-positive`, `needs-fix`, and `needs-human-review` loop back to the executor with exact feedback.
7. Use `wait_agent` for mailbox signals, not proof of completion. For sub-tasks likely to exceed one wait cycle, require `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A timeout only means no new mailbox update arrived; after a timeout, run a single `list_agents` check for the named child when you need reassurance. If it is running or its latest message is `WORKING:`, treat it as alive. Do not use `list_agents` as a polling loop. Send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` only when the child is completed without the deliverable, ack-only, or no longer running. If that followup is still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
@@ -35,12 +35,18 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
- The worktree path (if set in boulder.json) governs every file edit and command. Do not stray into the main repo.
- session_ids you write to boulder.json MUST be prefixed `codex:`. Bare ids on read are legacy `opencode:`.
+# Global Review and Debugging Gate
+
+Before completion, run `review-work` and a `debugging` runtime audit. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, and inconclusive review lanes as failures, not progress. Record at least three debugging hypotheses and the runtime evidence that confirms or refutes each one.
+
+Do not print `ORCHESTRATION COMPLETE`. Do not create a PR, PR handoff, or branch handoff. Do not write a final completion answer until this gate passes. Always redact secrets, tokens, credentials, auth headers, cookies, env dumps, private logs, and PII from ledgers, PR bodies, and handoffs.
+
# Stop conditions for THIS turn
- A top-level checkbox flipped to `- [x]` after the 5-phase QA gate (Phase 1 read, Phase 2 automated, Phase 3 channel scenario, Phase 4 adversarial-class probing, Phase 5 gate decision). Then the Stop hook will re-evaluate; if more checkboxes remain you will be continued again.
-- 3 same-failure cycles on one sub-task → escalate via `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)` and stop dispatch.
+- 3 same-failure cycles on one sub-task → escalate via `spawn_agent({"task_name":"failure_escalation_review","message":"TASK: act as a rigorous reviewer. DELIVERABLE: diagnose the repeated sub-task failure and recommend the next safe action. VERIFY: cite the failing evidence.","fork_turns":"none"})` and stop dispatch.
- Safety boundary (destructive command, secret exfiltration, production write) → stop and surface a safe substitute.
-- All top-level checkboxes `- [x]` AND (if gate triggered) `codex-ultrawork-reviewer` approved unconditionally → print the ORCHESTRATION COMPLETE block and end.
+- All top-level checkboxes `- [x]` AND the Global Review and Debugging Gate passed → print the ORCHESTRATION COMPLETE block and end.
# Output discipline
diff --git a/plugins/omo/components/start-work-continuation/hooks/hooks.json b/plugins/omo/components/start-work-continuation/hooks/hooks.json
index fa7febb5..19228def 100644
--- a/plugins/omo/components/start-work-continuation/hooks/hooks.json
+++ b/plugins/omo/components/start-work-continuation/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js\" hook stop",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Start-Work Continuation"
+ "statusMessage": "LazyCodex(4.8.0): Checking Start-Work Continuation"
}
]
}
@@ -19,7 +19,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js\" hook subagent-stop",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Start-Work Continuation"
+ "statusMessage": "LazyCodex(4.8.0): Checking Start-Work Continuation"
}
]
}
diff --git a/plugins/omo/components/start-work-continuation/src/codex-hook.ts b/plugins/omo/components/start-work-continuation/src/codex-hook.ts
index 7717809f..ee3cbe63 100644
--- a/plugins/omo/components/start-work-continuation/src/codex-hook.ts
+++ b/plugins/omo/components/start-work-continuation/src/codex-hook.ts
@@ -6,6 +6,7 @@ import type { ReadonlyFileSystem, StopHookEventName, StopHookOutput, StopInput }
export function runStopHook(input: unknown, fs: ReadonlyFileSystem): string {
if (!isStopInput(input)) return "";
if (input.stop_hook_active) return "";
+ if (transcriptHasContextPressureMarker(input.transcript_path, fs)) return "";
const state = readContinuationState(input.cwd, input.session_id, fs);
if (state === null) return "";
return JSON.stringify({
@@ -38,6 +39,26 @@ function renderDirective(state: ContinuationState, sessionId: string): string {
return rendered;
}
+const CONTEXT_PRESSURE_MARKERS = [
+ "context compacted",
+ "context_length_exceeded",
+ "skill descriptions were shortened",
+ "context_too_large",
+ "codex ran out of room in the model's context window",
+ "your input exceeds the context window",
+ "long threads and multiple compactions",
+] as const;
+
+function transcriptHasContextPressureMarker(transcriptPath: string, fs: ReadonlyFileSystem): boolean {
+ try {
+ const transcript = fs.readFileSync(transcriptPath, "utf8").toLowerCase();
+ return CONTEXT_PRESSURE_MARKERS.some((marker) => transcript.includes(marker));
+ } catch (error) {
+ if (error instanceof Error) return false;
+ throw error;
+ }
+}
+
function isStopInput(value: unknown): value is StopInput {
return (
isRecord(value) &&
diff --git a/plugins/omo/components/start-work-continuation/test/codex-hook.test.ts b/plugins/omo/components/start-work-continuation/test/codex-hook.test.ts
index 120cf605..cba100bd 100644
--- a/plugins/omo/components/start-work-continuation/test/codex-hook.test.ts
+++ b/plugins/omo/components/start-work-continuation/test/codex-hook.test.ts
@@ -64,6 +64,38 @@ describe("start-work Stop hook", () => {
expect(parsed.reason).toContain("- Your session id in boulder.json: `codex:sess_abc`");
});
+ it("#given context-window pressure in transcript #when hook runs #then it does not inject continuation text", () => {
+ // given
+ const transcriptPath = "/repo/transcript.jsonl";
+ const fs = createMemoryFs({
+ [BOULDER_PATH]: createBoulderJson({
+ sessionIds: ["codex:sess_abc"],
+ status: "active",
+ }),
+ [PLAN_PATH]: ["# Plan", "", "## TODOs", "- [ ] First"].join("\n"),
+ [transcriptPath]: [
+ JSON.stringify({
+ type: "message",
+ payload: {
+ content: {
+ error: {
+ code: "context_too_large",
+ },
+ },
+ },
+ }),
+ "Your input exceeds the context window of this model.",
+ "",
+ ].join("\n"),
+ });
+
+ // when
+ const output = runStopHook({ ...createStopInput(), transcript_path: transcriptPath }, fs);
+
+ // then
+ expect(output).toBe("");
+ });
+
it("#given active codex work #when continuation directive is emitted #then subagent guidance is reliable", () => {
// given
const fs = createMemoryFs({
diff --git a/plugins/omo/components/telemetry/hooks/hooks.json b/plugins/omo/components/telemetry/hooks/hooks.json
index ed65ceab..3916d335 100644
--- a/plugins/omo/components/telemetry/hooks/hooks.json
+++ b/plugins/omo/components/telemetry/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook session-start",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Recording Session Telemetry"
+ "statusMessage": "LazyCodex(4.8.0): Recording Session Telemetry"
}
]
}
diff --git a/plugins/omo/components/telemetry/src/codex-hook.ts b/plugins/omo/components/telemetry/src/codex-hook.ts
index 58c2298a..223f4ddb 100644
--- a/plugins/omo/components/telemetry/src/codex-hook.ts
+++ b/plugins/omo/components/telemetry/src/codex-hook.ts
@@ -47,7 +47,14 @@ export async function runSessionStartHook(
const createClient = options.createClient ?? createPluginPostHog;
const getDistinctId = options.getDistinctId ?? getPostHogDistinctId;
- const client = await createClient();
+ let client: PostHogClient;
+ try {
+ client = await createClient();
+ } catch (error) {
+ writeHookDiagnostic("telemetry_posthog_init_failed", error, error instanceof Error ? "error" : "non_error");
+ return "";
+ }
+
try {
client.trackActive(getDistinctId(), SESSION_START_REASON);
} catch (error) {
diff --git a/plugins/omo/components/telemetry/test/codex-hook.test.ts b/plugins/omo/components/telemetry/test/codex-hook.test.ts
index 7842a8d8..98a5c7b5 100644
--- a/plugins/omo/components/telemetry/test/codex-hook.test.ts
+++ b/plugins/omo/components/telemetry/test/codex-hook.test.ts
@@ -122,6 +122,30 @@ describe("runSessionStartHook", () => {
expect(recorder.shutdownCalls).toBe(1);
});
});
+
+ describe("#given PostHog client creation fails", () => {
+ it("#when createClient throws #then hook resolves with empty output", async () => {
+ const output = await runSessionStartHook(makeSessionStartInput(), {
+ createClient: () => {
+ throw new Error("posthog unavailable");
+ },
+ getDistinctId: () => "distinct-id-abc",
+ });
+
+ expect(output).toBe("");
+ });
+
+ it("#when createClient rejects #then hook resolves with empty output", async () => {
+ const output = await runSessionStartHook(makeSessionStartInput(), {
+ createClient: async () => {
+ throw new Error("posthog unavailable");
+ },
+ getDistinctId: () => "distinct-id-abc",
+ });
+
+ expect(output).toBe("");
+ });
+ });
});
describe("telemetry CLI session-start hook (subprocess)", () => {
diff --git a/plugins/omo/components/ultrawork/README.md b/plugins/omo/components/ultrawork/README.md
index 3975ed7b..e8b81541 100644
--- a/plugins/omo/components/ultrawork/README.md
+++ b/plugins/omo/components/ultrawork/README.md
@@ -13,7 +13,7 @@ Bundled Codex agent role TOMLs in `agents/` are installed into `CODEX_HOME/agent
| Surface + paired cleanup | Execution loop step 4 (**SURFACE-AS-SCENARIO**) runs the chosen channel scenario end-to-end. Step 5 (**CLEANUP, PAIRED**) tears down every QA-spawned process / tmux session / browser context / container / port / temp dir, with a one-line receipt appended to the notepad. Leftover state → NOT done. |
| Durable /tmp notepad | `mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md` with sections `Plan`, `Success criteria + QA scenarios`, `Now`, `Todo`, `Findings`, `Learnings`. **Append**, never rewrite. |
| Obsessive atomic todos | Every action — even one-line edits, `ls`, single test runs — becomes a todo. Format: `path: <action> for <criterion> — verify by <check>`. One in_progress at a time, mark completed immediately. |
-| ChatGPT-compatible xhigh verification gate | Triggered automatically on user-requested rigor, 3+ files, 20+ turns, 30+ minutes, or refactor/migration/perf/security work. Use the bundled `codex-ultrawork-reviewer` agent role when available. Reviewer verdict is **binding**: no "false positive", no minimising, no arguing. Loop until **unconditional** approval. "Looks good but..." = REJECTION. |
+| ChatGPT-compatible high-reasoning verification gate | Triggered automatically on user-requested rigor, 3+ files, 20+ turns, 30+ minutes, or refactor/migration/perf/security work. Use the bundled `codex-ultrawork-reviewer` agent role when available. Reviewer verdict is **binding**: no "false positive", no minimising, no arguing. Loop until **unconditional** approval. "Looks good but..." = REJECTION. |
The directive is currently 10,951 chars / 231 lines and follows the GPT-5.5 prompting structure (Role / Goal / Manual-QA channels / Bootstrap / Execution loop / Verification gate / Commits / Constraints / Output / Stop rules).
diff --git a/plugins/omo/components/ultrawork/agents/codex-ultrawork-reviewer.toml b/plugins/omo/components/ultrawork/agents/codex-ultrawork-reviewer.toml
index 1f334aa4..180fbf11 100644
--- a/plugins/omo/components/ultrawork/agents/codex-ultrawork-reviewer.toml
+++ b/plugins/omo/components/ultrawork/agents/codex-ultrawork-reviewer.toml
@@ -2,7 +2,7 @@ name = "codex-ultrawork-reviewer"
description = "Strict ultrawork verification reviewer. Use after full QA evidence to audit the diff, goal, and scenario evidence before declaring done."
nickname_candidates = ["Verifier"]
model = "gpt-5.5"
-model_reasoning_effort = "xhigh"
+model_reasoning_effort = "high"
developer_instructions = """You are the ultrawork verification reviewer.
Review only. Do not implement.
@@ -11,6 +11,7 @@ The default model intentionally uses a ChatGPT account compatible frontier model
Input should include the goal, success criteria, full diff, QA evidence, and notepad path.
If Codex delivers parent review context as inter-agent commentary, treat the latest parent message with goal/diff/evidence as your active review assignment, not passive context.
+If the latest parent message starts with `TASK STILL ACTIVE:`, immediately return the requested verdict or `BLOCKED: <reason>` instead of continuing silently.
Verdict rules:
- Return `UNCONDITIONAL APPROVAL` only when the diff satisfies every success criterion and the evidence proves the real surface works.
diff --git a/plugins/omo/components/ultrawork/agents/explorer.toml b/plugins/omo/components/ultrawork/agents/explorer.toml
index 9a8288ed..303b7f69 100644
--- a/plugins/omo/components/ultrawork/agents/explorer.toml
+++ b/plugins/omo/components/ultrawork/agents/explorer.toml
@@ -46,7 +46,7 @@ If asked "where is auth?", explain the auth flow you found.]
</results>
# Tool strategy (parallel, flood the first wave)
-- Start with Sparkshell -> `omo sparkshell <command>` for repo-wide inspection, git/history checks, and bounded command output. Use `omo sparkshell --shell '<command>'` only when shell metacharacters are required. Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` only to summarize an existing tmux pane.
+- Prefer `omo sparkshell <command>` before raw shell commands for repo-wide inspection, CLI smoke tests, git/history checks, and bounded command output. Use `omo sparkshell --shell '<command>'` only when shell metacharacters are required. Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` only to inspect an existing tmux pane.
- Symbol questions -> `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`.
- Structural shapes -> `ast_grep_search` with `$VAR` / `$$$` metavars.
- Text / strings / comments / logs -> `rg` (grep).
diff --git a/plugins/omo/components/ultrawork/agents/metis.toml b/plugins/omo/components/ultrawork/agents/metis.toml
index 02628d6c..97288a60 100644
--- a/plugins/omo/components/ultrawork/agents/metis.toml
+++ b/plugins/omo/components/ultrawork/agents/metis.toml
@@ -3,7 +3,6 @@ description = "Pre-planning analyst. Detects contradictions, ambiguity, missing
nickname_candidates = ["Analyst"]
model = "gpt-5.5"
model_reasoning_effort = "high"
-service_tier = "fast"
developer_instructions = """
Role: pre-planning analyst. You examine a draft plan or vague request and surface contradictions, ambiguity, missing constraints, and execution risks BEFORE the planner finalizes. Read-only — you never write plans or code.
diff --git a/plugins/omo/components/ultrawork/agents/momus.toml b/plugins/omo/components/ultrawork/agents/momus.toml
index d9dc627b..82b4267a 100644
--- a/plugins/omo/components/ultrawork/agents/momus.toml
+++ b/plugins/omo/components/ultrawork/agents/momus.toml
@@ -3,7 +3,6 @@ description = "Plan reviewer. Verifies a work plan is executable: references exi
nickname_candidates = ["Reviewer"]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
-service_tier = "fast"
developer_instructions = """
Role: plan reviewer. You verify that a work plan is executable and references are valid. You are a blocker-finder, not a perfectionist. Read-only — you never write plans or code.
diff --git a/plugins/omo/components/ultrawork/agents/plan.toml b/plugins/omo/components/ultrawork/agents/plan.toml
index a9292a30..fd681b93 100644
--- a/plugins/omo/components/ultrawork/agents/plan.toml
+++ b/plugins/omo/components/ultrawork/agents/plan.toml
@@ -3,7 +3,6 @@ description = "Strategic planning consultant. Produces a single executable work
nickname_candidates = ["Planner"]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
-service_tier = "fast"
developer_instructions = """
Role: strategic planning consultant. You produce a single, bulletproof, executable work plan from a vague or large request. You are a PLANNER. NOT an implementer. You do not write product code. You may write a plan file (markdown).
diff --git a/plugins/omo/components/ultrawork/directive.md b/plugins/omo/components/ultrawork/directive.md
index 4f2afffb..d4af6bab 100644
--- a/plugins/omo/components/ultrawork/directive.md
+++ b/plugins/omo/components/ultrawork/directive.md
@@ -74,7 +74,7 @@ may skip the plan agent — justify that skip in the notepad.
## 1. Create the goal with binding success criteria
Call `create_goal` (or open your reply with a `# Goal` block treated as
-binding) using exactly `objective` and `status` fields. Goals are
+binding) using exactly `objective`. Do not include `status`. Goals are
unlimited; never invent a numeric budget or limit.
The criteria MUST list, upfront:
- The user-visible deliverable in one line.
@@ -166,11 +166,11 @@ production code before its failing test → rewrite.
Never guess from memory — locate with the right tool, and re-read before
you claim or change. Fire 3+ independent lookups in one action;
serialize only when one output strictly feeds the next.
-- Repo-wide inspection, git/history, bounded command output →
- `omo sparkshell <command>` (use `omo sparkshell --shell '<cmd>'` only
- when shell metacharacters are required; `--tmux-pane <id>
- --tail-lines N` only to summarize an existing pane). Sparkshell is
- your default lens on the tree.
+- Repo-wide inspection, CLI smoke tests, git/history, bounded command
+ output → prefer `omo sparkshell <command>` before raw shell commands
+ (use `omo sparkshell --shell '<cmd>'` only when shell metacharacters
+ are required; `--tmux-pane <id> --tail-lines N` only to inspect an
+ existing pane). Sparkshell is your default lens on the tree.
- Symbols — definitions, references, rename impact, diagnostics →
`lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`,
`lsp_diagnostics`. Use the LSP, not text search, for anything
@@ -237,6 +237,15 @@ handoff. Prefer `fork_turns: "none"` unless full history is truly
required; paste only the context the child needs. Full-history forks can
make the child continue old parent context instead of the delegated task.
+# TOML-backed subagent routing compatibility
+Treat TOML-backed role routing as **routing-unverified**. The available
+`spawn_agent` schema accepts only `task_name`, `message`, and
+`fork_turns`; it cannot select a TOML-backed role, model, reasoning
+effort, or `service_tier`. Say so briefly in the notepad, paste the
+role requirements into the message, and judge the result from delivered
+evidence. Never claim the reviewer, planner, or explorer role was
+selected from TOML unless runtime evidence confirms it.
+
Treat child status as a progress signal, not a timeout counter. For
work likely to exceed one wait cycle, tell the child to send
`WORKING: <task> - <current phase>` before long reading, testing, or
@@ -254,6 +263,19 @@ silent or ack-only, record the result as inconclusive, do not count it
as approval/pass, close it if safe, and respawn a smaller
`fork_turns: "none"` task with the missing deliverable.
+# Subagent-dependent transition barrier
+Do not mark an `update_plan` step `completed` while an active child owns
+evidence for that step. Do not start dependent implementation until the
+audit, research, or review result is integrated or explicitly recorded
+as inconclusive. Do not generate a plan before spawned research lanes
+that feed the plan have returned or been closed as inconclusive.
+Do not write the final answer, PR handoff, or completion summary while
+active child agents remain open. Use short `wait_agent` cycles.
+After two silent waits send `TASK STILL ACTIVE: return <deliverable> or
+BLOCKED: <reason>`. After four silent or ack-only checks, close the lane as
+inconclusive, record that it is not approval, and respawn smaller only
+if the deliverable is still required.
+
# Verification gate (TRIGGERED, NOT OPTIONAL)
Trigger when ANY apply:
@@ -263,10 +285,10 @@ Trigger when ANY apply:
anything the user called deep.
Procedure (NON-NEGOTIABLE):
-1. Spawn `agent_type="codex-ultrawork-reviewer"` with
- `fork_turns: "none"`. If unavailable, spawn `agent_type="worker"`
- with a self-contained reviewer assignment and tight scope. `model` +
- `reasoning_effort` alone creates a default agent, not a reviewer.
+1. Spawn a child with `fork_turns: "none"` and a self-contained reviewer
+ assignment in `message`. The `spawn_agent` schema cannot select a
+ TOML-backed reviewer role, so paste the reviewer requirements into
+ the message.
Pass: goal, success-criteria, scenario evidence, full diff, notepad
path.
2. Treat the reviewer's verdict as binding. There is NO "false
diff --git a/plugins/omo/components/ultrawork/hooks/hooks.json b/plugins/omo/components/ultrawork/hooks/hooks.json
index 3f1efcd9..0ca86fa0 100644
--- a/plugins/omo/components/ultrawork/hooks/hooks.json
+++ b/plugins/omo/components/ultrawork/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Checking Ultrawork Trigger"
+ "statusMessage": "LazyCodex(4.8.0): Checking Ultrawork Trigger"
}
]
}
diff --git a/plugins/omo/components/ultrawork/skills/ulw-plan/SKILL.md b/plugins/omo/components/ultrawork/skills/ulw-plan/SKILL.md
index 8e4c0027..40f3e6c0 100644
--- a/plugins/omo/components/ultrawork/skills/ulw-plan/SKILL.md
+++ b/plugins/omo/components/ultrawork/skills/ulw-plan/SKILL.md
@@ -44,7 +44,7 @@ Subagent outputs are not success or approval without independent verification.
You explore a LOT - fan out parallel read-only research before interviewing - but delegate with Codex discipline:
-- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`. Role selection requires `agent_type`; setting `model` + `reasoning_effort` alone creates a default agent, not the role you wanted. Prefer `fork_turns: "none"` unless full history is truly required.
+- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`. Prefer `fork_turns: "none"` unless full history is truly required.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
- While any child is active, keep yourself visibly alive with active subagent count, agent names, latest `WORKING:` phase, and whether you are waiting for mailbox updates.
@@ -55,10 +55,10 @@ You explore a LOT - fan out parallel read-only research before interviewing - bu
| Planning intent | Codex tool |
| --- | --- |
-| Internal codebase research | `spawn_agent(agent_type="explorer", fork_turns="none", ...)` |
-| External docs / library research | `spawn_agent(agent_type="librarian", fork_turns="none", ...)` |
-| Pre-plan gap analysis (after approval) | `spawn_agent(agent_type="metis", fork_turns="none", ...)` |
-| High-accuracy plan review (optional) | `spawn_agent(agent_type="momus", fork_turns="none", ...)` |
+| Internal codebase research | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| External docs / library research | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| Pre-plan gap analysis (after approval) | `spawn_agent({"task_name":"...","message":"TASK: act as a Metis gap-analysis reviewer. ...","fork_turns":"none"})` |
+| High-accuracy plan review (optional) | `spawn_agent({"task_name":"...","message":"TASK: act as a Momus plan reviewer. ...","fork_turns":"none"})` |
| Wait for a research result | `wait_agent(...)` |
| Release a finished subagent | `close_agent(...)` |
diff --git a/plugins/omo/components/ultrawork/skills/ulw-plan/references/full-workflow.md b/plugins/omo/components/ultrawork/skills/ulw-plan/references/full-workflow.md
index b7247f8a..d35d5ba2 100644
--- a/plugins/omo/components/ultrawork/skills/ulw-plan/references/full-workflow.md
+++ b/plugins/omo/components/ultrawork/skills/ulw-plan/references/full-workflow.md
@@ -22,8 +22,8 @@ Size your interview depth before diving in:
## Phase 1 - Ground (explore exhaustively BEFORE asking)
Eliminate unknowns by discovering facts, not by asking the user. Before your first question, fan out parallel read-only research and keep working while it runs.
-- `spawn_agent(agent_type="explorer", fork_turns="none", ...)` per internal aspect: existing patterns, conventions, similar implementations, naming/registration, test infrastructure. One agent per aspect.
-- `spawn_agent(agent_type="librarian", fork_turns="none", ...)` per external aspect: official docs, API contracts, recommended patterns, pitfalls.
+- `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` per internal aspect: existing patterns, conventions, similar implementations, naming/registration, test infrastructure. One agent per aspect.
+- `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` per external aspect: official docs, API contracts, recommended patterns, pitfalls.
- While they run, use direct read-only tools (`read`, `rg`, `ast_grep_search`, `lsp_*`) for immediate context. Do not idle.
### Dynamic workflow for architecture and bootstrap planning
@@ -61,7 +61,7 @@ Then **wait for the user's explicit okay** before generating the plan. No Metis,
Narrow `$start-work` bootstrap exception: if `$start-work` invoked this skill because there was no active Boulder work and no selectable plan, the user's `start work` request counts as approval to generate the plan and begin execution. Preserve the normal gate for ordinary `ulw-plan`; ask one focused question only if the objective is missing, destructive, or has a safety/product ambiguity that exploration cannot resolve.
## Phase 3 - Generate the plan (only after approval)
-1. **Metis gap analysis (mandatory):** `spawn_agent(agent_type="metis", fork_turns="none", message="TASK: review this planning session for gaps. DELIVERABLE: contradictions, missing constraints, scope-creep risks, unvalidated assumptions, missing acceptance criteria. VERIFY: each gap names a concrete fix.")`. Fold the findings in silently.
+1. **Metis gap analysis (mandatory):** `spawn_agent({"task_name":"metis_gap_analysis","message":"TASK: act as a Metis gap-analysis reviewer and review this planning session for gaps. DELIVERABLE: contradictions, missing constraints, scope-creep risks, unvalidated assumptions, missing acceptance criteria. VERIFY: each gap names a concrete fix.","fork_turns":"none"})`. Fold the findings in silently.
2. Write ONE plan to `.omo/plans/<slug>.md` using the template below. No "Phase 1 plan / Phase 2 plan" splits; 50+ todos is fine. Build it incrementally - skeleton first, then append todo batches - so output limits never truncate it; re-read the file to confirm completeness.
3. **Self-review:** every todo has references + agent-executable acceptance criteria + QA scenarios; no business-logic assumption without evidence; zero acceptance criteria require a human.
@@ -116,10 +116,10 @@ Critical path: ...
```
## Phase 4 - High-accuracy review (optional)
-If the user wants maximum rigor, `spawn_agent(agent_type="momus", fork_turns="none", message=".omo/plans/<slug>.md")` and pass ONLY the plan path. Fix every cited issue and resubmit until it approves.
+If the user wants maximum rigor, call `spawn_agent({"task_name":"momus_plan_review","message":"TASK: act as a Momus plan reviewer. DELIVERABLE: review .omo/plans/<slug>.md only. VERIFY: cite every required fix or approve.","fork_turns":"none"})` and pass ONLY the plan path in `message`. Fix every cited issue and resubmit until it approves.
## Delegation discipline (Codex)
-- Every `spawn_agent` message starts with `TASK:`, then `DELIVERABLE`, `SCOPE`, `VERIFY`. `agent_type` selects the role; `model` + `reasoning_effort` alone creates a default agent, not that role. Prefer `fork_turns: "none"`.
+- Every `spawn_agent` message starts with `TASK:`, then `DELIVERABLE`, `SCOPE`, `VERIFY`. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`. Prefer `fork_turns: "none"`.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops.
- Keep yourself visibly alive while children run: active subagent count, agent names, latest `WORKING:` phase, and whether you are waiting on mailbox updates.
diff --git a/plugins/omo/components/ultrawork/test/codex-hook.test.ts b/plugins/omo/components/ultrawork/test/codex-hook.test.ts
index 975e9a8c..4ef0eabb 100644
--- a/plugins/omo/components/ultrawork/test/codex-hook.test.ts
+++ b/plugins/omo/components/ultrawork/test/codex-hook.test.ts
@@ -211,7 +211,9 @@ describe("codex ultrawork hook", () => {
expect(parsed.hookSpecificOutput.additionalContext).toMatch(/CLEANUP \(PAIRED/);
expect(parsed.hookSpecificOutput.additionalContext).toMatch(/refresh current branch\/PR\/issue state/);
expect(parsed.hookSpecificOutput.additionalContext).toMatch(/preserve existing ordering\/policy/);
- expect(parsed.hookSpecificOutput.additionalContext).toMatch(/separate compatibility detection from policy changes/);
+ expect(parsed.hookSpecificOutput.additionalContext).toMatch(
+ /separate compatibility detection from policy changes/,
+ );
});
it("#given directive #when inspected #then avoids context-expensive agent polling", () => {
diff --git a/plugins/omo/components/ultrawork/test/directive-contract.test.ts b/plugins/omo/components/ultrawork/test/directive-contract.test.ts
new file mode 100644
index 00000000..e44e2324
--- /dev/null
+++ b/plugins/omo/components/ultrawork/test/directive-contract.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+
+import { ULTRAWORK_DIRECTIVE } from "../src/directive.js";
+
+describe("ultrawork directive contract", () => {
+ it("#given directive text #when create_goal guidance is inspected #then the payload contract is objective-only", () => {
+ // given
+ const directive = ULTRAWORK_DIRECTIVE;
+
+ // when
+ const createGoalSection = directive.slice(directive.indexOf("## 1. Create the goal"));
+
+ // then
+ expect(createGoalSection).toMatch(/exactly `objective`/);
+ expect(createGoalSection).toMatch(/Do not include `status`/);
+ expect(createGoalSection).not.toMatch(/`objective` and `status`/);
+ });
+});
diff --git a/plugins/omo/components/ultrawork/test/package-smoke.test.ts b/plugins/omo/components/ultrawork/test/package-smoke.test.ts
index cb3f759f..cd17b737 100644
--- a/plugins/omo/components/ultrawork/test/package-smoke.test.ts
+++ b/plugins/omo/components/ultrawork/test/package-smoke.test.ts
@@ -61,6 +61,7 @@ describe("codex ultrawork package metadata", () => {
expect(sparkshellIndex).toBeGreaterThanOrEqual(0);
expect(lspIndex).toBeGreaterThan(sparkshellIndex);
expect(structuralIndex).toBeGreaterThan(sparkshellIndex);
+ expect(guidance).toContain("prefer `omo sparkshell <command>` before raw shell commands");
expect(guidance).toContain("--shell '<command>'");
expect(guidance).toContain("--tmux-pane");
});
diff --git a/plugins/omo/components/ulw-loop/hooks/hooks.json b/plugins/omo/components/ulw-loop/hooks/hooks.json
index b809ab5b..75e89cae 100644
--- a/plugins/omo/components/ulw-loop/hooks/hooks.json
+++ b/plugins/omo/components/ulw-loop/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook user-prompt-submit",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Ulw-Loop Steering"
+ "statusMessage": "LazyCodex(4.8.0): Checking Ulw-Loop Steering"
}
]
}
@@ -20,7 +20,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook pre-tool-use",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Enforcing Unlimited Ulw-Loop Budget"
+ "statusMessage": "LazyCodex(4.8.0): Enforcing Unlimited Ulw-Loop Budget"
}
]
}
diff --git a/plugins/omo/components/ulw-loop/package.json b/plugins/omo/components/ulw-loop/package.json
index 06f46f6e..faca9e74 100644
--- a/plugins/omo/components/ulw-loop/package.json
+++ b/plugins/omo/components/ulw-loop/package.json
@@ -23,7 +23,7 @@
"typescript"
],
"bin": {
- "omo": "./dist/cli.js"
+ "omo-ulw-loop": "./dist/cli.js"
},
"files": [
"dist",
diff --git a/plugins/omo/components/ulw-loop/skills/ulw-loop/SKILL.md b/plugins/omo/components/ulw-loop/skills/ulw-loop/SKILL.md
index 8cbfa4ab..88f08fee 100644
--- a/plugins/omo/components/ulw-loop/skills/ulw-loop/SKILL.md
+++ b/plugins/omo/components/ulw-loop/skills/ulw-loop/SKILL.md
@@ -21,10 +21,11 @@ This Codex skill is intentionally compact to avoid adding a large operating manu
- Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
- After any compaction or context loss, re-read brief + goals + ledger FIRST (`omo sparkshell cat .omo/ulw-loop/ledger.jsonl` or read directly) plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
+- If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
- Every success criterion needs observable evidence from a real channel: tmux, HTTP, browser, or computer-use.
- Record evidence through the CLI only after cleanup receipts are available.
- Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
-- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; role selection requires `agent_type`, while `model` + `reasoning_effort` alone creates a default agent, not a reviewer or worker; prefer `fork_turns: "none"` unless full history is truly required.
+- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message` because the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`; prefer `fork_turns: "none"` unless full history is truly required.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
- While any child is active, keep the parent visibly alive with brief status updates that include active subagent count, agent names, latest `WORKING:` phase, and whether the parent is waiting for mailbox updates.
@@ -38,10 +39,10 @@ The full workflow may mention OpenCode-style orchestration examples. In Codex, t
| Workflow intent | Codex tool |
| --- | --- |
-| Plan agent | `spawn_agent(agent_type="plan", fork_turns="none", ...)` |
-| Search/read-only worker | `spawn_agent(agent_type="explorer", fork_turns="none", ...)` |
-| Implementation or QA worker | `spawn_agent(agent_type="worker", fork_turns="none", ...)` |
-| Final verification reviewer | `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)` |
+| Plan agent | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| Search/read-only worker | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| Implementation or QA worker | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
+| Final verification reviewer | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
| Wait for background result | `wait_agent(...)` |
| Clean up finished worker | `close_agent(...)` |
diff --git a/plugins/omo/components/ulw-loop/skills/ulw-loop/references/full-workflow.md b/plugins/omo/components/ulw-loop/skills/ulw-loop/references/full-workflow.md
index f637e8be..645f9c15 100644
--- a/plugins/omo/components/ulw-loop/skills/ulw-loop/references/full-workflow.md
+++ b/plugins/omo/components/ulw-loop/skills/ulw-loop/references/full-workflow.md
@@ -28,19 +28,19 @@ Auxiliary surfaces (pure CLI stdout / DB state diff / parsed config dump) satisf
## Delegation model (ATLAS-STYLE — YOU CONDUCT, WORKERS PLAY)
You read, search, plan, integrate, and QA. You DELEGATE every code edit, test write, bug fix, and QA execution to a right-sized `spawn_agent` worker, then verify what comes back. Fan out independent tasks in PARALLEL in a single response; serialize only on a NAMED dependency (one task consumes another's output or edits the same file).
-Size each worker to the task — never spend `xhigh` on a one-liner, never send a race condition to a mini. Every dispatch sets `agent_type`; `model` + `reasoning_effort` are overrides only. Setting them alone creates a default agent, not a reviewer or worker.
+Size each worker to the task. Put the intended role, rigor level, and specialty inside the worker `message`; the Codex `spawn_agent` schema only accepts `task_name`, `message`, and `fork_turns`.
-| Task shape | agent_type | model | reasoning_effort |
-|---|---|---|---|
-| Trivial / mechanical (rename, move, obvious one-liner, config edit) | `worker` | `gpt-5.4-mini` | `low` |
-| Pure implementation against a clear spec (new function, endpoint, test from a named pattern) | `worker` | `gpt-5.5` | `high` |
-| Deep debugging / race / perf / subtle cross-module reasoning | `worker` | `gpt-5.5` | `xhigh` |
-| QA execution (drive a channel, capture evidence) | `worker` | `gpt-5.5` | `high` |
-| Read-only codebase search | `explorer` | role default | role default |
-| External library / docs research | `librarian` | role default | role default |
-| Final verification audit | `codex-ultrawork-reviewer` | role default | role default |
+| Task shape | Message instruction |
+|---|---|
+| Trivial / mechanical (rename, move, obvious one-liner, config edit) | `TASK: act as a focused worker for a trivial mechanical edit. ...` |
+| Pure implementation against a clear spec (new function, endpoint, test from a named pattern) | `TASK: act as a high-rigor implementation worker. ...` |
+| Deep debugging / race / perf / subtle cross-module reasoning | `TASK: act as a deep debugging worker. ...` |
+| QA execution (drive a channel, capture evidence) | `TASK: act as a QA execution worker. ...` |
+| Read-only codebase search | `TASK: act as an explorer. ...` |
+| External library / docs research | `TASK: act as a librarian. ...` |
+| Final verification audit | `TASK: act as a rigorous final verification reviewer. ...` |
-If `codex-ultrawork-reviewer` is unavailable, use `agent_type="worker"` with a self-contained reviewer assignment, tight scope, and explicit verification. Never spawn a model-only default agent for review.
+For reviewer work, use a self-contained reviewer assignment, tight scope, and explicit verification in `message`. Never spawn a context-only child for review.
Every worker message MUST carry: goal + exact files in scope; the baseline characterization test pinning current behavior when the task touches existing code, then the failing test / reproduction required before production code; constraints + project rules; the verification commands to run; the ONE Manual-QA channel and the exact evidence artifact to capture; for git-tracked edits, require `git-master` plus repository-wide and touched-path commit history inspection before commit. Workers have NO interview context — be exhaustive, and forward accumulated learnings to every next worker.
@@ -109,6 +109,10 @@ omo ulw-loop create-goals --brief "<brief>" --json
omo ulw-loop create-goals --brief-file <path> --json
cat <brief> | omo ulw-loop create-goals --from-stdin --json
```
+If the existing aggregate is already complete, do not steer or force the
+completed default state for unrelated new work. Start a fresh run with
+`omo ulw-loop create-goals --session-id <new-id> ...`; use `--force`
+only when deliberately overwriting completed evidence.
Write state through the CLI path. Do not hand-edit state files.
### 2. Refine success criteria + a Prometheus-grade QA and parallelism plan per goal
@@ -174,7 +178,7 @@ Trigger only when one goal remains and all its criteria are passing.
1. Run targeted verification for changed behavior.
2. Run `ai-slop-cleaner` on changed files. If no relevant edits exist, record a passed no-op cleaner report.
3. Rerun verification after cleanup.
-4. Judge the change size. Spawn the `codex-ultrawork-reviewer` agent (`spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)`; fall back to `agent_type="worker"` with a scoped reviewer assignment if unavailable) only when the work is large or risky (multi-file, cross-cutting, new architecture, security/data surfaces, or you are unsure it is sound); for a small, local, low-risk change, do the review yourself and record `codeReview` with `evidence` starting `UNCONDITIONAL APPROVAL` plus a one-line justification of why the change was small enough to self-review.
+4. Judge the change size. Spawn a rigorous reviewer with `spawn_agent({"task_name":"final_verification_review","message":"TASK: act as a rigorous final verification reviewer. DELIVERABLE: approve or cite blockers. SCOPE: <changed files and goal>. VERIFY: inspect diff and verification evidence.","fork_turns":"none"})` only when the work is large or risky (multi-file, cross-cutting, new architecture, security/data surfaces, or you are unsure it is sound); for a small, local, low-risk change, do the review yourself and record `codeReview` with `evidence` starting `UNCONDITIONAL APPROVAL` plus a one-line justification of why the change was small enough to self-review.
5. Clean review means `codeReview.recommendation == "APPROVE"` and `codeReview.architectStatus == "CLEAR"`.
6. If review is non-clean, run `omo ulw-loop record-review-blockers --goal-id <id> --title "<...>" --objective "<...>" --evidence "<review findings>" --codex-goal-json <snapshot> --json`.
7. If clean, checkpoint final completion:
diff --git a/plugins/omo/components/ulw-loop/src/plan-crud.ts b/plugins/omo/components/ulw-loop/src/plan-crud.ts
index b2a61ca1..5a5b5f5c 100644
--- a/plugins/omo/components/ulw-loop/src/plan-crud.ts
+++ b/plugins/omo/components/ulw-loop/src/plan-crud.ts
@@ -2,7 +2,7 @@
import { existsSync } from "node:fs";
import { mkdir, writeFile } from "node:fs/promises";
-import { aggregateCodexObjectiveForScope } from "./goal-status.js";
+import { aggregateCodexObjectiveForScope, isUlwLoopDone } from "./goal-status.js";
import { type UlwLoopScope, ulwLoopBriefPath, ulwLoopBriefRelativePath, ulwLoopDir, ulwLoopGoalsPath, ulwLoopGoalsRelativePath, ulwLoopLedgerPath, ulwLoopLedgerRelativePath } from "./paths.js";
import { appendLedger, readUlwLoopPlan, withUlwLoopMutationLock, writePlan } from "./plan-io.js";
import type { UlwLoopCodexGoalMode, UlwLoopItem, UlwLoopPlan, UlwLoopSuccessCriterion } from "./types.js";
@@ -55,7 +55,11 @@ function clearGoalBlockerFields(goal: UlwLoopItem): void {
export async function createUlwLoopPlan(repoRoot: string, args: { brief: string; codexGoalMode?: UlwLoopCodexGoalMode; force?: boolean }, scope?: UlwLoopScope): Promise<UlwLoopPlan> {
return withUlwLoopMutationLock(repoRoot, scope, async () => {
- if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) throw new UlwLoopError(`Refusing to overwrite existing ${ulwLoopGoalsRelativePath(scope)}; pass --force to recreate it.`, "ULW_LOOP_PLAN_EXISTS");
+ if (!args.force && existsSync(ulwLoopGoalsPath(repoRoot, scope))) {
+ const existing = await readUlwLoopPlan(repoRoot, scope);
+ if (isUlwLoopDone(existing)) throw completedPlanExistsError(scope);
+ throw new UlwLoopError(`Refusing to overwrite existing ${ulwLoopGoalsRelativePath(scope)}; pass --force to recreate it.`, "ULW_LOOP_PLAN_EXISTS");
+ }
const now = iso();
const goals = deriveGoalCandidates(args.brief).map((goal, index) => makeGoal(goal.title, goal.objective, index, now));
const plan: UlwLoopPlan = { version: 1, createdAt: now, updatedAt: now, briefPath: ulwLoopBriefRelativePath(scope), goalsPath: ulwLoopGoalsRelativePath(scope), ledgerPath: ulwLoopLedgerRelativePath(scope), codexGoalMode: args.codexGoalMode ?? "aggregate", goals };
@@ -69,6 +73,17 @@ export async function createUlwLoopPlan(repoRoot: string, args: { brief: string;
});
}
+function completedPlanExistsError(scope?: UlwLoopScope): UlwLoopError {
+ return new UlwLoopError(
+ [
+ `Existing ulw-loop aggregate is already complete at ${ulwLoopGoalsRelativePath(scope)}.`,
+ "Start a new run with `omo ulw-loop create-goals --session-id <new-id> ...` to isolate fresh state.",
+ "Use --force only when you intentionally want to overwrite the completed evidence.",
+ ].join(" "),
+ "ULW_LOOP_PLAN_EXISTS_COMPLETE",
+ );
+}
+
export async function addUlwLoopGoal(repoRoot: string, args: { title: string; objective: string }, scope?: UlwLoopScope): Promise<{ plan: UlwLoopPlan; goal: UlwLoopItem }> {
return withUlwLoopMutationLock(repoRoot, scope, async () => {
const plan = await readUlwLoopPlan(repoRoot, scope);
diff --git a/plugins/omo/components/ulw-loop/test/cli-commands.test.ts b/plugins/omo/components/ulw-loop/test/cli-commands.test.ts
index 40d1a88c..84931d99 100644
--- a/plugins/omo/components/ulw-loop/test/cli-commands.test.ts
+++ b/plugins/omo/components/ulw-loop/test/cli-commands.test.ts
@@ -55,6 +55,14 @@ function stdoutJson(): Record<string, unknown> {
function codexSnapshot(status: "active" | "complete" = "active"): string {
return JSON.stringify({ goal: { objective: ULW_LOOP_AGGREGATE_CODEX_OBJECTIVE, status } });
}
+function qualityGate(): string {
+ return JSON.stringify({
+ aiSlopCleaner: { status: "passed", evidence: "no-op" },
+ verification: { status: "passed", commands: ["vitest"], evidence: "green" },
+ codeReview: { recommendation: "APPROVE", architectStatus: "CLEAR", evidence: "small test fixture" },
+ criteriaCoverage: { totalCriteria: 3, passCount: 3, adversarialClassesCovered: ["stale_state"] },
+ });
+}
async function createPlan(brief = "- Goal A\n- Goal B"): Promise<Record<string, unknown>> {
resetOutput();
@@ -101,6 +109,33 @@ describe("ulwLoopCommand create-goals", () => {
expect(await readFile(join(testDir, ".omo/ulw-loop/ledger.jsonl"), "utf8")).toContain("plan_created");
});
+ it("#given completed default aggregate #when creating another default plan #then guides to a fresh session", async () => {
+ await createPlan("- Finished");
+ for (const criterionId of ["C001", "C002", "C003"]) await passCriterion("G001-finished", criterionId);
+ expect(
+ await ulwLoopCommand([
+ "checkpoint",
+ "--goal-id",
+ "G001-finished",
+ "--status",
+ "complete",
+ "--evidence",
+ "done",
+ "--codex-goal-json",
+ codexSnapshot("complete"),
+ "--quality-gate-json",
+ qualityGate(),
+ ]),
+ ).toBe(0);
+ resetOutput();
+
+ expect(await ulwLoopCommand(["create-goals", "--brief", "- New task"])).toBe(1);
+
+ expect(err.join("")).toContain("Existing ulw-loop aggregate is already complete");
+ expect(err.join("")).toContain("create-goals --session-id <new-id>");
+ expect(err.join("")).toContain("--force only");
+ });
+
it("#given two session ids #when creating goals #then writes isolated session-scoped plans", async () => {
expect(await ulwLoopCommand(["create-goals", "--session-id", "session-A", "--brief", "- Alpha", "--json"])).toBe(
0,
diff --git a/plugins/omo/components/ulw-loop/test/cli-steering.test.ts b/plugins/omo/components/ulw-loop/test/cli-steering.test.ts
index 16566f06..7e1e0617 100644
--- a/plugins/omo/components/ulw-loop/test/cli-steering.test.ts
+++ b/plugins/omo/components/ulw-loop/test/cli-steering.test.ts
@@ -15,6 +15,15 @@ import type { SteerUlwLoopResult, UlwLoopPlan } from "../src/types.js";
import { UlwLoopError } from "../src/types.js";
const NOW = "2026-05-23T00:00:00.000Z";
+const REVISE_CRITERION_BASE_ARGS = [
+ "--kind",
+ "revise_criterion",
+ "--goal-id",
+ "G001",
+ "--criterion-id",
+ "C002",
+] as const;
+const REQUIRED_AUDIT_ARGS = ["--evidence", "x", "--rationale", "y"] as const;
function plan(): UlwLoopPlan {
return {
@@ -64,21 +73,23 @@ function captureStdout(action: () => void): string {
}
describe("parseSteeringKind", () => {
- it("returns valid kind from --kind", () => {
- expect(parseSteeringKind(["--kind", "add_subgoal"])).toBe("add_subgoal");
- });
-
- it("accepts revise_criterion", () => {
- expect(parseSteeringKind(["--kind", "revise_criterion"])).toBe("revise_criterion");
- });
-
- it("throws when --kind missing", () => {
- expect(() => parseSteeringKind([])).toThrow(UlwLoopError);
- });
-
- it("throws when kind unknown", () => {
- expect(() => parseSteeringKind(["--kind", "bogus"])).toThrow(UlwLoopError);
- });
+ for (const testCase of [
+ { name: "returns valid kind from --kind", args: ["--kind", "add_subgoal"], expected: "add_subgoal" },
+ { name: "accepts revise_criterion", args: ["--kind", "revise_criterion"], expected: "revise_criterion" },
+ ] as const) {
+ it(testCase.name, () => {
+ expect(parseSteeringKind(testCase.args)).toBe(testCase.expected);
+ });
+ }
+
+ for (const testCase of [
+ { name: "throws when --kind missing", args: [] },
+ { name: "throws when kind unknown", args: ["--kind", "bogus"] },
+ ] as const) {
+ it(testCase.name, () => {
+ expect(() => parseSteeringKind(testCase.args)).toThrow(UlwLoopError);
+ });
+ }
});
describe("parseSteeringSource", () => {
@@ -141,18 +152,10 @@ describe("parseSteeringProposal add_subgoal", () => {
describe("parseSteeringProposal revise_criterion", () => {
it("builds proposal with goal, criterion, scenario, evidence, and rationale", async () => {
const p = await parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--goal-id",
- "G001",
- "--criterion-id",
- "C002",
+ ...REVISE_CRITERION_BASE_ARGS,
"--scenario",
"new scenario",
- "--evidence",
- "x",
- "--rationale",
- "y",
+ ...REQUIRED_AUDIT_ARGS,
]);
expect(p.kind).toBe("revise_criterion");
@@ -162,94 +165,47 @@ describe("parseSteeringProposal revise_criterion", () => {
expect(p.scenario).toBe("new scenario");
});
- it("accepts --expected-evidence as an update field", async () => {
- const p = await parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--goal-id",
- "G001",
- "--criterion-id",
- "C002",
- "--expected-evidence",
- "new evidence",
- "--evidence",
- "x",
- "--rationale",
- "y",
- ]);
-
- expect(p.expectedEvidence).toBe("new evidence");
- });
-
- it("accepts --user-model as an update field", async () => {
- const p = await parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--goal-id",
- "G001",
- "--criterion-id",
- "C002",
- "--user-model",
- "edge",
- "--evidence",
- "x",
- "--rationale",
- "y",
- ]);
-
- expect(p.userModel).toBe("edge");
- });
-
- it("throws when none of scenario/expected-evidence/user-model provided", async () => {
- await expect(
- parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--goal-id",
- "G001",
- "--criterion-id",
- "C002",
- "--evidence",
- "x",
- "--rationale",
- "y",
- ]),
- ).rejects.toThrow(UlwLoopError);
- });
+ for (const testCase of [
+ {
+ name: "accepts --expected-evidence as an update field",
+ updateArgs: ["--expected-evidence", "new evidence"],
+ expected: { expectedEvidence: "new evidence" },
+ },
+ {
+ name: "accepts --user-model as an update field",
+ updateArgs: ["--user-model", "edge"],
+ expected: { userModel: "edge" },
+ },
+ ] as const) {
+ it(testCase.name, async () => {
+ const p = await parseSteeringProposal([
+ ...REVISE_CRITERION_BASE_ARGS,
+ ...testCase.updateArgs,
+ ...REQUIRED_AUDIT_ARGS,
+ ]);
- it("throws when goal-id missing", async () => {
- await expect(
- parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--criterion-id",
- "C002",
- "--scenario",
- "s",
- "--evidence",
- "x",
- "--rationale",
- "y",
- ]),
- ).rejects.toThrow(UlwLoopError);
- });
+ expect(p).toMatchObject(testCase.expected);
+ });
+ }
- it("throws when criterion-id missing", async () => {
- await expect(
- parseSteeringProposal([
- "--kind",
- "revise_criterion",
- "--goal-id",
- "G001",
- "--scenario",
- "s",
- "--evidence",
- "x",
- "--rationale",
- "y",
- ]),
- ).rejects.toThrow(UlwLoopError);
- });
+ for (const testCase of [
+ {
+ name: "throws when none of scenario/expected-evidence/user-model provided",
+ args: [...REVISE_CRITERION_BASE_ARGS, ...REQUIRED_AUDIT_ARGS],
+ },
+ {
+ name: "throws when goal-id missing",
+ args: ["--kind", "revise_criterion", "--criterion-id", "C002", "--scenario", "s", ...REQUIRED_AUDIT_ARGS],
+ },
+ {
+ name: "throws when criterion-id missing",
+ args: ["--kind", "revise_criterion", "--goal-id", "G001", "--scenario", "s", ...REQUIRED_AUDIT_ARGS],
+ },
+ ] as const) {
+ it(testCase.name, async () => {
+ await expect(parseSteeringProposal(testCase.args)).rejects.toThrow(UlwLoopError);
+ });
+ }
});
describe("parseSteeringProposal split_subgoal", () => {
diff --git a/plugins/omo/components/ulw-loop/test/package-smoke.test.ts b/plugins/omo/components/ulw-loop/test/package-smoke.test.ts
index d88da8f7..8cf5e8f6 100644
--- a/plugins/omo/components/ulw-loop/test/package-smoke.test.ts
+++ b/plugins/omo/components/ulw-loop/test/package-smoke.test.ts
@@ -59,10 +59,10 @@ describe("package.json", () => {
expect((pkg["engines"] as Record<string, unknown>)["node"]).toBe(">=20.0.0");
});
- it("exposes the omo binary pointing at dist/cli.js", async () => {
+ it("#given package metadata #when bin is inspected #then exposes the omo-ulw-loop binary pointing at dist/cli.js", async () => {
const pkg = await readJson("package.json") as Record<string, unknown>;
const bin = pkg["bin"] as Record<string, string>;
- expect(bin["omo"]).toBe("./dist/cli.js");
+ expect(bin["omo-ulw-loop"]).toBe("./dist/cli.js");
});
it("ships the expected files for npm publish", async () => {
@@ -218,6 +218,16 @@ describe("skills/ulw-loop/SKILL.md", () => {
expect(text).toContain(".omo/ulw-loop");
});
+ it("#given completed default state #when skill guidance is inspected #then it prefers a fresh session", async () => {
+ const skill = await readText("skills/ulw-loop/SKILL.md");
+ const workflow = await readText("skills/ulw-loop/references/full-workflow.md");
+
+ expect(skill).toContain("fresh `--session-id <new-id>`");
+ expect(skill).toContain("Use `--force` only");
+ expect(workflow).toContain("create-goals --session-id <new-id>");
+ expect(workflow).toContain("overwriting completed evidence");
+ });
+
it("#given long Codex runs #when worker guidance is inspected #then avoids context-expensive agent polling", async () => {
const text = await readText("skills/ulw-loop/references/full-workflow.md");
diff --git a/plugins/omo/components/ulw-loop/test/steering.test.ts b/plugins/omo/components/ulw-loop/test/steering.test.ts
index 674bc14f..cfd7e3ff 100644
--- a/plugins/omo/components/ulw-loop/test/steering.test.ts
+++ b/plugins/omo/components/ulw-loop/test/steering.test.ts
@@ -159,46 +159,37 @@ describe("steerUlwLoop", () => {
});
}
- it("add_subgoal: uses next numeric id + default success criteria", async () => {
- const repoRoot = await repoWithPlan(sluggedPlan());
- const result = await steerUlwLoop(repoRoot, steering({ idempotencyKey: "slug-add" }));
- expect(result.plan.goals.at(-1)).toMatchObject({
- id: "G003",
- successCriteria: [{ id: "C001" }, { id: "C002" }, { id: "C003" }],
- });
- });
-
- it("split_subgoal: replacement goals use default success criteria", async () => {
- const repoRoot = await repoWithPlan(sluggedPlan());
- const result = await steerUlwLoop(
- repoRoot,
+ for (const [name, proposal, goalIndex] of [
+ ["add_subgoal: uses next numeric id + default success criteria", steering({ idempotencyKey: "slug-add" }), -1],
+ [
+ "split_subgoal: replacement goals use default success criteria",
steering({
kind: "split_subgoal",
targetGoalId: "G001-goal-a",
childGoals: [{ title: "Child A", objective: "Do child A" }],
}),
- );
- expect(result.plan.goals[1]).toMatchObject({
- id: "G003",
- successCriteria: [{ id: "C001" }, { id: "C002" }, { id: "C003" }],
- });
- });
-
- it("mark_blocked_superseded: replacement goals use default success criteria", async () => {
- const repoRoot = await repoWithPlan(sluggedPlan());
- const result = await steerUlwLoop(
- repoRoot,
+ 1,
+ ],
+ [
+ "mark_blocked_superseded: replacement goals use default success criteria",
steering({
kind: "mark_blocked_superseded",
targetGoalId: "G001-goal-a",
childGoals: [{ title: "Replacement", objective: "Replace blocked path" }],
}),
- );
- expect(result.plan.goals[1]).toMatchObject({
- id: "G003",
- successCriteria: [{ id: "C001" }, { id: "C002" }, { id: "C003" }],
+ 1,
+ ],
+ ] as const) {
+ it(name, async () => {
+ const repoRoot = await repoWithPlan(sluggedPlan());
+ const result = await steerUlwLoop(repoRoot, proposal);
+ const createdGoal = goalIndex === -1 ? result.plan.goals.at(-1) : result.plan.goals[goalIndex];
+ expect(createdGoal).toMatchObject({
+ id: "G003",
+ successCriteria: [{ id: "C001" }, { id: "C002" }, { id: "C003" }],
+ });
});
- });
+ }
});
it("add_subgoal: appends goal + ledger entry", async () => {
diff --git a/plugins/omo/hooks/hooks.json b/plugins/omo/hooks/hooks.json
index d5546f74..37e16447 100644
--- a/plugins/omo/hooks/hooks.json
+++ b/plugins/omo/hooks/hooks.json
@@ -7,7 +7,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook session-start",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Loading Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Loading Project Rules"
}
]
},
@@ -17,7 +17,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/telemetry/dist/cli.js\" hook session-start",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Recording Session Telemetry"
+ "statusMessage": "LazyCodex(4.8.0): Recording Session Telemetry"
}
]
},
@@ -28,7 +28,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/scripts/auto-update.mjs\" hook session-start",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Checking Auto Update"
+ "statusMessage": "LazyCodex(4.8.0): Checking Auto Update"
}
]
}
@@ -40,7 +40,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook user-prompt-submit",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Loading Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Loading Project Rules"
}
]
},
@@ -50,7 +50,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/ultrawork/dist/cli.js\" hook user-prompt-submit",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Checking Ultrawork Trigger"
+ "statusMessage": "LazyCodex(4.8.0): Checking Ultrawork Trigger"
}
]
},
@@ -60,7 +60,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/ulw-loop/dist/cli.js\" hook user-prompt-submit",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Ulw-Loop Steering"
+ "statusMessage": "LazyCodex(4.8.0): Checking Ulw-Loop Steering"
}
]
}
@@ -73,7 +73,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/git-bash/dist/cli.js\" hook pre-tool-use",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Recommending Git Bash Mcp"
+ "statusMessage": "LazyCodex(4.8.0): Recommending Git Bash Mcp"
}
]
},
@@ -84,7 +84,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/ulw-loop/dist/cli.js\" hook pre-tool-use",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Enforcing Unlimited Goal Budget"
+ "statusMessage": "LazyCodex(4.8.0): Enforcing Unlimited Goal Budget"
}
]
}
@@ -97,13 +97,13 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/comment-checker/dist/cli.js\" hook post-tool-use",
"timeout": 30,
- "statusMessage": "LazyCodex(0.1.0): Checking Comments"
+ "statusMessage": "LazyCodex(4.8.0): Checking Comments"
},
{
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/lsp/dist/cli.js\" hook post-tool-use",
"timeout": 60,
- "statusMessage": "LazyCodex(0.1.0): Checking LSP Diagnostics"
+ "statusMessage": "LazyCodex(4.8.0): Checking LSP Diagnostics"
}
]
},
@@ -114,7 +114,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook post-tool-use",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Matching Project Rules"
+ "statusMessage": "LazyCodex(4.8.0): Matching Project Rules"
}
]
}
@@ -127,7 +127,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/git-bash/dist/cli.js\" hook post-compact",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Resetting Git Bash Mcp Reminder"
+ "statusMessage": "LazyCodex(4.8.0): Resetting Git Bash Mcp Reminder"
}
]
},
@@ -138,7 +138,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook post-compact",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Resetting Project Rule Cache"
+ "statusMessage": "LazyCodex(4.8.0): Resetting Project Rule Cache"
}
]
},
@@ -149,7 +149,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/lsp/dist/cli.js\" hook post-compact",
"timeout": 5,
- "statusMessage": "LazyCodex(0.1.0): Resetting LSP Diagnostics Cache"
+ "statusMessage": "LazyCodex(4.8.0): Resetting LSP Diagnostics Cache"
}
]
}
@@ -161,7 +161,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js\" hook stop",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Start-Work Continuation"
+ "statusMessage": "LazyCodex(4.8.0): Checking Start-Work Continuation"
}
]
}
@@ -173,7 +173,7 @@
"type": "command",
"command": "node \"${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js\" hook subagent-stop",
"timeout": 10,
- "statusMessage": "LazyCodex(0.1.0): Checking Start-Work Continuation"
+ "statusMessage": "LazyCodex(4.8.0): Checking Start-Work Continuation"
}
]
}
diff --git a/plugins/omo/model-catalog.json b/plugins/omo/model-catalog.json
index ed7bd265..02b14ed4 100644
--- a/plugins/omo/model-catalog.json
+++ b/plugins/omo/model-catalog.json
@@ -1,5 +1,5 @@
{
- "version": "2026-06-03.gpt-5.5-400k",
+ "version": "2026-06-04.gpt-5.5-400k-reviewer-high",
"current": {
"model": "gpt-5.5",
"model_context_window": 400000,
@@ -15,7 +15,7 @@
},
"verifier": {
"model": "gpt-5.5",
- "model_reasoning_effort": "xhigh"
+ "model_reasoning_effort": "high"
},
"worker": {
"model": "gpt-5.5",
diff --git a/plugins/omo/package-lock.json b/plugins/omo/package-lock.json
index e9ed8fa8..def5a31c 100644
--- a/plugins/omo/package-lock.json
+++ b/plugins/omo/package-lock.json
@@ -176,7 +176,7 @@
"version": "0.1.0",
"license": "MIT",
"bin": {
- "omo": "dist/cli.js"
+ "omo-ulw-loop": "dist/cli.js"
},
"devDependencies": {
"@biomejs/biome": "2.4.15",
diff --git a/plugins/omo/package.json b/plugins/omo/package.json
index 08788130..b997a242 100644
--- a/plugins/omo/package.json
+++ b/plugins/omo/package.json
@@ -1,6 +1,6 @@
{
"name": "@sisyphuslabs/omo-codex-plugin",
- "version": "0.1.0",
+ "version": "4.8.0",
"description": "Aggregate Codex plugin root for OMO components.",
"type": "module",
"packageManager": "[email protected]",
diff --git a/plugins/omo/scripts/auto-update.mjs b/plugins/omo/scripts/auto-update.mjs
index 1e2d814d..745f71d8 100644
--- a/plugins/omo/scripts/auto-update.mjs
+++ b/plugins/omo/scripts/auto-update.mjs
@@ -104,6 +104,9 @@ export async function runAutoUpdateCheck({ env = process.env, now = Date.now() }
});
if (!plan.shouldRun) {
await appendUpdateLog(env, now, "skipped", { reason: plan.reason });
+ if (plan.reason === "up-to-date") {
+ await writeState(statePath, { ...state, lastCheckedAt: now, lastStatus: "success" });
+ }
return { started: false, reason: plan.reason };
}
diff --git a/plugins/omo/scripts/migrate-codex-config.mjs b/plugins/omo/scripts/migrate-codex-config.mjs
index 9484803b..e1ae907f 100644
--- a/plugins/omo/scripts/migrate-codex-config.mjs
+++ b/plugins/omo/scripts/migrate-codex-config.mjs
@@ -1,44 +1,19 @@
#!/usr/bin/env node
-import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
import { pathToFileURL } from "node:url";
-const FALLBACK_CATALOG = {
- version: "fallback.gpt-5.5-400k",
- current: {
- model: "gpt-5.5",
- model_context_window: 400_000,
- model_reasoning_effort: "high",
- plan_mode_reasoning_effort: "xhigh",
- },
- roles: {
- default: {
- model: "gpt-5.5",
- model_context_window: 400_000,
- model_reasoning_effort: "high",
- plan_mode_reasoning_effort: "xhigh",
- },
- verifier: { model: "gpt-5.5", model_reasoning_effort: "xhigh" },
- worker: { model: "gpt-5.5", model_reasoning_effort: "high" },
- },
- managedProfiles: [
- {
- version: "legacy.gpt-5.5-1m",
- match: {
- model: "gpt-5.5",
- model_context_window: 1_000_000,
- model_reasoning_effort: "high",
- plan_mode_reasoning_effort: "xhigh",
- },
- },
- { version: "legacy.gpt-5.5-272k", match: { model: "gpt-5.5", model_context_window: 272_000 } },
- ],
-};
+import { FALLBACK_CATALOG, readModelCatalog } from "./migrate-codex-config/catalog.mjs";
+import { configPaths } from "./migrate-codex-config/config-paths.mjs";
+import { ensureCodexReasoningConfig as applyReasoningProfile, readRootSettings } from "./migrate-codex-config/root-settings.mjs";
+import { readState, resolveStatePath, writeState } from "./migrate-codex-config/state.mjs";
-const MANAGED_KEYS = ["model", "model_context_window", "model_reasoning_effort", "plan_mode_reasoning_effort"];
+export { readModelCatalog } from "./migrate-codex-config/catalog.mjs";
+
+export function ensureCodexReasoningConfig(config, profile = FALLBACK_CATALOG.current) {
+ return applyReasoningProfile(config, profile);
+}
export async function migrateCodexConfig({ env = process.env, cwd = process.cwd() } = {}) {
const catalog = await readModelCatalog(env);
@@ -66,7 +41,7 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG, previousState } = {}) {
const before = await readConfig(configPath);
const decision = shouldApplyCatalog(before, catalog, previousState);
- if (!decision.apply) return { changed: false, written: readRootSettings(before), managed: false };
+ if (!decision.apply) return { changed: false, written: readRootSettings(before), managed: decision.managed };
const after = ensureCodexReasoningConfig(before, catalog.current);
if (after === before) return { changed: false, written: catalog.current, managed: true };
await mkdir(dirname(configPath), { recursive: true });
@@ -74,35 +49,17 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
return { changed: true, written: catalog.current, managed: true };
}
-export function ensureCodexReasoningConfig(config, profile = FALLBACK_CATALOG.current) {
- let next = replaceOrInsertRootSetting(config, "model", JSON.stringify(profile.model));
- next = replaceOrInsertRootSetting(next, "model_context_window", profile.model_context_window.toString());
- next = replaceOrInsertRootSetting(next, "model_reasoning_effort", JSON.stringify(profile.model_reasoning_effort));
- next = replaceOrInsertRootSetting(next, "plan_mode_reasoning_effort", JSON.stringify(profile.plan_mode_reasoning_effort));
- return next;
-}
-
-export async function readModelCatalog(env = process.env) {
- const catalogPath = env.LAZYCODEX_MODEL_CATALOG_PATH?.trim() || join(dirname(fileURLToPath(import.meta.url)), "..", "model-catalog.json");
- try {
- return parseCatalog(JSON.parse(await readFile(catalogPath, "utf8"))) ?? FALLBACK_CATALOG;
- } catch (error) {
- if (error instanceof Error) return FALLBACK_CATALOG;
- throw error;
- }
-}
-
function shouldApplyCatalog(config, catalog, previousState) {
const current = readRootSettings(config);
if (Object.keys(current).length === 0) return { apply: true, reason: "empty" };
- if (matchesProfile(current, catalog.current)) return { apply: false, reason: "current" };
+ if (matchesProfile(current, catalog.current)) return { apply: false, reason: "current", managed: true };
if (previousState?.managed === true && matchesProfile(current, previousState.written)) {
return { apply: true, reason: "managed-state" };
}
for (const profile of catalog.managedProfiles) {
if (matchesProfile(current, profile.match)) return { apply: true, reason: profile.version };
}
- return { apply: false, reason: "user-modified" };
+ return { apply: false, reason: "user-modified", managed: false };
}
function matchesProfile(current, profile) {
@@ -113,81 +70,10 @@ function matchesProfile(current, profile) {
return true;
}
-function readRootSettings(config) {
- const settings = {};
- for (const line of config.split(/\n/)) {
- if (isSectionHeader(line)) break;
- for (const key of MANAGED_KEYS) {
- if (!isRootSetting(line, key)) continue;
- const value = parseTomlScalar(line.slice(line.indexOf("=") + 1));
- if (value !== undefined) settings[key] = value;
- }
- }
- return settings;
-}
-
-function parseTomlScalar(value) {
- const trimmed = value.trim();
- if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
- try {
- return JSON.parse(trimmed);
- } catch (error) {
- if (error instanceof SyntaxError) return undefined;
- throw error;
- }
- }
- const numeric = Number(trimmed);
- return Number.isFinite(numeric) ? numeric : undefined;
-}
-
-function parseCatalog(value) {
- if (!isRecord(value) || !isRecord(value.current) || !Array.isArray(value.managedProfiles)) return null;
- if (typeof value.version !== "string" || !isReasoningProfile(value.current)) return null;
- const managedProfiles = [];
- for (const profile of value.managedProfiles) {
- if (!isRecord(profile) || typeof profile.version !== "string" || !isRecord(profile.match)) return null;
- managedProfiles.push({ version: profile.version, match: profile.match });
- }
- return { version: value.version, current: value.current, managedProfiles, roles: isRecord(value.roles) ? value.roles : {} };
-}
-
-function isReasoningProfile(value) {
- return (
- isRecord(value) &&
- typeof value.model === "string" &&
- typeof value.model_context_window === "number" &&
- typeof value.model_reasoning_effort === "string" &&
- typeof value.plan_mode_reasoning_effort === "string"
- );
-}
-
function isRecord(value) {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
-async function configPaths({ env, cwd }) {
- const codexHome = resolve(env.CODEX_HOME?.trim() || join(homedir(), ".codex"));
- const paths = new Set([join(codexHome, "config.toml")]);
- for (const projectConfig of projectConfigPaths({ cwd, stopAt: homedir() })) {
- if (!(await isRegularFile(projectConfig))) continue;
- if (!(await isRegularDirectory(dirname(projectConfig)))) continue;
- paths.add(projectConfig);
- }
- return [...paths];
-}
-
-function projectConfigPaths({ cwd, stopAt }) {
- const paths = [];
- let current = resolve(cwd);
- const stop = resolve(stopAt);
- while (true) {
- paths.push(join(current, ".codex", "config.toml"));
- if (current === stop || current === dirname(current)) break;
- current = dirname(current);
- }
- return paths;
-}
-
async function readConfig(configPath) {
try {
return await readFile(configPath, "utf8");
@@ -197,80 +83,6 @@ async function readConfig(configPath) {
}
}
-function resolveStatePath(env) {
- if (env.LAZYCODEX_MODEL_CATALOG_STATE_PATH?.trim()) return env.LAZYCODEX_MODEL_CATALOG_STATE_PATH;
- const dataRoot = env.PLUGIN_DATA?.trim() || join(homedir(), ".local", "share", "lazycodex");
- return join(dataRoot, "model-catalog-state.json");
-}
-
-async function readState(statePath) {
- try {
- const parsed = JSON.parse(await readFile(statePath, "utf8"));
- return isRecord(parsed) ? parsed : {};
- } catch (error) {
- if (error instanceof Error) return {};
- throw error;
- }
-}
-
-async function writeState(statePath, state) {
- await mkdir(dirname(statePath), { recursive: true });
- await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
-}
-
-async function isRegularFile(path) {
- try {
- return (await lstat(path)).isFile();
- } catch (error) {
- if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
- throw error;
- }
-}
-
-async function isRegularDirectory(path) {
- try {
- return (await lstat(path)).isDirectory();
- } catch (error) {
- if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
- throw error;
- }
-}
-
-function replaceOrInsertRootSetting(config, key, value) {
- const lines = config.split(/\n/);
- const output = [];
- let replaced = false;
- let inserted = false;
- for (const line of lines) {
- if (!inserted && isSectionHeader(line)) {
- if (!replaced) output.push(`${key} = ${value}`);
- inserted = true;
- }
- if (isRootSetting(line, key)) {
- if (!replaced) {
- output.push(`${key} = ${value}`);
- replaced = true;
- }
- continue;
- }
- output.push(line);
- }
- if (!replaced && !inserted) output.push(`${key} = ${value}`);
- return output.join("\n");
-}
-
-function isSectionHeader(line) {
- const trimmed = line.trim();
- return trimmed.startsWith("[") && trimmed.endsWith("]");
-}
-
-function isRootSetting(line, key) {
- const trimmed = line.trimStart();
- if (trimmed.startsWith("#") || trimmed.startsWith("[")) return false;
- const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
- return match?.[1] === key;
-}
-
if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
migrateCodexConfig().catch((error) => {
if (!(error instanceof Error)) throw error;
diff --git a/plugins/omo/scripts/migrate-codex-config/catalog.mjs b/plugins/omo/scripts/migrate-codex-config/catalog.mjs
new file mode 100644
index 00000000..0500b9a4
--- /dev/null
+++ b/plugins/omo/scripts/migrate-codex-config/catalog.mjs
@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const FALLBACK_CATALOG = {
+ version: "fallback.gpt-5.5-400k-reviewer-high",
+ current: {
+ model: "gpt-5.5",
+ model_context_window: 400_000,
+ model_reasoning_effort: "high",
+ plan_mode_reasoning_effort: "xhigh",
+ },
+ roles: {
+ default: {
+ model: "gpt-5.5",
+ model_context_window: 400_000,
+ model_reasoning_effort: "high",
+ plan_mode_reasoning_effort: "xhigh",
+ },
+ verifier: { model: "gpt-5.5", model_reasoning_effort: "high" },
+ worker: { model: "gpt-5.5", model_reasoning_effort: "high" },
+ },
+ managedProfiles: [
+ {
+ version: "legacy.gpt-5.5-1m",
+ match: {
+ model: "gpt-5.5",
+ model_context_window: 1_000_000,
+ model_reasoning_effort: "high",
+ plan_mode_reasoning_effort: "xhigh",
+ },
+ },
+ { version: "legacy.gpt-5.5-272k", match: { model: "gpt-5.5", model_context_window: 272_000 } },
+ ],
+};
+
+export async function readModelCatalog(env = process.env) {
+ const catalogPath =
+ env.LAZYCODEX_MODEL_CATALOG_PATH?.trim() || join(dirname(fileURLToPath(import.meta.url)), "..", "model-catalog.json");
+ try {
+ return parseCatalog(JSON.parse(await readFile(catalogPath, "utf8"))) ?? FALLBACK_CATALOG;
+ } catch (error) {
+ if (error instanceof Error) return FALLBACK_CATALOG;
+ throw error;
+ }
+}
+
+function parseCatalog(value) {
+ if (!isRecord(value) || !isRecord(value.current) || !Array.isArray(value.managedProfiles)) return null;
+ if (typeof value.version !== "string" || !isReasoningProfile(value.current)) return null;
+ const managedProfiles = [];
+ for (const profile of value.managedProfiles) {
+ if (!isRecord(profile) || typeof profile.version !== "string" || !isRecord(profile.match)) return null;
+ managedProfiles.push({ version: profile.version, match: profile.match });
+ }
+ return { version: value.version, current: value.current, managedProfiles, roles: isRecord(value.roles) ? value.roles : {} };
+}
+
+function isReasoningProfile(value) {
+ return (
+ isRecord(value) &&
+ typeof value.model === "string" &&
+ typeof value.model_context_window === "number" &&
+ typeof value.model_reasoning_effort === "string" &&
+ typeof value.plan_mode_reasoning_effort === "string"
+ );
+}
+
+function isRecord(value) {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/plugins/omo/scripts/migrate-codex-config/config-paths.mjs b/plugins/omo/scripts/migrate-codex-config/config-paths.mjs
new file mode 100644
index 00000000..18b3b3dd
--- /dev/null
+++ b/plugins/omo/scripts/migrate-codex-config/config-paths.mjs
@@ -0,0 +1,44 @@
+import { lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export async function configPaths({ env, cwd }) {
+ const codexHome = resolve(env.CODEX_HOME?.trim() || join(homedir(), ".codex"));
+ const paths = new Set([join(codexHome, "config.toml")]);
+ for (const projectConfig of projectConfigPaths({ cwd, stopAt: homedir() })) {
+ if (!(await isRegularFile(projectConfig))) continue;
+ if (!(await isRegularDirectory(dirname(projectConfig)))) continue;
+ paths.add(projectConfig);
+ }
+ return [...paths];
+}
+
+function projectConfigPaths({ cwd, stopAt }) {
+ const paths = [];
+ let current = resolve(cwd);
+ const stop = resolve(stopAt);
+ while (true) {
+ paths.push(join(current, ".codex", "config.toml"));
+ if (current === stop || current === dirname(current)) break;
+ current = dirname(current);
+ }
+ return paths;
+}
+
+async function isRegularFile(path) {
+ try {
+ return (await lstat(path)).isFile();
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+ throw error;
+ }
+}
+
+async function isRegularDirectory(path) {
+ try {
+ return (await lstat(path)).isDirectory();
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+ throw error;
+ }
+}
diff --git a/plugins/omo/scripts/migrate-codex-config/root-settings.mjs b/plugins/omo/scripts/migrate-codex-config/root-settings.mjs
new file mode 100644
index 00000000..ad9c24bb
--- /dev/null
+++ b/plugins/omo/scripts/migrate-codex-config/root-settings.mjs
@@ -0,0 +1,74 @@
+export const MANAGED_KEYS = ["model", "model_context_window", "model_reasoning_effort", "plan_mode_reasoning_effort"];
+
+export function ensureCodexReasoningConfig(config, profile) {
+ let next = replaceOrInsertRootSetting(config, "model", JSON.stringify(profile.model));
+ next = replaceOrInsertRootSetting(next, "model_context_window", profile.model_context_window.toString());
+ next = replaceOrInsertRootSetting(next, "model_reasoning_effort", JSON.stringify(profile.model_reasoning_effort));
+ next = replaceOrInsertRootSetting(next, "plan_mode_reasoning_effort", JSON.stringify(profile.plan_mode_reasoning_effort));
+ return next;
+}
+
+export function readRootSettings(config) {
+ const settings = {};
+ for (const line of config.split(/\n/)) {
+ if (isSectionHeader(line)) break;
+ for (const key of MANAGED_KEYS) {
+ if (!isRootSetting(line, key)) continue;
+ const value = parseTomlScalar(line.slice(line.indexOf("=") + 1));
+ if (value !== undefined) settings[key] = value;
+ }
+ }
+ return settings;
+}
+
+function parseTomlScalar(value) {
+ const trimmed = value.trim();
+ if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+ try {
+ return JSON.parse(trimmed);
+ } catch (error) {
+ if (error instanceof SyntaxError) return undefined;
+ throw error;
+ }
+ }
+ const numeric = Number(trimmed);
+ return Number.isFinite(numeric) ? numeric : undefined;
+}
+
+function replaceOrInsertRootSetting(config, key, value) {
+ const lines = config.split(/\n/);
+ const output = [];
+ let replaced = false;
+ let inserted = false;
+ let inRoot = true;
+ for (const line of lines) {
+ const sectionHeader = isSectionHeader(line);
+ if (inRoot && !inserted && sectionHeader) {
+ if (!replaced) output.push(`${key} = ${value}`);
+ inserted = true;
+ }
+ if (inRoot && isRootSetting(line, key)) {
+ if (!replaced) {
+ output.push(`${key} = ${value}`);
+ replaced = true;
+ }
+ continue;
+ }
+ output.push(line);
+ if (sectionHeader) inRoot = false;
+ }
+ if (!replaced && !inserted) output.push(`${key} = ${value}`);
+ return output.join("\n");
+}
+
+function isSectionHeader(line) {
+ const trimmed = line.trim();
+ return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+
+function isRootSetting(line, key) {
+ const trimmed = line.trimStart();
+ if (trimmed.startsWith("#") || trimmed.startsWith("[")) return false;
+ const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+ return match?.[1] === key;
+}
diff --git a/plugins/omo/scripts/migrate-codex-config/state.mjs b/plugins/omo/scripts/migrate-codex-config/state.mjs
new file mode 100644
index 00000000..0c65f13d
--- /dev/null
+++ b/plugins/omo/scripts/migrate-codex-config/state.mjs
@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export function resolveStatePath(env) {
+ const explicitStatePath = env.LAZYCODEX_MODEL_CATALOG_STATE_PATH?.trim();
+ if (explicitStatePath) return explicitStatePath;
+ const dataRoot = env.PLUGIN_DATA?.trim() || join(homedir(), ".local", "share", "lazycodex");
+ return join(dataRoot, "model-catalog-state.json");
+}
+
+export async function readState(statePath) {
+ try {
+ const parsed = JSON.parse(await readFile(statePath, "utf8"));
+ return isRecord(parsed) ? parsed : {};
+ } catch (error) {
+ if (error instanceof Error) return {};
+ throw error;
+ }
+}
+
+export async function writeState(statePath, state) {
+ await mkdir(dirname(statePath), { recursive: true });
+ await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function isRecord(value) {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/plugins/omo/scripts/sync-skills.mjs b/plugins/omo/scripts/sync-skills.mjs
index ace5bb80..6b8f4416 100644
--- a/plugins/omo/scripts/sync-skills.mjs
+++ b/plugins/omo/scripts/sync-skills.mjs
@@ -1,12 +1,13 @@
#!/usr/bin/env node
import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
import { sharedSkillsRootPath } from "@oh-my-opencode/shared-skills";
const root = dirname(dirname(fileURLToPath(import.meta.url)));
const sharedSkillsRoot = sharedSkillsRootPath();
const skillsRoot = join(root, "skills");
+const sourceTestFilePattern = /\.test\.ts$/;
const skillSources = [
["comment-checker", "components/comment-checker/skills/comment-checker"],
["lsp", "components/lsp/skills/lsp"],
@@ -23,56 +24,155 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| \`call_omo_agent(subagent_type="explore", ...)\` | \`spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")\` |
-| \`call_omo_agent(subagent_type="librarian", ...)\` | \`spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")\` |
-| \`task(subagent_type="plan", ...)\` | \`spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")\` |
-| \`task(subagent_type="oracle", ...)\` for final verification | \`spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")\` |
-| \`task(category="...", ...)\` for implementation or QA | \`spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")\` |
+| \`call_omo_agent(subagent_type="explore", ...)\` | \`spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})\` |
+| \`call_omo_agent(subagent_type="librarian", ...)\` | \`spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})\` |
+| \`task(subagent_type="plan", ...)\` | \`spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})\` |
+| \`task(subagent_type="oracle", ...)\` for final verification | \`spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})\` |
+| \`task(category="...", ...)\` for implementation or QA | \`spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})\` |
| \`background_output(task_id="...")\` | \`wait_agent(...)\` for mailbox signals; after a timeout, run one \`list_agents\` check for the named child if reassurance is needed |
| \`team_*(...)\` | Use Codex native subagents plus \`send_message\`, \`followup_task\`, \`wait_agent\`, and \`close_agent\` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with \`agent_type\` must use a non-full-history fork mode such as \`fork_turns="none"\`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained \`message\` and usually should use a non-full-history fork mode such as \`fork_turns="none"\`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send \`WORKING: <task> - <current phase>\` before long passes and \`BLOCKED: <reason>\` only when progress stops. A \`wait_agent\` timeout only means no new mailbox update arrived. Treat a running child or latest \`WORKING:\` message as alive. Do not use \`list_agents\` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly \`BLOCKED:\`, or no longer running.
`;
-function insertCodexCompatibilityGuidance(content) {
+const codexCompatibilityEndMarkers = [
+ "For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
+ "Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns=\"none\"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+ "When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+ "When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+];
+
+function findCodexCompatibilitySectionEnd(content, searchStart) {
+ const structuralEndPattern = /\n(?:---|#{1,6}\s)/g;
+ structuralEndPattern.lastIndex = searchStart;
+ const structuralEnd = structuralEndPattern.exec(content);
+ if (structuralEnd) return structuralEnd.index + 1;
+
+ const knownEndMarker = codexCompatibilityEndMarkers.find((marker) => content.indexOf(marker, searchStart) !== -1);
+ if (knownEndMarker === undefined) return content.length;
+
+ return content.indexOf(knownEndMarker, searchStart) + knownEndMarker.length;
+}
+
+function removeCodexCompatibilityGuidance(content) {
+ const heading = "## Codex Harness Tool Compatibility";
+ let withoutGuidance = content;
+
+ while (true) {
+ const start = withoutGuidance.indexOf(heading);
+ if (start === -1) return withoutGuidance;
+
+ const end = findCodexCompatibilitySectionEnd(withoutGuidance, start + heading.length);
+
+ withoutGuidance = `${withoutGuidance.slice(0, start)}${withoutGuidance.slice(end)}`;
+ }
+}
+
+export function insertCodexCompatibilityGuidance(content) {
if (!opencodeOnlyOrchestrationPattern.test(content)) return content;
- if (content.includes("## Codex Harness Tool Compatibility")) return content;
+ const firstExampleIndex = content.search(opencodeOnlyOrchestrationPattern);
+ const compatibilityIndex = content.indexOf("## Codex Harness Tool Compatibility");
+ if (compatibilityIndex !== -1 && compatibilityIndex < firstExampleIndex) return content;
- const frontmatterMatch = content.match(/^---\n[\s\S]*?\n---\n+/);
+ const contentWithoutGuidance = removeCodexCompatibilityGuidance(content);
+
+ const frontmatterMatch = contentWithoutGuidance.match(/^---\n[\s\S]*?\n---\n+/);
if (!frontmatterMatch) {
- return `${codexHarnessToolCompatibility}${content}`;
+ return `${codexHarnessToolCompatibility}${contentWithoutGuidance}`;
}
- return `${frontmatterMatch[0]}${codexHarnessToolCompatibility}${content.slice(frontmatterMatch[0].length)}`;
+ return `${frontmatterMatch[0]}${codexHarnessToolCompatibility}${contentWithoutGuidance.slice(frontmatterMatch[0].length)}`;
+}
+
+const startWorkOriginalCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+3. Remove or mark the Boulder work as completed.
+4. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, artifacts, and cleanup receipts.`;
+
+const startWorkCodexCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+ - Invoke the \`review-work\` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, \`BLOCKED:\`, or inconclusive lane is a gate failure, not approval.
+ - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to \`.omo/start-work/ledger.jsonl\`.
+ - If any review lane or debugging hypothesis fails, invoke the \`debugging\` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
+ - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing \`.omo/start-work/ledger.jsonl\`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
+ - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+4. Remove or mark the Boulder work as completed.
+5. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.`;
+
+const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+const reviewWorkAnchor = "Launch 5 specialized sub-agents in parallel to review completed implementation work from every angle. All 5 must pass for the review to pass. If even ONE fails, the review fails.\n";
+
+const reviewWorkCodexGate = `
+When \`review-work\` is used as a final implementation, PR, or \`$start-work\`
+gate, it is blocking. A timeout, missing deliverable, ack-only response,
+explicit \`BLOCKED:\`, or inconclusive lane is not a pass. Treat that lane as
+failed, investigate the underlying uncertainty with the \`debugging\` skill when
+runtime behavior may be wrong, fix with evidence, and rerun the affected lane
+before claiming completion or handing off a PR.
+
+Review evidence must be safe to share. Redact or mask secrets and sensitive
+user data before including evidence in logs, PR bodies, or handoffs. Never
+include raw tokens, credentials, auth headers, cookies, API keys, env dumps,
+private logs, or PII; summarize with lengths, hashes, and short non-sensitive
+prefixes when identity is needed.
+`;
+
+function applyCodexSkillOverlays(skillName, content) {
+ if (skillName === "start-work") {
+ return content
+ .replace(startWorkOriginalCompletion, startWorkCodexCompletion)
+ .replace(startWorkOriginalHardRule, startWorkCodexHardRule);
+ }
+ if (skillName === "review-work" && !content.includes("When `review-work` is used as a final implementation")) {
+ return content.replace(reviewWorkAnchor, `${reviewWorkAnchor}${reviewWorkCodexGate}`);
+ }
+ return content;
}
async function adaptSkillForCodex(skillName) {
const skillPath = join(skillsRoot, skillName, "SKILL.md");
const content = await readFile(skillPath, "utf8");
- const adapted = insertCodexCompatibilityGuidance(content);
+ const adapted = applyCodexSkillOverlays(skillName, insertCodexCompatibilityGuidance(content));
if (adapted !== content) {
await writeFile(skillPath, adapted, "utf8");
}
}
-await rm(skillsRoot, { recursive: true, force: true });
-await mkdir(skillsRoot, { recursive: true });
+async function syncSkills() {
+ await rm(skillsRoot, { recursive: true, force: true });
+ await mkdir(skillsRoot, { recursive: true });
-for (const [name, source] of skillSources) {
- await cp(join(root, source), join(skillsRoot, name), { recursive: true });
- await adaptSkillForCodex(name);
-}
+ for (const [name, source] of skillSources) {
+ await cp(join(root, source), join(skillsRoot, name), { recursive: true });
+ await adaptSkillForCodex(name);
+ }
-const sharedSkillEntries = await readdir(sharedSkillsRoot, { withFileTypes: true });
-const sharedSkillNames = sharedSkillEntries
- .filter((entry) => entry.isDirectory())
- .map((entry) => entry.name)
- .sort();
+ const sharedSkillEntries = await readdir(sharedSkillsRoot, { withFileTypes: true });
+ const sharedSkillNames = sharedSkillEntries
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => entry.name)
+ .sort();
+
+ for (const skillName of sharedSkillNames) {
+ await cp(join(sharedSkillsRoot, skillName), join(skillsRoot, skillName), {
+ filter: (source) => !sourceTestFilePattern.test(source),
+ recursive: true,
+ });
+ await adaptSkillForCodex(skillName);
+ }
+}
-for (const skillName of sharedSkillNames) {
- await cp(join(sharedSkillsRoot, skillName), join(skillsRoot, skillName), { recursive: true });
- await adaptSkillForCodex(skillName);
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ await syncSkills();
}
diff --git a/plugins/omo/skills/init-deep/SKILL.md b/plugins/omo/skills/init-deep/SKILL.md
index 7a30501b..d3c4b878 100644
--- a/plugins/omo/skills/init-deep/SKILL.md
+++ b/plugins/omo/skills/init-deep/SKILL.md
@@ -8,15 +8,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
diff --git a/plugins/omo/skills/lcx-contribute-bug-fix/SKILL.md b/plugins/omo/skills/lcx-contribute-bug-fix/SKILL.md
new file mode 100644
index 00000000..c931381c
--- /dev/null
+++ b/plugins/omo/skills/lcx-contribute-bug-fix/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: lcx-contribute-bug-fix
+description: "Contribute a verified bug-fix PR for LazyCodex, lazycodex-ai, omo-codex, bundled Codex skills, or upstream Codex CLI bugs. Use when the user asks to fix a bug, contribute a bug fix, contribute to fix bug, open a PR for a bug, or debug and PR a LazyCodex/Codex defect."
+metadata:
+ short-description: Contribute verified LazyCodex or Codex bug-fix PRs
+---
+
+# lcx-contribute-bug-fix
+
+Use this skill to debug a concrete LazyCodex or Codex defect, implement the smallest correct fix in a fresh temporary workspace, and open a GitHub PR. Work in English, keep the PR body short, and support every claim with runtime or source evidence.
+
+Route ownership the same way as `$lcx-report-bug`:
+
+- `code-yeongyu/lazycodex` for LazyCodex, lazycodex-ai, omo-codex, bundled skills, hooks, MCP wiring, installer behavior, marketplace sync, docs, or packaging.
+- `openai/codex` for upstream Codex CLI bugs that reproduce without LazyCodex or come from Codex core behavior.
+
+## Required Outcome
+
+Create a PR that includes:
+
+- a focused branch from a fresh `/tmp` clone/worktree
+- reproduction logs from before the fix
+- the smallest implementation that fixes the defect
+- verification logs from after the fix
+- apply `lazycodex-generated` when label management is available
+- the required LazyCodex footer tag `Tag: lazycodex-generated`
+- cleanup of temporary worktrees and clones
+
+## Required Workflow
+
+1. Read the user's bug report and identify the affected surface.
+2. Invoke `$omo:debugging` for the investigation. If only unqualified skill names are exposed, invoke `$debugging` and state that it is the OMO debugging skill.
+3. Decide the target repository. If ownership is close, compare against upstream Codex source under `/tmp/openai-codex-source` before choosing.
+4. Create a fresh temporary clone and branch. Do not modify the user's current repository for the target fix unless the current repository is itself the requested target and the user explicitly asked for local edits.
+
+```bash
+TARGET_REPO="code-yeongyu/lazycodex" # or openai/codex
+WORK_ROOT="$(mktemp -d /tmp/lazycodex-fix-XXXXXX)"
+gh repo clone "$TARGET_REPO" "$WORK_ROOT/repo" -- --depth=1
+cd "$WORK_ROOT/repo"
+BASE_BRANCH="$(git remote show origin | sed -n '/HEAD branch/s/.*: //p')"
+git fetch origin "$BASE_BRANCH" --depth=1
+BRANCH_NAME="lazycodex/bug-fix-<short-slug>"
+git worktree add "$WORK_ROOT/worktree" -b "$BRANCH_NAME" "origin/$BASE_BRANCH"
+cd "$WORK_ROOT/worktree"
+```
+
+If `gh` cannot clone, use `git clone --depth=1 "https://github.com/$TARGET_REPO" "$WORK_ROOT/repo"` and continue with the same worktree flow.
+
+5. Reproduce the bug in the worktree through the real surface. Save exact command output to `/tmp/lazycodex-fix-<short-slug>-repro.log`.
+6. Write or update a failing regression test before production changes. Confirm it fails for the bug, not for a missing fixture or typo.
+7. Implement the smallest correct fix. Avoid refactors unless the fix cannot be made safely without one.
+8. Run the regression test, adjacent tests, and the smallest real-surface QA command that proves the user-visible behavior changed.
+9. Commit the verified fix before pushing. Inspect the status first so the PR cannot be empty or stale:
+
+```bash
+git status --short
+git add -A
+git commit -m "fix: <short bug-fix summary>"
+git log --oneline "origin/$BASE_BRANCH..HEAD"
+```
+
+10. Generate the PR body with `scripts/create-pr-body.mjs`.
+11. Ensure the generated label exists when the target repo allows label management. Keep the footer tag even when label creation is unavailable:
+
+```bash
+LABEL_ARGS=()
+if gh label create lazycodex-generated --repo "$TARGET_REPO" --color "7C3AED" --description "Created by LazyCodex" --force; then
+ LABEL_ARGS=(--label lazycodex-generated)
+else
+ echo "Label management unavailable for $TARGET_REPO; keeping the footer tag only."
+fi
+```
+
+12. Push to a writable remote, then create the PR. For upstream `openai/codex`, fork first and use the fork as the head repository:
+
+```bash
+PUSH_REMOTE="origin"
+PR_HEAD="$BRANCH_NAME"
+if [ "$TARGET_REPO" = "openai/codex" ]; then
+ gh repo fork "$TARGET_REPO" --remote --remote-name fork
+ PUSH_REMOTE="fork"
+ GH_USER="$(gh api user --jq .login)"
+ PR_HEAD="$GH_USER:$BRANCH_NAME"
+fi
+
+git push -u "$PUSH_REMOTE" "$BRANCH_NAME"
+gh pr create --repo "$TARGET_REPO" --base "$BASE_BRANCH" --head "$PR_HEAD" --title "<short fix title>" "${LABEL_ARGS[@]}" --body-file "$PR_BODY"
+```
+
+13. Clean up:
+
+```bash
+cd /
+git -C "$WORK_ROOT/repo" worktree remove "$WORK_ROOT/worktree"
+find "$WORK_ROOT" -mindepth 1 -maxdepth 1 -exec rm -r -- {} +
+rmdir "$WORK_ROOT"
+```
+
+Return the PR URL, the reproduction command, the verification command, and the cleanup receipt.
+
+## PR Body Generator
+
+Use the bundled script to generate the PR body. Create a JSON file with this shape:
+
+```json
+{
+ "title": "Fix short user-visible failure",
+ "targetRepository": "code-yeongyu/lazycodex",
+ "problem": "What is broken for the user.",
+ "reproductionLogs": "Exact failing command, log excerpt, or trace.",
+ "approach": "What changed and why this is the smallest correct fix.",
+ "confidence": "Why the diagnosis and fix are strongly supported.",
+ "risks": "Risk level and what could regress.",
+ "userVisibleBehaviorChanges": "What changes for the user after the PR.",
+ "verification": ["failing test before fix", "passing test after fix", "manual QA command"]
+}
+```
+
+Run:
+
+```bash
+PR_INPUT="/tmp/lazycodex-fix-<short-slug>-pr.json"
+PR_BODY="/tmp/lazycodex-fix-<short-slug>-pr.md"
+node "<skill-root>/scripts/create-pr-body.mjs" "$PR_INPUT" "$PR_BODY"
+```
+
+## PR Body Template
+
+The generated body must follow this structure:
+
+```markdown
+## Problem Situation
+[What failed for the user.]
+
+## Reproduction Logs
+[Exact failing command and relevant log excerpt.]
+
+## Approach
+[What changed and why.]
+
+## Why I Am Confident
+[Evidence that proves the root cause and fix.]
+
+## Risks
+[Risk level and possible regressions.]
+
+## User-Visible Behavior Changes
+[What users experience after this PR.]
+
+## Verification
+- [RED test output or repro before the fix]
+- [GREEN test output after the fix]
+- [Manual QA command and result]
+
+---
+This PR was debugged, implemented, and created with [LazyCodex](https://github.com/code-yeongyu/lazycodex).
+Tag: lazycodex-generated
+```
+
+## Stop Conditions
+
+Stop and ask one narrow question only when:
+
+- the bug cannot be reproduced from available information
+- target repository ownership remains ambiguous after comparing LazyCodex and upstream Codex evidence
+- authentication is missing for pushing or creating the PR
+- the fix requires a product decision rather than a technical correction
+
+Do not open:
+
+- a PR without a failing-before and passing-after test
+- a PR without a real-surface QA command
+- a PR without the `Tag: lazycodex-generated` footer
+- a vague fix that does not identify the root cause
+- a broad refactor disguised as a bug fix
diff --git a/plugins/omo/skills/lcx-contribute-bug-fix/agents/openai.yaml b/plugins/omo/skills/lcx-contribute-bug-fix/agents/openai.yaml
new file mode 100644
index 00000000..b8571fe1
--- /dev/null
+++ b/plugins/omo/skills/lcx-contribute-bug-fix/agents/openai.yaml
@@ -0,0 +1,12 @@
+interface:
+ display_name: "lcx-contribute-bug-fix (omo)"
+ short_description: "Contribute verified LazyCodex or Codex bug-fix PRs"
+ search_terms:
+ - "lcx-contribute-bug-fix"
+ - "contribute a bug fix"
+ - "contribute to fix bug"
+ - "fix bug pr"
+ - "lazycodex fix"
+ - "omo-codex bug fix"
+ - "codex bug fix pr"
+ default_prompt: "Use $lcx-contribute-bug-fix to debug this LazyCodex or Codex bug, work from a fresh /tmp clone and worktree, implement the smallest verified fix, generate the PR body, apply the lazycodex-generated label, open the PR, and clean up."
diff --git a/plugins/omo/skills/lcx-contribute-bug-fix/scripts/create-pr-body.mjs b/plugins/omo/skills/lcx-contribute-bug-fix/scripts/create-pr-body.mjs
new file mode 100644
index 00000000..73fd67a8
--- /dev/null
+++ b/plugins/omo/skills/lcx-contribute-bug-fix/scripts/create-pr-body.mjs
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+const REQUIRED_STRING_FIELDS = [
+ "title",
+ "targetRepository",
+ "problem",
+ "reproductionLogs",
+ "approach",
+ "confidence",
+ "risks",
+ "userVisibleBehaviorChanges",
+];
+
+function requireRecord(value) {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ throw new Error("input must be a JSON object");
+ }
+ return value;
+}
+
+function requireStringField(record, field) {
+ const value = record[field];
+ if (typeof value !== "string" || value.trim() === "") {
+ throw new Error(`${field} must be a non-empty string`);
+ }
+ return value.trim();
+}
+
+function requireVerification(record) {
+ const value = record.verification;
+ if (!Array.isArray(value) || value.length === 0) {
+ throw new Error("verification must be a non-empty string array");
+ }
+ return value.map((entry, index) => {
+ if (typeof entry !== "string" || entry.trim() === "") {
+ throw new Error(`verification[${index}] must be a non-empty string`);
+ }
+ return entry.trim();
+ });
+}
+
+function parseInput(value) {
+ const record = requireRecord(value);
+ const strings = Object.fromEntries(REQUIRED_STRING_FIELDS.map((field) => [field, requireStringField(record, field)]));
+ return {
+ title: strings.title,
+ targetRepository: strings.targetRepository,
+ problem: strings.problem,
+ reproductionLogs: strings.reproductionLogs,
+ approach: strings.approach,
+ confidence: strings.confidence,
+ risks: strings.risks,
+ userVisibleBehaviorChanges: strings.userVisibleBehaviorChanges,
+ verification: requireVerification(record),
+ };
+}
+
+function bulletList(items) {
+ return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function createLazyCodexBugFixPrBody(value) {
+ const input = parseInput(value);
+ return `## Problem Situation
+${input.problem}
+
+## Reproduction Logs
+${input.reproductionLogs}
+
+## Approach
+${input.approach}
+
+## Why I Am Confident
+${input.confidence}
+
+## Risks
+${input.risks}
+
+## User-Visible Behavior Changes
+${input.userVisibleBehaviorChanges}
+
+## Verification
+${bulletList(input.verification)}
+
+---
+This PR was debugged, implemented, and created with [LazyCodex](https://github.com/code-yeongyu/lazycodex).
+Tag: lazycodex-generated
+`;
+}
+
+async function main() {
+ const [, , inputPath, outputPath] = process.argv;
+ if (typeof inputPath !== "string" || inputPath.trim() === "") {
+ throw new Error("usage: create-pr-body.mjs <input.json> <output.md>");
+ }
+ if (typeof outputPath !== "string" || outputPath.trim() === "") {
+ throw new Error("usage: create-pr-body.mjs <input.json> <output.md>");
+ }
+ const parsed = JSON.parse(await readFile(inputPath, "utf8"));
+ await writeFile(outputPath, createLazyCodexBugFixPrBody(parsed), "utf8");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ await main();
+}
diff --git a/plugins/omo/skills/lcx-report-bug/SKILL.md b/plugins/omo/skills/lcx-report-bug/SKILL.md
index c3ad4551..bd7b3307 100644
--- a/plugins/omo/skills/lcx-report-bug/SKILL.md
+++ b/plugins/omo/skills/lcx-report-bug/SKILL.md
@@ -27,7 +27,7 @@ Create or prepare a GitHub issue or PR that includes:
- confirmed or strongly evidenced root cause
- fix approach, including files or components likely involved
- verification plan
-- required LazyCodex attribution footer
+- `lazycodex-generated` label and footer tag
## Required Workflow
@@ -63,16 +63,29 @@ gh issue list --repo "$TARGET_REPO" --search "<short error or symptom>" --state
```
8. If a matching open issue exists, add a comment with the new evidence instead of creating a duplicate.
-9. If no matching issue exists, create the issue with `gh`.
-10. Create a PR only when the user asked for a PR, the fix is already implemented on a branch, or the smallest correct fix can be safely made in the selected repo. Otherwise create an issue with fix guidance.
+9. Ensure the generated label exists in repositories you control:
-## Required Footer
+```bash
+LABEL_ARGS=()
+if gh label create lazycodex-generated --repo "$TARGET_REPO" --color "7C3AED" --description "Created by LazyCodex" --force; then
+ LABEL_ARGS=(--label lazycodex-generated)
+else
+ echo "Label management unavailable for $TARGET_REPO; keeping the footer tag only."
+fi
+```
-Every issue body, evidence comment, and PR body created by this skill must end with this footer. Do not put content after it.
+If the selected repo is `openai/codex` and label management is not available, still include the footer tag in the body and continue without claiming label creation succeeded.
+10. If no matching issue exists, create the issue with `gh` and apply the `lazycodex-generated` label.
+11. Create a PR only when the user asked for a PR, the fix is already implemented on a branch, or the smallest correct fix can be safely made in the selected repo. Apply the `lazycodex-generated` label to every PR created by this skill. Otherwise create an issue with fix guidance.
+
+## Required Label And Footer
+
+Every issue body, evidence comment, and PR body created by this skill must use the GitHub label `lazycodex-generated` when the artifact supports labels. It must also end with this footer. Do not put content after it.
```markdown
---
-🤖 This issue/PR was debugged and created with [LazyCodex](https://github.com/code-yeongyu/lazycodex).
+This issue or PR was generated by LazyCodex.
+Tag: lazycodex-generated
```
## Issue Body Template
@@ -122,7 +135,8 @@ Write the issue body in English and keep it direct:
- [Regression check for adjacent LazyCodex/Codex plugin behavior]
---
-🤖 This issue/PR was debugged and created with [LazyCodex](https://github.com/code-yeongyu/lazycodex).
+This issue or PR was generated by LazyCodex.
+Tag: lazycodex-generated
```
## PR Body Template
@@ -151,7 +165,8 @@ Use this when a PR is the right artifact:
- [Regression check for adjacent behavior]
---
-🤖 This issue/PR was debugged and created with [LazyCodex](https://github.com/code-yeongyu/lazycodex).
+This issue or PR was generated by LazyCodex.
+Tag: lazycodex-generated
```
## GitHub Creation Path
@@ -161,7 +176,7 @@ Prefer `gh`:
```bash
ISSUE_BODY="/tmp/lcx-report-bug-$(date +%Y%m%d-%H%M%S).md"
$EDITOR "$ISSUE_BODY"
-gh issue create --repo "$TARGET_REPO" --title "<clear title>" --body-file "$ISSUE_BODY"
+gh issue create --repo "$TARGET_REPO" --title "<clear title>" "${LABEL_ARGS[@]}" --body-file "$ISSUE_BODY"
```
If `$EDITOR` is not usable, write the file with the available file-editing tool, then run the same `gh issue create` command.
@@ -171,13 +186,16 @@ For an existing issue:
```bash
COMMENT_BODY="/tmp/lcx-report-bug-comment-$(date +%Y%m%d-%H%M%S).md"
gh issue comment "<issue-number>" --repo "$TARGET_REPO" --body-file "$COMMENT_BODY"
+if [ "${#LABEL_ARGS[@]}" -gt 0 ]; then
+ gh issue edit "<issue-number>" --repo "$TARGET_REPO" --add-label lazycodex-generated
+fi
```
For a PR from a branch pushed to the selected repo or fork:
```bash
PR_BODY="/tmp/lcx-report-bug-pr-$(date +%Y%m%d-%H%M%S).md"
-gh pr create --repo "$TARGET_REPO" --title "<clear title>" --body-file "$PR_BODY"
+gh pr create --repo "$TARGET_REPO" --title "<clear title>" "${LABEL_ARGS[@]}" --body-file "$PR_BODY"
```
After creating or commenting, return the issue or PR URL and a short summary of the evidence used.
diff --git a/plugins/omo/skills/lcx-report-bug/agents/openai.yaml b/plugins/omo/skills/lcx-report-bug/agents/openai.yaml
index cabbc8d2..47e1f3af 100644
--- a/plugins/omo/skills/lcx-report-bug/agents/openai.yaml
+++ b/plugins/omo/skills/lcx-report-bug/agents/openai.yaml
@@ -8,4 +8,4 @@ interface:
- "omo-codex bug"
- "openai codex bug"
- "codex upstream issue"
- default_prompt: "Use $lcx-report-bug to investigate this LazyCodex or Codex bug, compare LazyCodex evidence with /tmp openai/codex source, choose the correct GitHub repo, and file an issue or PR with reproduction, root cause, fix guidance, and the required LazyCodex footer."
+ default_prompt: "Use $lcx-report-bug to investigate this LazyCodex or Codex bug, compare LazyCodex evidence with /tmp openai/codex source, choose the correct GitHub repo, and file an issue or PR with reproduction, root cause, fix guidance, and the lazycodex-generated label and footer."
diff --git a/plugins/omo/skills/programming/SKILL.md b/plugins/omo/skills/programming/SKILL.md
index 55129171..1bb0f79d 100644
--- a/plugins/omo/skills/programming/SKILL.md
+++ b/plugins/omo/skills/programming/SKILL.md
@@ -176,7 +176,7 @@ A bare default constructor for any of these (no timeouts, no pool tuning, no sch
| UB / soundness gate | (n/a) | **nightly miri** with strict provenance + Tree Borrows pass | (n/a) | **`nilaway`** + `-race` detector + `goleak` are the equivalent gate |
| Disposable scripts | **PEP 723** inline metadata + `uv run script.py` | **rust-script** with inline `Cargo.toml` block | `bun run script.ts` | `//go:build ignore` + `go run script.go` |
| Bootstrap a new project | `scripts/python/new-project.py` | `scripts/rust/new-project.py` | `scripts/typescript/new-project.ts` | `scripts/go/new-project.py` |
-| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo +nightly clippy -- -D warnings && cargo nextest run && cargo +nightly miri test` | `npx biome check . && npx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
+| Pre-commit / CI gate | `ruff check . && basedpyright && pytest` | `cargo +nightly clippy -- -D warnings && cargo nextest run && cargo +nightly miri test` | `bunx biome check . && bunx tsc --noEmit && bun test` | `gofumpt -l . && golangci-lint run ./... && nilaway ./... && go test -race -shuffle=on -count=1 ./...` |
A `tsconfig.json` with `"strict": true` alone is **not** strict. The reference enumerates the additional flags. Same for `pyproject.toml` and `Cargo.toml` - the references contain the canonical full configuration.
diff --git a/plugins/omo/skills/programming/references/typescript/README.md b/plugins/omo/skills/programming/references/typescript/README.md
index 44fc4448..f7c9bd1e 100644
--- a/plugins/omo/skills/programming/references/typescript/README.md
+++ b/plugins/omo/skills/programming/references/typescript/README.md
@@ -127,7 +127,7 @@ bun run ../../scripts/typescript/new-project.ts my-api --path ./projects
Creates: `package.json` (Hono + Zod + Biome), `tsconfig.json` (ultra-strict), `biome.json`, `src/index.ts`, `.gitignore`. Works on macOS, Linux, Windows.
-For manual setup: `npx tsc --init`, then load `tsconfig-strict.md` for the full strict config.
+For manual setup: `bunx tsc --init`, then load `tsconfig-strict.md` for the full strict config.
Key flags beyond `"strict": true`:
diff --git a/plugins/omo/skills/programming/references/typescript/bootstrap.md b/plugins/omo/skills/programming/references/typescript/bootstrap.md
index a978b802..f0981b79 100644
--- a/plugins/omo/skills/programming/references/typescript/bootstrap.md
+++ b/plugins/omo/skills/programming/references/typescript/bootstrap.md
@@ -35,7 +35,7 @@ Use Node when:
- Production target is a Node-specific platform (some serverless platforms don't run Bun yet)
- You're contributing to a Node-only project
-Use `npx` in LazyCodex-facing setup snippets. `bun create` scaffolds projects.
+`bunx` replaces `npx`. `bun create` scaffolds projects.
## Package manager — pnpm > npm
diff --git a/plugins/omo/skills/programming/references/typescript/tsconfig-strict.md b/plugins/omo/skills/programming/references/typescript/tsconfig-strict.md
index 332b5d85..eb755d25 100644
--- a/plugins/omo/skills/programming/references/typescript/tsconfig-strict.md
+++ b/plugins/omo/skills/programming/references/typescript/tsconfig-strict.md
@@ -138,8 +138,8 @@ For Bun projects, add to `compilerOptions`:
## CI gate
```bash
-npx biome check .
-npx tsc --noEmit
+bunx biome check .
+bunx tsc --noEmit
bun test
```
diff --git a/plugins/omo/skills/programming/scripts/typescript/new-project.ts b/plugins/omo/skills/programming/scripts/typescript/new-project.ts
index d2f94d18..9bb2a3e7 100644
--- a/plugins/omo/skills/programming/scripts/typescript/new-project.ts
+++ b/plugins/omo/skills/programming/scripts/typescript/new-project.ts
@@ -64,8 +64,8 @@ const pkg = {
scripts: {
dev: "bun --hot src/index.ts",
start: "bun src/index.ts",
- check: "npx biome check . && npx tsc --noEmit && bun test",
- "check:fix": "npx biome check --write .",
+ check: "bunx biome check . && bunx tsc --noEmit && bun test",
+ "check:fix": "bunx biome check --write .",
test: "bun test",
},
dependencies: {
diff --git a/plugins/omo/skills/refactor/SKILL.md b/plugins/omo/skills/refactor/SKILL.md
index 4d7e6059..0e89b22e 100644
--- a/plugins/omo/skills/refactor/SKILL.md
+++ b/plugins/omo/skills/refactor/SKILL.md
@@ -9,15 +9,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
diff --git a/plugins/omo/skills/remove-ai-slops/SKILL.md b/plugins/omo/skills/remove-ai-slops/SKILL.md
index c51f16fb..18b7b932 100644
--- a/plugins/omo/skills/remove-ai-slops/SKILL.md
+++ b/plugins/omo/skills/remove-ai-slops/SKILL.md
@@ -9,15 +9,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
diff --git a/plugins/omo/skills/review-work/SKILL.md b/plugins/omo/skills/review-work/SKILL.md
index 4b0f294a..6a7ad619 100644
--- a/plugins/omo/skills/review-work/SKILL.md
+++ b/plugins/omo/skills/review-work/SKILL.md
@@ -8,24 +8,24 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
## Codex Subagent Reliability
Every `spawn_agent` message must be self-contained. Start with
`TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and
`VERIFY`. State that it is an executable assignment, not a context
-handoff. Role selection requires `agent_type`; `model` +
-`reasoning_effort` alone creates a default agent, not a reviewer or
-worker. Prefer `fork_turns: "none"` unless full history is truly
+handoff. Role or specialty instructions belong inside `message`; the
+Codex tool schema only accepts `task_name`, `message`, and `fork_turns`.
+Prefer `fork_turns: "none"` unless full history is truly
required; paste only the review context that worker needs.
Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles sized to the work. Never use a single long blocking wait for them, and never spin on tiny timeouts as a failure budget.
@@ -45,14 +45,29 @@ treat it as alive. Do not use `list_agents` as a polling loop or status
feed; it can replay large payloads. Fallback only when the child is
completed without the deliverable, ack-only after followup, explicitly
`BLOCKED:`, or no longer running. Then mark that review lane
-inconclusive, do not count it as PASS or approval, close if safe, and
+`INCONCLUSIVE`, do not count it as PASS or approval, close if safe, and
respawn a smaller `fork_turns: "none"` reviewer with the missing
-deliverable.
+deliverable. Preserve completed lane results immediately. If the retry
+budget is exhausted, keep the lane `INCONCLUSIVE` and still emit a final
+aggregate result.
# Review Work - 5-Agent Parallel Review Orchestrator
Launch 5 specialized sub-agents in parallel to review completed implementation work from every angle. All 5 must pass for the review to pass. If even ONE fails, the review fails.
+When `review-work` is used as a final implementation, PR, or `$start-work`
+gate, it is blocking. A timeout, missing deliverable, ack-only response,
+explicit `BLOCKED:`, or inconclusive lane is not a pass. Treat that lane as
+failed, investigate the underlying uncertainty with the `debugging` skill when
+runtime behavior may be wrong, fix with evidence, and rerun the affected lane
+before claiming completion or handing off a PR.
+
+Review evidence must be safe to share. Redact or mask secrets and sensitive
+user data before including evidence in logs, PR bodies, or handoffs. Never
+include raw tokens, credentials, auth headers, cookies, API keys, env dumps,
+private logs, or PII; summarize with lengths, hashes, and short non-sensitive
+prefixes when identity is needed.
+
The 5 agents cover complementary concerns - together they form a comprehensive review that no single reviewer could match:
| # | Agent | Type | Role | Focus Level |
@@ -529,19 +544,27 @@ cycles. Do not treat a timeout, ack-only reply, or empty child result as
a PASS.
As each completes, collect via the Codex mapping above (`wait_agent`,
-then the child's substantive final result). Store each verdict:
+then the child's substantive final result). Preserve completed lane
+results immediately; never lose a PASS/FAIL because another lane is
+still running. Store each verdict independently:
| Agent | Verdict | Notes |
|-------|---------|-------|
-| 1. Goal Verification | pending | - |
-| 2. QA Execution | pending | - |
-| 3. Code Quality | pending | - |
-| 4. Security | pending | - |
-| 5. Context Mining | pending | - |
-
-Do NOT deliver the final report until ALL 5 have completed.
+| 1. Goal Verification | pending/PASS/FAIL/INCONCLUSIVE | - |
+| 2. QA Execution | pending/PASS/FAIL/INCONCLUSIVE | - |
+| 3. Code Quality | pending/PASS/FAIL/INCONCLUSIVE | - |
+| 4. Security | pending/PASS/FAIL/INCONCLUSIVE | - |
+| 5. Context Mining | pending/PASS/FAIL/INCONCLUSIVE | - |
+
+Do NOT deliver the final report until ALL 5 lanes have a terminal state:
+PASS, FAIL, or INCONCLUSIVE.
If a lane remains silent after the reliability followup, record it as
inconclusive and respawn a smaller reviewer/worker for that exact lane.
+If it still remains unfinished after that retry, close the still-running
+agent if safe, keep the lane INCONCLUSIVE, and emit the final aggregate
+review result with the incomplete lane named. Do not spin in repeated
+wait/followup cycles. Do not use `send_message` as an interrupt; queued
+followups are not cancellation.
---
@@ -551,6 +574,7 @@ inconclusive and respawn a smaller reviewer/worker for that exact lane.
ALL 5 agents returned PASS → **REVIEW PASSED**
ANY agent returned FAIL → **REVIEW FAILED - criteria not met**
+ANY lane is INCONCLUSIVE and none failed → **REVIEW INCONCLUSIVE - not approved**
</verdict_logic>
@@ -559,15 +583,15 @@ Compile the final report in this format:
```markdown
# Review Work - Final Report
-## Overall Verdict: PASSED / FAILED
+## Overall Verdict: PASSED / FAILED / INCONCLUSIVE
| # | Review Area | Agent Type | Verdict | Confidence |
|---|------------|------------|---------|------------|
-| 1 | Goal & Constraint Verification | Oracle | PASS/FAIL | HIGH/MED/LOW |
-| 2 | QA Execution | unspecified-high | PASS/FAIL | HIGH/MED/LOW |
-| 3 | Code Quality | Oracle | PASS/FAIL | HIGH/MED/LOW |
-| 4 | Security (supplementary) | Oracle | PASS/FAIL | Severity |
-| 5 | Context Mining | unspecified-high | PASS/FAIL | HIGH/MED/LOW |
+| 1 | Goal & Constraint Verification | Oracle | PASS/FAIL/INCONCLUSIVE | HIGH/MED/LOW |
+| 2 | QA Execution | unspecified-high | PASS/FAIL/INCONCLUSIVE | HIGH/MED/LOW |
+| 3 | Code Quality | Oracle | PASS/FAIL/INCONCLUSIVE | HIGH/MED/LOW |
+| 4 | Security (supplementary) | Oracle | PASS/FAIL/INCONCLUSIVE | Severity |
+| 5 | Context Mining | unspecified-high | PASS/FAIL/INCONCLUSIVE | HIGH/MED/LOW |
## Blocking Issues
[Aggregated from all agents - deduplicated, prioritized]
diff --git a/plugins/omo/skills/start-work/SKILL.md b/plugins/omo/skills/start-work/SKILL.md
index eedc8f3c..7293b007 100644
--- a/plugins/omo/skills/start-work/SKILL.md
+++ b/plugins/omo/skills/start-work/SKILL.md
@@ -9,11 +9,11 @@ This skill ports the OpenCode `/start-work` flow onto Codex. Any OpenCode-only t
| OpenCode example | Codex tool to use |
| --- | --- |
-| `task(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `task(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `task(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `dispatchInternalPrompt(...)` | the `Stop` hook emits `{"decision":"block","reason":"<prompt>"}` automatically; see Continuation |
| `team_*(...)` | `spawn_agent` + `send_message` + `followup_task` + `wait_agent` + `close_agent` |
@@ -25,9 +25,9 @@ When translating `load_skills=[...]`, name the skills inside the spawned agent's
Every `spawn_agent` message must be self-contained. Start with
`TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and
`VERIFY`. State that it is an executable assignment, not a context
-handoff. Role selection requires `agent_type`; `model` +
-`reasoning_effort` alone creates a default agent, not a reviewer or
-worker. Prefer `fork_turns: "none"` unless full history is truly
+handoff. Role or specialty instructions belong inside `message`; the
+Codex tool schema only accepts `task_name`, `message`, and `fork_turns`.
+Prefer `fork_turns: "none"` unless full history is truly
required; paste only the context the child needs.
Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles sized to the work. Never use a single long blocking wait for them, and never spin on tiny timeouts as a failure budget.
@@ -192,9 +192,15 @@ Only after verification passes:
When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are complete:
1. Run the plan's final verification commands.
-2. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
-3. Remove or mark the Boulder work as completed.
-4. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, artifacts, and cleanup receipts.
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+ - Invoke the `review-work` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, `BLOCKED:`, or inconclusive lane is a gate failure, not approval.
+ - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to `.omo/start-work/ledger.jsonl`.
+ - If any review lane or debugging hypothesis fails, invoke the `debugging` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
+ - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing `.omo/start-work/ledger.jsonl`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
+ - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+4. Remove or mark the Boulder work as completed.
+5. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.
## Hard rules
@@ -202,5 +208,6 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
- No `--dry-run` as completion evidence.
- No tests-only completion claim. A Manual-QA artifact is required.
- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
+- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.
- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.
- No stale-memory execution. The plan and ledger are the durable source of truth.
diff --git a/plugins/omo/skills/ultraresearch/SKILL.md b/plugins/omo/skills/ultraresearch/SKILL.md
new file mode 100644
index 00000000..783df69a
--- /dev/null
+++ b/plugins/omo/skills/ultraresearch/SKILL.md
@@ -0,0 +1,770 @@
+---
+name: ultraresearch
+description: "Maximum-saturation research skill. Spawns massive parallel explore+librarian subagents to exhaust every source: codebase grep/LSP/ast-grep, websearch with advanced operators, Context7 docs, grep.app, gh CLI, headless browsing. Recursive EXPAND loop until convergence. Empirically verifies ambiguous claims via code execution. Reports (MD/HTML/PDF/PPTX) with charts, screenshots, citations. ONLY activates on explicit user command. Triggers: 'ultraresearch', '/ultraresearch', '$ultraresearch'."
+---
+
+## Codex Harness Tool Compatibility
+
+This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as `call_omo_agent(...)`, `task(...)`, `background_output(...)`, or `team_*(...)` literally. Translate those examples to Codex native tools:
+
+| OpenCode example | Codex tool to use |
+| --- | --- |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="quick", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a focused worker. ...","fork_turns":"none"})` |
+| `task(category="deep", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a deep research worker. ...","fork_turns":"none"})` |
+| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
+
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
+---
+
+# ULTRARESEARCH — Maximum Saturation Research
+
+> **MANDATORY**: Say "ULTRARESEARCH MODE ENABLED!" as your first response. Then immediately begin orchestration.
+
+You are a research orchestrator. Your single purpose: **exhaust every available information source** to answer the user's query. Not "good enough." Not "representative sampling." EVERYTHING. Overkill is the baseline.
+
+## Core Principles
+
+1. **Parallel saturation** — spawn the maximum number of subagents, each with a unique angle. Never sequential.
+2. **Recursive expansion** — every finding can spawn new searches. Keep expanding until no new leads remain.
+3. **Empirical verification** — ambiguous or contested claims get verified by actually running code. No "it should work."
+4. **websearch is your primary weapon** — fire 10-20+ websearch calls per librarian agent. Advanced operators on EVERY query.
+5. **English first** — all searches in English by default. Largest corpus, most authoritative sources.
+6. **Evidence or silence** — every claim in the final output has a citation, a code proof, or both.
+
+## Language Policy
+
+**ALL searches, queries, and subagent prompts MUST be in English by default.** English yields the largest result corpus on every search engine, GitHub, Stack Overflow, arxiv, and documentation site.
+
+Exceptions (the ONLY cases where non-English is acceptable):
+- The user explicitly asks for results in a specific language
+- The topic is inherently local (Korean law, Japanese market data, etc.)
+- A supplementary sweep for Korean/local sources AFTER the English sweep is complete
+
+When bilingual coverage is warranted, run the English sweep FIRST (primary), then spawn 1-2 additional librarian agents for Korean/local sources as a secondary layer. Never replace the English sweep with a local-language sweep.
+
+---
+
+## Phase 0: Query Decomposition
+
+Before spawning anything, decompose the user's query into orthogonal research axes:
+
+```
+<analysis>
+**User Query**: [verbatim]
+**Core Question**: [the actual information need]
+**Research Axes**:
+ 1. [axis] — what to search, where, why
+ 2. [axis] — ...
+ 3. [axis] — ...
+ (minimum 3, no maximum)
+**Codebase Relevance**: [yes/no — does the local codebase contain relevant code?]
+**External Relevance**: [yes/no — do we need web/docs/repos?]
+**Browsing Needed**: [yes/no — are there pages that need rendering/interaction?]
+**Verification Needed**: [yes/no — are there claims that need code-based proof?]
+**Report Requested**: [yes/no/format — did the user ask for a deliverable document?]
+</analysis>
+```
+
+Create the session log directory immediately:
+
+```bash
+mkdir -p .omo/ultraresearch/$(date +%Y%m%d-%H%M%S)
+```
+
+This is your **session directory** (`$SESSION_DIR`). All agents append findings here.
+
+---
+
+## Phase 1: Spawn the Research Swarm
+
+Launch ALL agents in a SINGLE turn. Every agent uses `run_in_background=true`. No sequential launches. No "let me start with one and see." ALL AT ONCE.
+
+### 1A. Codebase Agents (explore) — spawn 2-4
+
+Each explore agent gets a DIFFERENT search angle. Never duplicate angles.
+
+```
+task(
+ subagent_type="explore",
+ run_in_background=true,
+ prompt="ULTRARESEARCH CODEBASE SWEEP — AXIS: [specific axis]
+
+SESSION_DIR: [session_dir_path]
+
+Your mission: Find EVERYTHING in this codebase related to: [specific search angle]
+
+SEARCH STRATEGY — execute ALL of these in parallel:
+1. grep with 3+ different keyword variations (synonyms, abbreviations, full names)
+2. ast_grep_search for structural patterns (function signatures, class shapes, imports)
+3. LSP: lsp_goto_definition, lsp_find_references, lsp_symbols for type/function names
+4. glob for file name patterns
+5. git log --all -S 'keyword' for historical mentions (even deleted code)
+6. git log --all --grep='keyword' for commit messages
+
+Cross-validate: if grep finds file X, use LSP to find all references TO file X.
+
+After searching, APPEND your findings to $SESSION_DIR/codebase-[axis-slug].md:
+
+## Codebase Findings: [axis]
+### Search Queries Used
+- [list every query you ran]
+### Files Found
+- [absolute path] — [why relevant, key lines]
+### Code Patterns
+- [pattern description with file:line references]
+### Cross-References
+- [how findings connect to each other]
+
+## EXPAND MARKERS
+- [ ] EXPAND: [new lead discovered] — [why it matters] — [suggested search angle]
+- [x] DEAD END: [lead that was already fully explored]
+"
+)
+```
+
+### 1B. Web Research Agents (librarian) — spawn 3-6
+
+Each librarian targets a DIFFERENT search strategy. **websearch is the core tool — fire 10-20+ calls per agent.**
+
+```
+task(
+ subagent_type="librarian",
+ run_in_background=true,
+ prompt="ULTRARESEARCH WEB SWEEP — AXIS: [specific axis]
+
+SESSION_DIR: [session_dir_path]
+
+Your mission: Find EVERYTHING on the internet related to: [specific search angle]
+ALL SEARCHES MUST BE IN ENGLISH unless the topic is inherently non-English.
+
+## WEBSEARCH SATURATION PROTOCOL
+
+You MUST fire ALL of the following. Not some. ALL. In parallel where possible.
+The MINIMUM is 10 distinct websearch calls. 15-20 is normal. Do not stop early.
+
+### A. websearch — Advanced Operators (the primary weapon)
+
+Each websearch call MUST use different operators and angles:
+
+1. websearch('[topic] [keywords]')
+2. websearch('[topic] site:github.com')
+3. websearch('[topic] site:docs.[domain].com OR site:[domain].dev')
+4. websearch('[topic] filetype:md OR filetype:pdf')
+5. websearch('[topic] intitle:[key term]')
+6. websearch('[topic] [current year]')
+7. websearch('[topic] site:stackoverflow.com OR site:reddit.com OR site:news.ycombinator.com')
+8. websearch('[topic] site:arxiv.org OR site:dl.acm.org OR site:scholar.google.com')
+9. websearch('[topic] analysis OR comparison OR benchmark OR review [current year]')
+10. websearch('[topic] -tutorial -beginner advanced implementation')
+11. websearch('[topic] inurl:api OR inurl:docs OR inurl:reference')
+12. websearch('\"[exact phrase]\" [additional context]')
+13. websearch('[topic] vs OR alternative OR compared to')
+14. websearch('[topic] source code implementation github')
+15. websearch('[topic] changelog OR release notes OR migration guide [version]')
+16. websearch('[topic] site:medium.com OR site:dev.to OR site:blog')
+17. websearch('[topic] best practices production [current year]')
+18. websearch('[topic] known issues OR caveats OR gotchas OR limitations')
+19. websearch('[topic] example OR demo OR sample project')
+20. websearch('[topic] conference talk OR presentation OR workshop [current year]')
+
+For EVERY important search result, fetch the FULL page with webfetch/FetchURL. Do not summarize from search snippets alone.
+
+### B. Context7 Documentation Lookup
+
+context7_resolve-library-id('[library]')
+ then context7_query-docs with AT LEAST 3 different queries per library.
+
+### C. grep.app GitHub Code Search
+
+grep_app_searchGitHub(query: '[pattern]', language: ['TypeScript'])
+grep_app_searchGitHub(query: '[alternative pattern]', language: ['Python'])
+grep_app_searchGitHub(query: '[pattern]', repo: 'owner/repo')
+
+### D. GitHub CLI Deep Dive
+
+gh search repos '[topic]' --sort stars --limit 10
+gh search code '[pattern]' --language typescript --limit 20
+gh search issues '[topic]' --state open --sort reactions --limit 10
+gh api search/repositories -f q='[topic] stars:>100' --jq '.items[] | {name, url, description, stars: .stargazers_count}'
+
+### E. Official Documentation Fetch
+
+webfetch('[official docs URL]')
+webfetch('[official docs URL]/sitemap.xml') // discover all doc pages
+webfetch('[API reference URL]')
+webfetch('[changelog/releases URL]')
+
+Fetch sitemaps to discover the FULL doc surface. Don't just read the front page.
+
+After searching, APPEND findings to $SESSION_DIR/web-[axis-slug].md:
+
+## Web Findings: [axis]
+### Searches Executed
+- [list every websearch query with operator used — ALL of them]
+### Key Sources (ranked by quality)
+1. [URL] — [what it contains, key data points]
+### Documentation References
+- [official doc links with specific sections]
+### Code Examples Found
+- [GitHub links with context]
+### Discussions/Opinions
+- [forum links with key points]
+### Data/Benchmarks
+- [any quantitative findings]
+
+## EXPAND MARKERS
+- [ ] EXPAND: [new lead from search results] — [why] — [suggested angle]
+"
+)
+```
+
+### 1C. Browsing Agents (for protected/dynamic pages) — spawn 1-3 as needed
+
+```
+task(
+ category="quick",
+ run_in_background=true,
+ load_skills=["browsing", "insane-search"],
+ prompt="ULTRARESEARCH BROWSER SWEEP
+
+SESSION_DIR: [session_dir_path]
+
+Your mission: Access and extract content from URLs that regular fetch cannot reach:
+[list of URLs]
+
+Use the browsing skill's two-tier approach:
+1. Try insane-search first (headless extraction, WAF bypass)
+2. If that fails, use CloakBrowser+agent-browser (stealth Chromium)
+
+For each URL: extract ALL content, take screenshots if visual context matters.
+APPEND findings to $SESSION_DIR/browsed-[slug].md with URL, method, content.
+
+## EXPAND MARKERS
+- [ ] EXPAND: [new lead from browsed content] — [why] — [angle]
+"
+)
+```
+
+### 1D. Cross-Repository Deep Dive Agents — spawn 1-2 for implementation research
+
+```
+task(
+ subagent_type="librarian",
+ run_in_background=true,
+ prompt="ULTRARESEARCH REPO DEEP DIVE
+
+SESSION_DIR: [session_dir_path]
+Target repositories: [repos identified from initial searches]
+
+For EACH repository:
+1. gh repo clone owner/repo ${TMPDIR:-/tmp}/ur-[repo] -- --depth 1
+2. Get HEAD SHA for permalinks
+3. Read README, CONTRIBUTING, ARCHITECTURE docs
+4. grep/ast_grep for core patterns, read key source files, follow call chains
+5. git log --oneline -20, git blame on critical sections
+6. Construct GitHub permalinks for every finding
+
+APPEND to $SESSION_DIR/repos-[slug].md
+
+## EXPAND MARKERS
+- [ ] EXPAND: [dependency/module worth investigating separately] — [why] — [angle]
+"
+)
+```
+
+### Scaling Rules
+
+| Query Scope | explore | librarian | browsing | repo-dive | total min |
+|---|---|---|---|---|---|
+| Single topic, codebase only | 3 | 0 | 0 | 0 | 3 |
+| Single topic, web only | 0 | 4 | 1 | 1 | 6 |
+| Single topic, both | 2 | 3 | 1 | 1 | 7 |
+| Multi-faceted research | 4 | 6 | 2 | 2 | 14 |
+| Full due diligence | 4 | 6 | 3 | 2 | 15 |
+
+The table is a FLOOR, not a ceiling. More angles = more agents.
+
+---
+
+## Phase 2: Recursive Discovery Loop (EXPAND Protocol)
+
+This is NOT a single-pass search. Research is **recursive**. Every finding can spawn new questions.
+
+### The EXPAND Marker System
+
+Every agent MUST end its report with an `EXPAND` section:
+
+```markdown
+## EXPAND MARKERS
+- [ ] EXPAND: [new lead discovered] — [why it matters] — [suggested search angle]
+- [ ] EXPAND: [another lead] — [why] — [angle]
+- [x] DEAD END: [lead that was already fully explored]
+```
+
+What triggers an EXPAND marker:
+- A search result mentions a related library/tool/concept not yet investigated
+- A GitHub issue links to another repo with relevant implementation
+- A blog post references a paper, benchmark, or alternative approach
+- A code pattern imports a module whose behavior is unclear
+- Documentation mentions a deprecated predecessor worth understanding
+- A comparison article names competitors not yet searched
+- An API response reveals undocumented endpoints or features
+- A forum answer contradicts official docs (needs verification)
+
+### The Expansion Loop
+
+After collecting initial agent results:
+
+1. **Read ALL files in `$SESSION_DIR/`**
+2. **Scan for unchecked `[ ] EXPAND:` markers** across all reports
+3. **Deduplicate** — if two agents flagged the same lead, merge into one
+4. **For each unique unchecked EXPAND marker**, spawn a NEW agent:
+
+```
+task(
+ subagent_type="librarian", // or "explore" if codebase-scoped
+ run_in_background=true,
+ prompt="ULTRARESEARCH EXPANSION — LEAD: [expand marker text]
+
+SESSION_DIR: [session_dir_path]
+PARENT FINDING: [which report spawned this lead]
+EXPANSION WAVE: [N]
+
+This is a recursive expansion. A previous research agent found this lead.
+Investigate it thoroughly using the full websearch saturation protocol.
+ALL SEARCHES IN ENGLISH unless the topic is inherently local.
+Fire 10+ websearch calls with advanced operators for this specific lead.
+
+APPEND to $SESSION_DIR/expand-[wave]-[slug].md.
+Include your OWN EXPAND markers if you discover further leads.
+"
+)
+```
+
+5. **Repeat until convergence**:
+ - No new unchecked EXPAND markers remain, OR
+ - 3 consecutive expansion waves produce no new actionable leads, OR
+ - Expansion depth reaches 5 levels (safety cap — override with user confirmation)
+
+6. **Track expansion state** in `$SESSION_DIR/expansion-log.md`:
+
+```markdown
+# Expansion Log
+
+## Wave 1 (initial)
+- Spawned: 8 agents
+- EXPAND markers generated: 12
+- New leads: [list]
+
+## Wave 2
+- Spawned: 5 agents (from 12 markers, 7 were duplicates/dead-ends)
+- EXPAND markers generated: 4
+
+## Wave 3
+- Spawned: 2 agents
+- EXPAND markers generated: 0
+- CONVERGED — no new leads
+```
+
+**Do NOT wait for all agents before starting the next wave.** Collect as each finishes. Scan for EXPAND markers. Spawn immediately. The loop is continuous.
+
+---
+
+## Phase 3: Empirical Verification
+
+**Any claim that is ambiguous, contested, or unverifiable from documentation alone MUST be verified by running actual code.**
+
+This is not optional. If two sources disagree, if a behavior is undocumented, if a performance claim has no benchmark — WRITE CODE, RUN IT, PROVE IT.
+
+### When to Verify
+
+| Signal | Action |
+|---|---|
+| Source A says X, Source B says Y | Write a test that proves which is correct |
+| "This should work" / "In theory" | Write code that actually does it and capture output |
+| Performance claim without benchmark | Write a benchmark, run it, report numbers |
+| API behavior not in docs | Make the actual API call, capture response |
+| Library version compatibility claim | Install both versions, run the same code, compare |
+| "Deprecated but still works" | Try it, capture the warning/error/success |
+| Security claim | Write a PoC that demonstrates the vulnerability or proves safety |
+
+### How to Verify
+
+Spawn a verification agent for each claim that needs proof:
+
+```
+task(
+ category="deep",
+ run_in_background=true,
+ prompt="ULTRARESEARCH VERIFICATION — CLAIM: [the claim to verify]
+
+SESSION_DIR: [session_dir_path]
+SOURCE: [where this claim came from]
+CONTRADICTION: [what the opposing source says, if any]
+
+Your job: PROVE OR DISPROVE this claim with executable evidence.
+
+1. Write a minimal, self-contained script that tests the claim
+2. Execute it (use bash, or for complex cases: uv run --with [deps] python -c '...')
+3. Capture the FULL output (stdout + stderr)
+4. If it requires a specific environment/dependency, install it first
+5. If it requires network access, make the actual call
+6. If it requires a specific version, pin it
+
+EVIDENCE FORMAT — append to $SESSION_DIR/verify-[slug].md:
+
+## Verification: [claim summary]
+### Claim
+[exact claim being tested]
+### Source
+[URL or file path]
+### Test Code
+\`\`\`[language]
+[the exact code that was executed]
+\`\`\`
+### Execution Output
+\`\`\`
+[full stdout + stderr]
+\`\`\`
+### Verdict
+**CONFIRMED** / **REFUTED** / **PARTIALLY TRUE** — [explanation with evidence]
+### Environment
+- OS: [os]
+- Runtime: [version]
+- Dependencies: [list with versions]
+"
+)
+```
+
+### SparkShell for Codex Harness
+
+When running under the Codex harness where SparkShell is available, prefer SparkShell for code execution — it provides intelligent command classification, secret redaction, and tmux-integrated output capture. The verification agent should use SparkShell for:
+- Running test scripts with full output capture
+- Interactive REPL sessions for exploratory verification
+- Long-running benchmarks that benefit from tmux durability
+- Multi-step verification sequences that need session persistence
+
+When SparkShell is not available (OpenCode harness), use bash + `uv run` for Python, `bun run` for TypeScript, or direct compilation for Rust/Go/C.
+
+---
+
+## Phase 4: Synthesize
+
+Once the expansion loop has CONVERGED and all agents (including verification) have reported:
+
+1. Read ALL files in `$SESSION_DIR/`
+2. Cross-reference findings across ALL agents (initial + expansion waves + verification)
+3. Identify:
+ - **Consensus**: findings confirmed by 2+ agents/sources
+ - **Verified facts**: claims proven by code execution
+ - **Unique discoveries**: found by only one agent but high-value
+ - **Contradictions**: conflicting info (flag with both sources + verification result)
+ - **Gaps**: questions still unanswered despite saturation
+
+4. Write synthesis to `$SESSION_DIR/SYNTHESIS.md`:
+
+```markdown
+# Ultraresearch Synthesis: [query]
+**Date**: [date]
+**Agents Spawned**: [total across all waves]
+**Expansion Waves**: [count]
+**Sources Consulted**: [count]
+**Verifications Executed**: [count]
+
+## Executive Summary
+[2-3 paragraph answer to the user's core question, clear and direct]
+
+## Detailed Findings
+
+### [Topic Area 1]
+**Consensus**: [what multiple sources agree on]
+**Evidence**: [source links]
+**Key Quote**: "[under 20 words]" — [Source]
+**Verified**: [yes/no — link to verification report if yes]
+
+### [Topic Area 2]
+...
+
+## Codebase Findings
+[relevant code locations with absolute paths and line numbers]
+
+## External Sources (ranked by quality)
+1. [URL] — [relevance, reliability assessment, access date]
+2. ...
+
+## Verified Claims
+| Claim | Verdict | Evidence |
+|---|---|---|
+| [claim] | CONFIRMED/REFUTED | [link to verify-*.md] |
+
+## Contradictions Found
+- [source A says X] vs [source B says Y] — [verdict with evidence]
+
+## Remaining Gaps
+- [what we couldn't find despite exhaustive search]
+
+## Expansion Trace
+- Wave 1: [N agents] -> [M expand markers]
+- Wave 2: [N agents] -> [M expand markers]
+- Convergence: [reason]
+
+## Raw Agent Reports
+- [list of all session files]
+```
+
+5. **If the user requested a report**: proceed to Phase 5.
+6. **If no report requested**: deliver the synthesis directly with inline citations `[Source N]` for every claim.
+
+---
+
+## Phase 5: Report Generation (when requested)
+
+If the user asked for a report, presentation, or formatted deliverable — spawn a report generation wave AFTER synthesis.
+
+### Determine Output Format
+
+| User Signal | Format | Tools |
+|---|---|---|
+| "report", "document", "보고서" | Markdown (default) | Direct write |
+| "pdf" | PDF via HTML-to-PDF | `frontend-design` + python `weasyprint` |
+| "pptx", "slides", "presentation", "발표" | PPTX | python `python-pptx` |
+| "html", "webpage" | Standalone HTML | `frontend-design` skill |
+| No format specified | Markdown | Direct write |
+
+### Report Content Agents
+
+#### A. Data Visualization Agent
+
+```
+task(
+ category="quick",
+ run_in_background=true,
+ prompt="ULTRARESEARCH REPORT — DATA VISUALIZATION
+
+SESSION_DIR: [session_dir_path]
+
+Read ALL findings in $SESSION_DIR/. Identify data that benefits from visualization:
+- Comparison tables -> bar/radar charts
+- Timeline data -> timeline charts
+- Architecture -> mermaid diagrams
+- Statistics/benchmarks -> graphs with clear labels
+- Relationships -> network/dependency graphs
+
+Generate using:
+uv run --with numpy --with matplotlib --with plotly python -c \"[code]\"
+
+Save ALL images to $SESSION_DIR/assets/
+Write index to $SESSION_DIR/assets/manifest.md
+"
+)
+```
+
+#### B. Screenshot Collection Agent
+
+```
+task(
+ category="quick",
+ run_in_background=true,
+ load_skills=["browsing"],
+ prompt="ULTRARESEARCH REPORT — SCREENSHOTS
+
+SESSION_DIR: [session_dir_path]
+
+Read web findings. Identify the top 5-10 most important web sources.
+For each: full page screenshot using the browsing skill.
+Save to $SESSION_DIR/assets/screenshots/
+Write manifest to $SESSION_DIR/assets/screenshots/manifest.md
+"
+)
+```
+
+#### C. Image Generation Agent (if diagrams/infographics needed)
+
+```
+task(
+ category="quick",
+ run_in_background=true,
+ load_skills=["imagegen"],
+ prompt="ULTRARESEARCH REPORT — INFOGRAPHICS
+
+SESSION_DIR: [session_dir_path]
+
+Read synthesis. Generate architecture diagrams, concept maps, comparison infographics, or process flows as needed using the imagegen skill.
+Save to $SESSION_DIR/assets/generated/
+"
+)
+```
+
+#### D. Report Assembly Agent
+
+For HTML, PDF, or PPTX output: the report assembly agent MUST first discover and load **every available frontend and design skill** in the system before writing a single line. This includes but is not limited to: `frontend-design`, `frontend-perfectionist`, `open-design`, `data-scientist`, `imagegen`, and any other design/UI/visualization skill present. Read each skill's SKILL.md, absorb its design references, brand systems, and quality gates, then apply them to the report.
+
+```
+task(
+ category="deep",
+ run_in_background=true,
+ load_skills=["frontend-design", "frontend-perfectionist", "open-design", "data-scientist", "imagegen"],
+ prompt="ULTRARESEARCH REPORT — FINAL ASSEMBLY
+
+SESSION_DIR: [session_dir_path]
+REQUESTED FORMAT: [markdown/html/pdf/pptx]
+
+## MANDATORY FIRST STEP
+
+Before writing anything, discover and read ALL available frontend, design, and visualization skills:
+- Read $frontend-design SKILL.md — absorb design references, anti-slop rules, brand-grade standards
+- Read $frontend-perfectionist SKILL.md — absorb Lighthouse 100 perf gates, render measurement, Core Web Vitals
+- Read $open-design SKILL.md — discover the 137+ composable design skills and 150+ brand-grade design systems
+- Read $data-scientist SKILL.md — absorb DuckDB/Polars/numpy/matplotlib best practices
+- Read $imagegen SKILL.md — absorb async image generation workflow
+- List ALL other available skills (ls ~/.agents/skills/ and project .agents/skills/) and read any that relate to design, visualization, or document generation
+
+Apply EVERYTHING you learned from those skills to the report. The report is not a text dump — it is a designed artifact.
+
+Read:
+1. $SESSION_DIR/SYNTHESIS.md
+2. $SESSION_DIR/assets/manifest.md
+3. $SESSION_DIR/assets/screenshots/manifest.md
+4. ALL $SESSION_DIR/*.md files for detail
+
+## Report Structure
+1. **Executive Summary** — 3-5 sentences answering the core question
+2. **Key Findings** — organized by theme, not by agent
+3. **Detailed Analysis** — each finding with:
+ - Evidence (direct quotes under 20 words, with source URL)
+ - Supporting charts (embed from assets/)
+ - Code examples with file paths or GitHub links
+ - Verification results where applicable
+4. **Comparative Analysis** — if multiple options/approaches exist
+5. **Visual Evidence** — embedded screenshots, charts, diagrams
+6. **Sources & References** — numbered, with URLs, access dates, reliability notes
+7. **Appendix: Methodology** — agents spawned, searches executed, expansion waves, verifications
+
+## Quality Rules
+- Every claim MUST cite: [Source N] linking to reference list
+- Every quote under 20 words with quotation marks and attribution
+- Tables for comparisons, not prose
+- Charts/graphs for quantitative data, not number tables
+- Screenshots for UI/visual claims
+- Professional but accessible — a smart non-expert understands everything
+- Technical depth preserved — an expert finds no oversimplifications
+- Design quality: apply the brand-grade standards from the design skills you loaded. No generic HTML. No unstyled tables. No default matplotlib themes.
+
+## Format-Specific
+
+**Markdown**: $SESSION_DIR/REPORT.md with ![alt](assets/path.png) embeds.
+
+**HTML**: Single self-contained HTML with embedded CSS. Apply the design skills fully — modern typography, responsive layout, dark/light mode, smooth transitions, proper spacing, brand-grade color palette. Base64-embedded images. Lighthouse-quality markup (semantic HTML, proper headings, alt text, ARIA labels). $SESSION_DIR/REPORT.html.
+
+**PDF**: Generate the HTML report first (full design quality as above), then:
+uv run --with weasyprint python -c \"from weasyprint import HTML; HTML('$SESSION_DIR/REPORT.html').write_pdf('$SESSION_DIR/REPORT.pdf')\"
+Ensure print-friendly CSS: proper page breaks, margins, header/footer. $SESSION_DIR/REPORT.pdf.
+
+**PPTX**: Use python-pptx with Pillow for image handling:
+uv run --with python-pptx --with Pillow python -c \"[build slides]\"
+Slide design: consistent theme, proper typography hierarchy, one key finding per slide, full-bleed images where appropriate, minimal text per slide, speaker notes with detail.
+Slide flow: Title -> Executive Summary -> Key Finding per slide -> Visual Evidence -> Comparative Analysis -> Sources.
+$SESSION_DIR/REPORT.pptx.
+"
+)
+```
+
+---
+
+## Advanced Search Operator Reference
+
+Agents MUST use these aggressively on every websearch call. This is core technique, not garnish.
+
+### Web Search Operators
+| Operator | Example | Purpose |
+|---|---|---|
+| `site:` | `site:github.com react hooks` | Restrict to domain |
+| `filetype:` | `filetype:pdf machine learning survey` | Specific file types |
+| `intitle:` | `intitle:benchmark comparison 2026` | Title must contain term |
+| `inurl:` | `inurl:api reference authentication` | URL must contain term |
+| `"exact"` | `"dependency injection" typescript` | Exact phrase match |
+| `-term` | `react state management -redux` | Exclude term |
+| `OR` | `nextjs OR nuxt server components` | Either term |
+| `before:` | `LLM agents before:2026-01-01` | Date upper bound |
+| `after:` | `LLM agents after:2025-06-01` | Date lower bound |
+| `related:` | `related:vercel.com` | Similar sites |
+| `*` wildcard | `"how to * with typescript"` | Fill-in-the-blank |
+
+### Combination Patterns
+
+```
+# Official docs
+"[library] site:[library].dev OR site:docs.[library].com"
+
+# GitHub implementations
+"[pattern] site:github.com filetype:ts OR filetype:tsx"
+
+# Recent discussion
+"[topic] site:reddit.com OR site:news.ycombinator.com after:2025-01-01"
+
+# Academic + industry
+"[topic] site:arxiv.org OR filetype:pdf survey OR benchmark [year]"
+
+# Stack Overflow high engagement
+"[topic] site:stackoverflow.com [specific error or pattern]"
+
+# Korean sources (secondary sweep only)
+"[topic] site:tistory.com OR site:velog.io OR site:naver.com"
+
+# Changelog hunting
+"[library] changelog OR release notes OR migration guide [version]"
+
+# Alternatives/comparison
+"[topic] vs OR alternative OR comparison OR benchmark"
+```
+
+### GitHub Search (gh CLI)
+
+```bash
+gh search code '[pattern]' --language typescript --limit 30
+gh search repos '[topic]' --sort stars --limit 20
+gh search issues '[error message]' --state all --sort reactions --limit 20
+gh search prs '[feature]' --state merged --sort updated --limit 15
+```
+
+### grep.app
+
+```
+grep_app_searchGitHub(query: "[pattern]", language: ["TypeScript", "JavaScript"])
+grep_app_searchGitHub(query: "[pattern]", repo: "owner/repo")
+grep_app_searchGitHub(query: "[config key]", language: ["JSON", "YAML", "TOML"])
+```
+
+---
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why it fails | Fix |
+|---|---|---|
+| Sequential agent spawning | Wastes time, defeats purpose | ALL agents in ONE turn |
+| Single websearch per librarian | Barely scratches the surface | 10-20 websearch calls MINIMUM per agent |
+| No search operators | Generic results, misses targeted content | site:/filetype:/intitle: on EVERY websearch |
+| Not fetching full pages | Search snippets lie | webfetch every important result |
+| Skipping Context7 | Misses official doc embeddings | Always query for known libraries |
+| Not recording to session dir | Findings lost, can't synthesize | Every agent MUST append to $SESSION_DIR/ |
+| Ignoring EXPAND markers | Misses recursive discoveries | Every unchecked marker MUST be investigated |
+| No EXPAND markers in reports | Breaks the recursive loop | Every agent MUST output EXPAND section |
+| Stopping when "enough" found | Surface-level results | Goal is EXHAUSTION, minimum 2 expansion waves |
+| Single-pass research | Misses second-order connections | Expand until convergence |
+| Same query to multiple agents | Duplicate work | Each agent gets UNIQUE angle |
+| Searching in non-English first | Smaller corpus, less authoritative | English first, ALWAYS |
+| "It should work" without proof | Unverified speculation | Write code, run it, capture output |
+| Delivering without citations | Unverifiable claims | Every claim needs [Source N] with URL |
+| Skipping visualization for data | Dense tables nobody reads | Charts/graphs for quantitative findings |
+| Trusting a single source | Single point of failure | Cross-validate across 3+ sources |
+| Ambiguous claim left unverified | Readers inherit uncertainty | Spawn verification agent, run actual code |
diff --git a/plugins/omo/skills/ulw-loop/SKILL.md b/plugins/omo/skills/ulw-loop/SKILL.md
index 8cbfa4ab..88f08fee 100644
--- a/plugins/omo/skills/ulw-loop/SKILL.md
+++ b/plugins/omo/skills/ulw-loop/SKILL.md
@@ -21,10 +21,11 @@ This Codex skill is intentionally compact to avoid adding a large operating manu
- Use the ulw-loop CLI state under `.omo/ulw-loop`; do not hand-edit goal state.
- After any compaction or context loss, re-read brief + goals + ledger FIRST (`omo sparkshell cat .omo/ulw-loop/ledger.jsonl` or read directly) plus `omo ulw-loop status --json`, then resume; never re-plan from scratch.
+- If `omo ulw-loop create-goals` says the existing aggregate is already complete, start unrelated new work with a fresh `--session-id <new-id>` instead of steering or forcing the completed default state. Use `--force` only to intentionally overwrite completed evidence.
- Every success criterion needs observable evidence from a real channel: tmux, HTTP, browser, or computer-use.
- Record evidence through the CLI only after cleanup receipts are available.
- Delegate code edits, test writes, fixes, and QA execution to right-sized Codex subagents when the workflow requires it.
-- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; role selection requires `agent_type`, while `model` + `reasoning_effort` alone creates a default agent, not a reviewer or worker; prefer `fork_turns: "none"` unless full history is truly required.
+- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`; put role and specialty instructions inside `message` because the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`; prefer `fork_turns: "none"` unless full history is truly required.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
- While any child is active, keep the parent visibly alive with brief status updates that include active subagent count, agent names, latest `WORKING:` phase, and whether the parent is waiting for mailbox updates.
@@ -38,10 +39,10 @@ The full workflow may mention OpenCode-style orchestration examples. In Codex, t
| Workflow intent | Codex tool |
| --- | --- |
-| Plan agent | `spawn_agent(agent_type="plan", fork_turns="none", ...)` |
-| Search/read-only worker | `spawn_agent(agent_type="explorer", fork_turns="none", ...)` |
-| Implementation or QA worker | `spawn_agent(agent_type="worker", fork_turns="none", ...)` |
-| Final verification reviewer | `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)` |
+| Plan agent | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| Search/read-only worker | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| Implementation or QA worker | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
+| Final verification reviewer | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
| Wait for background result | `wait_agent(...)` |
| Clean up finished worker | `close_agent(...)` |
diff --git a/plugins/omo/skills/ulw-loop/references/full-workflow.md b/plugins/omo/skills/ulw-loop/references/full-workflow.md
index f637e8be..645f9c15 100644
--- a/plugins/omo/skills/ulw-loop/references/full-workflow.md
+++ b/plugins/omo/skills/ulw-loop/references/full-workflow.md
@@ -28,19 +28,19 @@ Auxiliary surfaces (pure CLI stdout / DB state diff / parsed config dump) satisf
## Delegation model (ATLAS-STYLE — YOU CONDUCT, WORKERS PLAY)
You read, search, plan, integrate, and QA. You DELEGATE every code edit, test write, bug fix, and QA execution to a right-sized `spawn_agent` worker, then verify what comes back. Fan out independent tasks in PARALLEL in a single response; serialize only on a NAMED dependency (one task consumes another's output or edits the same file).
-Size each worker to the task — never spend `xhigh` on a one-liner, never send a race condition to a mini. Every dispatch sets `agent_type`; `model` + `reasoning_effort` are overrides only. Setting them alone creates a default agent, not a reviewer or worker.
+Size each worker to the task. Put the intended role, rigor level, and specialty inside the worker `message`; the Codex `spawn_agent` schema only accepts `task_name`, `message`, and `fork_turns`.
-| Task shape | agent_type | model | reasoning_effort |
-|---|---|---|---|
-| Trivial / mechanical (rename, move, obvious one-liner, config edit) | `worker` | `gpt-5.4-mini` | `low` |
-| Pure implementation against a clear spec (new function, endpoint, test from a named pattern) | `worker` | `gpt-5.5` | `high` |
-| Deep debugging / race / perf / subtle cross-module reasoning | `worker` | `gpt-5.5` | `xhigh` |
-| QA execution (drive a channel, capture evidence) | `worker` | `gpt-5.5` | `high` |
-| Read-only codebase search | `explorer` | role default | role default |
-| External library / docs research | `librarian` | role default | role default |
-| Final verification audit | `codex-ultrawork-reviewer` | role default | role default |
+| Task shape | Message instruction |
+|---|---|
+| Trivial / mechanical (rename, move, obvious one-liner, config edit) | `TASK: act as a focused worker for a trivial mechanical edit. ...` |
+| Pure implementation against a clear spec (new function, endpoint, test from a named pattern) | `TASK: act as a high-rigor implementation worker. ...` |
+| Deep debugging / race / perf / subtle cross-module reasoning | `TASK: act as a deep debugging worker. ...` |
+| QA execution (drive a channel, capture evidence) | `TASK: act as a QA execution worker. ...` |
+| Read-only codebase search | `TASK: act as an explorer. ...` |
+| External library / docs research | `TASK: act as a librarian. ...` |
+| Final verification audit | `TASK: act as a rigorous final verification reviewer. ...` |
-If `codex-ultrawork-reviewer` is unavailable, use `agent_type="worker"` with a self-contained reviewer assignment, tight scope, and explicit verification. Never spawn a model-only default agent for review.
+For reviewer work, use a self-contained reviewer assignment, tight scope, and explicit verification in `message`. Never spawn a context-only child for review.
Every worker message MUST carry: goal + exact files in scope; the baseline characterization test pinning current behavior when the task touches existing code, then the failing test / reproduction required before production code; constraints + project rules; the verification commands to run; the ONE Manual-QA channel and the exact evidence artifact to capture; for git-tracked edits, require `git-master` plus repository-wide and touched-path commit history inspection before commit. Workers have NO interview context — be exhaustive, and forward accumulated learnings to every next worker.
@@ -109,6 +109,10 @@ omo ulw-loop create-goals --brief "<brief>" --json
omo ulw-loop create-goals --brief-file <path> --json
cat <brief> | omo ulw-loop create-goals --from-stdin --json
```
+If the existing aggregate is already complete, do not steer or force the
+completed default state for unrelated new work. Start a fresh run with
+`omo ulw-loop create-goals --session-id <new-id> ...`; use `--force`
+only when deliberately overwriting completed evidence.
Write state through the CLI path. Do not hand-edit state files.
### 2. Refine success criteria + a Prometheus-grade QA and parallelism plan per goal
@@ -174,7 +178,7 @@ Trigger only when one goal remains and all its criteria are passing.
1. Run targeted verification for changed behavior.
2. Run `ai-slop-cleaner` on changed files. If no relevant edits exist, record a passed no-op cleaner report.
3. Rerun verification after cleanup.
-4. Judge the change size. Spawn the `codex-ultrawork-reviewer` agent (`spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)`; fall back to `agent_type="worker"` with a scoped reviewer assignment if unavailable) only when the work is large or risky (multi-file, cross-cutting, new architecture, security/data surfaces, or you are unsure it is sound); for a small, local, low-risk change, do the review yourself and record `codeReview` with `evidence` starting `UNCONDITIONAL APPROVAL` plus a one-line justification of why the change was small enough to self-review.
+4. Judge the change size. Spawn a rigorous reviewer with `spawn_agent({"task_name":"final_verification_review","message":"TASK: act as a rigorous final verification reviewer. DELIVERABLE: approve or cite blockers. SCOPE: <changed files and goal>. VERIFY: inspect diff and verification evidence.","fork_turns":"none"})` only when the work is large or risky (multi-file, cross-cutting, new architecture, security/data surfaces, or you are unsure it is sound); for a small, local, low-risk change, do the review yourself and record `codeReview` with `evidence` starting `UNCONDITIONAL APPROVAL` plus a one-line justification of why the change was small enough to self-review.
5. Clean review means `codeReview.recommendation == "APPROVE"` and `codeReview.architectStatus == "CLEAR"`.
6. If review is non-clean, run `omo ulw-loop record-review-blockers --goal-id <id> --title "<...>" --objective "<...>" --evidence "<review findings>" --codex-goal-json <snapshot> --json`.
7. If clean, checkpoint final completion:
diff --git a/plugins/omo/skills/ulw-plan/SKILL.md b/plugins/omo/skills/ulw-plan/SKILL.md
index 8e4c0027..40f3e6c0 100644
--- a/plugins/omo/skills/ulw-plan/SKILL.md
+++ b/plugins/omo/skills/ulw-plan/SKILL.md
@@ -44,7 +44,7 @@ Subagent outputs are not success or approval without independent verification.
You explore a LOT - fan out parallel read-only research before interviewing - but delegate with Codex discipline:
-- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`. Role selection requires `agent_type`; setting `model` + `reasoning_effort` alone creates a default agent, not the role you wanted. Prefer `fork_turns: "none"` unless full history is truly required.
+- Every `spawn_agent` message starts with `TASK:`, then names `DELIVERABLE`, `SCOPE`, and `VERIFY`. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`. Prefer `fork_turns: "none"` unless full history is truly required.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long reading, testing, or review passes, and `BLOCKED: <reason>` only when it cannot progress.
- While any child is active, keep yourself visibly alive with active subagent count, agent names, latest `WORKING:` phase, and whether you are waiting for mailbox updates.
@@ -55,10 +55,10 @@ You explore a LOT - fan out parallel read-only research before interviewing - bu
| Planning intent | Codex tool |
| --- | --- |
-| Internal codebase research | `spawn_agent(agent_type="explorer", fork_turns="none", ...)` |
-| External docs / library research | `spawn_agent(agent_type="librarian", fork_turns="none", ...)` |
-| Pre-plan gap analysis (after approval) | `spawn_agent(agent_type="metis", fork_turns="none", ...)` |
-| High-accuracy plan review (optional) | `spawn_agent(agent_type="momus", fork_turns="none", ...)` |
+| Internal codebase research | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| External docs / library research | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| Pre-plan gap analysis (after approval) | `spawn_agent({"task_name":"...","message":"TASK: act as a Metis gap-analysis reviewer. ...","fork_turns":"none"})` |
+| High-accuracy plan review (optional) | `spawn_agent({"task_name":"...","message":"TASK: act as a Momus plan reviewer. ...","fork_turns":"none"})` |
| Wait for a research result | `wait_agent(...)` |
| Release a finished subagent | `close_agent(...)` |
diff --git a/plugins/omo/skills/ulw-plan/references/full-workflow.md b/plugins/omo/skills/ulw-plan/references/full-workflow.md
index b7247f8a..d35d5ba2 100644
--- a/plugins/omo/skills/ulw-plan/references/full-workflow.md
+++ b/plugins/omo/skills/ulw-plan/references/full-workflow.md
@@ -22,8 +22,8 @@ Size your interview depth before diving in:
## Phase 1 - Ground (explore exhaustively BEFORE asking)
Eliminate unknowns by discovering facts, not by asking the user. Before your first question, fan out parallel read-only research and keep working while it runs.
-- `spawn_agent(agent_type="explorer", fork_turns="none", ...)` per internal aspect: existing patterns, conventions, similar implementations, naming/registration, test infrastructure. One agent per aspect.
-- `spawn_agent(agent_type="librarian", fork_turns="none", ...)` per external aspect: official docs, API contracts, recommended patterns, pitfalls.
+- `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` per internal aspect: existing patterns, conventions, similar implementations, naming/registration, test infrastructure. One agent per aspect.
+- `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` per external aspect: official docs, API contracts, recommended patterns, pitfalls.
- While they run, use direct read-only tools (`read`, `rg`, `ast_grep_search`, `lsp_*`) for immediate context. Do not idle.
### Dynamic workflow for architecture and bootstrap planning
@@ -61,7 +61,7 @@ Then **wait for the user's explicit okay** before generating the plan. No Metis,
Narrow `$start-work` bootstrap exception: if `$start-work` invoked this skill because there was no active Boulder work and no selectable plan, the user's `start work` request counts as approval to generate the plan and begin execution. Preserve the normal gate for ordinary `ulw-plan`; ask one focused question only if the objective is missing, destructive, or has a safety/product ambiguity that exploration cannot resolve.
## Phase 3 - Generate the plan (only after approval)
-1. **Metis gap analysis (mandatory):** `spawn_agent(agent_type="metis", fork_turns="none", message="TASK: review this planning session for gaps. DELIVERABLE: contradictions, missing constraints, scope-creep risks, unvalidated assumptions, missing acceptance criteria. VERIFY: each gap names a concrete fix.")`. Fold the findings in silently.
+1. **Metis gap analysis (mandatory):** `spawn_agent({"task_name":"metis_gap_analysis","message":"TASK: act as a Metis gap-analysis reviewer and review this planning session for gaps. DELIVERABLE: contradictions, missing constraints, scope-creep risks, unvalidated assumptions, missing acceptance criteria. VERIFY: each gap names a concrete fix.","fork_turns":"none"})`. Fold the findings in silently.
2. Write ONE plan to `.omo/plans/<slug>.md` using the template below. No "Phase 1 plan / Phase 2 plan" splits; 50+ todos is fine. Build it incrementally - skeleton first, then append todo batches - so output limits never truncate it; re-read the file to confirm completeness.
3. **Self-review:** every todo has references + agent-executable acceptance criteria + QA scenarios; no business-logic assumption without evidence; zero acceptance criteria require a human.
@@ -116,10 +116,10 @@ Critical path: ...
```
## Phase 4 - High-accuracy review (optional)
-If the user wants maximum rigor, `spawn_agent(agent_type="momus", fork_turns="none", message=".omo/plans/<slug>.md")` and pass ONLY the plan path. Fix every cited issue and resubmit until it approves.
+If the user wants maximum rigor, call `spawn_agent({"task_name":"momus_plan_review","message":"TASK: act as a Momus plan reviewer. DELIVERABLE: review .omo/plans/<slug>.md only. VERIFY: cite every required fix or approve.","fork_turns":"none"})` and pass ONLY the plan path in `message`. Fix every cited issue and resubmit until it approves.
## Delegation discipline (Codex)
-- Every `spawn_agent` message starts with `TASK:`, then `DELIVERABLE`, `SCOPE`, `VERIFY`. `agent_type` selects the role; `model` + `reasoning_effort` alone creates a default agent, not that role. Prefer `fork_turns: "none"`.
+- Every `spawn_agent` message starts with `TASK:`, then `DELIVERABLE`, `SCOPE`, `VERIFY`. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`. Prefer `fork_turns: "none"`.
- Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles. Never use a single long blocking wait for them.
- For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops.
- Keep yourself visibly alive while children run: active subagent count, agent names, latest `WORKING:` phase, and whether you are waiting on mailbox updates.
diff --git a/plugins/omo/skills/visual-qa/SKILL.md b/plugins/omo/skills/visual-qa/SKILL.md
index 50e03879..c0340d3e 100644
--- a/plugins/omo/skills/visual-qa/SKILL.md
+++ b/plugins/omo/skills/visual-qa/SKILL.md
@@ -9,15 +9,15 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
| OpenCode example | Codex tool to use |
| --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...", fork_turns="none")` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...", fork_turns="none")` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...", fork_turns="none")` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...", fork_turns="none")` |
+| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
+| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
+| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
+| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
-Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
@@ -28,7 +28,7 @@ Verify a rendered UI against intent using objective script evidence plus two par
## Purpose and when to use
- Use after you build or change any UI, before calling it done. Covers web/page UIs and TUI/terminal UIs.
-- Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip or misalign; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
+- Use when output must match a mock, a baseline, or a stated design intent; when you suspect a regression; when CJK (Korean/Japanese/Chinese) text may clip, misalign, or wrap awkwardly; when a claimed design system might actually be a flat image; when a terminal layout may overflow or its borders may break.
- Skip when there is no rendered surface (pure backend or library logic with no visual or terminal output). For broad post-implementation review use review-work; this skill is the visual specialist.
In the commands below, `$SKILL_DIR` is this skill's own directory (the folder containing this SKILL.md). The bundled script lives at `scripts/cli.ts` inside it.
@@ -73,11 +73,11 @@ Key fields: `maxWidth`, `overflowLines[]`, `borderMisaligned`, `wideCharColumns[
This JSON (diff ratio, similarity score, hotspots or overflow lines, border alignment, wide-char columns, alpha) is REFERENCE evidence to aim the reviewers. It is not the verdict by itself.
-## Step 3 - Dispatch two read-only QA passes in parallel
+## Step 3 - Dispatch two read-only QA subagents in parallel
-Send BOTH task calls in a single message so they run concurrently. Each oracle is read-only: it reviews and reports, it cannot modify files. Each returns PASS, REVISE, or FAIL with concrete, located findings.
+Send BOTH task calls in a single message so they run concurrently. Each oracle is read-only: it reviews and reports, it cannot modify files. Each returns PASS, REVISE, or FAIL with concrete, located findings. Pass A proves the surface is a real design-system implementation, not a mock-only or faked-image substitute. Pass B directly opens screenshots and inspects source/content for visual and CJK defects.
-Paste evidence directly into each prompt, because the oracle works only from the prompt text: source code, the plain-text TUI captures, the script JSON, and the screenshot paths plus your described observations for web. The two passes differ in depth by charter, not by any model or effort setting, which cannot be pinned per call.
+Paste evidence directly into each prompt: source code, the plain-text TUI captures, the script JSON, and the screenshot paths plus your described observations for web. The two passes differ in depth by charter, not by any model or effort setting, which cannot be pinned per call.
### Pass A - Design-system and functional integrity (deeper, strict)
@@ -88,7 +88,7 @@ task(subagent_type="oracle",
description="Visual QA pass A: design-system and functional integrity",
prompt="""
REVIEW TYPE: DESIGN-SYSTEM AND FUNCTIONAL INTEGRITY (read-only)
-TIER INTENT: Treat this as the deeper, stricter pass. Reason exhaustively before concluding. Assume a plausible-looking surface may be faked until the source proves otherwise.
+TIER INTENT: Treat this as the deeper, stricter pass. Reason exhaustively before concluding. Assume a plausible-looking surface may be faked or mock-only until the source proves otherwise.
INTENT:
{What the user asked for, the mock or baseline, and the constraints.}
@@ -105,7 +105,7 @@ SHARED SCRIPT EVIDENCE (reference, not verdict):
{Paste the image-diff or tui-check JSON. Use alphaChannelIntact for the transparency check.}
CHECK EACH:
-1. Real design system vs ad-hoc: are styles driven by coherent design tokens and reused primitives, or one-off hardcoded values scattered per element?
+1. Real design system vs ad-hoc/mock-only: are styles driven by coherent design tokens and reused primitives, or one-off hardcoded values scattered per element? Treat mock-only screens, static compositions, or one-page hardcoded styling with no reusable system as BLOCKING unless the user explicitly requested a throwaway mock.
2. Faked-with-an-image anti-pattern: is the UI a real DOM/component tree, or a pasted raster/screenshot or background-image standing in for live elements? For TUI: a real layout that reflows, or hardcoded pre-rendered text at fixed widths?
3. Alpha and transparency: handled correctly, with no unexpected opaque or black fills and correct PNG/CSS alpha? Cross-check alphaChannelIntact.
4. Code style and implementation quality.
@@ -132,7 +132,7 @@ task(subagent_type="oracle",
description="Visual QA pass B: visual fidelity and CJK precision",
prompt="""
REVIEW TYPE: VISUAL FIDELITY AND CJK PRECISION (read-only)
-TIER INTENT: Treat this as the focused visual pass. Anchor every claim to the script evidence and the captures.
+TIER INTENT: Treat this as the focused visual pass. Directly open the screenshots with the available image-viewing tool (`view_image`, `look_at`, or browser inspection) before judging. Anchor every claim to the script evidence, source code, and captures.
INTENT:
{What the user requested and the mock or baseline to match.}
@@ -142,17 +142,20 @@ SURFACE: {web | tui | both}
CAPTURES:
{Web: actual and reference screenshot paths plus your described observations. TUI: paste capture.txt and capture-ansi.txt inline.}
+SOURCE CODE:
+{For web: include the rendered text/content, components, typography, layout, and style code. For TUI: include render code that controls wrapping, width, and wide-character handling.}
+
SCRIPT EVIDENCE (required, consume every field):
{Paste the image-diff or tui-check JSON.}
USE THE EVIDENCE:
-- Web (image-diff): start from diffRatio and similarityScore, then open every hotspots[] entry (gridX, gridY, x, y, width, height, diffRatio) and explain the visual cause of each flagged region.
+- Web (image-diff): start from diffRatio and similarityScore, then directly open every screenshot path and inspect every hotspots[] entry (gridX, gridY, x, y, width, height, diffRatio). Explain the visual cause of each flagged region from the pixels and source/content together.
- TUI (tui-check): inspect maxWidth vs expectedColumns, every overflowLines[] entry, borderMisaligned, and wideCharColumns[].
CHECK:
1. Does the rendered output match what the user requested: layout, spacing, color, type, alignment?
2. CJK precision:
- - Web: baseline/descender clipping, dropped glyphs (tofu), broken line-breaking, mismatched font metrics between reference and actual.
+ - Web: natural CJK line breaking for display and body text. Flag oversized headings that create orphaned one-character or final-syllable lines, split Korean/Japanese/Chinese semantic phrases unnaturally, detach labels such as `[Image #1]` from their content, clip baselines/descenders, drop glyphs (tofu), or show font metric mismatch. Treat the screenshot pattern `에이전트 오케스트 / 레이션 현황 및 미 / 래` as REVISE/FAIL, not acceptable wrapping.
- TUI: wide-character column drift (CJK cells counted as 1 instead of 2), box-drawing border misalignment, content overflowing past the terminal width.
OUTPUT:
diff --git a/plugins/omo/skills/visual-qa/scripts/ansi.test.ts b/plugins/omo/skills/visual-qa/scripts/ansi.test.ts
deleted file mode 100644
index f3763a57..00000000
--- a/plugins/omo/skills/visual-qa/scripts/ansi.test.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import { hasAnsi, stripAnsi } from "./ansi"
-
-const ESC = String.fromCharCode(0x1b)
-
-describe("stripAnsi", () => {
- test("#given an ANSI-wrapped string #when stripped #then escape codes are removed", () => {
- // given
- const input = `${ESC}[31mred${ESC}[0m`
- // when
- const stripped = stripAnsi(input)
- // then
- expect(stripped).toBe("red")
- })
-
- test("#given a plain string #when stripped #then it is unchanged", () => {
- // given
- const input = "plain text"
- // when
- const stripped = stripAnsi(input)
- // then
- expect(stripped).toBe("plain text")
- })
-})
-
-describe("hasAnsi", () => {
- test("#given a string with ANSI codes #when checked #then it is true", () => {
- // given
- const input = `${ESC}[1mbold${ESC}[0m`
- // when
- const detected = hasAnsi(input)
- // then
- expect(detected).toBe(true)
- })
-
- test("#given a plain string #when checked #then it is false", () => {
- // given
- const input = "no ansi here"
- // when
- const detected = hasAnsi(input)
- // then
- expect(detected).toBe(false)
- })
-})
diff --git a/plugins/omo/skills/visual-qa/scripts/cli.test.ts b/plugins/omo/skills/visual-qa/scripts/cli.test.ts
deleted file mode 100644
index 35d7f707..00000000
--- a/plugins/omo/skills/visual-qa/scripts/cli.test.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { mkdtempSync, writeFileSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-
-import { run, runImageDiff, runTuiCheck } from "./cli"
-import { encodeRgbaPng, solidRgba } from "./png-synth"
-
-function tempDir(): string {
- return mkdtempSync(join(tmpdir(), "visual-qa-"))
-}
-
-describe("runImageDiff", () => {
- test("#given two identical PNG files #when diffed #then similarity is 100", () => {
- // given
- const dir = tempDir()
- const reference = join(dir, "reference.png")
- const actual = join(dir, "actual.png")
- writeFileSync(reference, encodeRgbaPng(2, 2, solidRgba(2, 2, [1, 2, 3, 255])))
- writeFileSync(actual, encodeRgbaPng(2, 2, solidRgba(2, 2, [1, 2, 3, 255])))
- // when
- const result = runImageDiff([reference, actual])
- // then
- expect(result.command).toBe("image-diff")
- expect(result.similarityScore).toBe(100)
- expect(result.dimensionsMatch).toBe(true)
- })
-
- test("#given missing arguments #when diffed #then it throws a usage error", () => {
- // given / when / then
- expect(() => runImageDiff([])).toThrow("usage")
- })
-})
-
-describe("runTuiCheck", () => {
- test("#given a CJK capture file #when checked #then widths count wide characters", () => {
- // given
- const dir = tempDir()
- const file = join(dir, "capture.txt")
- writeFileSync(file, "가나\nhello")
- // when
- const result = runTuiCheck([file, "--cols", "40"])
- // then
- expect(result.command).toBe("tui-check")
- expect(result.expectedColumns).toBe(40)
- expect(result.lineWidths).toEqual([4, 5])
- })
-})
-
-describe("run dispatch", () => {
- test("#given an unknown command #when run #then it throws", () => {
- // given / when / then
- expect(() => run(["bogus"])).toThrow("unknown command")
- })
-})
-
-describe("cli entry", () => {
- test("#given the cli is spawned for image-diff #when it runs #then it prints JSON and exits zero", () => {
- // given
- const dir = tempDir()
- const reference = join(dir, "reference.png")
- const actual = join(dir, "actual.png")
- writeFileSync(reference, encodeRgbaPng(2, 2, solidRgba(2, 2, [0, 0, 0, 255])))
- writeFileSync(actual, encodeRgbaPng(2, 2, solidRgba(2, 2, [255, 255, 255, 255])))
- // when
- const proc = Bun.spawnSync(["bun", join(import.meta.dir, "cli.ts"), "image-diff", reference, actual])
- // then
- expect(proc.exitCode).toBe(0)
- const parsed: Record<string, unknown> = JSON.parse(proc.stdout.toString())
- expect(parsed["command"]).toBe("image-diff")
- expect(parsed["similarityScore"]).toBe(0)
- })
-})
diff --git a/plugins/omo/skills/visual-qa/scripts/east-asian-width.test.ts b/plugins/omo/skills/visual-qa/scripts/east-asian-width.test.ts
deleted file mode 100644
index cf342acc..00000000
--- a/plugins/omo/skills/visual-qa/scripts/east-asian-width.test.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import { charWidth, stringWidth } from "./east-asian-width"
-
-describe("charWidth", () => {
- test("#given an ASCII letter #when measured #then it is one column", () => {
- // given / when / then
- expect(charWidth(0x61)).toBe(1)
- })
-
- test("#given a Hangul syllable #when measured #then it is two columns", () => {
- expect(charWidth(0xac00)).toBe(2)
- })
-
- test("#given a CJK ideograph #when measured #then it is two columns", () => {
- expect(charWidth(0x4e00)).toBe(2)
- })
-
- test("#given a fullwidth Latin letter #when measured #then it is two columns", () => {
- expect(charWidth(0xff21)).toBe(2)
- })
-
- test("#given a halfwidth katakana #when measured #then it is one column", () => {
- expect(charWidth(0xff71)).toBe(1)
- })
-
- test("#given a combining diacritic #when measured #then it is zero columns", () => {
- expect(charWidth(0x0301)).toBe(0)
- })
-
- test("#given a zero-width space #when measured #then it is zero columns", () => {
- expect(charWidth(0x200b)).toBe(0)
- })
-
- test("#given an emoji #when measured #then it is two columns", () => {
- expect(charWidth(0x1f600)).toBe(2)
- })
-})
-
-describe("stringWidth", () => {
- test("#given an ASCII string #when measured #then width equals character count", () => {
- expect(stringWidth("hello")).toBe(5)
- })
-
- test("#given Hangul text #when measured #then each syllable counts as two", () => {
- expect(stringWidth("가나다")).toBe(6)
- })
-
- test("#given CJK text #when measured #then each ideograph counts as two", () => {
- expect(stringWidth("日本語")).toBe(6)
- })
-
- test("#given a base letter plus a combining mark #when measured #then it is one column", () => {
- expect(stringWidth("e\u0301")).toBe(1)
- })
-
- test("#given mixed ASCII and CJK #when measured #then widths add up", () => {
- expect(stringWidth("AB가")).toBe(4)
- })
-})
diff --git a/plugins/omo/skills/visual-qa/scripts/image-diff.test.ts b/plugins/omo/skills/visual-qa/scripts/image-diff.test.ts
deleted file mode 100644
index 0735df52..00000000
--- a/plugins/omo/skills/visual-qa/scripts/image-diff.test.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import { diffImages } from "./image-diff"
-import { solidRgba } from "./png-synth"
-import type { DecodedImage } from "./types"
-
-function makeImage(width: number, height: number, rgba: Uint8Array, transparent = false): DecodedImage {
- return { width, height, rgba, hasAlphaChannel: true, hasTransparentPixels: transparent }
-}
-
-describe("diffImages", () => {
- test("#given two identical images #when diffed #then similarity is 100 with no hotspots", () => {
- // given
- const ref = makeImage(4, 4, solidRgba(4, 4, [10, 20, 30, 255]))
- const act = makeImage(4, 4, solidRgba(4, 4, [10, 20, 30, 255]))
- // when
- const result = diffImages(ref, act)
- // then
- expect(result.diffPixels).toBe(0)
- expect(result.similarityScore).toBe(100)
- expect(result.hotspots.length).toBe(0)
- expect(result.dimensionsMatch).toBe(true)
- })
-
- test("#given two fully different images #when diffed #then similarity is 0 with hotspots", () => {
- // given
- const ref = makeImage(4, 4, solidRgba(4, 4, [0, 0, 0, 255]))
- const act = makeImage(4, 4, solidRgba(4, 4, [255, 255, 255, 255]))
- // when
- const result = diffImages(ref, act)
- // then
- expect(result.diffPixels).toBe(16)
- expect(result.similarityScore).toBe(0)
- expect(result.hotspots.length).toBeGreaterThan(0)
- })
-
- test("#given images of different sizes #when diffed #then dimensionsMatch is false", () => {
- // given
- const ref = makeImage(4, 4, solidRgba(4, 4, [0, 0, 0, 255]))
- const act = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 255]))
- // when
- const result = diffImages(ref, act)
- // then
- expect(result.dimensionsMatch).toBe(false)
- })
-
- test("#given a transparent reference and an opaque actual #when diffed #then alpha is flagged", () => {
- // given
- const ref = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 128]), true)
- const act = makeImage(2, 2, solidRgba(2, 2, [0, 0, 0, 255]), false)
- // when
- const result = diffImages(ref, act)
- // then
- expect(result.alphaChannelIntact).toBe(false)
- })
-
- test("#given a single changed pixel #when diffed #then one hotspot marks its grid cell", () => {
- // given
- const base = solidRgba(8, 8, [0, 0, 0, 255])
- const changed = solidRgba(8, 8, [0, 0, 0, 255])
- changed[0] = 255
- // when
- const result = diffImages(makeImage(8, 8, base), makeImage(8, 8, changed))
- // then
- expect(result.diffPixels).toBe(1)
- expect(result.hotspots.length).toBe(1)
- expect(result.hotspots[0]?.gridX).toBe(0)
- expect(result.hotspots[0]?.gridY).toBe(0)
- })
-})
diff --git a/plugins/omo/skills/visual-qa/scripts/png-decode.test.ts b/plugins/omo/skills/visual-qa/scripts/png-decode.test.ts
deleted file mode 100644
index 733ca373..00000000
--- a/plugins/omo/skills/visual-qa/scripts/png-decode.test.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { Buffer } from "node:buffer"
-
-import { decodePng } from "./png-decode"
-import { encodeRgbaPng, solidRgba } from "./png-synth"
-
-describe("decodePng", () => {
- test("#given an encoded RGBA image #when decoded #then dimensions and first pixel round-trip", () => {
- // given
- const png = encodeRgbaPng(3, 2, solidRgba(3, 2, [10, 20, 30, 255]))
- // when
- const decoded = decodePng(png)
- // then
- expect(decoded.width).toBe(3)
- expect(decoded.height).toBe(2)
- expect(Array.from(decoded.rgba.subarray(0, 4))).toEqual([10, 20, 30, 255])
- })
-
- test("#given a fully opaque image #when decoded #then it has no transparent pixels", () => {
- // given
- const png = encodeRgbaPng(2, 2, solidRgba(2, 2, [0, 0, 0, 255]))
- // when
- const decoded = decodePng(png)
- // then
- expect(decoded.hasAlphaChannel).toBe(true)
- expect(decoded.hasTransparentPixels).toBe(false)
- })
-
- test("#given a semi-transparent image #when decoded #then it reports transparent pixels", () => {
- // given
- const png = encodeRgbaPng(2, 2, solidRgba(2, 2, [255, 255, 255, 128]))
- // when
- const decoded = decodePng(png)
- // then
- expect(decoded.hasTransparentPixels).toBe(true)
- })
-
- test("#given a non-PNG buffer #when decoded #then it throws", () => {
- // given
- const notPng = Buffer.from("this is not a png file")
- // when / then
- expect(() => decodePng(notPng)).toThrow("not a PNG")
- })
-})
diff --git a/plugins/omo/skills/visual-qa/scripts/tui-grid.test.ts b/plugins/omo/skills/visual-qa/scripts/tui-grid.test.ts
deleted file mode 100644
index 77ca8f3b..00000000
--- a/plugins/omo/skills/visual-qa/scripts/tui-grid.test.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import { checkTui } from "./tui-grid"
-
-const ESC = String.fromCharCode(0x1b)
-
-describe("checkTui", () => {
- test("#given ASCII lines within the width #when checked #then there is no overflow", () => {
- // given / when
- const result = checkTui("hello\nworld", 80)
- // then
- expect(result.lineCount).toBe(2)
- expect(result.lineWidths).toEqual([5, 5])
- expect(result.maxWidth).toBe(5)
- expect(result.overflowLines.length).toBe(0)
- expect(result.hasAnsi).toBe(false)
- })
-
- test("#given a line wider than the expected columns #when checked #then it is flagged as overflow", () => {
- // given / when
- const result = checkTui("short\nthis line is definitely too long", 10)
- // then
- expect(result.overflowLines.length).toBe(1)
- expect(result.overflowLines[0]?.line).toBe(2)
- expect(result.maxWidth).toBeGreaterThan(10)
- })
-
- test("#given CJK text #when checked #then wide characters count as two columns", () => {
- // given / when
- const result = checkTui("가나다", 80)
- // then
- expect(result.lineWidths).toEqual([6])
- expect(result.wideCharColumns).toEqual([0, 2, 4])
- })
-
- test("#given a box whose CJK content is wider than its border #when checked #then borders are misaligned", () => {
- // given / when
- const result = checkTui("┌──┐\n│가가│\n└──┘", 80)
- // then
- expect(result.borderMisaligned).toBe(true)
- })
-
- test("#given a well-formed box #when checked #then borders are aligned", () => {
- // given / when
- const result = checkTui("┌──┐\n│ab│\n└──┘", 80)
- // then
- expect(result.borderMisaligned).toBe(false)
- })
-
- test("#given text with ANSI color codes #when checked #then ANSI is detected and ignored for width", () => {
- // given / when
- const result = checkTui(`${ESC}[31mred${ESC}[0m`, 80)
- // then
- expect(result.hasAnsi).toBe(true)
- expect(result.lineWidths).toEqual([3])
- })
-})
diff --git a/plugins/omo/test/aggregate-agents.test.mjs b/plugins/omo/test/aggregate-agents.test.mjs
index 82e98845..1aadd26b 100644
--- a/plugins/omo/test/aggregate-agents.test.mjs
+++ b/plugins/omo/test/aggregate-agents.test.mjs
@@ -41,14 +41,15 @@ test("#given planner agent prompt #when inspected #then generated artifacts stay
assert.doesNotMatch(prompt, /(?<!\.omo\/)evidence\/task-/);
});
-test("#given reviewer agent prompt #when inspected #then default model is ChatGPT-account compatible", async () => {
+test("#given reviewer agent prompt #when inspected #then default model uses bounded reasoning", async () => {
const prompt = await readFile(
join(root, "components", "ultrawork", "agents", "codex-ultrawork-reviewer.toml"),
"utf8",
);
assert.match(prompt, /^model\s*=\s*"gpt-5\.5"$/m);
- assert.match(prompt, /^model_reasoning_effort\s*=\s*"xhigh"$/m);
+ assert.match(prompt, /^model_reasoning_effort\s*=\s*"high"$/m);
+ assert.doesNotMatch(prompt, /^model_reasoning_effort\s*=\s*"xhigh"$/m);
assert.doesNotMatch(prompt, /^model\s*=\s*"gpt-5\.2"$/m);
assert.match(prompt, /ChatGPT account/);
});
diff --git a/plugins/omo/test/aggregate-build.test.mjs b/plugins/omo/test/aggregate-build.test.mjs
index c6e9d476..e2c7b428 100644
--- a/plugins/omo/test/aggregate-build.test.mjs
+++ b/plugins/omo/test/aggregate-build.test.mjs
@@ -7,18 +7,23 @@ import { readJson, root } from "./aggregate-plugin-fixture.mjs";
test("#given aggregate plugin build script #when inspected #then hook status and telemetry sync run before workspace builds", async () => {
// given
+ const packageText = await readFile(join(root, "package.json"), "utf8");
const packageJson = await readJson("package.json");
const telemetrySyncScript = await readFile(join(root, "..", "scripts", "sync-telemetry-component.mjs"), "utf8");
// when
const buildScript = packageJson.scripts.build;
+ const testScript = packageJson.scripts.test;
// then
assert.equal(
buildScript,
"node scripts/sync-hook-status-messages.mjs && node scripts/build-bundled-mcp-runtimes.mjs && node scripts/sync-skills.mjs && node ../scripts/sync-telemetry-component.mjs && node scripts/build-components.mjs",
);
+ assert.equal(testScript, "node --test test/*.test.mjs");
+ assert(packageJson.workspaces.includes("components/ultrawork"));
assert.match(telemetrySyncScript, /syncTelemetryComponent/);
+ assert.doesNotMatch(packageText, /\bpython3?\b|ultrawork-detector\.py/);
});
test("#given omo-codex package build script #when inspected #then delegates to the aggregate plugin package", async () => {
diff --git a/plugins/omo/test/aggregate-hooks.test.mjs b/plugins/omo/test/aggregate-hooks.test.mjs
index f508ed92..e9ad3f2d 100644
--- a/plugins/omo/test/aggregate-hooks.test.mjs
+++ b/plugins/omo/test/aggregate-hooks.test.mjs
@@ -1,4 +1,6 @@
import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
import test from "node:test";
import {
@@ -8,6 +10,7 @@ import {
readComponentHookManifests,
readJson,
readPluginVersion,
+ root,
} from "./aggregate-plugin-fixture.mjs";
test("#given isolated components #when hooks are inspected #then commands stay inside component roots", async () => {
@@ -66,6 +69,20 @@ test("#given aggregate hook commands #when inspected #then every command exposes
assert.deepEqual(missingStatusMessages, []);
});
+test("#given aggregate hook commands #when inspected #then commands stay Node-based and platform-neutral", async () => {
+ // given
+ const hooks = await readJson("hooks/hooks.json");
+
+ // when
+ const commands = collectCommandHooks(hooks, "hooks/hooks.json").map(({ handler }) => handler.command);
+
+ // then
+ assert(!commands.some((command) => /\bpython3?\b/i.test(command)));
+ assert(commands.includes('node "${PLUGIN_ROOT}/components/ultrawork/dist/cli.js" hook user-prompt-submit'));
+ assert(commands.every((command) => command.startsWith("node ")));
+ assert(commands.every((command) => !command.includes("\\")));
+});
+
test("#given component hook commands #when inspected #then standalone packages expose Codex status messages", async () => {
// given
const componentHooks = await readComponentHookManifests();
@@ -133,3 +150,15 @@ test("#given aggregate SessionStart hooks #when inspected #then LazyCodex auto-u
assert.match(text, /Checking Auto Update/);
assert(sessionStartCommands.some((command) => command.includes("scripts/auto-update.mjs")));
});
+
+test("#given aggregate plugin packaging #when inspected #then hooks and compatibility sentinels stay Python-free", async () => {
+ // given
+ const hooksText = await readFile(join(root, "hooks/hooks.json"), "utf8");
+ const aggregateTestText = await readFile(join(root, "test/aggregate.test.mjs"), "utf8");
+
+ // when
+ const aggregateText = `${hooksText}\n${aggregateTestText}`;
+
+ // then
+ assert.doesNotMatch(aggregateText, /\bpython3?\b|ultrawork-detector\.py/);
+});
diff --git a/plugins/omo/test/aggregate-model-catalog.test.mjs b/plugins/omo/test/aggregate-model-catalog.test.mjs
index d1f34e4b..4efee8a8 100644
--- a/plugins/omo/test/aggregate-model-catalog.test.mjs
+++ b/plugins/omo/test/aggregate-model-catalog.test.mjs
@@ -15,7 +15,7 @@ test("#given bundled model catalog #when inspected #then default verifier and wo
assert.deepEqual(catalog.roles.default, catalog.current);
assert.deepEqual(catalog.roles.verifier, {
model: "gpt-5.5",
- model_reasoning_effort: "xhigh",
+ model_reasoning_effort: "high",
});
assert.deepEqual(catalog.roles.worker, {
model: "gpt-5.5",
diff --git a/plugins/omo/test/aggregate-plugin-fixture.mjs b/plugins/omo/test/aggregate-plugin-fixture.mjs
index 7e05aec0..43b01838 100644
--- a/plugins/omo/test/aggregate-plugin-fixture.mjs
+++ b/plugins/omo/test/aggregate-plugin-fixture.mjs
@@ -66,21 +66,16 @@ export function hookLocation({ source, eventName, groupIndex, handlerIndex, hand
return `${source}:${eventName}:${groupIndex}:${handlerIndex}:${handler.command}`;
}
-export function findSpawnAgentTypes(content) {
- const agentTypes = new Set();
- const regex = /spawn_agent\(agent_type="([^"]+)"/g;
- for (const match of content.matchAll(regex)) {
- agentTypes.add(match[1]);
- }
- return [...agentTypes].sort();
+export function findInvalidSpawnAgentRoleParameters(content) {
+ return [...content.matchAll(/spawn_agent\([^)\n]*(?:agent_type|model|reasoning_effort)\s*=/g)].map((match) => match[0]);
}
-export function findRoleSpecificSpawnsWithoutForkTurnsNone(content) {
+export function findSpawnAgentCallsWithoutForkTurnsNone(content) {
const missingForkTurns = [];
- const regex = /spawn_agent\(agent_type="([^"]+)"[^)]*\)/g;
+ const regex = /spawn_agent\(([^)]*)\)/g;
for (const match of content.matchAll(regex)) {
const call = match[0];
- if (!call.includes('fork_turns="none"')) {
+ if (!/"fork_turns"\s*:\s*"none"|fork_turns:\s*"none"|fork_turns="none"/.test(call)) {
missingForkTurns.push(call);
}
}
diff --git a/plugins/omo/test/aggregate-skills.test.mjs b/plugins/omo/test/aggregate-skills.test.mjs
index 00b65be4..46436f2a 100644
--- a/plugins/omo/test/aggregate-skills.test.mjs
+++ b/plugins/omo/test/aggregate-skills.test.mjs
@@ -4,38 +4,27 @@ import { basename, dirname, join } from "node:path";
import test from "node:test";
import {
- findRoleSpecificSpawnsWithoutForkTurnsNone,
- findSpawnAgentTypes,
+ findInvalidSpawnAgentRoleParameters,
+ findSpawnAgentCallsWithoutForkTurnsNone,
root,
} from "./aggregate-plugin-fixture.mjs";
-test("#given synced skills with Codex compatibility guidance #when a bundled agent_type is referenced #then a matching TOML is bundled", async () => {
+test("#given synced skills with Codex compatibility guidance #when spawn_agent is documented #then invalid role parameters are absent", async () => {
const skillsDir = join(root, "skills");
const skillEntries = await readdir(skillsDir, { withFileTypes: true });
const skillFiles = skillEntries
.filter((entry) => entry.isDirectory())
.map((entry) => join(skillsDir, entry.name, "SKILL.md"));
- const referencedAgentTypes = new Set();
+ const invalidCalls = [];
for (const skillPath of skillFiles) {
const content = await readFile(skillPath, "utf8");
- for (const agentType of findSpawnAgentTypes(content)) {
- if (agentType === "worker" || agentType === "codex-ultrawork-reviewer") {
- continue;
- }
- referencedAgentTypes.add(agentType);
+ for (const call of findInvalidSpawnAgentRoleParameters(content)) {
+ invalidCalls.push(`${basename(dirname(skillPath))}/${basename(skillPath)}: ${call}`);
}
}
- const expected = [...referencedAgentTypes].sort();
- assert.deepEqual(expected, ["explorer", "librarian", "metis", "momus", "plan"]);
-
- for (const agentType of expected) {
- const tomlPath = join(root, "components", "ultrawork", "agents", `${agentType}.toml`);
- const fileStat = await stat(tomlPath);
- assert.equal(fileStat.isFile(), true);
- assert.equal(basename(tomlPath), `${agentType}.toml`);
- }
+ assert.deepEqual(invalidCalls, []);
});
test('#given synced skills and bundled rules #when role-specific agents are spawned #then they set fork_turns="none"', async () => {
@@ -49,7 +38,7 @@ test('#given synced skills and bundled rules #when role-specific agents are spaw
const missingForkTurns = [];
for (const promptPath of promptFiles) {
const content = await readFile(promptPath, "utf8");
- for (const call of findRoleSpecificSpawnsWithoutForkTurnsNone(content)) {
+ for (const call of findSpawnAgentCallsWithoutForkTurnsNone(content)) {
missingForkTurns.push(`${basename(dirname(promptPath))}/${basename(promptPath)}: ${call}`);
}
}
diff --git a/plugins/omo/test/auto-update-state-persistence.test.mjs b/plugins/omo/test/auto-update-state-persistence.test.mjs
new file mode 100644
index 00000000..591f970e
--- /dev/null
+++ b/plugins/omo/test/auto-update-state-persistence.test.mjs
@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { runAutoUpdateCheck } from "../scripts/auto-update.mjs";
+
+function autoUpdateEnv(root, extra = {}) {
+ return {
+ CODEX_HOME: join(root, "codex-home"),
+ LAZYCODEX_CURRENT_VERSION: "1.0.1",
+ LAZYCODEX_LATEST_VERSION: "1.0.1",
+ LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json"),
+ LAZYCODEX_AUTO_UPDATE_STATE_PATH: join(root, "state.json"),
+ LAZYCODEX_AUTO_UPDATE_LOG_PATH: join(root, "auto-update.log"),
+ ...extra,
+ };
+}
+
+test("#given lazycodex is up to date #when running check #then persists checked success state", async () => {
+ const root = await mkdtemp(join(tmpdir(), "lazycodex-auto-update-state-"));
+ const env = autoUpdateEnv(root);
+
+ const result = await runAutoUpdateCheck({
+ env,
+ now: 123_456,
+ });
+
+ assert.equal(result.started, false);
+ assert.equal(result.reason, "up-to-date");
+ assert.deepEqual(JSON.parse(await readFile(env.LAZYCODEX_AUTO_UPDATE_STATE_PATH, "utf8")), {
+ lastCheckedAt: 123_456,
+ lastStatus: "success",
+ });
+});
diff --git a/plugins/omo/test/component-bin-names.test.mjs b/plugins/omo/test/component-bin-names.test.mjs
index 0af913c4..1cae5f0a 100644
--- a/plugins/omo/test/component-bin-names.test.mjs
+++ b/plugins/omo/test/component-bin-names.test.mjs
@@ -13,7 +13,7 @@ const EXPECTED_COMPONENT_BINS = new Map([
["start-work-continuation", "omo-start-work-continuation"],
["telemetry", "omo-telemetry"],
["ultrawork", "omo-ultrawork"],
- ["ulw-loop", "omo"],
+ ["ulw-loop", "omo-ulw-loop"],
]);
const EXPECTED_USAGE_PREFIXES = new Map([
diff --git a/plugins/omo/test/global-review-debug-gate.test.mjs b/plugins/omo/test/global-review-debug-gate.test.mjs
new file mode 100644
index 00000000..8d95d13d
--- /dev/null
+++ b/plugins/omo/test/global-review-debug-gate.test.mjs
@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+test("#given start-work continuation directive #when inspected #then final handoff requires review and debugging gate", async () => {
+ const text = await readFile(join(pluginRoot, "components", "start-work-continuation", "directive.md"), "utf8");
+
+ assert.match(text, /Global Review and Debugging Gate/);
+ assert.match(text, /review-work/);
+ assert.match(text, /debugging/);
+ assert.match(text, /Do not print `ORCHESTRATION COMPLETE`/);
+ assert.match(text, /Do not create a PR, PR handoff, or branch handoff/);
+ assert.match(text, /redact.*secrets.*PII/s);
+});
+
+test("#given Hephaestus baseline rule #when inspected #then significant implementation and PR handoff require the same gate", async () => {
+ const text = await readFile(join(pluginRoot, "components", "rules", "bundled-rules", "hephaestus.md"), "utf8");
+
+ assert.match(text, /Global Review and Debugging Gate/);
+ assert.match(text, /significant implementation work/);
+ assert.match(text, /review-work/);
+ assert.match(text, /debugging/);
+ assert.match(text, /PR handoff/);
+ assert.match(text, /redact.*secrets.*PII/s);
+});
diff --git a/plugins/omo/test/lcx-bug-skills.test.mjs b/plugins/omo/test/lcx-bug-skills.test.mjs
new file mode 100644
index 00000000..f0edf27f
--- /dev/null
+++ b/plugins/omo/test/lcx-bug-skills.test.mjs
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+test("#given synced lcx-report-bug skill #when inspected #then it files LazyCodex bug issues with generated labels", async () => {
+ // given
+ const skillRoot = join(root, "skills", "lcx-report-bug");
+
+ // when
+ const skill = await readFile(join(skillRoot, "SKILL.md"), "utf8");
+ const interfaceMetadata = await readFile(join(skillRoot, "agents", "openai.yaml"), "utf8");
+
+ // then
+ assert.match(skill, /^---\r?\nname: lcx-report-bug\r?\n/m);
+ assert.match(skill, /code-yeongyu\/lazycodex/);
+ assert.match(skill, /openai\/codex/);
+ assert.match(skill, /\/tmp\/openai-codex-source/);
+ assert.match(skill, /\$omo:debugging/);
+ assert.match(skill, /Repository Decision/);
+ assert.match(skill, /TARGET_REPO="code-yeongyu\/lazycodex" # or openai\/codex/);
+ assert.match(skill, /LABEL_ARGS=\(\)/);
+ assert.match(skill, /gh label create lazycodex-generated.*--force/);
+ assert.match(skill, /gh issue create --repo "\$TARGET_REPO".*"\$\{LABEL_ARGS\[@\]\}"/);
+ assert.match(skill, /gh pr create --repo "\$TARGET_REPO".*"\$\{LABEL_ARGS\[@\]\}"/);
+ assert.match(skill, /lazycodex-generated/);
+ assert.match(skill, /This issue or PR was generated by LazyCodex/);
+ assert.match(skill, /Tag: lazycodex-generated/);
+ assert.match(skill, /Browser use fallback/);
+ assert.match(skill, /Computer use fallback/);
+ assert.match(skill, /## Issue Body Template/);
+ assert.match(interfaceMetadata, /display_name: "lcx-report-bug \(omo\)"/);
+ assert.match(interfaceMetadata, /- "lazycodex bug"/);
+ assert.match(interfaceMetadata, /- "openai codex bug"/);
+});
+
+test("#given synced lcx-contribute-bug-fix skill #when inspected #then it contributes LazyCodex bug-fix PRs from fresh temp workspaces", async () => {
+ // given
+ const skillRoot = join(root, "skills", "lcx-contribute-bug-fix");
+
+ // when
+ const skill = await readFile(join(skillRoot, "SKILL.md"), "utf8");
+ const interfaceMetadata = await readFile(join(skillRoot, "agents", "openai.yaml"), "utf8");
+ const script = await readFile(join(skillRoot, "scripts", "create-pr-body.mjs"), "utf8");
+
+ // then
+ assert.match(skill, /^---\r?\nname: lcx-contribute-bug-fix\r?\n/m);
+ assert.match(skill, /Contribute a verified bug-fix PR/);
+ assert.match(skill, /fresh `\/tmp` clone\/worktree/);
+ assert.match(skill, /\/tmp\/lazycodex-fix-/);
+ assert.match(skill, /git worktree add/);
+ assert.match(skill, /apply `lazycodex-generated` when label management is available/);
+ assert.match(skill, /git add -A/);
+ assert.match(skill, /git commit -m/);
+ assert.match(skill, /git log --oneline "origin\/\$BASE_BRANCH\.\.HEAD"/);
+ assert.match(skill, /gh repo fork "\$TARGET_REPO" --remote --remote-name fork/);
+ assert.match(skill, /PUSH_REMOTE/);
+ assert.match(skill, /lazycodex-generated/);
+ assert.match(skill, /LABEL_ARGS=\(\)/);
+ assert.match(skill, /gh label create lazycodex-generated.*--force/);
+ assert.match(skill, /gh pr create --repo "\$TARGET_REPO".*"\$\{LABEL_ARGS\[@\]\}"/);
+ assert.match(skill, /--head "\$PR_HEAD"/);
+ assert.doesNotMatch(skill, /a PR without the `lazycodex-generated` label/);
+ assert.match(skill, /scripts\/create-pr-body\.mjs/);
+ assert.match(skill, /## Problem Situation/);
+ assert.match(skill, /## Reproduction Logs/);
+ assert.match(skill, /## Approach/);
+ assert.match(skill, /## Why I Am Confident/);
+ assert.match(skill, /## Risks/);
+ assert.match(skill, /## User-Visible Behavior Changes/);
+ assert.match(skill, /Clean up/);
+ assert.match(interfaceMetadata, /display_name: "lcx-contribute-bug-fix \(omo\)"/);
+ assert.match(interfaceMetadata, /- "contribute a bug fix"/);
+ assert.match(interfaceMetadata, /- "fix bug pr"/);
+ assert.match(script, /createLazyCodexBugFixPrBody/);
+ assert.match(script, /Problem Situation/);
+ assert.match(script, /Why I Am Confident/);
+});
diff --git a/plugins/omo/test/lcx-contribute-bug-fix-template.test.mjs b/plugins/omo/test/lcx-contribute-bug-fix-template.test.mjs
new file mode 100644
index 00000000..24a73648
--- /dev/null
+++ b/plugins/omo/test/lcx-contribute-bug-fix-template.test.mjs
@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const scriptPath = join(root, "skills", "lcx-contribute-bug-fix", "scripts", "create-pr-body.mjs");
+
+test("#given complete bug-fix evidence #when creating a PR body #then required LazyCodex sections and label are emitted", async () => {
+ // given
+ const { createLazyCodexBugFixPrBody } = await import(`file://${scriptPath}`);
+ const input = {
+ title: "Fix Codex skill sync drift",
+ targetRepository: "code-yeongyu/lazycodex",
+ problem: "Skill sync omitted a shared skill from the aggregate plugin.",
+ reproductionLogs: "npm test -- --test-name-pattern sync-skills failed before the fix.",
+ approach: "Add the missing shared skill source and sync the aggregate plugin.",
+ confidence: "The failing sync test now passes and the aggregate skill matches the source.",
+ risks: "Low risk; this changes only packaged skill instructions.",
+ userVisibleBehaviorChanges: "Users can ask LazyCodex to contribute a bug-fix PR directly.",
+ verification: ["npm test -- --test-name-pattern lcx-contribute-bug-fix", "npm run sync:skills"],
+ };
+
+ // when
+ const body = createLazyCodexBugFixPrBody(input);
+
+ // then
+ assert.match(body, /^## Problem Situation/m);
+ assert.match(body, /## Reproduction Logs/);
+ assert.match(body, /## Approach/);
+ assert.match(body, /## Why I Am Confident/);
+ assert.match(body, /## Risks/);
+ assert.match(body, /## User-Visible Behavior Changes/);
+ assert.match(body, /## Verification/);
+ assert.match(body, /lazycodex-generated/);
+ assert.match(body, /This PR was debugged, implemented, and created with \[LazyCodex\]/);
+});
+
+test("#given missing bug-fix evidence #when creating a PR body #then the script rejects the incomplete payload", async () => {
+ // given
+ const { createLazyCodexBugFixPrBody } = await import(`file://${scriptPath}`);
+
+ // when
+ const action = () =>
+ createLazyCodexBugFixPrBody({
+ title: "Fix Codex skill sync drift",
+ targetRepository: "code-yeongyu/lazycodex",
+ problem: "Skill sync omitted a shared skill from the aggregate plugin.",
+ reproductionLogs: "",
+ approach: "Add the missing shared skill source and sync the aggregate plugin.",
+ confidence: "The failing sync test now passes.",
+ risks: "Low risk.",
+ userVisibleBehaviorChanges: "Users get a new skill.",
+ verification: ["npm test"],
+ });
+
+ // then
+ assert.throws(action, /reproductionLogs must be a non-empty string/);
+});
+
+test("#given a JSON payload path #when running the PR body script #then markdown is written to the requested file", async () => {
+ // given
+ const workspace = await mkdtemp(join(tmpdir(), "lcx-pr-body-test-"));
+ const inputPath = join(workspace, "input.json");
+ const outputPath = join(workspace, "body.md");
+ await writeFile(
+ inputPath,
+ JSON.stringify({
+ title: "Fix Codex skill sync drift",
+ targetRepository: "code-yeongyu/lazycodex",
+ problem: "Skill sync omitted a shared skill from the aggregate plugin.",
+ reproductionLogs: "node --test failed before the fix.",
+ approach: "Add the missing shared skill source and sync the aggregate plugin.",
+ confidence: "The failing sync test now passes.",
+ risks: "Low risk.",
+ userVisibleBehaviorChanges: "Users get a direct bug-fix PR skill.",
+ verification: ["node --test test/lcx-contribute-bug-fix-template.test.mjs"],
+ }),
+ "utf8",
+ );
+
+ // when
+ const { spawnSync } = await import("node:child_process");
+ const result = spawnSync(process.execPath, [scriptPath, inputPath, outputPath], { encoding: "utf8" });
+
+ // then
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(await readFile(outputPath, "utf8"), /## User-Visible Behavior Changes/);
+});
diff --git a/plugins/omo/test/migrate-codex-config.test.mjs b/plugins/omo/test/migrate-codex-config.test.mjs
index c34b71c2..cf496e66 100644
--- a/plugins/omo/test/migrate-codex-config.test.mjs
+++ b/plugins/omo/test/migrate-codex-config.test.mjs
@@ -32,6 +32,29 @@ test("#given stale root reasoning config #when ensuring config #then replaces st
assert.match(result, /\[features\]/);
});
+test("#given section settings reuse managed root keys #when ensuring config #then section settings are preserved", () => {
+ const result = ensureCodexReasoningConfig(
+ [
+ 'model = "gpt-5.5"',
+ "model_context_window = 272000",
+ "",
+ "[model_providers.openai]",
+ 'model = "provider-scoped-value"',
+ "model_context_window = 123456",
+ "",
+ "[profiles.review]",
+ 'model_reasoning_effort = "medium"',
+ 'plan_mode_reasoning_effort = "medium"',
+ "",
+ ].join("\n"),
+ );
+
+ assert.match(result, /^model = "gpt-5\.5"$/m);
+ assert.match(result, /^model_context_window = 400000$/m);
+ assert.match(result, /\[model_providers\.openai\]\nmodel = "provider-scoped-value"\nmodel_context_window = 123456/);
+ assert.match(result, /\[profiles\.review\]\nmodel_reasoning_effort = "medium"\nplan_mode_reasoning_effort = "medium"/);
+});
+
test("#given project .codex is a symlink #when migrating #then project config is skipped", async (t) => {
if (!(await canCreateSymlink("dir"))) t.skip("symbolic links are unavailable in this environment");
@@ -134,6 +157,29 @@ test("#given model catalog is unavailable and stale 272k config #when migrating
assert.match(content, /model_context_window = 400000/);
});
+test("#given model catalog is malformed and stale config #when migrating #then fallback catalog still upgrades it", async () => {
+ const root = await mkdtemp(join(tmpdir(), "lazycodex-config-malformed-catalog-"));
+ const codexHome = join(root, "codex-home");
+ const catalogPath = join(root, "model-catalog.json");
+ await mkdir(codexHome, { recursive: true });
+ await writeFile(catalogPath, "{not-json");
+ await writeFile(join(codexHome, "config.toml"), 'model = "gpt-5.5"\nmodel_context_window = 272000\n');
+
+ const result = await migrateCodexConfig({
+ env: {
+ CODEX_HOME: codexHome,
+ LAZYCODEX_MODEL_CATALOG_PATH: catalogPath,
+ LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json"),
+ },
+ cwd: root,
+ });
+
+ const content = await readFile(join(codexHome, "config.toml"), "utf8");
+ assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
+ assert.match(content, /model = "gpt-5\.5"/);
+ assert.match(content, /model_context_window = 400000/);
+});
+
test("#given user-customized Codex model config #when migrating #then user values are preserved", async () => {
const root = await mkdtemp(join(tmpdir(), "lazycodex-config-custom-"));
const codexHome = join(root, "codex-home");
@@ -162,6 +208,43 @@ test("#given user-customized Codex model config #when migrating #then user value
assert.match(content, /plan_mode_reasoning_effort = "medium"/);
});
+test("#given managed config state is malformed #when migrating #then migration ignores stale state safely", async () => {
+ const root = await mkdtemp(join(tmpdir(), "lazycodex-config-malformed-state-"));
+ const codexHome = join(root, "codex-home");
+ const statePath = join(root, "model-state.json");
+ await mkdir(codexHome, { recursive: true });
+ await writeFile(statePath, "[broken-json");
+ await writeFile(join(codexHome, "config.toml"), 'model = "gpt-5.5"\nmodel_context_window = 272000\n');
+
+ const result = await migrateCodexConfig({
+ env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: statePath },
+ cwd: root,
+ });
+
+ const content = await readFile(join(codexHome, "config.toml"), "utf8");
+ const state = JSON.parse(await readFile(statePath, "utf8"));
+ assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
+ assert.match(content, /model_context_window = 400000/);
+ assert.equal(state.files[join(codexHome, "config.toml")].managed, true);
+});
+
+test("#given managed config state path has surrounding whitespace #when migrating #then trimmed state path is used", async () => {
+ const root = await mkdtemp(join(tmpdir(), "lazycodex-config-trimmed-state-"));
+ const codexHome = join(root, "codex-home");
+ const statePath = join(root, "model-state.json");
+ await mkdir(codexHome, { recursive: true });
+ await writeFile(join(codexHome, "config.toml"), 'model = "gpt-5.5"\nmodel_context_window = 272000\n');
+
+ const result = await migrateCodexConfig({
+ env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: ` ${statePath} ` },
+ cwd: root,
+ });
+
+ const state = JSON.parse(await readFile(statePath, "utf8"));
+ assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
+ assert.equal(state.files[join(codexHome, "config.toml")].managed, true);
+});
+
test("#given managed catalog state #when catalog version advances #then only previously managed config is updated", async () => {
const root = await mkdtemp(join(tmpdir(), "lazycodex-config-catalog-state-"));
const codexHome = join(root, "codex-home");
@@ -227,6 +310,57 @@ test("#given managed catalog state #when catalog version advances #then only pre
assert.match(content, /model_context_window = 400000/);
});
+test("#given config already matches current catalog #when catalog version advances for role-only changes #then managed state is preserved", async () => {
+ const root = await mkdtemp(join(tmpdir(), "lazycodex-config-current-managed-"));
+ const codexHome = join(root, "codex-home");
+ const catalogPath = join(root, "catalog.json");
+ const statePath = join(root, "model-state.json");
+ const configPath = join(codexHome, "config.toml");
+ await mkdir(codexHome, { recursive: true });
+ await writeFile(
+ configPath,
+ [
+ 'model = "gpt-5.5"',
+ "model_context_window = 400000",
+ 'model_reasoning_effort = "high"',
+ 'plan_mode_reasoning_effort = "xhigh"',
+ "",
+ ].join("\n"),
+ );
+ await writeFile(
+ catalogPath,
+ JSON.stringify(
+ {
+ version: "test.role-only",
+ current: {
+ model: "gpt-5.5",
+ model_context_window: 400000,
+ model_reasoning_effort: "high",
+ plan_mode_reasoning_effort: "xhigh",
+ },
+ roles: { verifier: { model: "gpt-5.5", model_reasoning_effort: "high" } },
+ managedProfiles: [],
+ },
+ null,
+ 2,
+ ),
+ );
+
+ const result = await migrateCodexConfig({
+ env: {
+ CODEX_HOME: codexHome,
+ LAZYCODEX_MODEL_CATALOG_PATH: catalogPath,
+ LAZYCODEX_MODEL_CATALOG_STATE_PATH: statePath,
+ },
+ cwd: root,
+ });
+
+ const state = JSON.parse(await readFile(statePath, "utf8"));
+ assert.deepEqual(result.changed, []);
+ assert.equal(state.files[configPath].managed, true);
+ assert.equal(state.files[configPath].catalogVersion, "test.role-only");
+});
+
async function canCreateSymlink(type) {
const root = await mkdtemp(join(tmpdir(), "lazycodex-symlink-capability-"));
const target = join(root, "target");
diff --git a/plugins/omo/test/node-install-surface.test.mjs b/plugins/omo/test/node-install-surface.test.mjs
index d7f6868d..81c96f26 100644
--- a/plugins/omo/test/node-install-surface.test.mjs
+++ b/plugins/omo/test/node-install-surface.test.mjs
@@ -24,7 +24,6 @@ test("#given Codex Light install docs #when inspected #then lazycodex is npm-fir
// then
for (const [path, text] of docs) {
assert.match(text, /\bnpx lazycodex-ai install\b/, `${path} should document the Node/npm install command`);
- const oldRunnerPattern = new RegExp(`\\b${["bu", "nx"].join("")} lazycodex-ai\\b`);
- assert.doesNotMatch(text, oldRunnerPattern, `${path} should not require Bun for lazycodex`);
+ assert.doesNotMatch(text, /\bbunx lazycodex-ai\b/, `${path} should not require Bun for lazycodex`);
}
});
diff --git a/plugins/omo/test/start-work-skill.test.mjs b/plugins/omo/test/start-work-skill.test.mjs
index 029e15c7..a8d93518 100644
--- a/plugins/omo/test/start-work-skill.test.mjs
+++ b/plugins/omo/test/start-work-skill.test.mjs
@@ -9,6 +9,9 @@ const repoRoot = dirname(dirname(dirname(pluginRoot)));
const startWorkSkillPaths = [
join(repoRoot, "packages", "shared-skills", "skills", "start-work", "SKILL.md"),
];
+const packagedStartWorkSkillPath = join(pluginRoot, "skills", "start-work", "SKILL.md");
+const packagedReviewWorkSkillPath = join(pluginRoot, "skills", "review-work", "SKILL.md");
+const hephaestusRulePath = join(pluginRoot, "components", "rules", "bundled-rules", "hephaestus.md");
const stopHookPath = join(
pluginRoot,
"components",
@@ -67,6 +70,28 @@ test("#given worker done claim #when start-work contract is inspected #then adve
assert.deepEqual(missing, []);
});
+test("#given packaged start-work completion surfaces #when inspected #then global review and debugging gate blocks completion", async () => {
+ // given
+ const [startWorkSkill, reviewWorkSkill, hephaestusRule] = await Promise.all([
+ readFile(packagedStartWorkSkillPath, "utf8"),
+ readFile(packagedReviewWorkSkillPath, "utf8"),
+ readFile(hephaestusRulePath, "utf8"),
+ ]);
+
+ // then
+ assert.match(startWorkSkill, /Global Review and Debugging Gate/);
+ assert.match(startWorkSkill, /\breview-work\b/);
+ assert.match(startWorkSkill, /\bdebugging\b/);
+ assert.match(startWorkSkill, /inconclusive/i);
+ assert.match(startWorkSkill, /redact|mask/i);
+ assert.match(startWorkSkill, /raw (?:tokens|credentials|auth headers|cookies)/i);
+ assert.match(startWorkSkill, /ORCHESTRATION COMPLETE/);
+ assert.match(reviewWorkSkill, /debugging/i);
+ assert.match(reviewWorkSkill, /inconclusive/i);
+ assert.match(hephaestusRule, /Global Review and Debugging Gate/);
+ assert.match(hephaestusRule, /redact.*secrets.*PII/s);
+});
+
test("#given start-work continuation hook #when inspected #then it remains Boulder-only without planning bootstrap logic", async () => {
// given
const hook = await readFile(stopHookPath, "utf8");
diff --git a/plugins/omo/test/subagent-guidance.test.mjs b/plugins/omo/test/subagent-guidance.test.mjs
index d602d4d0..03c27942 100644
--- a/plugins/omo/test/subagent-guidance.test.mjs
+++ b/plugins/omo/test/subagent-guidance.test.mjs
@@ -32,7 +32,7 @@ test("#given orchestration skills #when inspected #then Codex subagent delegatio
!/wait_agent.*mailbox signals/s.test(text) ||
!/Fallback only when/.test(text) ||
!/respawn.*smaller/s.test(text) ||
- !/model.*reasoning_effort.*default agent/s.test(text) ||
+ !/schema only accepts `task_name`, `message`, and `fork_turns`/s.test(text) ||
!/Plan and reviewer agents may run for a long time/.test(text) ||
!/short wait_agent cycles/.test(text) ||
!/single long blocking wait/.test(text) ||
@@ -57,14 +57,45 @@ test("#given ultrawork directive #when inspected #then reviewer fallback keeps a
// then
assert.doesNotMatch(text, /any `gpt-5\.2`\s+xhigh reviewer/);
- assert.match(text, /codex-ultrawork-reviewer/);
- assert.match(text, /agent_type.*worker/s);
- assert.match(text, /model.*reasoning_effort.*default agent/s);
+ assert.match(text, /self-contained reviewer/);
+ assert.match(text, /schema cannot select.*TOML-backed reviewer role/s);
+ assert.match(text, /paste the reviewer requirements into\s+the message/s);
assert.match(text, /timeout only means no new mailbox update arrived/i);
assert.match(text, /WORKING:/);
assert.match(text, /single `list_agents`/);
});
+test("#given ultrawork directive #when inspected #then dependent subagent transitions are blocked", async () => {
+ // given
+ const directivePath = "components/ultrawork/directive.md";
+
+ // when
+ const text = await readFile(join(root, directivePath), "utf8");
+
+ // then
+ assert.match(text, /Subagent-dependent transition barrier/);
+ assert.match(text, /Do not mark.*update_plan.*completed.*active child/s);
+ assert.match(text, /Do not start dependent implementation.*audit.*research.*review.*integrated/s);
+ assert.match(text, /Do not write the final answer.*active child agents/s);
+ assert.match(text, /two silent waits.*TASK STILL ACTIVE/s);
+ assert.match(text, /four silent or ack-only checks.*inconclusive/s);
+});
+
+test("#given ultrawork directive #when inspected #then TOML-backed routing is treated as unverified when native spawn cannot select it", async () => {
+ // given
+ const directivePath = "components/ultrawork/directive.md";
+
+ // when
+ const text = await readFile(join(root, directivePath), "utf8");
+
+ // then
+ assert.match(text, /TOML-backed subagent routing compatibility/);
+ assert.match(text, /routing-unverified/);
+ assert.match(text, /schema accepts only `task_name`, `message`, and\s+`fork_turns`/s);
+ assert.match(text, /cannot select a TOML-backed role, model, reasoning\s+effort, or `service_tier`/s);
+ assert.match(text, /paste the\s+role requirements into the message/s);
+});
+
test("#given ulw-loop workflow #when inspected #then stale review refresh keeps policy changes narrow", async () => {
// given
const workflowPaths = [
@@ -105,3 +136,16 @@ test("#given ultrawork agents #when inspected #then inter-agent commentary is tr
// then
assert.deepEqual(missing, []);
});
+
+test("#given reviewer receives a targeted still-active followup #when prompt is inspected #then it must fail loud", async () => {
+ // given
+ const reviewerPath = "components/ultrawork/agents/codex-ultrawork-reviewer.toml";
+
+ // when
+ const text = await readFile(join(root, reviewerPath), "utf8");
+
+ // then
+ assert.match(text, /TASK STILL ACTIVE:/);
+ assert.match(text, /BLOCKED: <reason>/);
+ assert.match(text, /instead of continuing silently/);
+});
diff --git a/plugins/omo/test/sync-skills-orchestration.test.mjs b/plugins/omo/test/sync-skills-orchestration.test.mjs
index ea30deb7..40667790 100644
--- a/plugins/omo/test/sync-skills-orchestration.test.mjs
+++ b/plugins/omo/test/sync-skills-orchestration.test.mjs
@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import test from "node:test";
import { fileURLToPath } from "node:url";
+import { insertCodexCompatibilityGuidance } from "../scripts/sync-skills.mjs";
const root = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -32,8 +33,10 @@ test("#given synced aggregate Codex skills #when they contain OpenCode orchestra
const content = await readSkill(skillName);
if (!opencodeOnlyToolPattern.test(content)) continue;
+ const compatibilityMatches = content.match(/## Codex Harness Tool Compatibility/g) ?? [];
const compatibilityIndex = content.indexOf("## Codex Harness Tool Compatibility");
assert.notEqual(compatibilityIndex, -1, `${skillName} is missing Codex compatibility guidance`);
+ assert.equal(compatibilityMatches.length, 1, `${skillName} must not duplicate Codex compatibility guidance`);
assert.ok(
compatibilityIndex < content.search(opencodeOnlyToolPattern),
`${skillName} must explain Codex tool translation before OpenCode-only examples`,
@@ -41,6 +44,65 @@ test("#given synced aggregate Codex skills #when they contain OpenCode orchestra
}
});
+test("#given late variant Codex compatibility guidance #when adapting a skill #then it is moved without duplication", () => {
+ // given
+ const content = `---
+name: example
+---
+
+# Example Skill
+
+call_omo_agent(subagent_type="explore", prompt="inspect")
+
+## Codex Harness Tool Compatibility
+
+Older variant guidance.
+
+When translating \`load_skills=[...]\`, name the skills inside the spawned agent's \`message\`.
+
+---
+
+## Next Section
+
+task(category="quick", prompt="verify")
+`;
+
+ // when
+ const adapted = insertCodexCompatibilityGuidance(content);
+
+ // then
+ const compatibilityIndex = adapted.indexOf("## Codex Harness Tool Compatibility");
+ const firstToolIndex = adapted.search(/\b(?:call_omo_agent|task)\s*\(/);
+ assert.notEqual(compatibilityIndex, -1);
+ assert.ok(compatibilityIndex < firstToolIndex);
+ assert.equal(adapted.match(/## Codex Harness Tool Compatibility/g)?.length, 1);
+ assert.doesNotMatch(adapted, /Older variant guidance/);
+ assert.doesNotMatch(adapted, /When translating `load_skills=\[\.\.\.\]`/);
+ assert.match(adapted, /\n---\n\n## Next Section/);
+});
+
+test("#given early custom Codex compatibility guidance #when adapting a skill #then it is preserved exactly", () => {
+ // given
+ const content = `---
+name: example
+---
+
+## Codex Harness Tool Compatibility
+
+Custom guidance for this skill, including \`dispatchInternalPrompt(...)\`.
+
+# Example Skill
+
+call_omo_agent(subagent_type="explore", prompt="inspect")
+`;
+
+ // when
+ const adapted = insertCodexCompatibilityGuidance(content);
+
+ // then
+ assert.equal(adapted, content);
+});
+
test("#given synced aggregate Codex skills #when they describe background orchestration #then liveness is framed as progress rather than timeout failure", async () => {
// given
const orchestrationPattern = /\b(?:run_in_background|background_output|wait_agent)\b/;
@@ -75,3 +137,16 @@ test("#given synced aggregate Codex skills #when they describe background orches
}
}
});
+
+test("#given review-work skill #when some lanes do not finish #then aggregate result remains bounded", async () => {
+ const content = await readSkill("review-work");
+
+ assert.match(content, /pending\/PASS\/FAIL\/INCONCLUSIVE/);
+ assert.match(content, /Preserve completed lane results immediately/);
+ assert.match(content, /ALL 5 lanes have a terminal state/);
+ assert.match(content, /REVIEW INCONCLUSIVE - not approved/);
+ assert.match(content, /Overall Verdict: PASSED \/ FAILED \/ INCONCLUSIVE/);
+ assert.match(content, /PASS\/FAIL\/INCONCLUSIVE \| HIGH\/MED\/LOW/);
+ assert.match(content, /Do not spin in repeated/);
+ assert.match(content, /Do not use `send_message` as an interrupt/);
+});
diff --git a/plugins/omo/test/sync-skills.test.mjs b/plugins/omo/test/sync-skills.test.mjs
index ee9ecfb8..21587582 100644
--- a/plugins/omo/test/sync-skills.test.mjs
+++ b/plugins/omo/test/sync-skills.test.mjs
@@ -15,6 +15,7 @@ const expectedSkills = [
"frontend-ui-ux",
"git-master",
"init-deep",
+ "lcx-contribute-bug-fix",
"lcx-report-bug",
"lsp",
"programming",
@@ -23,6 +24,7 @@ const expectedSkills = [
"review-work",
"rules",
"start-work",
+ "ultraresearch",
"ulw-loop",
"ulw-plan",
"visual-qa",
@@ -38,7 +40,7 @@ const componentSkillSources = [
const codexCompatibilityEndMarkers = [
"For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
- "Codex full-history forks inherit the parent agent type, model, and reasoning effort, so role-specific spawns with `agent_type` must use a non-full-history fork mode such as `fork_turns=\"none\"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
+ "Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns=\"none\"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
"When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins.\n\n",
];
@@ -53,6 +55,45 @@ function removeCodexCompatibilityGuidance(content) {
return `${content.slice(0, start)}${content.slice(end + endMarker.length)}`;
}
+const startWorkOriginalCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+3. Remove or mark the Boulder work as completed.
+4. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, artifacts, and cleanup receipts.`;
+
+const startWorkCodexCompletion = `When all top-level checkboxes in \`## TODOs\` and \`## Final Verification Wave\` are complete:
+
+1. Run the plan's final verification commands.
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+ - Invoke the \`review-work\` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, \`BLOCKED:\`, or inconclusive lane is a gate failure, not approval.
+ - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to \`.omo/start-work/ledger.jsonl\`.
+ - If any review lane or debugging hypothesis fails, invoke the \`debugging\` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
+ - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing \`.omo/start-work/ledger.jsonl\`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
+ - If the work includes creating, updating, or handing off a PR, refresh \`git status\` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. If worktree mode was used, sync \`.omo/\` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+4. Remove or mark the Boulder work as completed.
+5. Print an \`ORCHESTRATION COMPLETE\` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.`;
+
+const startWorkOriginalHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+const startWorkCodexHardRule = "- No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.\n- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.\n- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.";
+
+const reviewWorkCodexGatePattern =
+ /\nWhen `review-work` is used as a final implementation, PR, or `\$start-work`\ngate, it is blocking\. A timeout, missing deliverable, ack-only response,\nexplicit `BLOCKED:`, or inconclusive lane is not a pass\. Treat that lane as\nfailed, investigate the underlying uncertainty with the `debugging` skill when\nruntime behavior may be wrong, fix with evidence, and rerun the affected lane\nbefore claiming completion or handing off a PR\.\n\nReview evidence must be safe to share\. Redact or mask secrets and sensitive\nuser data before including evidence in logs, PR bodies, or handoffs\. Never\ninclude raw tokens, credentials, auth headers, cookies, API keys, env dumps,\nprivate logs, or PII; summarize with lengths, hashes, and short non-sensitive\nprefixes when identity is needed\.\n/;
+
+function removeCodexSkillOverlays(skillName, content) {
+ if (skillName === "start-work") {
+ return content
+ .replace(startWorkCodexCompletion, startWorkOriginalCompletion)
+ .replace(startWorkCodexHardRule, startWorkOriginalHardRule);
+ }
+ if (skillName === "review-work") {
+ return content.replace(reviewWorkCodexGatePattern, "");
+ }
+ return content;
+}
+
async function listSkillFiles(dir) {
const entries = await readdir(dir, { withFileTypes: true });
const files = [];
@@ -133,13 +174,24 @@ test("#given shared skill package source #when aggregate Codex shared skills are
const sharedContent = await readFile(join(sharedSkillsRoot, skillName, "SKILL.md"), "utf8");
const aggregateContent = await readFile(join(aggregateSkillsRoot, skillName, "SKILL.md"), "utf8");
assert.equal(
- removeCodexCompatibilityGuidance(aggregateContent),
+ removeCodexSkillOverlays(skillName, removeCodexCompatibilityGuidance(aggregateContent)),
removeCodexCompatibilityGuidance(sharedContent),
`${skillName} drifted from shared-skills`,
);
}
});
+test("#given shared skill source tests #when aggregate Codex skills are synced #then source tests are not packaged", async () => {
+ // given
+ const aggregateSkillsRoot = join(root, "skills");
+
+ // when
+ const visualQaFiles = await listSkillFiles(join(aggregateSkillsRoot, "visual-qa"));
+
+ // then
+ assert.equal(visualQaFiles.some((file) => file.endsWith(".test.ts")), false);
+});
+
test("#given component skill sources #when aggregate Codex component skills are inspected #then generated copies have no hand-authored drift", async () => {
// given
const aggregateSkillsRoot = join(root, "skills");
@@ -192,33 +244,6 @@ test("#given synced ulw-loop skill #when Codex hint metadata is inspected #then
assert.match(interfaceMetadata, /- "ulw-loop"/);
});
-test("#given synced lcx-report-bug skill #when inspected #then it files LazyCodex bug issues from proven debugging evidence", async () => {
- // given
- const skillRoot = join(root, "skills", "lcx-report-bug");
-
- // when
- const skill = await readFile(join(skillRoot, "SKILL.md"), "utf8");
- const interfaceMetadata = await readFile(join(skillRoot, "agents", "openai.yaml"), "utf8");
-
- // then
- assert.match(skill, /^---\r?\nname: lcx-report-bug\r?\n/m);
- assert.match(skill, /code-yeongyu\/lazycodex/);
- assert.match(skill, /openai\/codex/);
- assert.match(skill, /\/tmp\/openai-codex-source/);
- assert.match(skill, /\$omo:debugging/);
- assert.match(skill, /Repository Decision/);
- assert.match(skill, /TARGET_REPO="code-yeongyu\/lazycodex" # or openai\/codex/);
- assert.match(skill, /gh issue create --repo "\$TARGET_REPO"/);
- assert.match(skill, /gh pr create --repo "\$TARGET_REPO"/);
- assert.match(skill, /🤖 This issue\/PR was debugged and created with \[LazyCodex\]/);
- assert.match(skill, /Browser use fallback/);
- assert.match(skill, /Computer use fallback/);
- assert.match(skill, /## Issue Body Template/);
- assert.match(interfaceMetadata, /display_name: "lcx-report-bug \(omo\)"/);
- assert.match(interfaceMetadata, /- "lazycodex bug"/);
- assert.match(interfaceMetadata, /- "openai codex bug"/);
-});
-
test("#given synced git-master skill #when inspected #then commits and git history route through it", async () => {
// given
const skillRoot = join(root, "skills", "git-master");
diff --git a/plugins/omo/test/ulw-plan-skill.test.mjs b/plugins/omo/test/ulw-plan-skill.test.mjs
index 314b164a..ce859015 100644
--- a/plugins/omo/test/ulw-plan-skill.test.mjs
+++ b/plugins/omo/test/ulw-plan-skill.test.mjs
@@ -16,7 +16,7 @@ test("#given ulw-plan skill #when inspected #then it is a Codex-native planner t
// then
assert.match(skill, /^---\r?\nname: ulw-plan\r?\n/m);
assert.match(skill, /references\/full-workflow\.md/);
- assert.match(skill, /spawn_agent\([^)]*fork_turns="none"/);
+ assert.match(skill, /spawn_agent\(\{[^)]*"fork_turns":"none"/);
assert.doesNotMatch(skill, opencodeOnlyToolPattern);
});
@@ -37,7 +37,7 @@ test("#given ulw-plan full workflow reference #when inspected #then it documents
// then
assert.match(workflow, /\.omo\/plans\/<slug>\.md/);
assert.match(workflow, /[Aa]pproval gate/);
- assert.match(workflow, /spawn_agent\([^)]*fork_turns="none"/);
+ assert.match(workflow, /spawn_agent\(\{[^)]*"fork_turns":"none"/);
assert.doesNotMatch(workflow, opencodeOnlyToolPattern);
assert.doesNotMatch(workflow, /Proceeding to plan generation/);
});