Find Omnibus

/find-omnibus

Kotlin/JVM 2.4.10 branch

Trigger this branch only for manifest-selected authored .kt declarations with explicit scout JSON. Keep sibling _kotlin, read ../_kotlin/GUIDE.md, and enter through scripts/run_kotlin.py. Declaration-name clusters only nominate candidates; the scout owns domain judgment. Resolved calls, overrides, delegation, reflection, generated members, Java, Gradle variants, runtime topology, and safe decomposition remain unresolved.

C# 14 / .NET 10 branch

Use scripts/run_csharp.py with the sibling _csharp provider and explicit scout JSON; run it with --help for the exact CLI. Direct method-name clusters from the current compiled manifest closure nominate candidates only. An explicit scout must distinguish domains from facets; syntax never proves responsibility boundaries or safe decomposition.

C++20 branch

Use scripts/run_cpp.py with the sibling _cpp provider and explicit scout JSON; run the script with --help for the exact CLI. It nominates name-cluster candidates from a current complete C++20 compiler-owned graph while retaining namespace/signature/overload identity. Human judgment owns responsibilities; ODR/ABI, specializations, dispatch, external variants, and safe decomposition are not inferred.

C17 branch

Use scripts/run_c.py with the sibling _c-syntax provider and explicit scout JSON; run python3 scripts/run_c.py --help for the exact CLI. This external- library branch uses function-name clusters only to nominate candidates. Human domain judgment remains mandatory, and no runtime responsibility or safe decomposition is inferred.

External syntax variants

For PHP or Ruby, load the selected skill with its sibling provider and read the matching on-demand guide before execution:

• ../_php-syntax/GUIDE.md
• ../_ruby-syntax/GUIDE.md

Both produce syntax candidates requiring hash-bound human scout judgment. The guides own the exact commands, copied closures, native gates, and non-claims.

Dart v1

Dart v1 consumes direct declarations from the shared _dart D3 snapshot and nominates four-or-more paired head-noun domains. Every candidate requires a SHA-bound scout verdict; syntax alone never becomes a decomposition finding.

SKILL_ROOT=".agents/skills/on-demand/find-omnibus"
python3 "${SKILL_ROOT}/scripts/run_dart.py" \
  --project-root "$PWD" --target lib --facts /tmp/dart-d3-facts.json \
  --output-dir "$PWD/reports/omnibus/dart" \
  --scout-dir "$PWD/reports/omnibus/dart/scout"

Rust v1

Rust v1 uses bounded named-item syntax to propose files with four or more paired head-noun domains, but the existing Stage 3 scout must still grade every candidate. A syntax candidate alone is never an omnibus verdict. Copy sibling _rust-syntax with this skill and keep cfg/macro/build uncertainty partial.

SKILL_ROOT=".agents/skills/on-demand/find-omnibus"
python3 "${SKILL_ROOT}/scripts/run_rust.py" \
  --project-root "$PWD" --target src \
  --output-dir "$PWD/reports/omnibus/rust" \
  --scout-dir "$PWD/reports/omnibus/rust/scout"

You are the orchestrator for an omnibus-module audit. Your job is to drive a detector + a scout-verification fan-out; the judgment calls (facet vs domain, known false-positive shapes, decomposition sketch) live in the scout brief and the knowledge files, not in this prompt.

The four buckets (confirmed_omnibus, borderline, coordination_omnibus, facets_not_domains), the facet-vs-domain evaluation rule, and the decomposition-sketch format are documented in knowledge/verification.md — scouts read it, you don't.

How success is judged

