oh-my-opencode 4.10.0 → 4.11.0

package/packages/omo-codex/plugin/scripts/migrate-omo-sot/scaffold.mjs

@@ -0,0 +1,29 @@
+export const SCAFFOLD = `{
+  // Shared OMO settings. Harness override blocks below are additive.
+  "codegraph": {
+    // "enabled": true,
+    // "auto_provision": true,
+    // "telemetry": false,
+    // "install_dir": "~/.omo/codegraph"
+  },
+
+  "[codex]": {
+    "codegraph": {
+      // "enabled": true,
+      // "auto_provision": true,
+      // "install_dir": "~/.omo/codegraph",
+      // "telemetry": false
+    }
+  },
+
+  "[opencode]": {
+    "codegraph": {
+      // "enabled": true,
+      // "auto_provision": true,
+      // "install_dir": "~/.omo/codegraph",
+      // "telemetry": false,
+      // "watch_debounce_ms": 250
+    }
+  }
+}
+`;

package/packages/omo-codex/plugin/scripts/migrate-omo-sot.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { addCodexCodegraphValues, hasOwn, isRecord, recordAt } from "./migrate-omo-sot/editor.mjs";
+import { parseJsonc } from "./migrate-omo-sot/jsonc.mjs";
+import { SCAFFOLD } from "./migrate-omo-sot/scaffold.mjs";
+
+const CODEGRAPH_KEYS = ["auto_provision", "enabled", "install_dir", "telemetry"];
+const ENV_MAPPINGS = [
+	["auto_provision", "OMO_CODEGRAPH_AUTO_PROVISION", "boolean"],
+	["auto_provision", "CODEX_CODEGRAPH_AUTO_PROVISION", "boolean"],
+	["enabled", "OMO_CODEGRAPH_ENABLED", "boolean"],
+	["enabled", "CODEX_CODEGRAPH_ENABLED", "boolean"],
+	["install_dir", "OMO_CODEGRAPH_INSTALL_DIR", "string"],
+	["install_dir", "CODEX_CODEGRAPH_INSTALL_DIR", "string"],
+	["telemetry", "OMO_CODEGRAPH_TELEMETRY", "boolean"],
+	["telemetry", "CODEX_CODEGRAPH_TELEMETRY", "boolean"],
+];
+
+export async function migrateOmoSotConfig({ env = process.env, seed = false, configPath } = {}) {
+	const targetPath = configPath ?? join(resolveHomeDir(env), ".omo", "config.jsonc");
+	if (!(await pathExists(targetPath))) {
+		if (!seed) return { changed: false, configPath: targetPath, seeded: false, warnings: [] };
+		const parsedScaffold = parseJsonc(SCAFFOLD);
+		if (!parsedScaffold.ok) throw parsedScaffold.error;
+		const additions = collectCodexAdditions(parsedScaffold.value, env);
+		const content = addCodexCodegraphValues(SCAFFOLD, parsedScaffold.value, additions);
+		await mkdir(dirname(targetPath), { recursive: true });
+		await writeFile(targetPath, content);
+		return { changed: true, configPath: targetPath, seeded: true, warnings: [] };
+	}
+
+	const content = await readFile(targetPath, "utf8");
+	const parsed = parseJsonc(content);
+	if (!parsed.ok) {
+		return {
+			changed: false,
+			configPath: targetPath,
+			seeded: false,
+			warnings: [`Could not parse ${targetPath}; left existing OMO SOT untouched: ${parsed.error.message}`],
+		};
+	}
+
+	const additions = collectCodexAdditions(parsed.value, env);
+	if (Object.keys(additions).length === 0) {
+		return { changed: false, configPath: targetPath, seeded: false, warnings: [] };
+	}
+
+	const edited = addCodexCodegraphValues(content, parsed.value, additions);
+	if (edited === content) return { changed: false, configPath: targetPath, seeded: false, warnings: [] };
+	await writeFile(targetPath, edited);
+	return { changed: true, configPath: targetPath, seeded: false, warnings: [] };
+}
+
+function resolveHomeDir(env) {
+	const candidate = env.HOME ?? env.USERPROFILE;
+	return candidate?.trim() ? candidate : homedir();
+}
+
+async function pathExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function collectCodexAdditions(config, env) {
+	const codexCodegraph = recordAt(recordAt(config, "[codex]"), "codegraph");
+	const additions = {};
+	addSupportedCodegraphValues(additions, recordAt(config, "codegraph"), codexCodegraph);
+	for (const [key, envKey, kind] of ENV_MAPPINGS) {
+		const raw = env[envKey];
+		if (raw === undefined || hasOwn(codexCodegraph, key)) continue;
+		const parsed = parseEnvValue(raw, kind);
+		if (parsed !== null) additions[key] = parsed;
+	}
+	for (const key of Object.keys(additions)) {
+		if (hasOwn(codexCodegraph, key)) delete additions[key];
+	}
+	return additions;
+}
+
+function addSupportedCodegraphValues(additions, baseCodegraph, codexCodegraph) {
+	if (!isRecord(baseCodegraph)) return;
+	for (const key of CODEGRAPH_KEYS) {
+		if (hasOwn(codexCodegraph, key) || !hasOwn(baseCodegraph, key)) continue;
+		const value = baseCodegraph[key];
+		if (isValidCodegraphValue(key, value)) additions[key] = value;
+	}
+}
+
+function parseEnvValue(value, kind) {
+	if (kind === "string") return value;
+	const normalized = value.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return null;
+}
+
+function isValidCodegraphValue(key, value) {
+	if (key === "install_dir") return typeof value === "string";
+	return typeof value === "boolean";
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	migrateOmoSotConfig({ seed: process.argv.includes("--seed") })
+		.then((result) => {
+			for (const warning of result.warnings) process.stderr.write(`${warning}\n`);
+		})
+		.catch((error) => {
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		});
+}

