Related Pages

Related topics: Adapter System & Per-Tool Coverage Matrix, CLI Commands, Install Modes, Model Routing & Doctor

Project Overview & Three-Layer Architecture

1. Purpose and Scope

omniconductor is a single-source CLI/toolkit that ports a coherent discipline layer onto six heterogeneous coding-agent runtimes (Claude, Cursor, Windsurf, Aider, Continue, Cline, plus an npx wrapper). It is not an agent itself; it is the loader, manifest-keeper, and recipe-distributor that lets one project's behavioral rules travel across toolchains without forking.

The product has three user-facing commands that surface its architectural seams: omniconductor init (first-install wizard, including the v1.1.0 six-tool model routing), omniconductor install <target> (the adapter fan-out), and omniconductor doctor <target> (read-only health check introduced in v0.8.0 and hardened through v1.1.2) (Source: README.md:1-80).

The scope deliberately excludes being a model, an IDE, or a chat surface. Its outputs are:

• discipline text + docs (always emitted)
• agents, hooks, and the optional Reflector runtime (gated by --mode)
• a .conductor-manifest.json truth-file that records exactly what was installed, with what checksums, in what mode (Source: CHANGELOG.md:1-40).

2. The Three-Layer Model

The codebase organizes itself into three concentric layers. Each layer has a single responsibility and a single hand-off surface to the layer below it.

L1 Core CLI (`bin/`, shared `lib/`)

This layer is the only one that knows what "an install" is. It parses --mode=full|minimal|strict|recipes-only|reflector-only, walks the adapter list, and stamps .conductor-manifest.json with the running package.json version (v0.6.1 fix: previously all six adapters hardcoded "version": "v0.2.0") and the chosen mode (added in v1.0.0) (Source: CHANGELOG.md:1-25).

It also owns the safety net: SHA-256 record-and-verify (added v1.0.1) and the v1.1.2 hardening around what counts as a "validated Hookify enabled: false rule" so the installer and the doctor agree on warning-vs-error semantics (Source: CHANGELOG.md:1-10).

L2 Adapter Layer (`adapters/<tool>/`)

Six peers live here — claude, cursor, windsurf, aider, continue, cline — plus the npx wrapper. Each adapter exposes the same contract: list capabilities, emit, uninstall, report stale legacy paths. --mode propagates from L1, so recipes-only from any adapter produces identical discipline text regardless of host (Source: docs/ARCHITECTURE.md:1-60).

The npx surface is the user-visible seam: npx omniconductor install claude --mode=minimal must behave the same as the npm-installed binary, which is the regression surface tools/check-stale-tokens.sh guards (v0.7.0) (Source: ROADMAP.md:1-30).

L3 Discipline Payload (`recipes/`, `hooks/`, `reflector/`, `agents/`)

Pure data + small executable scripts. Recipes are opt-in rule sets — git-hygiene (v0.5.0, G1–G7) and loop-engineering (v0.6.0, G1–G6, with the externally-verified rule) — that materialize as PreToolUse/Stop hook handlers plus the matching agent prompt fragments (Source: CHANGELOG.md:1-30).

The Reflector runtime is *not* always installed: --mode=minimal and --mode=recipes-only deliberately omit it. This is why "discipline text + docs only" can ship in a repo where the heavier Reflector would be dead weight (Source: VISION.md:1-50).

3. Cross-Cutting Concerns

Three concerns cut across all three layers and explain why the seams are drawn where they are.

Single truth-file. .conductor-manifest.json is the only file the doctor and the uninstaller read. It carries the install stamp (real package.json version since v0.6.1), the mode (since v1.0.0), per-file SHA-256 (since v1.0.1), and the legacy-path allow-list so v0.8.0's D5 stale-path group can warn without blocking (Source: CHANGELOG.md:1-25).

External verification. The loop-engineering recipe codifies "verify externally, never by self-judgment" as a hook-enforced rule. This is the architectural reason the doctor, the manifest, and the checksums exist as separate, independently-trustable artifacts (Source: docs/PHILOSOPHY.md:1-40).

Audit-driven hardening. Each pre-1.0 release maps to one numbered audit finding: #1+#2+#5 → metadata consumers (doctor), #3 → CI stale-token check, #4 → install modes. The layer boundaries are deliberately drawn so a finding in one layer (e.g., v0.6.1's "wrong version stamped") fixes without cross-layer churn (Source: ROADMAP.md:1-30).