• Every reported candidate carries a Stage 3 scout verdict at scout/<candidate_id>.json, bucketed by the facet-vs-domain rule (confirmed_omnibus / borderline / coordination_omnibus / facets_not_domains) — no detector hit reaches report.md ungraded.
• The closeout pastes the real Stage 1/2/4 stderr lines ([detect_omnibus], [collapse], [report]) plus the scout JSON count; claims without those artifacts do not satisfy the audit.
• The substrate gate (ADR 0032 rule 3) ran before any decomposition recommendation; failing layers get "substrate ADR first", not a spec.
• The handoff is named: /refactor-subsystem <spec-id> for confirmed candidates, /map-product-workflow for coordination_omnibus.
• Zero code edits — read-only audit.
• A Java Stage 1 run writes scan.json; its final findings.json repeats the Java status, source inventory, and compiler-tree provenance. A zero-candidate result is clean only when that status is complete. Write toward these gates from Stage 0.

Scope

• Target path: the required --target argument. Must be a directory.
• Project root: this worktree's root.
• Python: host Python 3.11+; use the host .venv/bin/python when present, otherwise python3. Never depend on a toolkit venv.
• TypeScript v1: Node plus typescript resolvable from the target project's package.json. The bundled parser needs syntax spans only; it deliberately does not read tsconfig, resolve modules, inspect types, or infer framework behavior. Missing prerequisites fail Stage 1 clearly.
• Go v1: Go 1.22+ on PATH. The bundled helper uses go/parser and go/ast for top-level functions and methods only; it resolves no imports or types. Generated, vendored, test, and testdata sources are excluded. Build-constrained files stop the scan as unsupported rather than being silently omitted.
• Java v1: JDK 17+ (java and javac) on PATH. The bundled public Compiler Tree API helper extracts only direct methods and constructors of named top-level types, with exact source spans. It does not resolve imports, types, aliases, overloads, receivers, or frameworks; nested/local/anonymous types, lambdas, implicit constructors, Kotlin, and build semantics are out of scope. Generated, vendored, test, build-output, and external-symlink sources are excluded. Syntax/read/tool failures stop Stage 1 with exit 2; they never become a zero-candidate result. A Java-only target containing Kotlin source also stops as unsupported rather than presenting Kotlin as Java coverage. An empty or excluded-only selection in a Java-only project is unsupported (exit 2), not a clean zero-candidate scan.
• Swift v1: Swift 6+ (swiftc) on PATH, bounded to dependency-free SwiftPM source. The family-local adapter requires successful compiler syntax/typecheck evidence, parses only an explicit fail-closed subset of swiftc -dump-ast, and carries complete, partial, unsupported, or failed through the final report. It does not claim SwiftSyntax, resolved references, complete project semantics, Xcode/framework behavior, macros, reflection, conditional-compilation completeness, or mixed-language support.
• Project-specific defaults (generic-verb strip list, skip patterns, directory-package precedent, known false-positive shapes): in knowledge/.
• Coordination omnibus rule: broad workflow coordinators such as app/views/site_config.py may be real omnibus files even when most domain behavior has moved out. Bucket them as coordination_omnibus when the next improvement is a workflow registry or route ownership map, not another service extraction.

Pipeline stages (each has a contract)

Each stage reads files the previous stage wrote and writes files the next stage reads. Set TARGET to the requested directory. Before each command block, run this resolver verbatim from the project root; it supports both the stock install location and this repository's source-tree location:

SKILL_ROOT=""
for SKILL_CANDIDATE in \
  ".agents/skills/find-omnibus" \
  ".claude/skills/find-omnibus"
do
  if [ -f "${SKILL_CANDIDATE}/SKILL.md" ]; then
    SKILL_ROOT="$(cd "${SKILL_CANDIDATE}" && pwd)"
    break
  fi
done
if [ -z "${SKILL_ROOT}" ]; then
  printf '%s\n' "find-omnibus is not installed in .agents/skills or .claude/skills" >&2
  exit 2
fi
if [ -n "${ENGINEERING_SKILLS_PYTHON:-}" ]; then
  if [ ! -x "${ENGINEERING_SKILLS_PYTHON}" ]; then
    printf '%s\n' "ENGINEERING_SKILLS_PYTHON must name an executable Python 3.11+ runtime" >&2
    exit 2
  fi
  HOST_PYTHON="${ENGINEERING_SKILLS_PYTHON}"