package/packages/omo-codex/plugin/scripts/sync-skills.mjs

@@ -15,6 +15,7 @@ const skillSources = [
 	["ulw-loop", "components/ulw-loop/skills/ulw-loop"],
 	["ulw-plan", "components/ultrawork/skills/ulw-plan"],
 ];
+const componentSkillNames = new Set(skillSources.map(([name]) => name));
 
 const opencodeOnlyOrchestrationPattern = /\b(?:call_omo_agent|background_output|team_[a-z_]+|task)\s*\(/;
 
@@ -27,12 +28,12 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | \`call_omo_agent(subagent_type="explore", ...)\` | \`multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})\` |
 | \`call_omo_agent(subagent_type="librarian", ...)\` | \`multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})\` |
 | \`task(subagent_type="plan", ...)\` | \`multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})\` |
-| \`task(subagent_type="oracle", ...)\` for final verification | \`multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"codex-ultrawork-reviewer","fork_context":false})\` |
+| \`task(subagent_type="oracle", ...)\` for final verification | \`multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})\` |
 | \`task(category="...", ...)\` for implementation or QA | \`multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})\` |
 | \`background_output(task_id="...")\` | \`multi_agent_v1.wait_agent(...)\` for mailbox signals |
 | \`team_*(...)\` | Use Codex native subagents via \`multi_agent_v1.spawn_agent\`, \`multi_agent_v1.send_input\`, \`multi_agent_v1.wait_agent\`, and \`multi_agent_v1.close_agent\` |
 
-Role-specific behavior must be described in a self-contained \`message\`. Use \`fork_context: false\` to start the child with only the initial prompt (no parent history); use \`fork_context: true\` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. OMO installs these selectable agent roles into \`~/.codex/agents/\`: \`explorer\`, \`librarian\`, \`plan\`, \`momus\`, \`metis\`, and \`codex-ultrawork-reviewer\` — pass the matching name as \`agent_type\` so the child gets that role's model and instructions. On \`multi_agent_v2\` sessions the same \`agent_type\` applies (the OMO installer exposes it) with \`fork_turns\` instead of \`fork_context\`. If the spawn tool exposes no \`agent_type\` parameter, omit it and describe the role inside \`message\`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained \`message\`. Use \`fork_context: false\` to start the child with only the initial prompt (no parent history); use \`fork_context: true\` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's \`message\`. OMO installs these selectable agent roles into \`~/.codex/agents/\`: \`explorer\`, \`librarian\`, \`plan\`, \`momus\`, \`metis\`, \`lazycodex-code-reviewer\`, \`lazycodex-qa-executor\`, and \`lazycodex-gate-reviewer\` - pass the matching name as \`agent_type\` so the child gets that role's model and instructions. If the spawn tool exposes no \`agent_type\` parameter, omit it and describe the role inside \`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 \`multi_agent_v1.wait_agent\` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly \`BLOCKED:\`, or no longer running.
 
@@ -41,8 +42,6 @@ For work likely to exceed one wait cycle, require the child to send \`WORKING: <
 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 `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.\n\n",
 	"Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. 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",
-	"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",
 ];