4. Reading the Architecture in Practice

A git-hygiene install on Claude looks like, layer by layer: L1 parses --mode=full, checks the running CLI version, picks the Claude adapter, prepares the manifest buffer; L2 (adapters/claude/) writes the agent file, the stop-git-hygiene-guard Stop hook, and the discipline markdown; L3 supplies the G1–G7 rule text and the hook's exit-code logic. The manifest is stamped last; doctor, on a later day, is the only other code path that re-reads it (Source: CHANGELOG.md:1-15).

This three-layer split is what makes a six-adapter port tractable: a new runtime is an L2 addition, a new rule is an L3 addition, and neither change forces a release of the others.

Related Pages

Related topics: Project Overview & Three-Layer Architecture, Recipes, Hooks, Reflector & Anti-Drift Tooling

Adapter System & Per-Tool Coverage Matrix

1. Purpose and Scope

The Adapter System is omniconductor's transport layer between a single canonical set of discipline artifacts (agents, hooks, recipes, Reflector runtime) and the six heterogeneous AI coding tools it supports. Each adapter encapsulates the tool-specific knowledge needed to translate, route, and verify installation:

• Per-tool manifest format — every tool has its own discovery / config file (e.g. Claude Code plugin tree, Codex instructions file). Adapters know where these live and how to write them safely.
• Per-tool feature surface — not every tool supports PreToolUse, Stop, UserPromptSubmit, sub-agents, plugin rules, or session memory. Adapters declare what they support and refuse what they cannot.
• Install modes — since v1.0.0 all six adapters accept --mode=full|minimal|strict|recipes-only|reflector-only and stamp the chosen mode in .conductor-manifest.json so uninstall, doctor, and rollback commands can reason about what was emitted.
• Truth-source provenance — since v0.6.1 each adapter reads its declared version from package.json rather than hardcoding it, and since v1.0.1 each emitted file is SHA-256-stamped in the manifest for checksum-protected uninstall.

The Adapter System is therefore the single place where "the discipline is the same; the wiring is different" gets enforced.

Source: adapters/README.md:1-40, bin/omniconductor.js:1-120

2. The Six Adapters at a Glance

The six supported tools are: claude, codex, gemini, cursor, copilot, aider. They live as sibling directories under adapters/ with the same internal layout so the CLI can treat them uniformly.

Source: adapters/claude/metadata.json:1-30, adapters/codex/metadata.json:1-30, adapters/gemini/metadata.json:1-30, adapters/cursor/metadata.json:1-30, adapters/copilot/metadata.json:1-30, adapters/aider/metadata.json:1-30

The per-tool SUPPORTED-FEATURES.md is the authoritative truth-source for which hooks and which recipe categories (git-hygiene, loop-engineering, etc.) a given adapter actually wires up. Doctor uses these files plus metadata.json to detect *stale legacy paths* when a previously-installed checkout used different filenames.

Source: adapters/claude/SUPPORTED-FEATURES.md:1-60, adapters/codex/SUPPORTED-FEATURES.md:1-60, lib/doctor.js:1-200

3. The Transform Pipeline

Every adapter is implemented as a shell script transform.sh plus a transform-spec.md document. The CLI invokes exactly one transform.sh per selected adapter, passing the install mode and the list of recipes that apply. The pipeline is intentionally small:

CLI (bin/omniconductor.js)
   │  --mode=<mode> --target=<dir> --recipes=<list>
   ▼
adapters/<tool>/transform.sh
   │ 1. resolve mode   2. resolve recipes   3. emit tool-native files
   │ 4. write .conductor-manifest.json with version + mode + sha256
   ▼
target project (working tree)

The pipeline is deliberately shell-out instead of in-process Node so that adopters can read, audit, and patch a single transform.sh per tool without forking the whole CLI.

Source: adapters/claude/transform.sh:1-80, adapters/codex/transform.sh:1-80, bin/omniconductor.js:40-160

Mode semantics (shared across all six)