elif [ -x ".venv/bin/python" ]; then
  HOST_PYTHON="$(pwd)/.venv/bin/python"
else
  HOST_PYTHON="python3"
fi

Stage 0 — Setup

Pre: none. Post: ${REPORT_DIR} exists, latest symlink points to it.

: "${TARGET:?Set TARGET to the directory to audit}"
TS=$(date +%Y%m%d-%H%M%S)
REPORT_DIR="reports/omnibus/scan-${TS}"
mkdir -p "${REPORT_DIR}/scout"
ln -sfn "scan-${TS}" reports/omnibus/latest

Stage 1 — Detect

Pre: target directory exists. Post: omnibus.jsonl with one record per flagged file (score-sorted by responsibility count, then security/side-effect sensitivity, then LOC). When the selected inputs are Java, including through this generic command, Stage 1 also writes adjacent scan.json with its source-role inventory and parser provenance.

: "${TARGET:?Set TARGET to the directory to audit}"
REPORT_DIR="reports/omnibus/$(readlink reports/omnibus/latest)"
"${HOST_PYTHON}" "${SKILL_ROOT}/scripts/detect.py" \
  --target "${TARGET}" \
  --project-root "$(pwd)" \
  --output "${REPORT_DIR}/omnibus.jsonl"

Stage 2 — Collapse

Pre: omnibus.jsonl. Post: ${REPORT_DIR}/candidates.jsonl — top-30 candidates with candidate_id assigned.

REPORT_DIR="reports/omnibus/$(readlink reports/omnibus/latest)"
"${HOST_PYTHON}" "${SKILL_ROOT}/scripts/collapse.py" \
  --detections "${REPORT_DIR}/omnibus.jsonl" \
  --output "${REPORT_DIR}/candidates.jsonl" \
  --top 30

Stage 3 — Verify (parallel fan-out)

Pre: candidates.jsonl. Post: ${REPORT_DIR}/scout/<candidate_id>.json for every verified candidate.

This is the only stage where LLM judgment runs. Use the host agent's standard sub-agent capability directly. Dispatch one fresh read-only sub-agent per top-10 candidate (or fewer if the candidate list is shorter). Do not invoke an external model CLI, toolkit dispatcher, host adapter, or another skill. Each sub-agent receives:

• the candidate JSON (one line from candidates.jsonl),
• the prompt template from agents/verify.md,
• the bundled knowledge/verification.md,
• an output path it must write to.

Budget: verify up to the top 10 candidates by default. If the user asked for a deeper scan, raise the budget. If the user asked for a specific subset (e.g., "only the views"), filter before dispatch.

For each candidate, expand the bundled agents/verify.md (substitute {{candidate_id}}, {{candidate_json}}, {{project_root}}, {{skill_root}}, {{output_path}}) and send it through the standard sub-agent capability. Dispatch concurrently when capacity allows; when it does not, dispatch serially. Capacity may change latency, never the verdict source.

Declare the verdict to every scout: its output is accepted only if it writes valid JSON at {{output_path}}, uses one of the four buckets, records domains_confirmed and facets_collapsed, and provides decomposition_depth_note for confirmed omnibus files. When merging, reject or re-dispatch malformed scout files; do not let report.py turn an unverified candidate into a decomposition recommendation.

If a scout returns invalid JSON or flags the verification as aborted, re-dispatch once with a stricter "respond only with file-write confirmation" nudge; skip the candidate if it fails twice.

Stage 4 — Report