@@ -162,7 +161,7 @@ async function adaptSkillForCodex(skillName) {
 }
 
 async function syncSkills() {
-	await rm(skillsRoot, { recursive: true, force: true });
+	await rm(skillsRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
 	await mkdir(skillsRoot, { recursive: true });
 
 	for (const [name, source] of skillSources) {
@@ -177,6 +176,7 @@ async function syncSkills() {
 		.sort();
 
 	for (const skillName of sharedSkillNames) {
+		if (componentSkillNames.has(skillName)) continue;
 		await cp(join(sharedSkillsRoot, skillName), join(skillsRoot, skillName), {
 			filter: (source) => !sourceTestFilePattern.test(source),
 			recursive: true,

package/packages/omo-codex/plugin/shared/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@sisyphuslabs/omo-codex-shared",
+	"version": "4.10.0",
+	"description": "Shared source modules for OMO Codex plugin components.",
+	"type": "module",
+	"private": true,
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"build": "tsc --noEmit -p tsconfig.build.json",
+		"test": "bun test test/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@oh-my-opencode/utils": "file:../../../utils",
+		"@types/node": "^25.9.3",
+		"bun-types": "1.3.14",
+		"typescript": "^6.0.3"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}

package/packages/omo-codex/plugin/shared/src/config-loader.ts

@@ -0,0 +1,28 @@
+import {
+	loadOmoConfig,
+	type LoadOmoConfigOptions,
+} from "../../../../utils/src/omo-config/loader.ts"
+import type { OmoConfig } from "../../../../utils/src/omo-config.ts"
+import type { OmoConfigSource } from "../../../../utils/src/omo-config/resolve.ts"
+
+export type CodexOmoConfigOptions = Omit<LoadOmoConfigOptions, "harness">
+
+export type CodexOmoConfig = OmoConfig & {
+	readonly sources: readonly OmoConfigSource[]
+	readonly warnings: readonly string[]
+}
+
+export function getCodexOmoConfig(options: CodexOmoConfigOptions = {}): CodexOmoConfig {
+	const result = loadOmoConfig({
+		...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+		...(options.env === undefined ? {} : { env: options.env }),
+		...(options.homeDir === undefined ? {} : { homeDir: options.homeDir }),
+		harness: "codex",
+	})
+
+	return {
+		...result.config,
+		sources: result.sources,
+		warnings: result.warnings,
+	}
+}

package/packages/omo-codex/plugin/shared/test/config-loader.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it } from "bun:test"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { getCodexOmoConfig } from "../src/config-loader.ts"
+
+const temporaryDirectories: string[] = []
+
+function createTemporaryDirectory(prefix: string): string {
+	const directory = mkdtempSync(join(tmpdir(), prefix))
+	temporaryDirectories.push(directory)
+	return directory
+}
+
+function writeOmoConfig(homeDir: string, content: string): void {
+	const configDir = join(homeDir, ".omo")
+	mkdirSync(configDir, { recursive: true })
+	writeFileSync(join(configDir, "config.jsonc"), content)
+}
+
+afterEach(() => {
+	for (const directory of temporaryDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true })
+	}
+})
+
+describe("getCodexOmoConfig", () => {
+	it("#given base and codex SOT blocks #when loading config #then returns the codex-merged effective config", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-")
+		const cwd = createTemporaryDirectory("omo-codex-project-")
+		writeOmoConfig(
+			homeDir,
+			JSON.stringify({
+				codegraph: { enabled: true, install_dir: "/base" },
+				"[codex]": { codegraph: { enabled: false } },
+				"[opencode]": { codegraph: { install_dir: "/opencode-only" } },
+			}),
+		)
+
+		// when
+		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
+
+		// then
+		expect(result.codegraph).toEqual({
+			auto_provision: true,
+			enabled: false,
+			install_dir: "/base",
+			telemetry: false,
+		})
+	})
+
+	it("#given legacy env override and SOT value #when loading config #then env wins over the SOT", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-env-")
+		const cwd = createTemporaryDirectory("omo-codex-project-env-")
+		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true } }))
+
+		// when
+		const result = getCodexOmoConfig({
+			cwd,
+			homeDir,
+			env: { CODEX_CODEGRAPH_ENABLED: "0" },
+		})
+
+		// then
+		expect(result.codegraph?.enabled).toBe(false)
+	})
+
+	it("#given no SOT files #when loading config #then returns built-in defaults and missing global source", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-defaults-")
+		const cwd = createTemporaryDirectory("omo-codex-project-defaults-")
+
+		// when
+		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
+
+		// then
+		expect(result.codegraph).toEqual({
+			auto_provision: true,
+			enabled: true,
+			telemetry: false,
+		})
+		expect(result.sources).toContainEqual({
+			exists: false,
+			loaded: false,
+			path: join(homeDir, ".omo", "config.jsonc"),
+			scope: "global",
+		})
+	})
+
+	it("#given codex-unsupported codegraph setting #when loading config #then returns loader warnings", () => {
+		// given
+		const homeDir = createTemporaryDirectory("omo-codex-shared-warnings-")
+		const cwd = createTemporaryDirectory("omo-codex-project-warnings-")
+		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { watch_debounce_ms: 42 } } }))
+
+		// when
+		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
+
+		// then
+		expect(result.warnings).toContain("codegraph.watch_debounce_ms is not supported for harness codex")
+	})
+})

