oh-my-opencode 5.0.0-beta.17 → 5.0.0-beta.19

package/packages/shared-skills/skills/ast-grep/AGENTS.md

@@ -0,0 +1,51 @@
+# ast-grep — Vendored Structural-Search Skill
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+Vendored skill teaching agents ast-grep (`sg`) structural search/rewrite, plus a stdlib-Python helper CLI that wraps the `sg` binary. Vendoring pin in `SOURCE`: upstream `code-yeongyu/ast-grep-skill @ 3148c69` (ast-grep 0.45.0), "vendored as a sync; do not fork-drift". Earned this file: own executable surface (749-LOC helper + installers + smoke tests) and a no-fork-drift upstream contract that has no analogue elsewhere in `shared-skills`.
+
+## STRUCTURE
+
+```
+ast-grep/
+├── SKILL.md / README.md          # agent workflow / user overview
+├── SOURCE                        # upstream pin — the no-fork-drift contract
+├── scripts/ast_grep_helper.py    # 749-LOC stdlib CLI (argparse; no deps)
+├── install.sh / install.ps1      # macOS/Linux + Windows installers
+├── references/                   # cli, install, patterns, pitfalls, recipes, yaml-rules (510 LOC), sgconfig
+└── tests/smoke.{sh,ps1}          # POSIX + PowerShell smoke (also shell syntax + content checks)
+```
+
+## HELPER CLI (`scripts/ast_grep_helper.py`)
+
+Subcommands: `search`, `replace` (dry-run; `--apply` to write), `scan`, `test`, `new`, `langs`, `doctor`, `install`, `validate`. Resolves the `sg`/`ast-grep` binary across PATH, Homebrew, npm, and OMO caches, validates patterns before executing, and shells out — it never links ast-grep as a library. Internal handlers `cmd_*`; utilities `validate_pattern`, `normalize_lang`, `resolve_binary`, `run_sg`. Nothing in-repo imports it; docs and skills invoke it by path. `omo-opencode/src/cli/install-ast-grep-sg.ts` locates this skill dir to install the binary.
+
+## CONVENTIONS
+
+- AST patterns, never regex, for syntax-shaped queries; `$VAR` singles, `$$$` multis; patterns must parse as complete code in the target language.
+- Two-pass rewrites: preview with `--json=compact`, apply separately with `--update-all` — the flags are mutually exclusive in `sg`.
+- `sgconfig.yml` discovered upward; `ruleDirs`, optional `testConfigs`/`utilDirs`, language globs, custom languages, injections.
+- Upstream syncs land as whole vendored refreshes matching `SOURCE`; local edits ride along until the next sync absorbs or reverts them.
+
+## ANTI-PATTERNS
+
+- NO regex constructs (`.*`, `.+`, `\w`, `\d`, literal `|`) inside AST patterns — that is the skill's #1 pitfall.
+- No incomplete patterns (e.g. Python `def $F($$$):` without a body).
+- NEVER `--apply` a rewrite without the dry-run preview first.
+- Text/comment/byte queries go to `rg`, not structural matching.
+- Do not fork-drift from the `SOURCE` pin; a sync is a vendored refresh, not a merge.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/ast-grep/
+python3 scripts/ast_grep_helper.py search '<PATTERN>' --lang ts [path]
+python3 scripts/ast_grep_helper.py replace '<PATTERN>' '<REWRITE>' --lang ts   # dry-run; add --apply
+python3 scripts/ast_grep_helper.py doctor
+bash tests/smoke.sh          # or: pwsh tests/smoke.ps1
+# direct:  sg run -p '<PATTERN>' --lang ts path
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/shared-skills/skills/coding-agent-sessions/AGENTS.md