Pre: candidates.jsonl, scout/*.json. Post: ${REPORT_DIR}/report.md and ${REPORT_DIR}/findings.json. When Stage 1 emitted Java scan.json, the report carries its status and provenance forward; do not call an unsupported or partial Java selection clean.

: "${TARGET:?Set TARGET to the directory to audit}"
REPORT_DIR="reports/omnibus/$(readlink reports/omnibus/latest)"
"${HOST_PYTHON}" "${SKILL_ROOT}/scripts/report.py" \
  --candidates "${REPORT_DIR}/candidates.jsonl" \
  --scout-dir "${REPORT_DIR}/scout" \
  --output-md "${REPORT_DIR}/report.md" \
  --output-json "${REPORT_DIR}/findings.json" \
  --scan-id "$(basename "${REPORT_DIR}")" \
  --target "${TARGET}"

The four scripts in this skill are self-contained; a host may record an effectiveness event separately, but that optional repository concern is not part of the selected-skill runtime.

Stage 5 — Summarize

Report to the user in ≤10 lines:

• counts by bucket (confirmed_omnibus / borderline / coordination_omnibus / facets_not_domains / unverified),
• top 3 candidates (one line each: file, and-count, risk signals, recommendation),
• path to ${REPORT_DIR}/report.md and the latest symlink,
• recommended next slash command — for the worst confirmed candidate, /refactor-subsystem <spec-id> in decomposition mode. Remind the user that the spec must be scaffolded first under ai-docs/specs/<id>.md (Phase 0 of /refactor-subsystem handles the stub). For coordination_omnibus, prefer /map-product-workflow and /extract-workflow-registry before decomposition.

Substrate gate (ADR 0032 rule 3). Before recommending decomposition for any confirmed candidate, check the target layer's substrate: (a) a module/import mechanism, (b) test infrastructure that can pin behavior across the split, (c) infrastructure helpers (fetch/escape/log wrappers) that exist once, not per-file. Python targets in a tested package pass trivially. A script-tag JavaScript file with no module system fails (a) and usually (b) — splitting it just multiplies globals. When any leg fails, the recommendation is re-architect: substrate ADR first (module mechanism, test story, shared-helper home), with a grandfathered size-growth lint as the interim control — not a decomposition spec. Findings from heuristic adapters (analyzer != python-ast) deserve a skim of the actual file before this call; coarse extraction can over- or under-cluster.

The report is the source of truth — do not enumerate every candidate.

Replay case

When detect.py, collapse.py, report.py, or the scout JSON schema changes, replay a disposable Python target with one file containing three independently understandable domains (for example credentials loading, export rendering, and task dispatch) plus one cohesive helper file. Expected evidence: Stage 1 writes exactly one omnibus candidate for the multi-domain file; Stage 2 preserves that candidate; after a hand-written scout JSON that buckets it as confirmed_omnibus, Stage 4 writes report.md and findings.json with one decomposition recommendation and no finding for the cohesive helper.

Non-goals

• Executing decompositions (that's /refactor-subsystem after user approval).
• Editing or deleting code — read-only audit.
• Detecting duplication (that's /find-duplication / /find-semantic-duplication).
• Detecting layer violations (that's /find-layer-violation).
• Running tests — the report is the output; tests run during /refactor-subsystem.
• CI gates — periodic audit, not a per-commit check.

When things go sideways

Repository layout

find-omnibus/
├── SKILL.md                  # this file — orchestrator
├── scripts/
│   ├── detect.py             # Stage 1 — Python/JS/TS/Go/Java cluster extraction
│   ├── detect_typescript_symbols.mjs  # bundled Compiler API TS/TSX spans
│   ├── detect_go_symbols.go  # bundled Go standard-library syntax facts
│   ├── detect_java_symbols.java # bundled JDK 17+ direct top-level symbols
│   ├── collapse.py           # Stage 2 — cap to top-N, assign ids
│   └── report.py             # Stage 4 — render report.md + findings.json
├── agents/
│   └── verify.md             # Stage 3 scout brief
└── knowledge/                # sub-agent context, never loaded by orchestrator
    └── verification.md

The orchestrator (you) never reads files in knowledge/. Those are for the scout sub-agents. Keeping them out of your context is the whole point of this architecture.