## File: docs/architecture/cli-first-mcp-taxonomy.md # CLI-first MCP taxonomy Issue #2214 establishes a runtime-support boundary for OMX: **CLI/JSON is the canonical durable runtime and control-plane contract**. MCP remains useful, but it is an optional integration and compatibility layer rather than the authority for stateful orchestration. This page is intentionally a taxonomy and recovery guide. It does not change setup defaults, remove first-party MCP servers, or deprecate compatibility surfaces by itself. ## Contract levels | Level | Meaning | Support expectation | | --- | --- | --- | | Canonical CLI/JSON | The durable contract for automation, lifecycle control, state mutation, and recovery. | Document first. Keep machine-readable `--json` behavior stable or migrate it deliberately. | | CLI parity | A CLI command exposes the same durable state or read result as another surface. | Prefer it for scripts and recovery, especially when host integrations fail. | | MCP integration/compat | Optional host/editor/app integration or compatibility surface backed by OMX behavior. | Useful for convenience and existing workflows, but not the source of lifecycle authority. | | Deprecated/legacy | A surface retained only for migration or older workflows. | Point users to the canonical CLI/JSON command and avoid new automation against it. | ## Stateful control plane vs. read-only inspection Stateful lifecycle and mutation surfaces have stricter requirements than read-only inspection because they make decisions that can start, stop, resume, mutate, or recover a runtime. ### Stateful lifecycle and mutation surfaces These surfaces should have one canonical CLI/JSON owner: - mode/session state: `omx state ... --json` - team lifecycle and mutation: `omx team ...` and `omx team api ... --json` - durable memory writes: `omx notepad ... --json`, `omx project-memory ... --json`, and `omx wiki ... --json` - trace/runtime event mutation or cleanup paths where supported by the CLI MCP tools for these areas are compatibility or host-integration surfaces. If MCP transport or process lifecycle fails, retry through the documented CLI/JSON parity command rather than looping on the same MCP call. ### Read-only inspection surfaces Read-only inspection can remain broader and more convenient: - trace viewing and summaries - code-intel diagnostics/search - wiki reads and project-memory reads - status or inventory commands Inspection surfaces may expose both CLI parity and optional MCP integration. They should not be treated as runtime control-plane authority unless the operation mutates state or lifecycle. ## Canonical surface requirements A surface marked canonical should provide: 1. a stable `omx ...` CLI entrypoint, 2. machine-readable `--json` output for automation, 3. explicit MCP status such as parity, compat, integration, or deprecated, 4. documented fallback guidance for MCP stdio/process failures, 5. clear lifecycle ownership when the command can mutate runtime state. ## Compatibility and recovery matrix | Area | Operation type | Owner/canonical surface | MCP status | Fallback/parity surface | Recovery guidance | | --- | --- | --- | --- | --- | --- | | Team launch/lifecycle | Stateful lifecycle | `omx team ...` | Legacy/compat where applicable | `omx team ...` | Use the CLI launcher as the source of truth; avoid separate MCP runners for lifecycle ownership. | | Team mutation/read API | Stateful mutation and reads | `omx team api --input ... --json` | Legacy `team_*` tools are deprecated/compat | Same `omx team api ... --json` operation | When a host tool is stale or unavailable, replay the operation through the CLI JSON API. | | Mode/session state | Stateful mutation and reads | `omx state read/write/clear --input ... --json` | Compatibility | Same `omx state ... --json` command | If MCP stdio closes or reports transport failure, retry once through CLI parity with the same payload. | | Notepad | Durable memory mutation/read | `omx notepad ... --json` | Integration/compat | Same `omx notepad ... --json` command | Prefer CLI for durable writes and recovery because it is pasteable and auditable. | | Project memory | Durable memory mutation/read | `omx project-memory ... --json` | Integration/compat | Same `omx project-memory ... --json` command | Use CLI JSON for automation; MCP may be used by hosts that need inline memory tools. | | Wiki | Durable knowledge mutation/read | `omx wiki ... --json` | Supported integration with CLI parity | Same `omx wiki ... --json` command | Keep CLI parity documented first for scripts, recovery, and issue reproduction. | | Trace | Mostly read-only inspection, with CLI-owned cleanup where available | `omx trace ... --json` | Supported integration/compat | Same `omx trace ... --json` command | Treat read-only MCP trace tools as visibility aids; use CLI JSON for durable artifacts and recovery. | | Code intelligence | Read-only inspection | CLI/code-intel command surfaces where available | Optional integration | CLI diagnostics/search where available | Failures should not affect runtime lifecycle; fall back to CLI or local static checks. | | Shared MCP registry sync | Setup-time integration config | `omx setup` with explicit MCP compatibility mode/preferences | Optional setup integration | `omx setup --mcp compat` when MCP sync is desired | No-MCP setup mode should omit first-party MCP blocks while preserving user-authored MCP servers. | | First-party MCP servers | Optional integration | `omx mcp-serve ` for explicitly enabled clients | Optional compatibility/integration | Matching CLI/JSON command for durable operations | Keep servers available for opt-in clients; do not make them required for runtime-critical recovery. | ## Setup and migration posture Current safe sequencing is: 1. document the CLI-first taxonomy and recovery rules, 2. keep setup defaults stable unless a later product decision explicitly changes them, 3. support no-MCP or compatibility profiles with tests before any default flip, 4. update skills/templates/plugin wording after the taxonomy is accepted, 5. only consider fresh-default changes after owner approval, release notes, and compatibility coverage. This preserves MCP for users and clients that need it while making the durable automation path unambiguous. --- ## File: docs/audit/skills-agents-bloat-audit/bloat-audit.md # Bloat audit — skills + agents (omx) Generated 2026-05-23. Companion to `inventory.md`. Each entry is classified into one of: - **KEEP-AS-IS** — actively used, fits cleanly with neighbors. - **CONSOLIDATE** — duplicated or redundant with another surface; merge into the canonical entry. - **STREAMLINE** — useful but bloated; cut boilerplate or dead branches. - **DEPRECATE** — not used anywhere or superseded; remove from disk + manifest after a grace cycle. - **AMBIGUOUS — NEEDS OWNER DECISION** — could go either way; flagged for owner. Evidence per entry: catalog status (`src/catalog/manifest.json`), reference count (`rg -l -F` outside the entry's own directory), and where applicable LOC + most-recent commit. Risk level is the auditor's estimate of what could break if the entry were removed *as-is*. The full reference set per item is in `inventory.md`. > Style: classifications are deterministic functions of the data, not subjective. The same inputs would produce the same labels next month. Disagreement should be resolved against the data, not the prose. --- ## Inventory anomalies (resolve before per-entry triage) These are not classifications — they are catalog/disk consistency findings the owner should resolve before any deletion PR lands. ### A1. `wiki` skill is on disk but missing from `src/catalog/manifest.json` - **Evidence**: `find ./skills -maxdepth 2 -name 'SKILL.md'` returns `skills/wiki/SKILL.md`. `python3 -c "import json; m=json.load(open('src/catalog/manifest.json')); print(['wiki' in [s['name'] for s in m['skills']]])"` → `[False]`. The catalog hygiene test in `src/hooks/__tests__/skill-catalog-hygiene.test.ts` is the most likely surface to flag this. - **Impact**: any code that iterates the catalog manifest (e.g. setup flow, doctor checks, `installable.ts`) will not see `wiki`, so it may not be installed by `omx setup`. Direct invocation via `$wiki` still works because the prompt loader resolves by filename. - **Decision needed**: add the manifest row (`{ "name": "wiki", "category": "utility", "status": "active" }`) OR remove `skills/wiki/`. Pick by intent — is `$wiki` a supported user-facing surface, or an internal scratchpad? - **Owner default recommendation**: ADD the manifest row. The skill body is 43-reference-rich and is invoked from documented places. ### A2. Four manifest entries with no disk counterpart - **Names**: `configure-discord`, `configure-openclaw`, `configure-slack`, `configure-telegram` - **Status**: all `merged → configure-notifications`. - **Impact**: this is by design — `configure-notifications` is the canonical, and the four alias rows let `omx setup` accept legacy invocations. **No action needed**, listed here only so the next owner doesn't think it's a bug. ### A3. 17 on-disk skills not shipped via `plugins/oh-my-codex/skills/` - **Deprecated (no longer shipped, by design)** (16): `ask-claude`, `ask-gemini`, `build-fix`, `deepsearch`, `ecomode`, `frontend-ui-ux`, `help`, `note`, `ralph-init`, `review`, `security-review`, `swarm`, `tdd`, `trace`, `visual-verdict`, `web-clone` - **Other** (1): `git-master` - **Impact**: these directories exist only as tombstones so `src/catalog/__tests__/schema.test.ts` and `src/catalog/manifest.json` stay consistent. They are not installed for users; the only consumer is the lint+catalog test surface. - **Decision needed**: once the deprecated grace period passes, all 17 can be removed in a single sweep (PR-1 in the roadmap). Until then, leave alone. --- ## Skills Entries grouped by classification, then alphabetical. Each entry: `` → status → LOC, refs → classification → evidence → risk → one-line rationale. ### KEEP-AS-IS (16) #### `ai-slop-cleaner` - catalog: `status=active` `canonical=—` `category=shortcut` - shape: LOC=148 · ref_count=16 · shipped=yes - last commit: 2026-05-08 · docs: add UI design anti-slop signals (#2168) - evidence: Active skill, 148 LOC, 16 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `analyze` - catalog: `status=active` `canonical=—` `category=shortcut` - shape: LOC=146 · ref_count=28 · shipped=yes - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Active skill, 146 LOC, 28 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `ask` - catalog: `status=active` `canonical=—` `category=shortcut` - shape: LOC=58 · ref_count=295 · shipped=yes - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Active skill, 58 LOC, 295 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `autopilot` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=205 · ref_count=65 · shipped=yes - last commit: 2026-05-22 · Guard autopilot ralplan consensus handoff (review fixes) (#2 - evidence: Active skill, 205 LOC, 65 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `autoresearch` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=72 · ref_count=72 · shipped=yes - last commit: 2026-05-22 · Clarify research planning boundaries - evidence: Active skill, 72 LOC, 72 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `autoresearch-goal` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=36 · ref_count=20 · shipped=yes - last commit: 2026-05-22 · Clarify research planning boundaries - evidence: Active skill, 36 LOC, 20 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `design` - catalog: `status=active` `canonical=designer` `category=shortcut` - shape: LOC=180 · ref_count=62 · shipped=yes - last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow - evidence: Active skill, 180 LOC, 62 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `doctor` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=239 · ref_count=34 · shipped=yes - last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258) - evidence: Active skill, 239 LOC, 34 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `hud` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=98 · ref_count=86 · shipped=yes - last commit: 2026-03-11 · draft: bootstrap Rust CLI parity harness and initial omx com - evidence: Active skill, 98 LOC, 86 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `performance-goal` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=65 · ref_count=18 · shipped=yes - last commit: 2026-05-05 · Protect goal workflows with snapshot reconciliation - evidence: Active skill, 65 LOC, 18 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `pipeline` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=97 · ref_count=32 · shipped=yes - last commit: 2026-05-22 · Guard autopilot ralplan consensus handoff (review fixes) (#2 - evidence: Active skill, 97 LOC, 32 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `ralplan` - catalog: `status=active` `canonical=plan` `category=planning` - shape: LOC=187 · ref_count=77 · shipped=yes - last commit: 2026-05-23 · Merge branch 'dev' into omx-issue-2453-ralplan-ultragoal-doc - evidence: Active skill, 187 LOC, 77 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `ultragoal` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=131 · ref_count=68 · shipped=yes - last commit: 2026-05-20 · Avoid noisy fresh-session guidance in Ultragoal - evidence: Active skill, 131 LOC, 68 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `ultraqa` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=254 · ref_count=36 · shipped=yes - last commit: 2026-05-11 · Ensure UltraQA catches adversarial e2e regressions (#2276) - evidence: Active skill, 254 LOC, 36 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `ultrawork` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=175 · ref_count=46 · shipped=yes - last commit: 2026-05-20 · Make autopilot default to Ultragoal - evidence: Active skill, 175 LOC, 46 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. #### `visual-ralph` - catalog: `status=active` `canonical=designer` `category=shortcut` - shape: LOC=161 · ref_count=17 · shipped=yes - last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow - evidence: Active skill, 161 LOC, 17 refs. Sits cleanly in the current workflow set. - action: No action. - risk if removed: **low** - rationale: Active and well-connected; nothing to change. ### KEEP-AS-IS (alias) (1) #### `git-master` - catalog: `status=alias` `canonical=git-master` `category=shortcut` - shape: LOC=27 · ref_count=8 · shipped=no - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Alias for `git-master`. Shim is intentional. 27 LOC. - action: No action unless the canonical is itself being changed. - risk if removed: **low** - rationale: Alias entry redirects to `git-master`; intentional surface. ### KEEP-AS-IS (internal) (1) #### `worker` - catalog: `status=internal` `canonical=—` `category=utility` - shape: LOC=106 · ref_count=165 · shipped=yes - last commit: 2026-03-17 · fix: stop generating skill agents (#897) - evidence: Internal skill (106 LOC, refs 165). Used by an internal surface — do not expose, do not delete. - action: No action. - risk if removed: **low** - rationale: Internal-only utility; ship-blocked by design. ### STREAMLINE (optional) (7) #### `cancel` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=399 · ref_count=67 · shipped=yes - last commit: 2026-05-20 · Make autopilot default to Ultragoal - evidence: Active and well-connected (67 refs) but heavy (399 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `code-review` - catalog: `status=active` `canonical=code-reviewer` `category=shortcut` - shape: LOC=288 · ref_count=54 · shipped=yes - last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258) - evidence: Active and well-connected (54 refs) but heavy (288 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `deep-interview` - catalog: `status=active` `canonical=—` `category=planning` - shape: LOC=490 · ref_count=74 · shipped=yes - last commit: 2026-05-21 · Prefer Ultragoal for durable follow-up guidance - evidence: Active and well-connected (74 refs) but heavy (490 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `plan` - catalog: `status=active` `canonical=—` `category=planning` - shape: LOC=277 · ref_count=204 · shipped=yes - last commit: 2026-05-22 · Clarify research planning boundaries - evidence: Active and well-connected (204 refs) but heavy (277 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `ralph` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=294 · ref_count=141 · shipped=yes - last commit: 2026-05-19 · fix(ralph): enforce completion audit state contract (#2385) - evidence: Active and well-connected (141 refs) but heavy (294 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `skill` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=836 · ref_count=160 · shipped=yes - last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow - evidence: Active and well-connected (160 refs) but heavy (836 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. #### `team` - catalog: `status=active` `canonical=—` `category=execution` - shape: LOC=520 · ref_count=270 · shipped=yes - last commit: 2026-05-21 · Prefer Ultragoal for durable follow-up guidance - evidence: Active and well-connected (270 refs) but heavy (520 LOC). Streamline is *optional* — only worth doing if the content rotted relative to current contracts. - action: Defer until after the tombstone-deletion PR lands so the diff is easier to read. - risk if removed: **low** - rationale: Sized for its load, but a quality pass could still help. ### CONSOLIDATE — already collapsed (4) #### `configure-discord` - catalog: `status=merged` `canonical=configure-notifications` `category=utility` - shape: LOC=— · ref_count=0 · shipped=— - last commit: — (no dir) - evidence: Skill `configure-discord` exists only in the manifest, merged into `configure-notifications`. Manifest entry preserves the alias for `omx setup` lookups. - action: No directory under `./skills/configure-discord/` — already done. Keep manifest row unless owner decides to fully drop the public name. - risk if removed: **low** - rationale: Already merged into `configure-notifications`; manifest row is the only remaining surface. #### `configure-openclaw` - catalog: `status=merged` `canonical=configure-notifications` `category=utility` - shape: LOC=— · ref_count=0 · shipped=— - last commit: — (no dir) - evidence: Skill `configure-openclaw` exists only in the manifest, merged into `configure-notifications`. Manifest entry preserves the alias for `omx setup` lookups. - action: No directory under `./skills/configure-openclaw/` — already done. Keep manifest row unless owner decides to fully drop the public name. - risk if removed: **low** - rationale: Already merged into `configure-notifications`; manifest row is the only remaining surface. #### `configure-slack` - catalog: `status=merged` `canonical=configure-notifications` `category=utility` - shape: LOC=— · ref_count=0 · shipped=— - last commit: — (no dir) - evidence: Skill `configure-slack` exists only in the manifest, merged into `configure-notifications`. Manifest entry preserves the alias for `omx setup` lookups. - action: No directory under `./skills/configure-slack/` — already done. Keep manifest row unless owner decides to fully drop the public name. - risk if removed: **low** - rationale: Already merged into `configure-notifications`; manifest row is the only remaining surface. #### `configure-telegram` - catalog: `status=merged` `canonical=configure-notifications` `category=utility` - shape: LOC=— · ref_count=0 · shipped=— - last commit: — (no dir) - evidence: Skill `configure-telegram` exists only in the manifest, merged into `configure-notifications`. Manifest entry preserves the alias for `omx setup` lookups. - action: No directory under `./skills/configure-telegram/` — already done. Keep manifest row unless owner decides to fully drop the public name. - risk if removed: **low** - rationale: Already merged into `configure-notifications`; manifest row is the only remaining surface. ### DEPRECATE (16) #### `ask-claude` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=12 · ref_count=9 · shipped=no - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (9) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `ask-gemini` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=12 · ref_count=10 · shipped=no - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `build-fix` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=10 · ref_count=8 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (8) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `deepsearch` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=10 · ref_count=5 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (5) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `ecomode` - catalog: `status=deprecated` `canonical=—` `category=execution` - shape: LOC=114 · ref_count=10 · shipped=no - last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258) - evidence: Hard-deprecated stub (114 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `frontend-ui-ux` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=16 · ref_count=10 · shipped=no - last commit: 2026-05-11 · Establish DESIGN.md as the canonical design workflow - evidence: Hard-deprecated stub (16 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `help` - catalog: `status=deprecated` `canonical=—` `category=utility` - shape: LOC=10 · ref_count=161 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (161) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **medium** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `note` - catalog: `status=deprecated` `canonical=—` `category=utility` - shape: LOC=10 · ref_count=74 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (74) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **medium** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `ralph-init` - catalog: `status=deprecated` `canonical=—` `category=utility` - shape: LOC=10 · ref_count=6 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (6) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `review` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=10 · ref_count=163 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (163) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **medium** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `security-review` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=10 · ref_count=8 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (8) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `swarm` - catalog: `status=deprecated` `canonical=—` `category=execution` - shape: LOC=12 · ref_count=17 · shipped=no - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Hard-deprecated stub (12 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (17) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `tdd` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=104 · ref_count=6 · shipped=no - last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258) - evidence: Hard-deprecated stub (104 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (6) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `trace` - catalog: `status=deprecated` `canonical=—` `category=utility` - shape: LOC=10 · ref_count=41 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (41) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **medium** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `visual-verdict` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=10 · ref_count=9 · shipped=no - last commit: 2026-05-06 · Retire obsolete OMX skills (#2132) - evidence: Hard-deprecated stub (10 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (9) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. #### `web-clone` - catalog: `status=deprecated` `canonical=—` `category=shortcut` - shape: LOC=357 · ref_count=10 · shipped=no - last commit: 2026-05-10 · chore(skills): prune obsolete catalog entries - evidence: Hard-deprecated stub (357 LOC). Body explicitly says "Do not invoke or route this skill." Reference count (10) is concentrated in catalog/manifest entries and lint contract tests, not real consumers. - action: Once owner confirms no external `$` users remain, remove the directory and the manifest row in a single sweep. - risk if removed: **low** - rationale: Tombstone — body is already a redirect; remove directory + manifest row after grace period. ### AMBIGUOUS — NEEDS OWNER DECISION (5) #### `best-practice-research` - catalog: `status=active` `canonical=—` `category=planning` - shape: LOC=83 · ref_count=12 · shipped=yes - last commit: 2026-05-22 · Clarify research planning boundaries - evidence: Active skill but low connectivity (12 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned. - action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body. - risk if removed: **medium** - rationale: Data is inconclusive; owner sees the case better than the auditor. #### `configure-notifications` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=287 · ref_count=6 · shipped=yes - last commit: 2026-04-13 · Release 0.12.6 - evidence: Active skill but low connectivity (6 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned. - action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body. - risk if removed: **medium** - rationale: Data is inconclusive; owner sees the case better than the auditor. #### `omx-setup` - catalog: `status=active` `canonical=—` `category=utility` - shape: LOC=135 · ref_count=15 · shipped=yes - last commit: 2026-05-21 · Unblock plugin-scoped hooks from verifier - evidence: Active skill but low connectivity (15 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned. - action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body. - risk if removed: **medium** - rationale: Data is inconclusive; owner sees the case better than the auditor. #### `prometheus-strict` - catalog: `status=active` `canonical=—` `category=planning` - shape: LOC=219 · ref_count=11 · shipped=yes - last commit: 2026-05-23 · feat(prometheus-strict): require second planning round - evidence: Active skill but low connectivity (11 refs). Either the skill is doing important work that the rest of the codebase forgot to advertise, or it is quietly orphaned. - action: Owner should confirm it is still in the autopilot/ralplan/team narrative. If not, downgrade to internal or move into a parent skill's body. - risk if removed: **medium** - rationale: Data is inconclusive; owner sees the case better than the auditor. #### `wiki` - catalog: `status=NOT_IN_MANIFEST` `canonical=—` `category=—` - shape: LOC=57 · ref_count=43 · shipped=yes - last commit: 2026-05-11 · Prefer CLI-first OMX setup over MCP defaults (#2258) - evidence: On-disk skill `wiki` is not registered in `src/catalog/manifest.json`. Either add a manifest entry (so install/lint surfaces see it) or remove the directory. - action: Tests in `src/catalog/__tests__/schema.test.ts` reject unknown skills if they are not core; consistency tests in `src/hooks/__tests__/skill-catalog-hygiene.test.ts` may already flag this. Verify before adding. - risk if removed: **medium** - rationale: Data is inconclusive; owner sees the case better than the auditor. --- ## Agents Same format as skills. The 3 entries with `status=NOT_IN_MANIFEST` are the non-installable prompt assets listed in `src/agents/policy.ts` (`explore-harness`, `sisyphus-lite`, `team-orchestrator`). ### KEEP-AS-IS (18) #### `analyst` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=15 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis - evidence: Active agent, 15 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `architect` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=111 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only - evidence: Active agent, 111 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `code-reviewer` - catalog: `status=active` `canonical=—` `category=review` - shape: ref_count=21 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only - evidence: Active agent, 21 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `critic` - catalog: `status=active` `canonical=—` `category=coordination` - shape: ref_count=56 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only - evidence: Active agent, 56 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `debugger` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=25 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=standard · routingRole=executor · tools=analysis - evidence: Active agent, 25 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `dependency-expert` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=14 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis - evidence: Active agent, 14 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `designer` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=24 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution - evidence: Active agent, 24 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `executor` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=114 - definition (`src/agents/definitions.ts`): posture=— · modelClass=— · routingRole=— · tools=— - evidence: Active agent, 114 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `explore` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=99 - definition (`src/agents/definitions.ts`): posture=fast-lane · modelClass=fast · routingRole=specialist · tools=read-only - evidence: Active agent, 99 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `planner` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=35 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis - evidence: Active agent, 35 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `prometheus-strict-metis` - catalog: `status=active` `canonical=—` `category=coordination` - shape: ref_count=7 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis - evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `prometheus-strict-momus` - catalog: `status=active` `canonical=—` `category=coordination` - shape: ref_count=7 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=analysis - evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `prometheus-strict-oracle` - catalog: `status=active` `canonical=—` `category=coordination` - shape: ref_count=7 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis - evidence: Active agent, 7 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `researcher` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=33 - definition (`src/agents/definitions.ts`): posture=fast-lane · modelClass=standard · routingRole=specialist · tools=analysis - evidence: Active agent, 33 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `test-engineer` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=28 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=frontier · routingRole=executor · tools=execution - evidence: Active agent, 28 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `verifier` - catalog: `status=active` `canonical=—` `category=build` - shape: ref_count=23 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis - evidence: Active agent, 23 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `vision` - catalog: `status=active` `canonical=—` `category=coordination` - shape: ref_count=17 - definition (`src/agents/definitions.ts`): posture=fast-lane · modelClass=frontier · routingRole=specialist · tools=read-only - evidence: Active agent, 17 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. #### `writer` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=21 - definition (`src/agents/definitions.ts`): posture=fast-lane · modelClass=standard · routingRole=specialist · tools=execution - evidence: Active agent, 21 refs. Loaded into the current routing/pipeline narrative. - action: No action. - risk if removed: **low** - rationale: Used by current routing/pipeline. ### KEEP-AS-IS (internal) (2) #### `code-simplifier` - catalog: `status=internal` `canonical=—` `category=domain` - shape: ref_count=11 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=frontier · routingRole=executor · tools=execution - evidence: Intentional internal-only agent. Not surfaced for direct routing. - action: No action. - risk if removed: **low** - rationale: Intentional internal-only. #### `team-executor` - catalog: `status=internal` `canonical=—` `category=build` - shape: ref_count=9 - definition (`src/agents/definitions.ts`): posture=— · modelClass=— · routingRole=— · tools=— - evidence: Intentional internal-only agent. Not surfaced for direct routing. - action: No action. - risk if removed: **low** - rationale: Intentional internal-only. ### KEEP-AS-IS (non-installable asset) (3) #### `explore-harness` - catalog: `status=NOT_IN_MANIFEST` `canonical=—` `category=—` - shape: ref_count=12 - definition (`src/agents/definitions.ts`): posture=— · modelClass=— · routingRole=— · tools=— - evidence: Listed in `NON_NATIVE_AGENT_PROMPT_ASSETS` (`src/agents/policy.ts`). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent. - action: Verify the consuming skill (e.g. `sisyphus-lite` → `ralph`, `team-orchestrator` → `team`, `explore-harness` → `explore`) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep. - risk if removed: **medium** - rationale: Prompt asset for an embedded role; not directly installed. #### `sisyphus-lite` - catalog: `status=NOT_IN_MANIFEST` `canonical=—` `category=—` - shape: ref_count=5 - definition (`src/agents/definitions.ts`): posture=— · modelClass=— · routingRole=— · tools=— - evidence: Listed in `NON_NATIVE_AGENT_PROMPT_ASSETS` (`src/agents/policy.ts`). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent. - action: Verify the consuming skill (e.g. `sisyphus-lite` → `ralph`, `team-orchestrator` → `team`, `explore-harness` → `explore`) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep. - risk if removed: **medium** - rationale: Prompt asset for an embedded role; not directly installed. #### `team-orchestrator` - catalog: `status=NOT_IN_MANIFEST` `canonical=—` `category=—` - shape: ref_count=2 - definition (`src/agents/definitions.ts`): posture=— · modelClass=— · routingRole=— · tools=— - evidence: Listed in `NON_NATIVE_AGENT_PROMPT_ASSETS` (`src/agents/policy.ts`). Prompt is bundled into skills or used as a sub-prompt, not as a standalone Codex agent. - action: Verify the consuming skill (e.g. `sisyphus-lite` → `ralph`, `team-orchestrator` → `team`, `explore-harness` → `explore`) still pulls the prompt. If not, this is dead code and should be deleted in a follow-up sweep. - risk if removed: **low** - rationale: Prompt asset for an embedded role; not directly installed. ### CONSOLIDATE (10) #### `api-reviewer` - catalog: `status=merged` `canonical=code-reviewer` `category=review` - shape: ref_count=9 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only - evidence: Already merged into `code-reviewer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/api-reviewer.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/api-reviewer.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `code-reviewer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `information-architect` - catalog: `status=merged` `canonical=designer` `category=product` - shape: ref_count=7 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis - evidence: Already merged into `designer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/information-architect.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/information-architect.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `designer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `performance-reviewer` - catalog: `status=merged` `canonical=code-reviewer` `category=review` - shape: ref_count=13 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only - evidence: Already merged into `code-reviewer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/performance-reviewer.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/performance-reviewer.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `code-reviewer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `product-analyst` - catalog: `status=merged` `canonical=analyst` `category=product` - shape: ref_count=8 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis - evidence: Already merged into `analyst` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/product-analyst.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/product-analyst.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `analyst`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `product-manager` - catalog: `status=merged` `canonical=analyst` `category=product` - shape: ref_count=11 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis - evidence: Already merged into `analyst` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/product-manager.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/product-manager.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `analyst`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `qa-tester` - catalog: `status=merged` `canonical=test-engineer` `category=domain` - shape: ref_count=9 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution - evidence: Already merged into `test-engineer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/qa-tester.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/qa-tester.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `test-engineer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `quality-reviewer` - catalog: `status=merged` `canonical=code-reviewer` `category=review` - shape: ref_count=17 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=read-only - evidence: Already merged into `code-reviewer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/quality-reviewer.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/quality-reviewer.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **medium** - rationale: Already collapsed into `code-reviewer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `quality-strategist` - catalog: `status=merged` `canonical=verifier` `category=domain` - shape: ref_count=6 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=leader · tools=analysis - evidence: Already merged into `verifier` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/quality-strategist.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/quality-strategist.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `verifier`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `style-reviewer` - catalog: `status=merged` `canonical=code-reviewer` `category=review` - shape: ref_count=15 - definition (`src/agents/definitions.ts`): posture=fast-lane · modelClass=fast · routingRole=specialist · tools=read-only - evidence: Already merged into `code-reviewer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/style-reviewer.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/style-reviewer.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `code-reviewer`; entry stays for upgrade-path parity, schedule removal after grace cycle. #### `ux-researcher` - catalog: `status=merged` `canonical=designer` `category=product` - shape: ref_count=8 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=standard · routingRole=specialist · tools=analysis - evidence: Already merged into `designer` per catalog. Entry kept in `AGENT_DEFINITIONS` + `prompts/ux-researcher.md` only for `omx setup` parity with older installs. - action: After ≥1 release cycle of merged status, remove the `AGENT_DEFINITIONS` entry and the `prompts/ux-researcher.md` file. Keep the manifest row as `merged` for upgrade-path stability. - risk if removed: **low** - rationale: Already collapsed into `designer`; entry stays for upgrade-path parity, schedule removal after grace cycle. ### DEPRECATE (2) #### `build-fixer` - catalog: `status=deprecated` `canonical=—` `category=domain` - shape: ref_count=5 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution - evidence: Catalog marks this agent deprecated. ref_count 5 is mostly catalog/test boilerplate. - action: Confirm no skill body still names it; if clean, remove `AGENT_DEFINITIONS` entry, `prompts/build-fixer.md`, and any policy carve-outs. - risk if removed: **low** - rationale: Catalog says deprecated and references are catalog/test boilerplate. #### `security-reviewer` - catalog: `status=deprecated` `canonical=—` `category=review` - shape: ref_count=5 - definition (`src/agents/definitions.ts`): posture=frontier-orchestrator · modelClass=frontier · routingRole=leader · tools=read-only - evidence: Catalog marks this agent deprecated. ref_count 5 is mostly catalog/test boilerplate. - action: Confirm no skill body still names it; if clean, remove `AGENT_DEFINITIONS` entry, `prompts/security-reviewer.md`, and any policy carve-outs. - risk if removed: **low** - rationale: Catalog says deprecated and references are catalog/test boilerplate. ### AMBIGUOUS — NEEDS OWNER DECISION (1) #### `git-master` - catalog: `status=active` `canonical=—` `category=domain` - shape: ref_count=8 - definition (`src/agents/definitions.ts`): posture=deep-worker · modelClass=standard · routingRole=executor · tools=execution - evidence: Active agent with low connectivity (8 refs). Either underused or the work is delegated implicitly via routing. - action: Owner should confirm the agent has a live consumer. If not, downgrade to internal or merge into the closest neighbor. - risk if removed: **medium** - rationale: Active in catalog but low connectivity in code+skill bodies. --- ## Summary ### Skills | classification | count | |----------------|-------| | KEEP-AS-IS | 16 | | KEEP-AS-IS (alias) | 1 | | KEEP-AS-IS (internal) | 1 | | STREAMLINE (optional) | 7 | | CONSOLIDATE — already collapsed | 4 | | DEPRECATE | 16 | | AMBIGUOUS — NEEDS OWNER DECISION | 5 | | **total** | 50 | ### Agents | classification | count | |----------------|-------| | KEEP-AS-IS | 18 | | KEEP-AS-IS (internal) | 2 | | KEEP-AS-IS (non-installable asset) | 3 | | CONSOLIDATE | 10 | | DEPRECATE | 2 | | AMBIGUOUS — NEEDS OWNER DECISION | 1 | | **total** | 36 | Read this alongside `connectivity-roadmap.md` for the proposed PR-by-PR sequence to act on these classifications. --- *Generated for owner review. Re-run by regenerating `notes/combined.json` and re-running the bloat-audit generator.* --- ## File: docs/audit/skills-agents-bloat-audit/connectivity-roadmap.md # Connectivity roadmap — skills + agents (omx) Generated 2026-05-23. Companion to `inventory.md` and `bloat-audit.md`. This document is about the **organic connectivity** between skills and agents that the owner asked about: where a useful surface exists but the next-step links to its neighbors are missing, so the model can't find it during routing. It also lays out the recommended **PR-by-PR sequence** to land the bloat-audit cleanup safely. Every PR is scoped to be ≤30-minute review. --- ## How the data was collected Three signals were combined: 1. **`rg -l -F '' skills/ src/ prompts/ templates/`** — total reference count per skill and per agent (from `inventory.md`). False positives possible for English-word names (`ask`, `plan`, `team`, `note`, `review`, `help`). 2. **Skill body → agent name** — does each `SKILL.md` textually mention any agent name? Builds the *narrative coupling* matrix (in `inventory.md` § Skill → agent reference matrix). 3. **Agent prompt → skill name** — does each `prompts/.md` textually mention any skill name? Read against this evidence: a skill or agent is *orphan-ish* if it is `status=active` in the catalog AND it falls into ≥1 of the following: - zero other-skill bodies reference it, - zero active agents reference it (and it is a workflow/orchestration skill where agent routing would be expected), - zero active skills reference it (and it is a workflow/specialist agent where skill orientation would be expected), - its total `ref_count` is ≤ 15 AND it isn't a core skill. False-positive caveat: `ask` and `cancel` and `configure-notifications` and `omx-setup` mention no agents — but this is *not* orphan behavior, it is correct (they are infrastructure surfaces below the routing layer). Treat them as KEEP-AS-IS. --- ## Section 1 — Orphan analysis (the data) ### 1.1 Active skills whose body mentions zero active agents | skill | analysis | |-------|----------| | `ask` | Acceptable — `ask` is an *advisor CLI shim*, lives below the agent layer. No fix needed. | | `cancel` | Acceptable — `cancel` clears mode state; no agent role belongs in its body. No fix needed. | | `configure-notifications` | Acceptable — pure config skill. No fix needed. | | `omx-setup` | Acceptable — pure install/setup skill. No fix needed. | | `performance-goal` | **Orphan candidate**. The skill defines an "Agent Loop" section but does not name any of `executor`, `test-engineer`, `verifier`, or `quality-strategist`. A reader (or the model in routing) has no signal of which agent runs the optimization patches or the evaluator. | ### 1.2 Active skills NOT referenced by any other skill body | skill | analysis | |-------|----------| | `prometheus-strict` | Entry-point skill. It is *meant* to be invoked directly (`$prometheus-strict`), so a one-way fan-out is expected. But neither `autopilot` nor `plan` nor `ralplan` currently link to it as a deeper-rigor alternative — and the bloat-audit shows `autopilot` already chains `$deep-interview → $ralplan`, so there's a clean place to mention `prometheus-strict` as the *high-stakes* variant. **Soft fix recommended.** | ### 1.3 Active skills with weak inter-skill connectivity (≤ 2 other-skill refs) | skill | currently referenced by | observation | |-------|------------------------|-------------| | `ai-slop-cleaner` | `ralph`, `ultragoal` | `autopilot` also runs a deslop step in spirit but never names this skill. Adding the name to `autopilot`'s skill body would close the loop. | | `configure-notifications` | `omx-setup` | After deprecated `help` is removed (PR-1), this stays connected via `omx-setup`. No fix needed. | | `doctor` | `help` (deprecated), `omx-setup` | After `help` is removed, falls to 1 ref. **Soft fix**: cross-reference `doctor` from `omx-setup`'s troubleshooting paragraph and from `configure-notifications`'s "diagnose webhook issues" section. | | `omx-setup` | `help` (deprecated) | After `help` is removed, ZERO inter-skill refs. **Soft fix**: cross-reference `omx-setup` from `doctor`'s recovery instructions. | ### 1.4 Active agents with low total reference count | agent | refs | notes | |-------|------|-------| | `prometheus-strict-metis` | 7 | Tightly coupled to `prometheus-strict` skill. Working as intended. No fix. | | `prometheus-strict-momus` | 7 | Same as above. | | `prometheus-strict-oracle` | 7 | Same as above. | | `git-master` (agent) | 8 | Mostly catalog/template refs. Not mentioned by `$code-review` or `$plan` bodies even though commit hygiene is a natural part of either. **Soft fix**: add a "for commit strategy, defer to `git-master`" line in `code-review` and in `plan` (post-implementation step). | | `dependency-expert` | 14 | Referenced from `best-practice-research` only. Could be cross-linked from `analyze` (when a question is about an external SDK) and from `ralplan` (when a plan touches a new dependency). | | `vision` | 17 | Used by `team` and `visual-ralph`. Could also be cross-linked from `code-review` (for screenshots) and `design` (for reference images). | ### 1.5 Agents with empty `prompts/.md` skill mentions All 33 active agents mention at least one active skill in their prompt body (`ag_to_sk` returned no empty sets). The most-common backlink is to `$ask`, which is mentioned by **every** agent prompt — confirming `ask` is the canonical advisor backstop. No orphan agents on this signal. --- ## Section 2 — Connectivity fixes Recommendations are grouped by effort. Each carries the proposed concrete edit and which file would change. No edits are made in this PR — they are queued for follow-ups. ### 2.1 Quick wins (single-file edit, <30 min each) | # | edit | file | proposed change | risk | |---|------|------|-----------------|------| | Q1 | Name agents in `performance-goal` Agent Loop | `skills/performance-goal/SKILL.md` | Step 3 (`Optimize in small reversible patches`) → "via `executor`" or "via the planner+executor lane". Step 4 (`Run the evaluator and related regression tests`) → "via `test-engineer` when adjustments to the eval suite are needed". | low — pure documentation | | Q2 | Cross-link `omx-setup` ↔ `doctor` | `skills/omx-setup/SKILL.md`, `skills/doctor/SKILL.md` | In `omx-setup`'s troubleshooting paragraph add: "If setup completes but a subsystem misbehaves, run `$doctor`." In `doctor`'s top: "If `omx` itself isn't installed yet, run `$omx-setup` first." | low | | Q3 | Cross-link `configure-notifications` → `doctor` | `skills/configure-notifications/SKILL.md` | Bottom of the file: "If a webhook fails after configuration, run `$doctor` to surface logged delivery errors." | low | | Q4 | Cross-link `autopilot` → `ai-slop-cleaner` | `skills/autopilot/SKILL.md` | In the "+ optional cleanup" line in the Purpose block: explicitly name `$ai-slop-cleaner`. Currently the body refers only obliquely to anti-slop. | low | | Q5 | Cross-link `code-review` → `git-master` | `skills/code-review/SKILL.md` | In the post-review/commit-prep step: "For commit-message rewrite or split, defer to the `git-master` agent." | low | | Q6 | Cross-link `analyze` → `dependency-expert` | `skills/analyze/SKILL.md` | In the "When the question is about an external SDK/package, prefer `dependency-expert`" subsection: replace soft phrasing with the explicit agent name. | low | | Q7 | Cross-link `ralplan` → `dependency-expert` | `skills/ralplan/SKILL.md` | In the planning-time risk-flag section: "When the plan touches a new SDK or external API, escalate to `dependency-expert` before sequencing." | low | | Q8 | Cross-link `design` → `vision` | `skills/design/SKILL.md` | In the reference-image acceptance step: "For raster reference comparison, route image analysis to `vision`." | low | | Q9 | Add `prometheus-strict` mention to `autopilot` | `skills/autopilot/SKILL.md` | One-line note: "For high-stakes / mathematically gated work, swap `$deep-interview` for `$prometheus-strict`." | low | | Q10 | Resolve `wiki` skill manifest gap | `src/catalog/manifest.json` | Add `{ "name": "wiki", "category": "utility", "status": "active" }` (see anomaly A1 in `bloat-audit.md`). | medium — verify lint contract test | ### 2.2 Medium-effort (multi-file or requires test) | # | edit | files | proposed change | risk | |---|------|-------|-----------------|------| | M1 | Land the deprecated-skill tombstone sweep | `skills/{ask-claude,ask-gemini,build-fix,deepsearch,ecomode,frontend-ui-ux,help,note,ralph-init,review,security-review,swarm,tdd,trace,visual-verdict,web-clone}/`, `src/catalog/manifest.json`, plus any test that hard-codes those names | Delete the 16 tombstone directories; downgrade their manifest rows from `status=deprecated` to actually-removed-from-shipped (a `removed` status, OR drop the rows if the schema already accepts removal). Update `src/catalog/__tests__/schema.test.ts` and `src/hooks/__tests__/skill-catalog-hygiene.test.ts`. | medium — touches catalog tests. Pre-flight: confirm `omx setup` no longer warns missing aliases. | | M2 | Land the merged-agent sweep | `src/agents/definitions.ts`, `prompts/{api-reviewer,quality-reviewer,style-reviewer,performance-reviewer,quality-strategist,qa-tester,product-manager,product-analyst,ux-researcher,information-architect}.md`, `src/agents/__tests__/definitions.test.ts` | Remove the 10 merged-agent entries from `AGENT_DEFINITIONS` and their `prompts/.md` files. Keep manifest rows as `merged → ` so upgrade paths from old installs still resolve. | medium — agent prompts may still be referenced by lint tests; verify. | | M3 | Land the deprecated-agent sweep | `src/agents/definitions.ts`, `prompts/{security-reviewer,build-fixer}.md` | Remove the 2 `deprecated` agent entries and their prompts. | low — refs are catalog/test only | | M4 | Reconcile `git-master` skill alias | `skills/git-master/SKILL.md` | Confirm intent: keep the skill alias (27 LOC) as a shim for `$git-master` → `git-master` agent invocation. If yes, leave as-is. If owner prefers a pure-agent route, remove the skill alias and bump the agent's `category` or its routing surface accordingly. | medium — affects user-facing `$git-master` invocation | ### 2.3 Strategic items (owner judgment required) | # | proposal | rationale | |---|----------|-----------| | S1 | Decide the long-term fate of the 4 `configure-*` merged manifest rows. | They're currently kept to absorb legacy invocations like `$configure-discord`. Owner can decide if they keep them for ≥2 more releases (low cost, modest catalog noise) or drop them now (cleaner but breaks one-shot users who still type the merged names). | | S2 | Decide whether `prometheus-strict-{metis,momus,oracle}` should remain three separate `AGENT_DEFINITIONS` rows or become one composite agent with three modes. | Today each is a distinct entry but they only ever run together inside `prometheus-strict`. Three rows make the prompt boundary explicit; one composite simplifies the catalog at the cost of a longer single prompt. Owner-only call. | | S3 | Decide whether `team-executor` should remain an `internal` agent or become `active`. | Today it is internal; `team` skill body still mentions it. Promoting it to active makes `$team-executor` directly invocable; keeping it internal preserves the routing-through-`team` invariant. | | S4 | Decide whether `worker` skill should stay `internal` or be split. | `worker` has 165 references — by far the highest among internal skills — because it is referenced by every team-runtime test. Owner should confirm this is intended; if so, no change. If `worker` is becoming a public-facing concept, promote it. | | S5 | Decide whether `wiki` skill is a supported user surface. | The catalog manifest gap (anomaly A1) is the immediate symptom. The deeper question is whether the wiki workflow is a first-class skill (and so needs the manifest row + install path) or an internal Code-side surface (and so should not be in `./skills/` at all). | | S6 | Decide whether `performance-goal` belongs as its own skill or as a variant of `ultragoal`. | `performance-goal` is the only `*-goal` skill besides `ultragoal` and `autoresearch-goal`. Either keep all three as siblings (current shape) or fold `performance-goal` into `ultragoal` as a `--performance` mode. The latter would let `ultragoal`'s evaluator-gated loop subsume it. | --- ## Section 3 — Suggested PR-split The proposed sequence is **deprecations first**, **consolidations second**, **connectivity edits third**. This ordering ensures every connectivity fix lands against the final shape of the catalog rather than a transitional one, and avoids the wasted review-time of editing a soon-to-be-removed file. Each PR is sized so the review is ≤30 min for someone who has read this document. All PRs target `dev`, not `main`. ### Phase A — Tombstone deletion (clears the floor) **PR-1** — `chore(skills): remove 16 deprecated tombstone skills` - Type: `chore` (deletion) - Touches: 16 skill directories + `src/catalog/manifest.json` + 2 catalog tests - Scope: delete the 16 directories listed in M1; for each, either remove the manifest row entirely or change its `status` to a new `removed` value (owner picks one). - Pre-flight: grep `rg -l -F ''` for each before deletion — if any source file (not test) still hard-codes the name, fix that source file in the same PR or pull it into a follow-up. - Risk: medium. Catalog tests are the only real surface. - Depends on: nothing. **PR-2** — `chore(agents): remove 10 merged + 2 deprecated agents` - Type: `chore` (deletion) - Touches: `src/agents/definitions.ts` (12 entries), 12 `prompts/*.md`, possibly `src/agents/__tests__/definitions.test.ts` - Scope: remove the 10 `merged` agents (api-reviewer, quality-reviewer, style-reviewer, performance-reviewer, quality-strategist, qa-tester, product-manager, product-analyst, ux-researcher, information-architect) and the 2 `deprecated` agents (security-reviewer, build-fixer) from both `AGENT_DEFINITIONS` and the `prompts/` tree. Keep the manifest rows as `merged → ` for upgrade-path stability. - Pre-flight: grep each agent name in `skills/*/SKILL.md` — they should not appear in any active skill body. If they do, that's actually an M2 follow-up — bring it into this PR or split. - Risk: medium. Some agents may still be in lint tests as expected entries. - Depends on: PR-1 (so the cleanup is a single bloat-removal phase rather than two interleaved ones). ### Phase B — Inventory anomaly resolution **PR-3** — `chore(catalog): add wiki to manifest OR remove skills/wiki` - Type: `chore` (catalog) OR `chore` (deletion) - Touches: `src/catalog/manifest.json` + `src/catalog/__tests__/` (one row OR a directory removal + test rule) - Scope: resolve anomaly A1. Default recommendation in `bloat-audit.md` is ADD the row. Owner picks. - Depends on: nothing (can land before, during, or after PR-1/PR-2). Listed here for the sequence. ### Phase C — Connectivity quick wins (docs-only) These are all SKILL.md edits. They can land as a single PR or split — but they should land *after* Phase A so the editor isn't writing references to dead skills. **PR-4** — `docs(skills): wire orphan-ish surfaces into their neighbors` - Type: `docs` - Touches: `skills/{performance-goal,omx-setup,doctor,configure-notifications,autopilot,code-review,analyze,ralplan,design}/SKILL.md` (≈9 single-line additions per Q1–Q9) - Scope: apply Q1 through Q9 from § 2.1. - Risk: low. Pure documentation. - Depends on: PR-1 (so `help` is gone before we'd cross-link from it), PR-2 (so we're not referencing a now-removed agent like `qa-tester`). ### Phase D — Strategic decisions (one PR each, owner-routed) These do NOT have a default recommendation in this document. Each lands as its own owner-approved PR. **PR-5 (optional)** — `refactor(agents): merge prometheus-strict triple into one composite` (S2) — only if owner picks the composite option. **PR-6 (optional)** — `refactor(agents): promote team-executor to active` (S3) — only if owner decides. **PR-7 (optional)** — `chore(catalog): drop legacy configure-* merged rows` (S1) — only after ≥2 more releases. **PR-8 (optional)** — `refactor(skills): fold performance-goal into ultragoal --performance` (S6) — only if owner decides. ### Dependency graph ```text PR-1 (chore: delete tombstones) ───┐ ├──► PR-4 (docs: connectivity quick wins) PR-2 (chore: delete merged agents)─┘ PR-3 (chore: resolve wiki anomaly) — independent, can land anywhere PR-5..8 — owner-routed, no fixed sequence among themselves; can land after PR-4 or independently if their scope doesn't overlap PR-4 edits. ``` --- ## Section 4 — Risk + verification per PR For each PR above, the minimum verification before landing: | PR | verification | |----|--------------| | PR-1 | `npm run lint:deps` (optional), `npm test -- src/catalog` (catalog tests), `npm test -- src/hooks/__tests__/skill-catalog-hygiene` to ensure the tombstone removal does not break the hygiene contract. | | PR-2 | `npm test -- src/agents`, `npm test -- src/cli/__tests__/setup-prompts-overwrite` (because that test enumerates expected prompt files), and a manual `omx setup --dry-run` if reachable. | | PR-3 | If adding the row: re-run `src/catalog/__tests__/schema.test.ts`. If removing the dir: also re-run any `wiki` prompt enumeration test. | | PR-4 | Pure docs. CI should be a no-op other than markdown lint. | | PR-5..8 | Owner-routed; verification scope decided per PR. | --- ## Section 5 — What this roadmap deliberately does NOT do - It does not propose deleting the `configure-{discord,telegram,slack,openclaw}` merged manifest rows. Those are intentional upgrade-path absorbers. Removing them is a separate strategic decision (S1). - It does not propose adding new skills. The owner explicitly asked for bloat triage + connectivity; new skills are out of scope. - It does not propose touching `src/agents/policy.ts` or `src/agents/native-config.ts` beyond what is already covered by removing the merged/deprecated entries from `AGENT_DEFINITIONS`. Those files' logic is sound; only the data they operate on is shrinking. - It does not propose rewriting any of the 7 STREAMLINE (optional) skills. Per `bloat-audit.md`, those are deferred until after the tombstone deletion lands so the diff stays small. - It does not propose any change to `./prompts/explore-harness.md`, `./prompts/sisyphus-lite.md`, or `./prompts/team-orchestrator.md`. They are intentionally non-installable per `src/agents/policy.ts`'s `NON_NATIVE_AGENT_PROMPT_ASSETS`. --- ## Section 6 — Quick reference Counts at a glance (drawn from `bloat-audit.md` § Summary): - Skills to **DEPRECATE**: 16 → PR-1 - Agents to **CONSOLIDATE**: 10 → PR-2 (merged) - Agents to **DEPRECATE**: 2 → PR-2 (deprecated) - Skills with manifest anomaly: 1 (`wiki`) → PR-3 - Connectivity quick wins: 9 → PR-4 - Strategic decisions outstanding: 6 (S1–S6) → PR-5..8 (optional) After PR-1 through PR-4 land, the surface is: - ~30 skills (currently 50 catalog entries; 46 on-disk → 30 on-disk after tombstone deletion). - ~21 agents (currently 33 in `AGENT_DEFINITIONS` → 21 after consolidation/deprecation). - Zero on-disk skills missing from the manifest (anomaly A1 closed). - Every active skill has at least one cross-skill link (or is intentionally below the cross-link layer). That is the target shape this roadmap moves toward. --- *Generated for owner review. Re-run by regenerating `notes/combined.json` and recomputing the orphan analysis.* --- ## File: docs/audit/skills-agents-bloat-audit/inventory.md # Inventory — skills + agents (omx) Generated 2026-05-23. Data sources: `src/catalog/manifest.json`, `src/agents/definitions.ts`, `git log -1 -- skills//`, and `rg -l --no-messages -F '' skills/ src/ prompts/ templates/`. - **Total skills**: 50 (46 on disk + 4 merged-only in manifest). - **Total agents**: 36 (33 in `AGENT_DEFINITIONS` + 3 non-installable prompt assets: `explore-harness`, `sisyphus-lite`, `team-orchestrator`). - **Catalog statuses** (`src/catalog/schema.ts`): `active` | `internal` | `alias` | `merged` | `deprecated`. - **Shipped surface** is `plugins/oh-my-codex/skills/` (29 dirs). Anything in `./skills/` but not in `./plugins/oh-my-codex/skills/` is a *catalog-only shadow* (kept on disk to preserve the public/catalog contract while no longer being installed). Conventions in the tables below: - `ref_count` = number of files (outside the skill/agent's own directory and outside its own prompts/*.md) matching the literal name via `rg -l -F`. False positives are possible for short, English-word names (e.g. `ask`, `plan`, `note`, `help`, `review`, `team`). Treat these as upper bounds; structural references in `src/catalog/*`, `templates/`, and `src/cli/*` are the most load-bearing. - `shipped` = directory exists under `plugins/oh-my-codex/skills/`. - `last_commit` = `%cs %s` of the newest commit that touched the skill directory (`git log -1 --format='%cs|%s' -- skills//`). For agents, the relevant signal lives in `src/agents/definitions.ts` (single file) plus the agent's `prompts/.md`; per-agent commit dates were not separately rolled up because the central `definitions.ts` aggregates them. ## Skills Sorted alphabetically. All paths relative to repo root. | # | skill | status | canonical | category | shipped | LOC | last_commit (date \| msg head) | refs | description (head) | |---|-------|--------|-----------|----------|---------|-----|--------------------------------|------|--------------------| | 1 | `ai-slop-cleaner` | active | — | shortcut | yes | 148 | 2026-05-08 \| docs: add UI design anti-slop signals (#2168) | 16 | Run an anti-slop cleanup/refactor/deslop workflow | | 2 | `analyze` | active | — | shortcut | yes | 146 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 28 | Run read-only deep repository analysis and return a ranked synthesis with explic | | 3 | `ask` | active | — | shortcut | yes | 58 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 295 | Ask a local external advisor CLI (Claude or Gemini) and capture a reusable artif | | 4 | `ask-claude` | deprecated | — | shortcut | no | 12 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 9 | Deprecated compatibility shim for Claude advisor requests | | 5 | `ask-gemini` | deprecated | — | shortcut | no | 12 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 10 | Deprecated compatibility shim for Gemini advisor requests | | 6 | `autopilot` | active | — | execution | yes | 205 | 2026-05-22 \| Guard autopilot ralplan consensus handoff (review fixes) (#2 | 65 | [OMX] Strict autonomous loop: $deep-interview -> $ralplan -> $ultragoal (+ $team | | 7 | `autoresearch` | active | — | execution | yes | 72 | 2026-05-22 \| Clarify research planning boundaries | 72 | Stateful validator-gated research loop with native-hook persistence | | 8 | `autoresearch-goal` | active | — | execution | yes | 36 | 2026-05-22 \| Clarify research planning boundaries | 20 | Durable professor-critic research workflow over Codex goal mode without reviving | | 9 | `best-practice-research` | active | — | planning | yes | 83 | 2026-05-22 \| Clarify research planning boundaries | 12 | [OMX] Bounded best-practice research wrapper using official/upstream evidence fi | | 10 | `build-fix` | deprecated | — | shortcut | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 8 | Build Fix deprecated shim | | 11 | `cancel` | active | — | utility | yes | 399 | 2026-05-20 \| Make autopilot default to Ultragoal | 67 | Cancel any active OMX mode (autopilot; ralph; ultrawork; ecomode; ultraqa; swarm | | 12 | `code-review` | active | code-reviewer | shortcut | yes | 288 | 2026-05-11 \| Prefer CLI-first OMX setup over MCP defaults (#2258) | 54 | Run a comprehensive code review | | 13 | `configure-discord` | merged | configure-notifications | utility | — | — | — (no dir) | 0 | | | 14 | `configure-notifications` | active | — | utility | yes | 287 | 2026-04-13 \| Release 0.12.6 | 6 | Configure OMX notifications - unified entry point for all platforms | | 15 | `configure-openclaw` | merged | configure-notifications | utility | — | — | — (no dir) | 0 | | | 16 | `configure-slack` | merged | configure-notifications | utility | — | — | — (no dir) | 0 | | | 17 | `configure-telegram` | merged | configure-notifications | utility | — | — | — (no dir) | 0 | | | 18 | `deep-interview` | active | — | planning | yes | 490 | 2026-05-21 \| Prefer Ultragoal for durable follow-up guidance | 74 | Socratic deep interview with mathematical ambiguity gating before execution | | 19 | `deepsearch` | deprecated | — | shortcut | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 5 | Deepsearch deprecated shim | | 20 | `design` | active | designer | shortcut | yes | 180 | 2026-05-11 \| Establish DESIGN.md as the canonical design workflow | 62 | Canonical repo-local DESIGN.md workflow for product; UI/UX; and frontend decisio | | 21 | `doctor` | active | — | utility | yes | 239 | 2026-05-11 \| Prefer CLI-first OMX setup over MCP defaults (#2258) | 34 | Diagnose and fix oh-my-codex installation issues | | 22 | `ecomode` | deprecated | — | execution | no | 114 | 2026-05-11 \| Prefer CLI-first OMX setup over MCP defaults (#2258) | 10 | Ecomode deprecated shim | | 23 | `frontend-ui-ux` | deprecated | — | shortcut | no | 16 | 2026-05-11 \| Establish DESIGN.md as the canonical design workflow | 10 | Deprecated compatibility shim for frontend UI/UX work; use $design or $visual-ra | | 24 | `git-master` | alias | git-master | shortcut | no | 27 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 8 | Git expert for atomic commits; rebasing; and history management | | 25 | `help` | deprecated | — | utility | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 161 | Help deprecated skill | | 26 | `hud` | active | — | utility | yes | 98 | 2026-03-11 \| draft: bootstrap Rust CLI parity harness and initial omx com | 86 | Show or configure the OMX HUD (two-layer statusline) | | 27 | `note` | deprecated | — | utility | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 74 | Note deprecated shim | | 28 | `omx-setup` | active | — | utility | yes | 135 | 2026-05-21 \| Unblock plugin-scoped hooks from verifier | 15 | Setup and configure oh-my-codex using current CLI behavior | | 29 | `performance-goal` | active | — | execution | yes | 65 | 2026-05-05 \| Protect goal workflows with snapshot reconciliation | 18 | Run an evaluator-gated performance optimization workflow over Codex goal mode wi | | 30 | `pipeline` | active | — | execution | yes | 97 | 2026-05-22 \| Guard autopilot ralplan consensus handoff (review fixes) (#2 | 32 | Configurable pipeline orchestrator for sequencing stages | | 31 | `plan` | active | — | planning | yes | 277 | 2026-05-22 \| Clarify research planning boundaries | 204 | Strategic planning with optional interview workflow | | 32 | `prometheus-strict` | active | — | planning | yes | 219 | 2026-05-23 \| feat(prometheus-strict): require second planning round | 11 | [OMX] Clean-room interview-driven planner: Metis clarifies; Momus challenges; Or | | 33 | `ralph` | active | — | execution | yes | 294 | 2026-05-19 \| fix(ralph): enforce completion audit state contract (#2385) | 141 | Self-referential loop until task completion with architect verification | | 34 | `ralph-init` | deprecated | — | utility | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 6 | Ralph Init deprecated skill | | 35 | `ralplan` | active | plan | planning | yes | 187 | 2026-05-23 \| Merge branch 'dev' into omx-issue-2453-ralplan-ultragoal-doc | 77 | Alias for $plan --consensus | | 36 | `review` | deprecated | — | shortcut | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 163 | Deprecated standalone review skill | | 37 | `security-review` | deprecated | — | shortcut | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 8 | Deprecated standalone security review skill | | 38 | `skill` | active | — | utility | yes | 836 | 2026-05-11 \| Establish DESIGN.md as the canonical design workflow | 160 | Manage local skills - list; add; remove; search; edit; setup wizard | | 39 | `swarm` | deprecated | — | execution | no | 12 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 17 | Deprecated compatibility shim for team execution | | 40 | `tdd` | deprecated | — | shortcut | no | 104 | 2026-05-11 \| Prefer CLI-first OMX setup over MCP defaults (#2258) | 6 | TDD deprecated shim | | 41 | `team` | active | — | execution | yes | 520 | 2026-05-21 \| Prefer Ultragoal for durable follow-up guidance | 270 | N coordinated agents on shared task list using tmux-based orchestration | | 42 | `trace` | deprecated | — | utility | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 41 | Trace deprecated shim | | 43 | `ultragoal` | active | — | execution | yes | 131 | 2026-05-20 \| Avoid noisy fresh-session guidance in Ultragoal | 68 | Create and execute durable repo-native multi-goal plans over Codex goal mode art | | 44 | `ultraqa` | active | — | execution | yes | 254 | 2026-05-11 \| Ensure UltraQA catches adversarial e2e regressions (#2276) | 36 | Adversarial dynamic e2e QA workflow - generate hostile scenarios; test; verify; | | 45 | `ultrawork` | active | — | execution | yes | 175 | 2026-05-20 \| Make autopilot default to Ultragoal | 46 | Parallel execution engine for high-throughput task completion | | 46 | `visual-ralph` | active | designer | shortcut | yes | 161 | 2026-05-11 \| Establish DESIGN.md as the canonical design workflow | 17 | Visual Ralph orchestration for frontend UI from generated references; static ref | | 47 | `visual-verdict` | deprecated | — | shortcut | no | 10 | 2026-05-06 \| Retire obsolete OMX skills (#2132) | 9 | Visual Verdict deprecated skill | | 48 | `web-clone` | deprecated | — | shortcut | no | 357 | 2026-05-10 \| chore(skills): prune obsolete catalog entries | 10 | Web Clone deprecated shim | | 49 | `wiki` | NOT_IN_MANIFEST | — | — | yes | 57 | 2026-05-11 \| Prefer CLI-first OMX setup over MCP defaults (#2258) | 43 | Persistent markdown project wiki stored under repository omx_wiki with keyword s | | 50 | `worker` | internal | — | utility | yes | 106 | 2026-03-17 \| fix: stop generating skill agents (#897) | 165 | Team worker protocol (ACK; mailbox; task lifecycle) for tmux-based OMX teams | ### Skill cross-reference detail Selected breakdowns of skill → referencing files. Skills with ref_count ≤ 15 are fully expanded; high-ref skills are summarized as counts-by-kind to keep the table digestible. | skill | status | refs_total | in_other_skills | in_prompts | in_src_ts | in_src_tests | in_templates | full_list (only if ≤ 15) | |-------|--------|------------|-----------------|------------|-----------|--------------|--------------|---------------------------| | `ai-slop-cleaner` | active | 16 | 2 | 0 | 5 | 8 | 1 | *(>15, see refs_by_kind columns)* | | `analyze` | active | 28 | 3 | 5 | 8 | 11 | 1 | *(>15, see refs_by_kind columns)* | | `ask` | active | 295 | 40 | 36 | 112 | 106 | 1 | *(>15, see refs_by_kind columns)* | | `ask-claude` | deprecated | 9 | 1 | 0 | 3 | 4 | 1 | `skills/ask/SKILL.md``src/catalog/__tests__/generator.test.ts``src/catalog/__tests__/schema.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-scope.test.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/scripts/ask-claude.sh``templates/catalog-manifest.json` | | `ask-gemini` | deprecated | 10 | 1 | 0 | 3 | 5 | 1 | `skills/ask/SKILL.md``src/catalog/__tests__/generator.test.ts``src/catalog/__tests__/schema.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/ask.test.ts``src/cli/__tests__/setup-scope.test.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/scripts/ask-gemini.sh``templates/catalog-manifest.json` | | `autopilot` | active | 65 | 9 | 1 | 24 | 30 | 1 | *(>15, see refs_by_kind columns)* | | `autoresearch` | active | 72 | 4 | 1 | 34 | 32 | 1 | *(>15, see refs_by_kind columns)* | | `autoresearch-goal` | active | 20 | 3 | 1 | 6 | 9 | 1 | *(>15, see refs_by_kind columns)* | | `best-practice-research` | active | 12 | 4 | 0 | 3 | 4 | 1 | `skills/autoresearch/SKILL.md``skills/deep-interview/SKILL.md``skills/plan/SKILL.md``skills/ralplan/SKILL.md``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/best-practice-research-skill.test.ts``src/hooks/__tests__/keyword-detector.test.ts``src/hooks/__tests__/research-workflow-boundaries.test.ts``src/hooks/keyword-registry.ts``src/scripts/__tests__/docs-site-contract.test.ts``templates/catalog-manifest.json` | | `build-fix` | deprecated | 8 | 0 | 1 | 4 | 2 | 1 | `prompts/build-fixer.md``src/agents/__tests__/definitions.test.ts``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/team/role-router.ts``src/utils/__tests__/agents-model-table.test.ts``templates/catalog-manifest.json` | | `cancel` | active | 67 | 8 | 2 | 33 | 23 | 1 | *(>15, see refs_by_kind columns)* | | `code-review` | active | 54 | 6 | 8 | 21 | 18 | 1 | *(>15, see refs_by_kind columns)* | | `configure-notifications` | active | 6 | 1 | 0 | 2 | 2 | 1 | `skills/omx-setup/SKILL.md``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-skills-overwrite.test.ts``src/hooks/__tests__/openclaw-setup-contract.test.ts``templates/catalog-manifest.json` | | `deep-interview` | active | 74 | 8 | 0 | 26 | 39 | 1 | *(>15, see refs_by_kind columns)* | | `deepsearch` | deprecated | 5 | 1 | 0 | 2 | 1 | 1 | `skills/doctor/SKILL.md``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/task-size-detector.test.ts``templates/catalog-manifest.json` | | `design` | active | 62 | 8 | 17 | 21 | 15 | 1 | *(>15, see refs_by_kind columns)* | | `doctor` | active | 34 | 2 | 0 | 16 | 15 | 1 | *(>15, see refs_by_kind columns)* | | `ecomode` | deprecated | 10 | 3 | 0 | 3 | 3 | 1 | `skills/cancel/SKILL.md``skills/hud/SKILL.md``skills/ultrawork/SKILL.md``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/codex-plugin-layout.test.ts``src/cli/__tests__/setup-skills-overwrite.test.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/modes/base.ts``templates/catalog-manifest.json` | | `frontend-ui-ux` | deprecated | 10 | 1 | 0 | 4 | 4 | 1 | `skills/skill/SKILL.md``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-skills-overwrite.test.ts``src/hooks/__tests__/design-skill.test.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/hooks/keyword-detector.ts``src/hooks/keyword-registry.ts``templates/catalog-manifest.json` | | `git-master` | alias | 8 | 1 | 0 | 4 | 2 | 1 | `skills/skill/SKILL.md``src/agents/__tests__/definitions.test.ts``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `help` | deprecated | 161 | 6 | 9 | 49 | 96 | 1 | *(>15, see refs_by_kind columns)* | | `hud` | active | 86 | 3 | 0 | 42 | 40 | 1 | *(>15, see refs_by_kind columns)* | | `note` | deprecated | 74 | 15 | 8 | 24 | 26 | 1 | *(>15, see refs_by_kind columns)* | | `omx-setup` | active | 15 | 1 | 0 | 2 | 11 | 1 | `skills/help/SKILL.md``src/catalog/__tests__/plugin-bundle-ssot.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/codex-plugin-layout.test.ts``src/cli/__tests__/setup-agents-overwrite.test.ts``src/cli/__tests__/setup-gh-star.test.ts``src/cli/__tests__/setup-hooks-shared-ownership.test.ts``src/cli/__tests__/setup-install-mode.test.ts``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/cli/__tests__/setup-refresh.test.ts``src/cli/__tests__/setup-scope.test.ts``src/cli/__tests__/setup-skill-validation.test.ts``src/cli/__tests__/setup-skills-overwrite.test.ts``templates/catalog-manifest.json` | | `performance-goal` | active | 18 | 3 | 1 | 6 | 7 | 1 | *(>15, see refs_by_kind columns)* | | `pipeline` | active | 32 | 7 | 1 | 14 | 9 | 1 | *(>15, see refs_by_kind columns)* | | `plan` | active | 204 | 24 | 18 | 74 | 84 | 3 | *(>15, see refs_by_kind columns)* | | `prometheus-strict` | active | 11 | 0 | 1 | 4 | 5 | 1 | `prompts/prometheus-strict-metis.md``src/agents/__tests__/definitions.test.ts``src/agents/__tests__/native-config.test.ts``src/agents/definitions.ts``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/keyword-detector.test.ts``src/hooks/__tests__/prometheus-strict-contract.test.ts``src/hooks/keyword-registry.ts``templates/catalog-manifest.json` | | `ralph` | active | 141 | 20 | 1 | 43 | 76 | 1 | *(>15, see refs_by_kind columns)* | | `ralph-init` | deprecated | 6 | 0 | 0 | 2 | 3 | 1 | `src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/ralph-prd-deep-interview.test.ts``src/cli/__tests__/setup-skills-overwrite.test.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``templates/catalog-manifest.json` | | `ralplan` | active | 77 | 13 | 2 | 29 | 32 | 1 | *(>15, see refs_by_kind columns)* | | `review` | deprecated | 163 | 18 | 23 | 61 | 59 | 1 | *(>15, see refs_by_kind columns)* | | `security-review` | deprecated | 8 | 0 | 1 | 3 | 3 | 1 | `prompts/security-reviewer.md``src/agents/__tests__/definitions.test.ts``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/keyword-detector.test.ts``src/utils/__tests__/agents-model-table.test.ts``templates/catalog-manifest.json` | | `skill` | active | 160 | 37 | 3 | 50 | 68 | 1 | *(>15, see refs_by_kind columns)* | | `swarm` | deprecated | 17 | 2 | 0 | 6 | 8 | 1 | *(>15, see refs_by_kind columns)* | | `tdd` | deprecated | 6 | 0 | 0 | 3 | 2 | 1 | `src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/hooks/__tests__/task-size-detector.test.ts``src/team/role-router.ts``templates/catalog-manifest.json` | | `team` | active | 270 | 17 | 15 | 108 | 128 | 1 | *(>15, see refs_by_kind columns)* | | `trace` | deprecated | 41 | 4 | 3 | 16 | 17 | 1 | *(>15, see refs_by_kind columns)* | | `ultragoal` | active | 68 | 8 | 4 | 26 | 28 | 1 | *(>15, see refs_by_kind columns)* | | `ultraqa` | active | 36 | 4 | 0 | 19 | 12 | 1 | *(>15, see refs_by_kind columns)* | | `ultrawork` | active | 46 | 7 | 1 | 22 | 15 | 1 | *(>15, see refs_by_kind columns)* | | `visual-ralph` | active | 17 | 6 | 0 | 3 | 7 | 1 | *(>15, see refs_by_kind columns)* | | `visual-verdict` | deprecated | 9 | 1 | 0 | 4 | 3 | 1 | `skills/web-clone/SKILL.md``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/notify-hook-session-scope.test.ts``src/hooks/__tests__/notify-hook-visual-verdict.test.ts``src/hooks/__tests__/visual-verdict-loop.test.ts``src/imagegen/continuation.ts``src/scripts/notify-hook.ts``templates/catalog-manifest.json` | | `web-clone` | deprecated | 10 | 2 | 0 | 3 | 4 | 1 | `skills/ralph/SKILL.md``skills/visual-ralph/SKILL.md``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-skills-overwrite.test.ts``src/cli/setup.ts``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/hooks/__tests__/visual-ralph-skill.test.ts``templates/catalog-manifest.json` | | `wiki` | NOT_IN_MANIFEST | 43 | 0 | 0 | 20 | 23 | 0 | *(>15, see refs_by_kind columns)* | | `worker` | internal | 165 | 7 | 2 | 77 | 78 | 1 | *(>15, see refs_by_kind columns)* | ## Agents Sorted alphabetically. The 3 entries with `status = NOT_IN_MANIFEST` are non-installable prompt assets (see `NON_NATIVE_AGENT_PROMPT_ASSETS` in `src/agents/policy.ts`). `reasoningEffort`, `posture`, `modelClass`, `routingRole`, `tools` come from `src/agents/definitions.ts`. Description is the one-line `description` field there. | # | agent | status | canonical | category | posture | modelClass | routingRole | tools | refs | description | |---|-------|--------|-----------|----------|---------|------------|-------------|-------|------|-------------| | 1 | `analyst` | active | — | build | frontier-orchestrator | frontier | leader | analysis | 15 | Requirements clarity, acceptance criteria, hidden constraints | | 2 | `api-reviewer` | merged | code-reviewer | review | frontier-orchestrator | standard | leader | read-only | 9 | API contracts, versioning, backward compatibility | | 3 | `architect` | active | — | build | frontier-orchestrator | frontier | leader | read-only | 111 | System design, boundaries, interfaces, long-horizon tradeoffs | | 4 | `build-fixer` | deprecated | — | domain | deep-worker | standard | executor | execution | 5 | Build/toolchain/type failures resolution | | 5 | `code-reviewer` | active | — | review | frontier-orchestrator | frontier | leader | read-only | 21 | Comprehensive review across all concerns | | 6 | `code-simplifier` | internal | — | domain | deep-worker | frontier | executor | execution | 11 | Simplifies recently modified code for clarity and consistency without changing behavior | | 7 | `critic` | active | — | coordination | frontier-orchestrator | frontier | leader | read-only | 56 | Plan/design critical challenge and review | | 8 | `debugger` | active | — | build | deep-worker | standard | executor | analysis | 25 | Root-cause analysis, regression isolation, failure diagnosis | | 9 | `dependency-expert` | active | — | domain | frontier-orchestrator | standard | specialist | analysis | 14 | External SDK/API/package evaluation | | 10 | `designer` | active | — | domain | deep-worker | standard | executor | execution | 24 | UX/UI architecture, interaction design | | 11 | `executor` | active | — | build | — | — | — | — | 114 | — | | 12 | `explore` | active | — | build | fast-lane | fast | specialist | read-only | 99 | Fast codebase search and file/symbol mapping | | 13 | `explore-harness` | NOT_IN_MANIFEST | — | — | — | — | — | — | 12 | — | | 14 | `git-master` | active | — | domain | deep-worker | standard | executor | execution | 8 | Commit strategy, history hygiene, rebasing | | 15 | `information-architect` | merged | designer | product | frontier-orchestrator | standard | specialist | analysis | 7 | Taxonomy, navigation, findability | | 16 | `performance-reviewer` | merged | code-reviewer | review | frontier-orchestrator | standard | leader | read-only | 13 | Hotspots, complexity, memory/latency optimization | | 17 | `planner` | active | — | build | frontier-orchestrator | frontier | leader | analysis | 35 | Task sequencing, execution plans, risk flags | | 18 | `product-analyst` | merged | analyst | product | frontier-orchestrator | standard | specialist | analysis | 8 | Product metrics, funnel analysis, experiments | | 19 | `product-manager` | merged | analyst | product | frontier-orchestrator | standard | leader | analysis | 11 | Problem framing, personas/JTBD, PRDs | | 20 | `prometheus-strict-metis` | active | — | coordination | frontier-orchestrator | frontier | leader | analysis | 7 | Prometheus Strict requirements interviewer and ambiguity mapper | | 21 | `prometheus-strict-momus` | active | — | coordination | frontier-orchestrator | frontier | leader | analysis | 7 | Prometheus Strict adversarial plan critic and risk challenger | | 22 | `prometheus-strict-oracle` | active | — | coordination | frontier-orchestrator | standard | leader | analysis | 7 | Prometheus Strict implementation readiness verifier and handoff judge | | 23 | `qa-tester` | merged | test-engineer | domain | deep-worker | standard | executor | execution | 9 | Interactive CLI/service runtime validation | | 24 | `quality-reviewer` | merged | code-reviewer | review | frontier-orchestrator | standard | leader | read-only | 17 | Logic defects, maintainability, anti-patterns | | 25 | `quality-strategist` | merged | verifier | domain | frontier-orchestrator | standard | leader | analysis | 6 | Quality strategy, release readiness, risk assessment | | 26 | `researcher` | active | — | domain | fast-lane | standard | specialist | analysis | 33 | External documentation and reference research | | 27 | `security-reviewer` | deprecated | — | review | frontier-orchestrator | frontier | leader | read-only | 5 | Vulnerabilities, trust boundaries, authn/authz | | 28 | `sisyphus-lite` | NOT_IN_MANIFEST | — | — | — | — | — | — | 5 | — | | 29 | `style-reviewer` | merged | code-reviewer | review | fast-lane | fast | specialist | read-only | 15 | Formatting, naming, idioms, lint conventions | | 30 | `team-executor` | internal | — | build | — | — | — | — | 9 | — | | 31 | `team-orchestrator` | NOT_IN_MANIFEST | — | — | — | — | — | — | 2 | — | | 32 | `test-engineer` | active | — | domain | deep-worker | frontier | executor | execution | 28 | Test strategy, coverage, flaky-test hardening | | 33 | `ux-researcher` | merged | designer | product | frontier-orchestrator | standard | specialist | analysis | 8 | Heuristic audits, usability, accessibility | | 34 | `verifier` | active | — | build | frontier-orchestrator | standard | leader | analysis | 23 | Completion evidence, claim validation, test adequacy | | 35 | `vision` | active | — | coordination | fast-lane | frontier | specialist | read-only | 17 | Image/screenshot/diagram analysis | | 36 | `writer` | active | — | domain | fast-lane | standard | specialist | execution | 21 | Documentation, migration notes, user guidance | ### Agent cross-reference detail Selected breakdowns of agent → referencing files. Agents with ref_count ≤ 15 are fully expanded; the rest are summarized. | agent | status | refs_total | in_skills | in_other_prompts | in_src_ts | in_src_tests | in_templates | full_list (only if ≤ 15) | |-------|--------|------------|-----------|------------------|-----------|--------------|--------------|---------------------------| | `analyst` | active | 15 | 1 | 4 | 6 | 3 | 1 | `prompts/critic.md``prompts/product-analyst.md``prompts/product-manager.md``prompts/ux-researcher.md``skills/plan/SKILL.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/__tests__/prompt-orchestration-boundary.test.ts``src/hooks/prompt-guidance-contract.ts``src/pipeline/__tests__/orchestrator.test.ts``src/team/orchestrator.ts``src/team/role-router.ts``templates/catalog-manifest.json` | | `api-reviewer` | merged | 9 | 0 | 3 | 4 | 1 | 1 | `prompts/performance-reviewer.md``prompts/quality-reviewer.md``prompts/style-reviewer.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `architect` | active | 111 | 20 | 19 | 30 | 41 | 1 | *(>15, see refs_by_kind columns)* | | `build-fixer` | deprecated | 5 | 0 | 0 | 3 | 1 | 1 | `src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/utils/__tests__/agents-model-table.test.ts``templates/catalog-manifest.json` | | `code-reviewer` | active | 21 | 1 | 6 | 7 | 6 | 1 | *(>15, see refs_by_kind columns)* | | `code-simplifier` | internal | 11 | 0 | 0 | 7 | 3 | 1 | `src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/code-simplifier/__tests__/index.test.ts``src/hooks/code-simplifier/index.ts``src/hooks/prompt-guidance-contract.ts``src/scripts/notify-hook.ts``src/team/__tests__/role-router.test.ts``src/team/role-router.ts``templates/catalog-manifest.json` | | `critic` | active | 56 | 11 | 3 | 24 | 17 | 1 | *(>15, see refs_by_kind columns)* | | `debugger` | active | 25 | 1 | 0 | 8 | 15 | 1 | *(>15, see refs_by_kind columns)* | | `dependency-expert` | active | 14 | 1 | 2 | 6 | 4 | 1 | `prompts/explore.md``prompts/researcher.md``skills/best-practice-research/SKILL.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/best-practice-research-skill.test.ts``src/hooks/__tests__/prompt-guidance-wave-two.test.ts``src/hooks/prompt-guidance-contract.ts``src/team/__tests__/followup-planner.test.ts``src/team/__tests__/role-router.test.ts``src/team/followup-planner.ts``src/team/role-router.ts``templates/catalog-manifest.json` | | `designer` | active | 24 | 2 | 4 | 11 | 6 | 1 | *(>15, see refs_by_kind columns)* | | `executor` | active | 114 | 11 | 11 | 28 | 63 | 1 | *(>15, see refs_by_kind columns)* | | `explore` | active | 99 | 12 | 28 | 26 | 31 | 2 | *(>15, see refs_by_kind columns)* | | `explore-harness` | NOT_IN_MANIFEST | 12 | 0 | 0 | 5 | 7 | 0 | `src/agents/policy.ts``src/cli/__tests__/doctor-warning-copy.test.ts``src/cli/__tests__/explore.test.ts``src/cli/__tests__/package-bin-contract.test.ts``src/cli/__tests__/packaged-explore-harness-lock.ts``src/cli/explore.ts``src/cli/native-assets.ts``src/hooks/__tests__/explore-sparkshell-guidance-contract.test.ts``src/scripts/__tests__/verify-native-agents.test.ts``src/scripts/build-explore-harness.ts``src/scripts/cleanup-explore-harness.ts``src/verification/__tests__/explore-harness-release-workflow.test.ts` | | `git-master` | active | 8 | 2 | 0 | 4 | 1 | 1 | `skills/git-master/SKILL.md``skills/skill/SKILL.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/skill-catalog-hygiene.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `information-architect` | merged | 7 | 0 | 1 | 4 | 1 | 1 | `prompts/ux-researcher.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `performance-reviewer` | merged | 13 | 0 | 7 | 4 | 1 | 1 | `prompts/api-reviewer.md``prompts/debugger.md``prompts/quality-reviewer.md``prompts/quality-strategist.md``prompts/security-reviewer.md``prompts/style-reviewer.md``prompts/test-engineer.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `planner` | active | 35 | 5 | 4 | 14 | 11 | 1 | *(>15, see refs_by_kind columns)* | | `product-analyst` | merged | 8 | 0 | 2 | 4 | 1 | 1 | `prompts/product-manager.md``prompts/ux-researcher.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `product-manager` | merged | 11 | 0 | 4 | 5 | 1 | 1 | `prompts/information-architect.md``prompts/product-analyst.md``prompts/quality-strategist.md``prompts/ux-researcher.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``src/team/orchestrator.ts``templates/catalog-manifest.json` | | `prometheus-strict-metis` | active | 7 | 1 | 0 | 3 | 2 | 1 | `skills/prometheus-strict/SKILL.md``src/agents/definitions.ts``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/prometheus-strict-contract.test.ts``templates/catalog-manifest.json` | | `prometheus-strict-momus` | active | 7 | 1 | 0 | 3 | 2 | 1 | `skills/prometheus-strict/SKILL.md``src/agents/definitions.ts``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/prometheus-strict-contract.test.ts``templates/catalog-manifest.json` | | `prometheus-strict-oracle` | active | 7 | 1 | 0 | 3 | 2 | 1 | `skills/prometheus-strict/SKILL.md``src/agents/definitions.ts``src/catalog/__tests__/generator.test.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/hooks/__tests__/prometheus-strict-contract.test.ts``templates/catalog-manifest.json` | | `qa-tester` | merged | 9 | 1 | 1 | 4 | 2 | 1 | `prompts/quality-strategist.md``skills/ultraqa/SKILL.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/__tests__/explore-sparkshell-guidance-contract.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `quality-reviewer` | merged | 17 | 1 | 5 | 7 | 3 | 1 | *(>15, see refs_by_kind columns)* | | `quality-strategist` | merged | 6 | 0 | 0 | 4 | 1 | 1 | `src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `researcher` | active | 33 | 6 | 7 | 10 | 9 | 1 | *(>15, see refs_by_kind columns)* | | `security-reviewer` | deprecated | 5 | 0 | 0 | 3 | 1 | 1 | `src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/utils/__tests__/agents-model-table.test.ts``templates/catalog-manifest.json` | | `sisyphus-lite` | NOT_IN_MANIFEST | 5 | 0 | 0 | 2 | 3 | 0 | `src/agents/policy.ts``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/__tests__/explore-sparkshell-guidance-contract.test.ts``src/hooks/prompt-guidance-contract.ts``src/team/__tests__/worker-runtime-identity.test.ts` | | `style-reviewer` | merged | 15 | 0 | 5 | 5 | 4 | 1 | `prompts/api-reviewer.md``prompts/debugger.md``prompts/performance-reviewer.md``prompts/quality-reviewer.md``prompts/security-reviewer.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``src/scripts/__tests__/verify-native-agents.test.ts``src/team/__tests__/model-contract.test.ts``src/team/__tests__/worker-runtime-identity.test.ts``src/team/model-contract.ts``templates/catalog-manifest.json` | | `team-executor` | internal | 9 | 0 | 0 | 4 | 4 | 1 | `src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/cli/__tests__/team-decompose.test.ts``src/cli/team.ts``src/team/__tests__/followup-planner.test.ts``src/team/__tests__/repo-aware-decomposition.test.ts``templates/catalog-manifest.json` | | `team-orchestrator` | NOT_IN_MANIFEST | 2 | 0 | 0 | 2 | 0 | 0 | `src/agents/policy.ts``src/hooks/agents-overlay.ts` | | `test-engineer` | active | 28 | 2 | 3 | 9 | 13 | 1 | *(>15, see refs_by_kind columns)* | | `ux-researcher` | merged | 8 | 0 | 2 | 4 | 1 | 1 | `prompts/information-architect.md``prompts/product-manager.md``src/agents/definitions.ts``src/catalog/generated/public-catalog.json``src/catalog/manifest.json``src/cli/__tests__/setup-prompts-overwrite.test.ts``src/hooks/prompt-guidance-contract.ts``templates/catalog-manifest.json` | | `verifier` | active | 23 | 1 | 2 | 11 | 8 | 1 | *(>15, see refs_by_kind columns)* | | `vision` | active | 17 | 2 | 2 | 8 | 4 | 1 | *(>15, see refs_by_kind columns)* | | `writer` | active | 21 | 1 | 1 | 6 | 12 | 1 | *(>15, see refs_by_kind columns)* | ## Skill → agent reference matrix Rows = skills that mention agent names in their `SKILL.md` body. Columns = agents (only those mentioned by at least one skill). A cell is `●` when the skill's SKILL.md textually contains the agent's bare name (`rg -F`). This is the *narrative* coupling, not the runtime call graph. It tells you whether a skill's documentation orients the model toward a specific agent; it does NOT mean the skill executes that agent automatically. | skill \ agent | `analyst` | `architect` | `code-reviewer` | `critic` | `debugger` | `dependency-expert` | `designer` | `executor` | `explore` | `git-master` | `planner` | `prometheus-strict-metis` | `prometheus-strict-momus` | `prometheus-strict-oracle` | `qa-tester` | `quality-reviewer` | `researcher` | `test-engineer` | `verifier` | `vision` | `writer` | |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---| | `ai-slop-cleaner` | | ● | | | | | | | | | | | | | | | | | | | | | `analyze` | | ● | | | ● | | | | | | | | | | | | | | | | | | `autopilot` | | ● | | ● | | | | ● | ● | | | | | | | | | | | | | | `autoresearch` | | ● | | | | | | | | | | | | | | | | | | | | | `autoresearch-goal` | | | | ● | | | | | | | | | | | | | | | | | | | `best-practice-research` | | ● | | | | ● | | ● | ● | | | | | | | | ● | | | | | | `code-review` | | ● | ● | ● | | | | | | | | | | | | | | | | | | | `deep-interview` | | ● | | ● | | | | | ● | | | | | | | | | | | | | | `deepsearch` | | | | | | | | | ● | | | | | | | | | | | | | | `design` | | ● | | ● | | | ● | | | | | | | | | | | | | | | | `doctor` | | ● | | | | | | ● | ● | | | | | | | | ● | | | | | | `ecomode` | | ● | | | | | | ● | ● | | ● | | | | | | | | | | ● | | `git-master` | | | | | | | | | | ● | | | | | | | | | | | | | `hud` | | ● | | | | | | | | | | | | | | | | | | | | | `pipeline` | | ● | | ● | | | | ● | | | ● | | | | | | | | | | | | `plan` | ● | ● | | ● | | | | ● | ● | | ● | | | | | ● | | | ● | | | | `prometheus-strict` | | | | | | | | ● | ● | | ● | ● | ● | ● | | | ● | | | | | | `ralph` | | ● | | ● | | | | ● | ● | | | | | | | | | | | | | | `ralplan` | | ● | | ● | | | | | ● | | | | | | | | ● | | | | | | `skill` | | | | | | | | | | ● | ● | | | | | | | | | | | | `tdd` | | ● | | ● | | | | | | | | | | | | | | ● | | | | | `team` | | | | ● | | | | ● | ● | | | | | | | | ● | | | ● | | | `ultragoal` | | ● | | | | | | | | | | | | | | | | | | | | | `ultraqa` | | ● | | | | | | ● | | | | | | | ● | | | | | | | | `ultrawork` | | ● | | | | | | ● | ● | | | | | | | | ● | ● | | | | | `visual-ralph` | | | | | | | ● | | | | | | | | | | | | | ● | | | `wiki` | | ● | | | | | | | | | | | | | | | | | | | | Skills not appearing as a row above mention zero agent names verbatim (19 skills). That is itself a connectivity signal (covered in `connectivity-roadmap.md`). **Skills with zero agent mentions in their SKILL.md body**: - `ask` - `ask-claude` - `ask-gemini` - `build-fix` - `cancel` - `configure-notifications` - `frontend-ui-ux` - `help` - `note` - `omx-setup` - `performance-goal` - `ralph-init` - `review` - `security-review` - `swarm` - `trace` - `visual-verdict` - `web-clone` - `worker` ## Catalog ↔ disk consistency - **On disk but not in `src/catalog/manifest.json`** (1): `wiki` - **In manifest but not on disk** (4): `configure-discord`, `configure-openclaw`, `configure-slack`, `configure-telegram` - **On disk but not shipped via `plugins/oh-my-codex/skills/`** (17): `ask-claude`, `ask-gemini`, `build-fix`, `deepsearch`, `ecomode`, `frontend-ui-ux`, `git-master`, `help`, `note`, `ralph-init`, `review`, `security-review`, `swarm`, `tdd`, `trace`, `visual-verdict`, `web-clone` These three lines are the most actionable consistency findings — see `bloat-audit.md` § *Inventory anomalies* for proposed fixes. --- *Generated for owner review. Do not edit by hand without re-running `notes/audit-*` data collection.* --- ## File: docs/audit/skills-agents-bloat-audit/README.md # Skills + agents bloat audit (omx) — 2026-05-23 This directory contains a read-only audit of the `./skills/` and `./src/agents/` surfaces of `oh-my-codex`, produced in response to an owner verbal request for a "comprehensive bloat-audit + connectivity-improvement roadmap." Audit ran on branch `chore/skills-agents-bloat-audit` rooted on `origin/dev`. ## How this audit was produced 1. Enumerated all canonical skills via `find ./skills -maxdepth 2 -name 'SKILL.md'` (46 on disk). 2. Enumerated agents from `src/agents/definitions.ts` (`AGENT_DEFINITIONS`) plus the 3 non-installable prompt assets in `src/agents/policy.ts` (`NON_NATIVE_AGENT_PROMPT_ASSETS`) → 36 total. 3. Pulled authoritative status (`active` / `internal` / `alias` / `merged` / `deprecated`) from `src/catalog/manifest.json` (49 skill rows + 33 agent rows). 4. Per skill: file LOC, last-touched commit (`git log -1 --format='%cs|%s' -- skills//`), frontmatter description. 5. Per skill and per agent: reference count via `rg -l --no-messages -F '' skills/ src/ prompts/ templates/`, excluding the entry's own directory and own `prompts/.md`. 6. Per skill: which agent names appear textually in its `SKILL.md` body (narrative coupling matrix). 7. Per agent: which skill names appear textually in its `prompts/.md` body. 8. Classified each entry deterministically per the rules in `bloat-audit.md` § header. Raw intermediate data (per-skill metrics CSV, reference CSVs, the flattened catalog dump, and the combined JSON) was generated in a scratch `notes/` directory during the audit; it is intentionally not committed (those files are reproducible from this repo at any commit by re-running the data collection described above). ## Contents | File | Purpose | Approx size | |------|---------|-------------| | [`inventory.md`](inventory.md) | Deliverable 1 — full table-heavy enumeration of skills + agents, with status, LOC, last-commit, reference counts, and a skill ↔ agent narrative coupling matrix. | ~280 lines | | [`bloat-audit.md`](bloat-audit.md) | Deliverable 2 — every skill and agent classified into one of: KEEP-AS-IS, CONSOLIDATE, STREAMLINE, DEPRECATE, or AMBIGUOUS. Each entry carries evidence, action, and risk. | ~970 lines | | [`connectivity-roadmap.md`](connectivity-roadmap.md) | Deliverable 3 — orphan analysis + concrete connectivity-fix proposals (quick wins / medium / strategic) + the suggested PR-by-PR sequence to actually land the cleanup. | ~280 lines | ## Top-line numbers From `bloat-audit.md` § Summary: - **Skills (50 catalog entries, 46 on disk):** - 18 KEEP-AS-IS (incl. alias + internal) - 7 STREAMLINE (optional) - 4 CONSOLIDATE — already collapsed - 16 DEPRECATE (all already tombstoned to ~10 LOC) - 5 AMBIGUOUS — owner decision needed - **Agents (36 total, 33 in `AGENT_DEFINITIONS`):** - 23 KEEP-AS-IS (incl. internal + non-installable asset) - 10 CONSOLIDATE (already-merged entries) - 2 DEPRECATE - 1 AMBIGUOUS — owner decision needed After the suggested PR-1 + PR-2 land, the surface contracts to ~30 on-disk skills and ~21 agents. See `connectivity-roadmap.md` § 6 — Quick reference. ## Important caveats - **This audit is opinion + evidence, not a unilateral mandate.** Every classification can be argued against the data. Owner reviews PR-by-PR; nothing is to be deleted in this PR. - **No files in `./skills/`, `./src/agents/`, `./prompts/`, or any other production surface were modified.** The committed delta is limited to this `docs/audit/skills-agents-bloat-audit/` directory. - **Reference counts are upper bounds.** Short, English-word names (`ask`, `plan`, `team`, `note`, `review`, `help`) inflate via false positives. The classifier weights structural references (catalog, templates, CLI surfaces) above prose mentions. - **Tests, benchmarks, and the full suite were NOT run.** Per the audit's scope guardrails. The next PR (PR-1 in the roadmap) is where verification gets reattached. ## Re-running this audit The data sources listed in § *How this audit was produced* are the entire input set. To re-run on a future commit: 1. Re-execute the 7 enumeration steps (1–7 above) against the new repo state. 2. Re-apply the classifier rules documented at the head of `bloat-audit.md`. 3. Diff the new `inventory.md` against the committed one to see what moved. Because every classification is a deterministic function of catalog status + LOC + reference counts, the same inputs at a future commit will produce the same labels (modulo new entries appearing or old entries being deleted). ## Next step Read `bloat-audit.md` for the per-entry triage, then `connectivity-roadmap.md` § 3 for the proposed PR sequence. The owner picks which PRs to authorize; this audit only proposes. — *[repo owner's gaebal-gajae (clawdbot) 🦞]* --- ## File: docs/contracts/autoresearch-command-contract.md # `omx autoresearch` parity contract `omx autoresearch` is a thin supervisor that drives one Codex experiment session per iteration while OMX owns the durable keep/discard/reset loop. ## CLI ```bash omx autoresearch [codex-args...] omx autoresearch --resume [codex-args...] omx autoresearch --help ``` - Fresh launch always creates a new run-tagged lane. - `--resume ` loads `.omx/logs/autoresearch//manifest.json`. - A second launch is rejected while repo-root `.omx/state/autoresearch-state.json` points at an active run. ## Mission / sandbox contract `` must be inside a git repo and contain `mission.md` plus `sandbox.md`. `sandbox.md` YAML frontmatter must define: - `evaluator.command` - `evaluator.format: json` - optional `evaluator.keep_policy: score_improvement | pass_only` Evaluator stdout must be JSON with required boolean `pass` and optional numeric `score`. ## Runtime model Fresh launch creates: - branch `autoresearch//` - worktree `.omx-worktrees/autoresearch--` - repo-root run artifacts under `.omx/logs/autoresearch//` Repo-root state responsibilities: - `.omx/state/autoresearch-state.json` = active-run pointer/lock only - `.omx/logs/autoresearch//manifest.json` = authoritative per-run state - `.omx/logs/autoresearch//candidate.json` = candidate handoff from the just-finished Codex session - `.omx/logs/autoresearch//iteration-ledger.json` = durable iteration history - `.omx/logs/autoresearch//latest-evaluator-result.json` = latest evaluator output Worktree-local state responsibilities: - `results.tsv` - optional evaluator logs such as `run.log` - these runtime-generated files must be excluded via worktree-local `.git/info/exclude` ## Candidate artifact The launched session must write repo-root `candidate.json` with: - `status`: `candidate | noop | abort | interrupted` - `candidate_commit`: string or `null` - `base_commit`: string - `description`: string - `notes`: string[] - `created_at`: ISO timestamp Integrity rules: - `status=candidate` requires a non-null `candidate_commit` - `candidate_commit` must resolve in git and match the worktree `HEAD` commit on exit - `base_commit` must resolve in git and match the supervisor-provided `last_kept_commit` Supervisor behavior: - `candidate` → run evaluator, classify keep/discard/ambiguous/error, update manifest/ledger/results, reset if discarded - `noop` → log noop iteration and continue by default - `abort` → stop run without reset - `interrupted` → if dirty, stop for operator intervention; if clean, log interrupted/noop style outcome ## Decision policy - Baseline row is always recorded. - `pass=false` => discard. - evaluator error/crash => discard. - `keep_policy=score_improvement` => keep only when `pass=true` and score improves over last kept score; pass without comparable score is `ambiguous` and discarded. - `keep_policy=pass_only` => any `pass=true` candidate is kept. - Discard / ambiguous / error paths must reset to the last kept commit. ## Resume `--resume ` must fail with actionable errors when: - manifest is missing - referenced worktree is missing - worktree is dirty outside allowlisted runtime artifacts - manifest is terminal Successful resume continues from the last kept commit and existing results history. ## Iteration handoff context Each launched worker session receives a supervisor-written instruction snapshot including: - current iteration number - baseline commit - last kept commit - last kept score when known - previous iteration outcome - bounded recent ledger summary - keep policy ## Verification targets Parity-aligned implementation should prove: 1. fresh launches create distinct run-tagged lanes 2. repo-root active-run lock rejects concurrent launches 3. candidate handoff artifact drives keep/discard/reset decisions 4. discarded candidates reset to `last_kept_commit` 5. `--resume ` reloads authoritative manifest/worktree state 6. README/help/contracts describe the thin-supervisor parity loop --- ## File: docs/contracts/autoresearch-command-review.md # `omx autoresearch` Full-Parity Review Notes Date: 2026-03-14 Reviewer lane: worker-3 ## Scope reviewed Compared the implementation and operator-facing docs against: - `.omx/plans/prd-autoresearch-full-parity.md` - `.omx/plans/test-spec-autoresearch-full-parity.md` Reviewed code and docs: - `src/cli/autoresearch.ts` - `src/autoresearch/contracts.ts` - `src/autoresearch/runtime.ts` - `src/team/worktree.ts` - `src/modes/base.ts` - `README.md` - `docs/contracts/autoresearch-command-contract.md` - focused autoresearch tests under `src/**/__tests__` ## Current status **Status:** parity-critical behavior appears implemented and the previously noted shared help/test wording mismatch is now resolved. The branch now matches the PRD/test-spec shape much more closely than the earlier scaffold review: - `omx autoresearch` exposes both fresh launch and `--resume ` flows. - the runtime owns a thin-supervisor loop boundary via repo-root candidate handoff + post-session evaluator decisions. - repo-root active-run locking and authoritative per-run manifests are present. - fresh launches create run-tagged autoresearch lanes instead of silently reusing one long-lived lane. - docs/help/contracts describe keep/discard/reset semantics instead of the earlier v1 scaffold. ## Verified evidence ### Build - `npm run build` → PASS ### Focused tests - `node --test dist/autoresearch/__tests__/runtime.test.js dist/cli/__tests__/autoresearch.test.js dist/cli/__tests__/index.test.js dist/cli/__tests__/nested-help-routing.test.js dist/team/__tests__/worktree.test.js dist/modes/__tests__/base-autoresearch-contract.test.js` → PASS - `node --test dist/cli/__tests__/session-search-help.test.js` → PASS ### Code/doc alignment observed - CLI help documents fresh launch + `--resume `: `src/cli/autoresearch.ts` - top-level help advertises thin-supervisor parity semantics: `src/cli/index.ts`, `src/compat/fixtures/help.stdout.txt` - README now explains baseline seeding, repo-root per-run artifacts, candidate handoff, keep/discard/reset, relaunch loop, and resume behavior: `README.md` - contract doc now defines run-tagged lanes, repo-root authority split, candidate artifact schema, decision policy, and resume failure conditions: `docs/contracts/autoresearch-command-contract.md` - runtime implements active-run lock, per-run manifest files, allowlisted runtime excludes, candidate parsing, evaluator-backed decisions, reset-to-last-kept behavior, and resume validation: `src/autoresearch/runtime.ts` - worktree planning test locks run-tagged autoresearch branch/path naming: `src/team/__tests__/worktree.test.ts` ## Parity checklist ### 1. Thin-supervisor iteration model **Pass.** - `buildAutoresearchInstructions()` tells the launched Codex session to perform exactly one experiment cycle and write the candidate artifact before exit. - `runAutoresearchLoop()` relaunches Codex after `processAutoresearchCandidate()` unless the run aborts/errors. ### 2. Repo-root state authority **Pass.** - repo-root active-run lock lives at `.omx/state/autoresearch-state.json`. - per-run manifest, candidate, ledger, and latest evaluator files live under `.omx/logs/autoresearch//`. - worktree-local runtime artifacts are limited to `results.tsv` and allowlisted logs. ### 3. Fresh-run semantics **Pass.** - fresh launches compute a run tag and plan `autoresearch//` plus `autoresearch--`. - focused worktree coverage now asserts run-tagged branch/path naming. ### 4. Resume contract **Pass.** - CLI parses `--resume `. - runtime rejects missing manifest, missing worktree, dirty worktree, and terminal runs. ### 5. Keep/discard/reset decision policy **Pass.** - baseline row is seeded. - evaluator failure/error discards. - `pass_only` keeps any pass. - `score_improvement` requires comparable numeric scores and improvement; otherwise ambiguous/discard. - discard paths reset to `last_kept_commit`. ### 6. Docs/help/contracts alignment **Pass.** - README, command help, top-level help, fixture help text, and the contract doc now describe the parity loop rather than a one-shot bootstrap scaffold. - Shared help/test wording now matches the thin-supervisor parity wording. ## Remaining review notes / risks 1. `runAutoresearchLoop()` currently reads the run id back from the manifest file via `execFileSync('cat', ...)` + `JSON.parse(...)` on each iteration. That works, but it is a slightly awkward implementation detail and could be simplified to avoid shelling out to `cat`. 2. Focused tests cover the main parity surfaces, but there is still room for broader runtime coverage around `noop`, `abort`, `interrupted`, and explicit `pass_only` policy branches if the lead wants even tighter semantic locking. 3. I verified focused parity coverage and build status, not the entire repository-wide test suite/lint suite. ## Reviewer conclusion This lane no longer looks like the earlier v1 scaffold. The reviewed implementation and docs now appear largely consistent with the requested thin-supervisor autoresearch parity model; the previously noted shared top-level help/test wording mismatch is resolved; remaining follow-ups are optional cleanup/coverage improvements. --- ## File: docs/contracts/autoresearch-ux-deep-interview-review.md # `omx autoresearch` deep-interview UX review notes Date: 2026-03-17 Reviewer lane: worker-3 ## Scope reviewed Compared the current implementation and operator-facing docs against: - `.omx/plans/prd-autoresearch-ux-deep-interview.md` - `.omx/plans/test-spec-autoresearch-ux-deep-interview.md` Reviewed files: - `src/cli/autoresearch.ts` - `src/cli/autoresearch-guided.ts` - `src/cli/__tests__/autoresearch-guided.test.ts` - `src/cli/__tests__/autoresearch.test.ts` - `skills/deep-interview/SKILL.md` - `README.md` - `docs/contracts/autoresearch-command-contract.md` - in-progress contract-test delta from worker-2: `src/hooks/__tests__/deep-interview-contract.test.ts` ## Current status **Status:** the PRD/test-spec behavior is not implemented on the reviewed branch yet. Current code still reflects the older guided-init flow: - `omx autoresearch` with no args enters `guidedAutoresearchSetup()` and immediately asks for a raw evaluator command. - bare `init` still routes into that same guided path instead of an explicit novice compatibility bridge. - there is no autoresearch-specific intake module, no canonical `.omx/specs/deep-interview-autoresearch-{slug}.md` artifact, and no confirm/refine launch gate. - launch still happens immediately after guided setup returns. - README/help/contract docs still describe the thin-supervisor runtime, but not the new novice deep-interview intake surface from this PRD. ## Evidence observed ### Code-path findings - `src/cli/autoresearch.ts` - `parseAutoresearchArgs()` only recognizes no-arg guided mode, `init`, `--resume`, and ``. - top-level `--topic/--evaluator/--keep-policy/--slug` seeded novice flags are not routed. - guided/init flows still call `spawnAutoresearchTmux()` immediately after mission creation. - `src/cli/autoresearch-guided.ts` - `guidedAutoresearchSetup()` still prompts directly for `Evaluator command`. - no placeholder/readiness rejection exists beyond `parseSandboxContract()`. - no draft artifact is written under `.omx/specs/`. - `skills/deep-interview/SKILL.md` - the generic execution bridge exists, but the autoresearch specialization section required by the PRD is absent on this branch. ### Test/doc alignment findings - `src/cli/__tests__/autoresearch-guided.test.ts` - covers mission/scaffold creation and flag parsing for the older init/guided flow only. - `src/cli/__tests__/autoresearch.test.ts` - still asserts the older `omx autoresearch init [--topic ...]` help surface and non-interactive `mission-dir is required` failure. - worker-2 has an in-progress test addition that correctly starts locking the expected deep-interview specialization text in `src/hooks/__tests__/deep-interview-contract.test.ts`. ## PRD checklist assessment ### 1. Vague-goal novice intake without raw evaluator knowledge **Fail on current branch.** The first guided prompt still asks for a concrete evaluator shell command. ### 2. Autoresearch-specific deep-interview/refinement bridge **Fail on current branch.** No autoresearch-specific refinement loop or seeded novice bridge exists. ### 3. Canonical draft artifact at `.omx/specs/deep-interview-autoresearch-{slug}.md` **Fail on current branch.** No `.omx/specs/` draft artifact is generated. ### 4. Explicit `refine further` vs `launch` confirmation boundary **Fail on current branch.** Guided setup returns launch-ready mission data and tmux launch happens immediately. ### 5. Placeholder evaluator rejection before launch **Fail on current branch.** There is no blocked-pattern gate for placeholder evaluator commands. ### 6. Top-level seeded novice flags (`--topic`, `--evaluator`, `--keep-policy`, `--slug`) **Fail on current branch.** Those flags are not accepted at top level; only `init` parses them today. ### 7. Expert flows preserved (``, `init --flags`, `--resume`) **Pass on current branch.** Existing expert/runtime flows remain intact. ### 8. Bare `omx autoresearch init` documented as novice alias **Fail on current branch.** Bare `init` is routed into guided mode, but help/docs do not explain the compatibility semantics required by the PRD. ### 9. Non-interactive no-arg failure preserved **Pass on current branch.** The TTY guard still rejects no-arg non-interactive invocation. ### 10. Regression coverage for interview/draft/confirm path **Fail on current branch.** Those tests are not present yet. ## Documentation follow-ups once implementation lands 1. Update `README.md` with the new novice entry surfaces: - `omx autoresearch` as a deep-interview-style refinement flow - top-level seeded novice flags - explicit confirm-before-launch behavior 2. Update `docs/contracts/autoresearch-command-contract.md` to add: - canonical draft artifact path - launch-readiness placeholder rejection rules - confirm/refine bridge semantics 3. Extend `skills/deep-interview/SKILL.md` with the PRD-required `Autoresearch specialization` section and required artifact headings. 4. Keep help text explicit about the split between novice refinement mode and expert `init --flags` / `` / `--resume` flows. ## Reviewer conclusion This review lane can confirm the current branch preserves existing autoresearch runtime behavior, but it does **not** yet satisfy the deep-interview UX enhancement PRD. The most useful near-term review output is therefore this baseline gap assessment plus the documentation checklist above; once worker-1 lands the implementation, this file should be refreshed with a final pass/fail review and verification evidence. --- ## File: docs/contracts/explicit-terminal-stop-model.md # Explicit Terminal Stop Model Contract Status: approved migration contract for runtime, hooks, MCP state, and prompt/documentation surfaces. ## Purpose This document locks the canonical terminal stop vocabulary for active OMX workflows. It exists so runtime code, native/fallback Stop handlers, MCP state, and user-facing handoff guidance all describe the same end-of-turn semantics. ## Canonical terminal lifecycle outcomes These are the only canonical user-facing terminal lifecycle outcomes for the explicit stop model: | Outcome | Meaning | Continuation rule | User-facing expectation | | --- | --- | --- | --- | | `finished` | The workflow completed successfully. | Do not auto-continue. | Report completion evidence and resulting artifacts. | | `blocked` | Progress cannot continue because a non-user prerequisite is missing. | Do not auto-continue until the blocker changes. | Report the blocker, why it matters, and the required handoff. | | `failed` | The workflow or verification failed. | Do not auto-continue until the failure is addressed. | Report failure evidence, impact, and recommended recovery. | | `userinterlude` | The user intentionally interrupted or paused the run. | Do not auto-continue unless the user explicitly restarts it. | Report that the stop was user-originated, not model-originated. | | `askuserQuestion` | OMX must ask the user a blocking question before safe progress can continue. | Do not auto-continue until the question is answered. | Ask one concrete blocking question and record the question metadata. | `askuserQuestion` and `userinterlude` are intentionally distinct: - `askuserQuestion` is model-originated and should normally be backed by `omx question` or equivalent machine-readable question metadata. - `userinterlude` is user-originated interruption/stop intent. ## Legacy compatibility rules Legacy values may still appear in persisted state during migration, but they are compatibility inputs, not the public canonical vocabulary. | Legacy value | Canonical interpretation | | --- | --- | | `finish`, `complete`, `completed`, `done` | normalize to `finished` | | `blocked_on_user` | compatibility-only user-wait signal; map to `askuserQuestion` when question metadata proves OMX asked a blocking question, otherwise map to `userinterlude`/user-wait compatibility according to the surrounding context | | `cancelled`, `canceled`, `abort`, `aborted` | internal legacy/admin stop compatibility only; do **not** present as a canonical user-facing lifecycle outcome | ### `cancelled` policy `cancelled` remains valid for legacy administrative state, teardown, or backward-compatible reads. It is **not** a canonical user-facing terminal lifecycle outcome in the explicit stop model. Docs, prompts, and runtime summaries should prefer one of: - `finished` - `blocked` - `failed` - `userinterlude` - `askuserQuestion` ## State / MCP precedence Terminal lifecycle metadata should be interpreted in this order: 1. a dedicated canonical lifecycle field such as `lifecycle_outcome` 2. legacy `run_outcome` compatibility data 3. fallback inference from `current_phase`, question metadata, and other persisted context Notes: - `current_phase` and lifecycle outcome are related but not identical. A workflow can keep legacy phase names while still exposing canonical lifecycle metadata. - If both canonical lifecycle metadata and legacy `run_outcome` are present, the canonical lifecycle field wins. - `run_outcome` should be treated as a compatibility read/write surface during migration, not as the long-term public contract. ## Stop / watcher interpretation rules Stop readers, native hooks, and fallback watchers should prefer explicit lifecycle metadata over assistant prose heuristics. During migration they should: - honor canonical `finished`, `blocked`, `failed`, `userinterlude`, and `askuserQuestion` metadata first - keep honoring legacy `blocked_on_user` as a suppress-continuation compatibility signal - avoid treating optional assistant prose as the semantic owner of lifecycle state - keep `cancelled` internal legacy-only when translating to user-facing lifecycle summaries ## Active workflow terminal handoff contract When an active workflow produces a terminal user-facing message, the handoff should be explicit and structured. The terminal summary should include: 1. **Outcome** — one explicit lifecycle label 2. **Evidence** — concrete verification output, failure evidence, or the missing dependency/question 3. **Artifacts / state** — changed files, saved artifacts, or recorded question identifiers when relevant 4. **Handoff** — the exact next owner or required answer, without optional permission-seeking phrasing ### Forbidden terminal pattern Do **not** end active workflow terminal handoffs with optional follow-up softeners such as: - `If you want, I can ...` - `If you'd like, I can ...` - `Would you like me to continue?` Those phrases make the lifecycle state ambiguous. The terminal outcome should already explain whether the run finished, failed, blocked, entered user interlude, or is waiting on a required user question. ## Non-goals This contract does **not** require every legacy internal phase name to be renamed immediately. It does require every migrated surface to expose and prefer the canonical terminal lifecycle concepts above. --- ## File: docs/contracts/multi-state-transition-contract.md # Multi-state transition compatibility contract This document freezes the first-pass peer workflow state model for the approved multi-state compatibility rollout from `.omx/plans/prd-multi-state-compat.md`. ## Canonical sources of truth The runtime must treat workflow state as a combination of: - mode state files under `.omx/state/{scope}/-state.json` - canonical workflow enumeration under `.omx/state/{scope}/skill-active-state.json` `skill-active-state.json` is the canonical active-set inventory. Legacy top-level fields such as `skill` or `phase` may remain as compatibility metadata, but they must not override the authoritative active set when multiple workflow members are live. ## Approved first-pass combinations Allowed active-set shapes in this rollout are intentionally narrow: - standalone single-workflow state for tracked workflows - `team + ralph` - `team + ultrawork` The resulting active set is peer state. Neither member is semantically primary just because it was activated first or happens to occupy the legacy top-level `skill` field. ## Standalone-only workflows These workflows remain standalone in this pass and must reject overlap attempts: - `autopilot` - `autoresearch` A denied overlap must preserve the current state unchanged. This fail-closed rule covers unsupported active-set combinations and state-integrity failures; it does not apply to ordinary Autopilot phase, review, or consensus evidence. ## Transition rules A canonical transition helper should answer three questions for every writer or consumer that mutates workflow state: 1. Is the requested transition allowed from the current active set? 2. What is the resulting active set if it is allowed? 3. What structured operator guidance should be shown if workflow evidence is missing? Identity, scope, corruption, and unsupported active-set checks remain fail-closed. Autopilot phase, review, and consensus checks are advisory: a permitted write records one structured advisory in `skipped_gates` with the skipped gate and the missing evidence. The first matching check wins, so one transition emits exactly one advisory. A successful terminalization with any skipped gate is reported as `complete with skipped gates`, never as clean success. ## Fail-closed transition UX Every denied transition must: 1. keep the current active state unchanged 2. name the denied combination explicitly 3. explain how to clear incompatible state before retrying 4. mention both supported clearing surfaces: - `omx state ...` - `omx_state.*` MCP tools Permitted-but-incomplete Autopilot transitions must instead: 1. preserve the requested phase 2. persist the structured advisory durably 3. expose the same advisory through the mode, state-operation, and keyword transports 4. retain fail-closed identity, scope, and corruption checks Example operator guidance shape for a denied overlap: > Cannot activate `` while `` is still active. Clear the > incompatible state first via `omx state ...` or the `omx_state.*` MCP tools, > then retry the transition. ### Operator recovery examples CLI parity surface: - `omx state clear --input '{"mode":"team"}' --json` - `omx state clear --input '{"mode":"ralph","all_sessions":true}' --json` MCP parity surface: - `omx_state.state_clear({ mode: "team" })` - `omx_state.state_clear({ mode: "ralph", all_sessions: true })` ## Brownfield consumer expectations The following surfaces must consume the same transition semantics instead of re-inventing their own precedence rules: - `src/state/skill-active.ts` — canonical active-set persistence/sync - `src/hooks/keyword-detector.ts` — keyword-triggered activation should add or deny according to the allowlist instead of overwriting to a single owner - `src/modes/base.ts` — mode start validation must defer to the same transition rules and emit the same operator guidance - `src/mcp/state-server.ts` — state writes/clears must preserve combined state correctly and remove only the cleared member - `src/hud/state.ts` — HUD rendering must show approved combined states even when legacy top-level metadata is non-authoritative - `src/hooks/agents-overlay.ts` — AGENTS overlay active-mode reporting must list every active approved member - `src/scripts/codex-native-hook.ts` — Stop/continuation logic must respect the combined state and stop blocking when the relevant member is cleared ## Scope behavior Session-scoped state remains authoritative when present. Root scope remains a compatibility fallback only. Clearing one member of an approved combined set must not accidentally delete the entire combined state. ## Regression expectations Implementation should be considered complete only when tests prove: 1. canonical active state can hold a multi-entry active set 2. `team + ralph` is allowed in both activation orders 3. `team + ultrawork` is allowed in both activation orders 4. unsupported overlaps deny without mutation 5. denial messages mention both `omx state` and `omx_state.*` 6. HUD / overlay / stop-hook consumers honor the combined set consistently 7. `autopilot` and `autoresearch` still reject unsupported overlap attempts; Autopilot review-driven planning loopbacks keep `autopilot` active and update its `current_phase` to `ralplan` instead of starting standalone `ralplan` 8. The retired Autopilot/Ralplan host-receipt gate must not block ordinary progression or authority-decreasing recovery. Native lanes, trackers, `codex_exec`, and artifacts remain planning/review evidence rather than an authorization boundary; missing host provenance does not terminalize the lightweight workflow. --- ## File: docs/contracts/multi-state-transition-review.md # Multi-state transition compatibility review notes Date: 2026-04-09 Reviewer lane: worker-3 ## Scope reviewed Compared the branch state against: - `.omx/plans/prd-multi-state-compat.md` - `.omx/plans/test-spec-multi-state-compat.md` Reviewed brownfield surfaces: - `src/state/skill-active.ts` - `src/hooks/keyword-detector.ts` - `src/modes/base.ts` - `src/mcp/state-server.ts` - `src/hud/state.ts` - `src/hooks/agents-overlay.ts` - `src/scripts/codex-native-hook.ts` ## Current branch snapshot **Status:** the repository already contains partial multi-state foundations, but it does not yet expose one documented canonical transition contract. Observed strengths: - `src/state/skill-active.ts` already persists `active_skills[]`, normalizes visible entries, and can sync more than one tracked workflow into the canonical state file. - `src/hud/state.ts` and `src/hooks/agents-overlay.ts` already read canonical skill-active state and are structurally closer to a peer-state model than a strict single-owner model. - `src/modes/base.ts` already preserves key standalone restrictions: `autopilot` and `autoresearch` remain exclusive; `ralph` and `ultrawork` remain mutually exclusive with each other. Primary gaps relative to the PRD/test-spec: 1. **No explicit transition-rule helper exists yet.** - Transition semantics are still distributed across mode lifecycle, keyword detection, MCP writes, HUD/overlay readers, and native-stop logic. 2. **Keyword activation is still effectively single-owner.** - `recordSkillActivation()` uses `detectPrimaryKeyword()` and writes a fresh one-entry `active_skills` array for the selected skill, so prompt-side activation still overwrites rather than validating/appending approved peer combinations. 3. **Invalid-transition guidance is not standardized.** - `src/modes/base.ts` still throws `Run cancel first.` for exclusivity failures, which does not meet the new requirement to mention explicit clearing paths via `omx state` and `omx_state.*`. 4. **The contract is not documented in one operator-facing place.** - The PRD and test spec define the rollout, but the repo lacked a dedicated contract doc describing the allowed set, the denied set, and the required recovery UX. ## Brownfield review details ### `src/state/skill-active.ts` - Good base for canonical peer state: it already deduplicates `active_skills[]` and can retain multiple active entries. - Still needs a shared allowlist-aware transition layer above persistence so the state file cannot drift into unsupported combinations. ### `src/hooks/keyword-detector.ts` - Main brownfield risk for this feature. - The prompt-side path currently records only the primary detected keyword and seeds one active skill at a time. - This is the clearest remaining single-owner assumption in the review sample. ### `src/modes/base.ts` - Current exclusivity rules are partly aligned with the rollout goals, because `team` is not exclusive while `autopilot`/`autoresearch` are. - However, the rules are encoded as a hard-coded exclusive set and generic error text, not as a canonical transition model with machine-testable guidance. ### `src/mcp/state-server.ts` - Already syncs canonical skill-active state for mode writes/clears. - Needs to consume the same allowlist/error builder as every other writer so MCP state writes cannot permit combinations the keyword or mode path denies. ### `src/hud/state.ts` and `src/hooks/agents-overlay.ts` - These consumers already appear structurally ready for a combined active set. - They still depend on upstream writers to keep the canonical state valid and to stop relying on top-level legacy fields as semantic truth. ### `src/scripts/codex-native-hook.ts` - Stop handling already reads canonical skill-active state plus mode files. - It still needs the finalized transition contract so combined-state blocking and clearing behavior stay aligned with the eventual allowlist. ## Documentation action taken in this lane Added a dedicated contract doc: - `docs/contracts/multi-state-transition-contract.md` This freezes the rollout expectations for: - approved first-pass overlaps - standalone-only workflows - denial UX requirements - brownfield consumer responsibilities - regression expectations Also clarified two adjacent operator-facing docs so the approved overlap is not misread as the old linked `team ralph` lifecycle: - `docs/contracts/ralph-state-contract.md` - `docs/codex-native-hooks.md` Added concrete recovery examples to the compatibility contract so denial messages can point operators at exact parity surfaces instead of vague placeholders: - `omx state clear --input '{"mode":"team"}' --json` - `omx_state.state_clear({ mode: "team" })` ## Reviewer conclusion The branch already has meaningful peer-state groundwork, but the PRD is correct that behavior is still fragmented. The main implementation risk is not raw state storage; it is inconsistent transition ownership across keyword activation, mode start validation, MCP writes, and stop/overlay consumers. The new contract doc should give the implementation lanes a stable operator-facing target while the code is migrated to a single allowlist-driven transition model. --- ## File: docs/contracts/mux-operation-space.md # OMX ↔ mux canonical operation space This document defines the mux boundary owned by OMX core semantics. ## Canonical operations | Operation | Purpose | |---|---| | `resolve-target` | Convert a logical delivery target into an adapter-specific endpoint. | | `send-input` | Forward literal input to a resolved target. | | `capture-tail` | Read a bounded tail of adapter output. | | `inspect-liveness` | Check whether a target is still alive. | | `attach` | Attach the operator to a live target. | | `detach` | Detach the operator from a live target. | ## Target kinds - `delivery-handle` - `detached` ## Transport primitives - `SubmitPolicy` controls how many isolated `C-m` submissions the adapter emits. - `InputEnvelope` holds literal text plus newline-normalization rules. - `InjectionPreflight` captures readiness checks before delivery. - `PaneReadinessReason` explains why a target is or is not injectable. - `DeliveryConfirmation` records whether a send was confirmed, active-task confirmed, or left unconfirmed. - `ConfirmationPolicy` defines the retry/verification window used by the adapter. ## Rules - The semantic contract must not depend on tmux-native nouns. - Tmux is the first adapter, not the model. - Adapter results may include tmux identifiers for debugging, but those identifiers are not semantic truth. - Retry, confirmation, and delivery decisions belong to the runtime contract, not the adapter implementation. ## TmuxAdapter implementation `TmuxAdapter` is fully implemented in `crates/omx-mux/src/tmux.rs`. All six canonical operations are supported. All `MuxOperation`, `MuxOutcome`, `MuxTarget`, and related types derive `Serialize`/`Deserialize`. Exact tmux CLI invocations per operation: | Operation | tmux command | |---|---| | `ResolveTarget` | `tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index}'` — verifies the handle appears in the pane list | | `SendInput` | `tmux send-keys -t -l ''` (literal text), then one `tmux send-keys -t C-m` per press defined by `SubmitPolicy::Enter { presses, delay_ms }` | | `CaptureTail` | `tmux capture-pane -t -p -S -` | | `InspectLiveness` | `tmux has-session -t ` (session name extracted from the handle, e.g. `"mysess:0.1"` → `"mysess"`) | | `Attach` | `tmux attach-session -t ` | | `Detach` | `tmux detach-client -t ` | Target handles use the format `session_name:window_index.pane_index` (e.g. `"omx:0.1"`). `MuxTarget::Detached` is rejected for all operations that require a real pane.