@@ -0,0 +1,62 @@
+# coding-agent-sessions — Cross-Platform Session Finder (Python)
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The only shared skill besides `ultimate-browsing` carrying a real sub-project: a Python package + CLI that finds, lists, searches, and reads local coding-agent session transcripts across ~25 platforms (Codex, Claude, OpenCode, OMO/Senpi/pi, and a long tail), normalizing them into one `Session` model. Earned this file: 33 files, 23 Python modules, own test suite, own `pyrightconfig.json`, own `.npmignore` (ships in the npm package minus tests/caches).
+
+## STRUCTURE
+
+```
+coding-agent-sessions/
+├── SKILL.md                      # router: platform table → references/<platform>.md
+├── references/                   # codex, claude, opencode, senpi, all-platforms (store layouts per platform)
+├── agents/openai.yaml            # Codex agent role declaration
+├── scripts/
+│   ├── find-agent-sessions.py    # thin shebang entry (PEP 723, >=3.11); runpy → agent_sessions.cli
+│   ├── agent_sessions/           # the package (12 modules)
+│   └── tests/                    # 6 pytest modules
+└── pyrightconfig.json            # extraPaths scripts/, excludes scripts/tests
+```
+
+## PUBLIC API (`scripts/agent_sessions/`)
+
+| Module | Key exports |
+|--------|-------------|
+| `scanners.py` | `scan`, `DEFAULT_PLATFORMS`, `PLATFORM_SCANNERS`, per-platform `scan_*` (codex, claude, opencode, senpi, oh_my_pi, gajae_code, …) |
+| `types.py` | `Session`, `Options`, `Json`, `JsonMap` — imported by nearly every module and test |
+| `transcript.py` | parallel file reads, normalization, timestamps, session ids; `recent`, `MAX_PLATFORM_FILES` |
+| `cli.py` | command parsing, filtering, payload construction, JSON emission (283 LOC — behavioral hotspot) |
+| platform adapters | `file_scanners.py` (file-backed providers), `opencode.py` (CLI/SQLite/storage fallbacks), `sqlite_scanners.py`, `sqlite_optional_scanners.py`, `pi_family.py`, `aside_scanner.py`, `kiro_scanner.py` |
+
+## CLI CONTRACT
+
+`python3 scripts/find-agent-sessions.py <command>`; aliases `find`=`search`, `read`=`get`. Commands: `list`, `find`/`search` (repeated `--query` lanes, `--from 7d`, repeated `--platform`, `--workers`, `--cwd/--model`, `--include-subagents`, `--limit`), `get`/`read <session-id>`. Output is JSON with `match_reasons` and reconstructed first/last user prompts — that JSON shape is the stable contract.
+
+## CONVENTIONS
+
+- Stdlib-only Python (`>=3.11`), `from __future__ import annotations`, pathlib everywhere; no third-party deps at runtime.
+- Probe-first, bounded discovery: platform-specific roots checked before broad globbing; optional platforms excluded from default search when they cannot reconstruct user prompts.
+- Main sessions hide subagent children by default but report child counts; `--include-subagents` flips it. Parent/child linkage preserved and records deduplicated.
+- Tests are pytest with `tmp_path` + `MonkeyPatch` isolation; in-file `# pyright: ignore[reportMissingImports]`-style relaxations for import diagnostics only.
+- `.npmignore` strips `scripts/tests/`, `pyrightconfig.json`, and caches from the shipped skill.
+
+## ANTI-PATTERNS
+
+- NEVER answer from normalized previews alone — pull the raw transcript (`read`/`get`) for exact evidence.
+- Usage-only stores are NOT transcript sources.
+- A Claude subagent's embedded `sessionId` is NOT its identity — use its `agentId` + parent-directory linkage.
+- Don't add a platform by globbing blindly; register it in `PLATFORM_SCANNERS`/`DEFAULT_PLATFORMS` with a bounded root probe.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/coding-agent-sessions/
+python3 scripts/find-agent-sessions.py list --limit 20
+python3 scripts/find-agent-sessions.py find "commit" --from 7d --platform senpi --platform opencode
+python3 scripts/find-agent-sessions.py read <session-id>
+pytest scripts/tests
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/shared-skills/skills/review-work/SKILL.md

@@ -90,7 +90,7 @@ Before launching agents, collect these inputs. Extract from conversation history
 </required_inputs>
 
 
-Review PRs and branches from a dedicated review worktree only: create or attach one with `git worktree add <path> <branch>` before collecting changed files, diff, file contents, or running checks. The main worktree is read-only context; never checkout, test, or edit the review branch there.
+Review PRs and branches from a dedicated review worktree only: create or attach one with `git worktree add <path> <branch>` before collecting changed files, diff, file contents, or running checks, then immediately lock it with `git worktree lock <path> --reason "review:<pr-or-branch>"`. The main worktree is read-only context; never checkout, test, or edit the review branch there.
 
 **Auto-collection sequence:**
 