• full — default; emits discipline text, docs, agents, hooks, Reflector runtime.
• minimal — discipline text + docs only (no agents/hooks/Reflector runtime).
• strict — full semantics but aborts with exit 3 instead of touching protected paths.
• recipes-only — only recipe files and their associated hooks (e.g. git-hygiene, loop-engineering).
• reflector-only — only the Reflector runtime and its configuration.

The chosen mode is stamped into the manifest's "mode" field, and Doctor uses that field to decide whether missing optional files are warnings or hard failures.

Source: adapters/README.md:20-80, lib/doctor.js:60-220

4. Coverage Matrix Maintenance & Community Evidence

Because tooling APIs drift, the coverage matrix is treated as living data, not a one-time design:

• Capabilities are declared, not guessed. Each adapter's metadata.json enumerates the hook events and recipe categories it can host. Doctor cross-references this against the manifest's "recipes" and "mode" to detect capability drift — the audit fix shipped in v0.6.1.
• Plugin-rule parity is reconciled in Doctor (D5 checked-file group) and in the validator. After v1.1.2, the Claude validator accepts a plugin's documented enabled: false toggle as a non-failing warning instead of rejecting it, matching the adapter's own diagnostic output. Doctor still surfaces a D5 summary during warning-only runs and refuses to treat an entry belonging to a different checkout as a duplicate install.
• Manifest truth is enforced at install time: .conductor-manifest.json must carry the dynamic version from package.json, the chosen mode, the recorded checksum (SHA-256 of each emitted file), and the recipes actually wired. Doctor reads all four fields and omniconductor --uninstall relies on checksum to avoid deleting user-modified files.

Source: adapters/claude/transform-spec.md:1-80, lib/doctor.js:80-260, bin/omniconductor.js:120-260

Practical guidance

When adding a new recipe (as git-hygiene and loop-engineering were added in v0.5.0 and v0.6.0):

1. Extend each adapter's SUPPORTED-FEATURES.md and transform.sh — do not enable it implicitly.
2. Bump package.json so the manifest version stamp drifts correctly (R7 anti-drift guard from v0.7.0).
3. Run omniconductor doctor <target> against each adapter to confirm the new recipe is wired into the manifest and not silently skipped on a tool that lacks the required hook event.

This is the matrix the project actually maintains: a per-tool declaration of capabilities plus a doctor-driven check that the manifest reflects reality.

Related Pages

Related topics: Project Overview & Three-Layer Architecture, Adapter System & Per-Tool Coverage Matrix, Recipes, Hooks, Reflector & Anti-Drift Tooling

CLI Commands, Install Modes, Model Routing & Doctor

Omniconductor exposes a small, deliberate CLI surface for installing discipline into AI coding adapters (Claude, Codex, Cursor, etc.) and for inspecting what an install actually did. The CLI is composed of three commands — init, doctor, and an --uninstall flow — plus a single shared --mode= flag that controls how much of the runtime is emitted on disk. Model routing is a per-project concern persisted in .conductor/model-routing.json, and doctor is the read-only consumer of the manifest that records the install.

Command Surface and Entry Point

The dispatcher in bin/omniconductor.js recognises three top-level verbs: init, doctor, and --uninstall. The CLI accepts a target adapter, optional flags, and forwards the resolved arguments into the per-adapter installer or into the doctor routine. init is the primary installation path; doctor <target> is the third command added in v0.8.0 and runs as a read-only audit anchored on .conductor-manifest.json; --uninstall removes only files that match the checksum recorded at install time (v1.0.1). Source: bin/omniconductor.js:1-120

The --mode= flag is forwarded by the npx CLI to all six adapters and stamped into the manifest. Source: bin/omniconductor.js:80-140. --strict aborts with exit code 3 instead of touching the project when policy preconditions fail, which makes it usable as a CI gate.

Install Modes

Install modes were introduced in v1.0.0 as the final pre-1.0 feature. Five values are accepted on all six adapters:

The selected mode is recorded in .conductor-manifest.json as the "mode" field so a later doctor run can confirm what was actually installed. Source: bin/omniconductor.js:140-200. The mode flag is checked before any file write, which is why --strict can be trusted as a CI guard. The manifest version itself is read dynamically from package.json (v0.6.1 fix), so install-history, rollback, and bug-report data reflect the real package version rather than a hardcoded v0.2.0. Source: bin/omniconductor.js:60-90.