package/packages/omo-codex/plugin/shared/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"declaration": false,
+		"noEmit": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["test/**/*"]
+}

package/packages/omo-codex/plugin/shared/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ESNext"],
+		"strict": true,
+		"esModuleInterop": true,
+		"allowImportingTsExtensions": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"types": ["bun-types"],
+		"noEmit": true
+	},
+	"include": ["src/**/*", "test/**/*"]
+}

package/packages/omo-codex/plugin/skills/ast-grep/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeongyu Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/omo-codex/plugin/skills/ast-grep/README.md

@@ -0,0 +1,136 @@
+# ast-grep-skill
+
+LLM-neutral skill for **AST-aware search and rewrite** across 25 languages. Wraps the [`ast-grep`](https://ast-grep.github.io/) (`sg`) CLI with offline pattern validation, the two-pass write trick, binary auto-resolution, and a per-OS installer.
+
+Same shape as [`web-fetch`](https://github.com/code-yeongyu/web-fetch) and [`web-search`](https://github.com/code-yeongyu/web-search), packaged as a standalone skill that any Bash-capable agent (Claude Code, OpenCode, pi, hermes, openclaw) can load.
+
+## Install
+
+```bash
+git clone https://github.com/code-yeongyu/ast-grep-skill ~/.agents/skills/ast-grep
+bash ~/.agents/skills/ast-grep/install.sh        # installs the ast-grep binary
+```
+
+That is it. The wrapper script is single-file Python 3 stdlib; no `pip install` needed. The installer tries `brew` → `npm` → `cargo` → `pip` → `nix` → `mise` → GitHub release in priority order, picks the first that works, and falls back to a cached binary at `<skill>/bin/sg`.
+
+### Symlink for active development
+
+```bash
+ln -s /path/to/your/clone ~/.agents/skills/ast-grep
+```
+
+### Other agents
+
+- **Claude Code / OpenCode**: drop the directory under `~/.agents/skills/` (or `~/.config/opencode/skills/`) and the skill auto-registers via the `name` + `description` in `SKILL.md` frontmatter.
+- **pi (`~/.senpi/agent`)**: not a `pi` extension — this is a skill. Pi consumes skills via `~/.agents/skills/` symlinks; the actual `pi-ast-grep` extension is at <https://github.com/code-yeongyu/pi-extensions>.
+- **Direct CLI use**: `python3 ~/.agents/skills/ast-grep/scripts/ast_grep_helper.py <subcommand>`.
+
+## Usage
+
+```bash
+# Search by AST pattern (the helper validates patterns offline first)
+python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/
+
+# Rewrite (dry-run preview by default)
+python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/
+
+# Apply the rewrite (two-pass: preview JSON + then --update-all)
+python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply
+
+# Run YAML lint rules from sgconfig.yml
+python3 scripts/ast_grep_helper.py scan src/
+
+# Validate a pattern OFFLINE (no sg call, no filesystem)
+python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
+# → exit 2: regex \w not supported. Use $VAR for identifiers.
+
+# Doctor: check ast-grep binary availability
+python3 scripts/ast_grep_helper.py doctor
+
+# List 25 supported languages
+python3 scripts/ast_grep_helper.py langs
+
+# Install / re-install the ast-grep binary
+python3 scripts/ast_grep_helper.py install
+```
+
+See [SKILL.md](./SKILL.md) for full agent-facing usage and the [`references/`](./references/) directory for deep dives.
+
+## Project layout
+
+```
+ast-grep-skill/
+├── SKILL.md                       agent-facing skill (loaded by Claude Code, OpenCode, pi, etc.)
+├── README.md                      this file
+├── LICENSE                        MIT
+├── install.sh                     POSIX installer (macOS / Linux / WSL / Git Bash)
+├── install.ps1                    Windows PowerShell installer
+├── scripts/
+│   └── ast_grep_helper.py         single-file Python 3 stdlib wrapper
+├── references/
+│   ├── install.md                 per-OS install methods + manual fallback
+│   ├── patterns.md                meta-variables ($VAR, $$$) and pattern syntax
+│   ├── pitfalls.md                regex anti-patterns + language-specific traps
+│   ├── recipes.md                 copy-paste patterns by language (TS/JS/Py/Go/Rust/...)
+│   ├── cli.md                     sg run / scan / test / new / lsp reference
+│   ├── yaml-rules.md              YAML rule schema (atomic / relational / composite / transform / fix)
+│   └── sgconfig.md                project configuration (ruleDirs, testConfigs, utilDirs)
+├── tests/
+│   ├── smoke.sh                   POSIX self-test
+│   └── smoke.ps1                  PowerShell self-test (Windows CI)
+└── .github/workflows/ci.yml       matrix CI: macos / ubuntu / windows × py 3.9-3.13
+```
+
+## What it does
+
+1. **Wraps `sg`** with a single Python 3 stdlib script that works the same on macOS, Linux, Windows, WSL, Git Bash.
+2. **Validates patterns offline** before calling `sg` — catches the regex-misuse class of mistakes (`\w`, `.*`, `|`, `[a-z]`) plus language-specific traps (Python trailing colons, JS/Go/Rust missing function bodies).
+3. **Resolves the binary** through 6 candidate paths: cached → PATH (with Linux `setgroups` collision detection) → Homebrew. Falls through to a clear install hint with copy-paste commands.
+4. **Runs the two-pass write trick** when applying rewrites — `sg run` silently ignores `--update-all` when `--json` is set, so `replace --apply` runs two invocations: pass 1 collects JSON matches, pass 2 mutates files.
+5. **Ships per-OS installers** that try every reasonable package manager and fall back to a GitHub release tarball.
+6. **Documents the failure modes** the model will hit (regex misuse, incomplete patterns, `--update-all` + `--json` trap, scope/type questions ast-grep can't answer) in `references/pitfalls.md`.
+
+## What it does NOT do
+
+- No type inference, scope analysis, or data flow. ast-grep is a structural matcher; for type-aware questions use TypeScript LSP, Pyright, Semgrep with type inference, or CodeQL.
+- No multi-repo federation. Run the helper once per repo.
+- No automatic `sgconfig.yml` discovery — it does what `sg scan` does (walk up from cwd looking for one).
+- No JS/Python rewriter authoring environment — for that, write YAML rules and use `sg test` for snapshot testing (see [`references/yaml-rules.md`](./references/yaml-rules.md)).
+
+## Limits
+
+- 5-minute timeout per `sg` invocation (configurable in the helper).
+- ast-grep itself supports 25 languages out-of-the-box. For anything else, use [`customLanguages`](./references/sgconfig.md#customlanguages-experimental) in `sgconfig.yml`.
+- Pattern hint detection is heuristic; pass `--force` to skip validation when you know the pattern is correct.
+
+## Requirements
+
+- Python ≥ 3.9 (stdlib only — no pip install).
+- `ast-grep` binary, installed via `install.sh` / `install.ps1` or one of:
+  - `brew install ast-grep` (macOS / linuxbrew)
+  - `npm install -g @ast-grep/cli` (any OS with Node)
+  - `cargo install ast-grep --locked` (any OS with Rust)
+  - `pip install ast-grep-cli` (any OS with Python)
+  - `scoop install main/ast-grep` (Windows)
+
+For older systems and Windows-specific setup, see [`references/install.md`](./references/install.md).
+
+## Testing
+
+```bash
+bash tests/smoke.sh        # POSIX (macOS / Linux / WSL / Git Bash)
+pwsh tests/smoke.ps1       # Windows (PowerShell 5.1+ or 7+)
+```
+
+CI runs the matrix on every push: `{macos-latest, ubuntu-latest, ubuntu-22.04, windows-latest}` × `{Python 3.9, 3.10, 3.11, 3.12, 3.13}` plus a syntax-floor check on Python 3.9 and 3.10.
+
+## License
+
+[MIT](./LICENSE).
+
+## Acknowledgments
+
+- [`omo` (oh-my-opencode)](https://github.com/code-yeongyu/oh-my-opencode) — `src/tools/ast-grep/` is the original tool implementation; this skill is a port of its pattern-hint detection and two-pass-write strategy.
+- [`pi-extensions/pi-ast-grep`](https://github.com/code-yeongyu/pi-extensions) — sibling Node port; the helper's binary-resolution cascade is modelled on it.
+- [ast-grep](https://github.com/ast-grep/ast-grep) — the CLI. All structural matching power comes from it.
+- [Anthropic skills](https://docs.anthropic.com/en/docs/claude-code/skills) — the `SKILL.md` + `references/` packaging convention.