@@ -530,8 +530,6 @@ OUTPUT FORMAT:
 """)
 ```
 
----
-
 ## Phase 2: Wait & Collect
 
 After launching all 5 agents in one turn, wait for completions in bounded
@@ -561,6 +559,8 @@ review result with the incomplete lane named. Do not spin in repeated
 wait/followup cycles. Do not use `multi_agent_v1.send_input` as an interrupt; queued
 followups are not cancellation.
 
+After ALL 5 lanes reach a terminal state and before delivering the verdict, tear down the review worktree: run `git worktree unlock <path>` followed by `git worktree remove <path>`. The lanes above run inside that worktree, so removing it earlier destroys their working directory; a crashed review leaves the locked tree as a recoverable marker for manual cleanup.
+
 ---
 
 ## Phase 3: Deliver Verdict

package/packages/shared-skills/skills/start-work/SKILL.md

@@ -102,6 +102,7 @@ For PR/branch work, a task-owned worktree is mandatory before implementation sta
 Solo orchestration with parallel background workers is the default topology. Decide once, when the wave's lanes are known, and record the verdict in the ledger:
 
 - **Independent lanes -> parallel workers.** Separate files, no shared contract: one parallel spawn burst; no team.
+- **Dependency-ordered lanes -> a dag run.** Sub-tasks with real ordering between them (C needs A and B finished first) and a harness with a native `dag` tool: dispatch the wave as ONE dag run — one producer node per lane plus a verification node — instead of a spawn burst, and watch the run's lifecycle instead of arming per-lane watchers. Read the `mass-ulw` skill's `SKILL.md` and `references/planning.md` IN FULL before defining any graph.
 - **Overlapping lanes -> a team.** The lanes touch the same module or contract AND running them concurrently actually finishes sooner: stand up a team (where the harness has one) so one lane's discoveries relay through you mid-flight.
 - **PR-mode independent lanes -> a worktree per lane.** Under `--make-pr`/`--ship`, when a wave holds independent checkboxes, give each lane its own branch and task-owned worktree, delivered as its own PR.
 
@@ -118,7 +119,7 @@ Landing rules, regardless of topology:
 3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections.
 4. Classify the checkbox tier and record it in its ledger entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency or transaction boundaries; a cross-domain refactor; or the plan or user signals care. When unsure, take HEAVY; upgrade and redo skipped gates the moment a HEAVY fact surfaces; never downgrade.
 5. Decompose that checkbox into atomic sub-tasks sized for ONE worker in ONE run — a sub-task that would need mid-flight steering is two sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently. A wave that could split further but holds fewer than 3 independent sub-tasks is under-split.
-6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); route named dependencies per the lane-topology decision above. Verification and checkbox marking stay per-checkbox.
 7. Give every dispatched sub-task its completion condition and watch for it per the section below. A dispatch whose completion nobody watches is an unfinished dispatch.
 
 ### Monitor every dispatched subagent to its completion condition

package/packages/shared-skills/skills/ultimate-browsing/SKILL.md

@@ -86,6 +86,8 @@ Routing table, per-platform auth (set `TWITTER_*` env vars, `gh auth login`, a t
 
 CloakBrowser is a stealth Chromium with source-level fingerprint patches that passes Cloudflare Turnstile, FingerprintJS, BrowserScan, and 30+ detectors; agent-browser is the CDP automation CLI that drives it. Both are runtime-installed tools (not vendored here). Full setup, version pins, launch flow, cookie login, and cross-platform notes are in [references/chrome-stealth.md](references/chrome-stealth.md).
 
+NEVER clear cookies, cache, or site data (`Network.clearBrowserCookies`, `Storage.clearCookies`, `chrome.browsingData.remove`, "clear browsing data") on the user's real/main browser profile — it wipes their logged-in state everywhere. If the task needs that profile's login state, clone the profile directory first (`rsync -a <profile>/ <tmp-clone>/`) and launch CloakBrowser / agent-browser with the clone as the user-data-dir; run any clearing on the clone only.
+
 ```bash
 # 1. Launch CloakBrowser with CDP on :9242 (see chrome-stealth.md for install + venv).
 # 2. CloakBrowser launches tabless — open the first tab via CDP before any agent-browser command:

package/packages/shared-skills/skills/ultimate-browsing/references/chrome-stealth.md

@@ -38,6 +38,8 @@ python -c "import cloakbrowser; print(cloakbrowser.__version__, cloakbrowser.CHR
 
 ## Launch + drive
 
+NEVER clear cookies, cache, or site data (`Network.clearBrowserCookies`, `Storage.clearCookies`, `chrome.browsingData.remove`, "clear browsing data") on the user's real/main browser profile — it wipes their logged-in state everywhere. If you need that profile's login state, clone it first (`rsync -a <profile>/ <tmp-clone>/`) and launch with the clone as the user-data-dir; run any clearing on the clone only.
+
 ```bash
 # 1. Launch CloakBrowser with CDP on :9242 (background). With the venv active:
 python -c "import asyncio,cloakbrowser; asyncio.run(cloakbrowser.launch_async(headless=False, stealth_args=True, args=['--remote-debugging-port=9242']))" &

package/packages/shared-skills/skills/visual-qa/AGENTS.md

@@ -0,0 +1,58 @@
+# visual-qa — Bundled Visual-Evidence CLI
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+The visual-QA skill's executable core: a zero-dependency Node CLI that produces machine evidence (`image-diff`, `tui-check`) plus the TypeScript sources it is bundled from. Earned this file: the only shared skill shipping a built bundle whose runtime and development sources must be kept in lockstep.
+
+## STRUCTURE
+
+```
+visual-qa/
+├── SKILL.md                      # reviewer workflow (dual oracle, evidence gates) — the prose contract
+├── references/agent-browser-setup.md
+└── scripts/
+    ├── visual-qa.mjs             # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
+    ├── cli.ts                    # development source; dispatches image-diff / tui-check
+    ├── image-diff.ts             # diffImages — 8x8 grid cells, hotspots, rounded metrics
+    ├── tui-grid.ts               # checkTui — column overflow + border alignment verdicts
+    ├── east-asian-width.ts       # charWidth / stringWidth — CJK-aware width math
+    ├── ansi.ts                   # ANSI escape stripping (width must be escape-aware)
+    ├── png-decode.ts / png-crc.ts / png-synth.ts   # stdlib PNG codec (no deps)
+    ├── types.ts
+    └── *.test.ts                 # co-located bun tests for every module above
+```
+
+## BUNDLE/SOURCE DUALITY
+
+`visual-qa.mjs` is the artifact the skill's commands invoke (`node "$SKILL_DIR/scripts/visual-qa.mjs" …`); the `.ts` files exist for development and tests only. A behavior fix lands in the TS source AND the bundle is regenerated from `cli.ts` — editing one without the other makes tests and runtime disagree. Never hand-edit the `.mjs`.
+
+## SURFACE
+
+- Commands: `image-diff <reference.png> <actual.png>` and `tui-check <capture.txt> --cols <N>`; JSON verdict output (hotspot cells, overflow lines, wide-char columns, border alignment).
+- Module exports: `diffImages`, `checkTui`, `charWidth`/`stringWidth`, ANSI + PNG helpers. `cli.ts` owns `CliError`, `parseColumns`, `run`, `main`.
+
+## CONVENTIONS
+
+- Zero runtime dependencies — PNG decode/synthesis and ANSI handling are hand-rolled in `scripts/`; keep it that way (the bundle must stay require-free apart from `node:` builtins).
+- Width is never `String.length`: CJK wide characters and ANSI escapes are accounted for before any column math.
+- Tests are co-located `bun test scripts/*.test.ts`, given/when/then style per repo convention.
+
+## ANTI-PATTERNS
+
+- NEVER hand-edit `visual-qa.mjs`; regenerate from source.
+- Don't add an npm dependency to make PNG/diff easier — the no-dep bundle is the point.
+- Column math that ignores CJK width or ANSI escapes is wrong by construction; `tui-check` exists because text-diff tools get terminal grids wrong.
+- Skill-level rule worth repeating for code changes: `tmux capture-pane` is forbidden as a capture mechanism.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/visual-qa/
+node scripts/visual-qa.mjs image-diff <reference.png> <actual.png>
+node scripts/visual-qa.mjs tui-check <capture.txt> --cols 80
+bun test scripts/*.test.ts
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).