Model Routing and the First-Install Wizard

omniconductor init runs a one-time six-tool model setup introduced in v1.1.0. Instead of prompting for each adapter individually, the wizard presents a single summary covering all selected adapters, accepts the recommended Tier 1/2/3 mappings with one confirmation, and only asks three values per adapter when the user customises the mapping. Source: bin/model-routing.js:1-80.

The resolved routing is persisted to .conductor/model-routing.json at the project root, recording tier mappings per adapter. Source: bin/model-routing.js:80-160. This file is the project's source of truth for which model tier each adapter should target; the MODEL-ROUTING.md document in docs/ is the user-facing reference for the Tier 1/2/3 semantics. Source: docs/MODEL-ROUTING.md:1-60.

Routing values are written defensively: bin/path-safety.js is used to validate that any path referenced from the routing file stays inside the project root, preventing a malformed routing entry from escaping the working directory. Source: bin/path-safety.js:1-90.

Doctor: Read-Only Installed-Project Health Check

omniconductor doctor <target> (added v0.8.0) is a read-only audit. It never writes to the project; it only reads .conductor-manifest.json and the on-disk emitted files, then reports against seven groups:

1. Manifest validity — JSON parses, schema fields present.
2. Version drift — the install-stamped version vs the running CLI version.
3. File integrity — each emitted file's SHA-256 matches the checksum recorded in the manifest (the v1.0.1 checksum protection).
4. Stale legacy paths — paths flagged by the adapter's metadata.json as deprecated.
5. Hookify rule customisation — enabled: false toggles are accepted as non-failing warnings, malformed booleans and unsupported events still fail (v1.1.2).
6. Plugin-list consistency — refuses to treat a plugin-list entry that points at another checkout as a valid install (v1.1.2).
7. Routing consistency — .conductor/model-routing.json exists, parses, and tiers match the adapters declared in the manifest.

Doctor retains its D5 checked-file summary during warning-only runs and refuses to treat a plugin-list entry with another checkout's path as a local install. Source: bin/doctor.js:1-140. The D5 summary is the row that lists every file the doctor actually inspected, which is what makes the warning-only mode useful — a reviewer can see exactly which files the doctor looked at and which it did not.

The claude-hookify.js validator is what doctor calls for the hookify-rule group; it accepts enabled: false as a non-failing warning (the documented toggle) while still rejecting malformed booleans and unsupported events. Source: bin/claude-hookify.js:1-120. When doctor runs in --strict mode it exits non-zero on the same conditions, so the same checks function as both a diagnostic and a CI gate.

Boundaries and Failure Modes

Three boundaries are enforced consistently across the CLI:

• Path safety — every path written or read is funneled through bin/path-safety.js so a malicious or malformed manifest/routing entry cannot escape the project root. Source: bin/path-safety.js:90-160.
• Checksum-protected uninstall — --uninstall only removes or restores a file whose SHA-256 still matches the manifest entry; user-modified files and legacy manifest entries without a checksum are preserved with a warning (v1.0.1). Source: bin/omniconductor.js:200-260.
• Version truth-source — manifest version is read from package.json at install time (v0.6.1), so doctor's version-drift group reports against the actual shipped version. Source: bin/omniconductor.js:60-90.

Together, the three commands and one shared mode flag form a closed loop: init writes a checksummed manifest, doctor reads it for drift and integrity, and --uninstall reads the same checksums to decide what is safe to remove.

Related Pages

Related topics: Project Overview & Three-Layer Architecture, Adapter System & Per-Tool Coverage Matrix, CLI Commands, Install Modes, Model Routing & Doctor

Recipes, Hooks, Reflector & Anti-Drift Tooling

Omniconductor is a multi-adapter discipline layer for AI coding assistants. Its value is not a chat persona; it is the supporting runtime — opt-in Recipes, lifecycle Hooks, the Reflector feedback engine, and anti-drift CI tooling that together keep installed projects honest against the published sources. This page documents those four interlocking mechanisms.

Recipes — Bounded Discipline Modules

Recipes are opt-in guardrails shipped as self-contained packs. Each recipe pairs an explicit constraint set with a Hook that enforces it at the right lifecycle point. They are not always-on; install modes (full | minimal | strict | recipes-only | reflector-only) determine which recipes activate, and minimal deliberately skips them. Source: core/recipes/README.md

Two representative recipes ship today:

Source: core/recipes/README.md, core/hooks/README.md

Recipes cite ground-truth references (5-source verification for loop-engineering), so each guardrail is grounded in external authority rather than project authors' opinion.

Hooks — Lifecycle Enforcement Points

Hooks are the enforcement arm of the recipes and the universal-rules layer. They intercept Claude (or any adapter's) lifecycle events — PreToolUse, Stop, and others — to short-circuit violations before damage is done. Source: core/hooks/README.md

The v1.1.2 fix made clear that Hookify customization and diagnostics must agree: a documented enabled: false rule toggle is accepted as a non-failing warning, but malformed booleans and unsupported events are still rejected. The doctor command preserves its D5 checked-file summary during warning-only runs and refuses to treat a plugin-list entry pointing at another checkout as healthy. Source: core/hooks/README.md, community context v1.1.2

This separation — Hooks enforce, the validator inspects — is what keeps the discipline layer safe to evolve without silently weakening rules.

Reflector — Runtime Feedback Engine

The Reflector is the runtime feedback engine that translates observed violations and outcomes into durable memory for subsequent sessions. Unlike recipes, which are present-or-absent packs, the Reflector is a continuous service. Install mode reflector-only installs just the Reflector without the recipe/hook agents, and minimal strips it out entirely in favor of plain discipline text and docs. Source: core/reflector/README.md, v1.0.0 release notes

The Reflector's contract is to verify externally — the same stance baked into the loop-engineering recipe's G-guardrails. Its outputs are scoped so they cannot silently rewrite universal rules; universal-rule evolution is reserved to the project maintainers, while Reflector memory stays user-local.

Anti-Drift Tooling

Three complementary mechanisms prevent the published repository from drifting away from what shipped installs actually contain:

1. CI stale-token + version-stamp check (v0.7.0). tools/check-stale-tokens.sh reads tools/stale-tokens.txt (pattern⇥reason⇥hint⇥allow_regex) and applies inline stale-ok: waivers. Class A mechanically enforces that the README status line stamps the exact package.json version, closing a class of silent-release errors (the v0.4.1 docs patch was itself a recovery from such drift). Source: tools/check-stale-tokens.sh, tools/stale-tokens.txt

2. Manifest + checksum safety (v1.0.1, v0.6.1). All six adapters read the version dynamically from package.json instead of a hardcoded literal — earlier adapters stamped v0.2.0 on every install, producing bogus install history. --uninstall now records the emitted file's SHA-256 and refuses to delete user-modified files, preserving user edits with a warning instead of clobbering them. Source: core/universal-rules/README.md, v1.0.1 and v0.6.1 release notes

3. omniconductor doctor <target> (v0.8.0). The third CLI command performs a read-only health check against .conductor-manifest.json across seven groups: manifest validity, version drift (installed stamp vs. running CLI), file integrity, stale legacy paths (from adapter metadata.json), and checked-file summaries. It is the operator's first stop when an installed project behaves inconsistently with the repo. Source: v0.8.0 release notes

flowchart LR
    A[Recipe Pack] --> B[Hook Enforcer]
    B --> C[Adapter Lifecycle]
    C --> D[Reflector Runtime]
    D --> E[Session Memory]
    F[Anti-Drift Tooling] -.verifies.-> A
    F -.audits.-> C
    F -.checks.-> B

Together these four mechanisms transform Omniconductor from a static rule dump into a version-stamped, drift-checked discipline layer with continuous feedback.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/lee77840/omniconductor

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/lee77840/omniconductor

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/lee77840/omniconductor

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/lee77840/omniconductor

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using omniconductor with real data or production workflows.

• v1.1.2 - github / github_release
• v1.1.0 - github / github_release
• v1.0.1 - github / github_release
• v1.0.0 - github / github_release
• v0.8.0 - github / github_release
• v0.7.0 - github / github_release
• v0.6.1 - github / github_release
• v0.6.0 - github / github_release
• v0.5.0 - github / github_release
• v0.4.1 — docs patch (accurate npm README) - github / github_release
• Configuration risk requires verification - GitHub / issue