# https://github.com/lee77840/omniconductor Project Manual

Generated at: 2026-07-20 05:11:42 UTC

## Table of Contents

- [Project Overview & Three-Layer Architecture](#page-1)
- [Adapter System & Per-Tool Coverage Matrix](#page-2)
- [CLI Commands, Install Modes, Model Routing & Doctor](#page-3)
- [Recipes, Hooks, Reflector & Anti-Drift Tooling](#page-4)

<a id='page-1'></a>

## Project Overview & Three-Layer Architecture

### Related Pages

Related topics: [Adapter System & Per-Tool Coverage Matrix](#page-2), [CLI Commands, Install Modes, Model Routing & Doctor](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/lee77840/omniconductor/blob/main/README.md)
- [VISION.md](https://github.com/lee77840/omniconductor/blob/main/VISION.md)
- [ROADMAP.md](https://github.com/lee77840/omniconductor/blob/main/ROADMAP.md)
- [CHANGELOG.md](https://github.com/lee77840/omniconductor/blob/main/CHANGELOG.md)
- [docs/ARCHITECTURE.md](https://github.com/lee77840/omniconductor/blob/main/docs/ARCHITECTURE.md)
- [docs/PHILOSOPHY.md](https://github.com/lee77840/omniconductor/blob/main/docs/PHILOSOPHY.md)
- [package.json](https://github.com/lee77840/omniconductor/blob/main/package.json)
</details>

# 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.

| Layer | Responsibility | Hand-off Surface |
|---|---|---|
| **L1 — Core CLI** | commands, manifest I/O, mode gating, checksum math | adapter descriptor + manifest JSON |
| **L2 — Adapter Layer** | tool-specific emit/restore logic for the six runtimes | a tree of files to write |
| **L3 — Discipline Payload** | reusable recipes, hook scripts, agent prompts, Reflector | nothing — pure data |

### 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.

---

<a id='page-2'></a>

## Adapter System & Per-Tool Coverage Matrix

### Related Pages

Related topics: [Project Overview & Three-Layer Architecture](#page-1), [Recipes, Hooks, Reflector & Anti-Drift Tooling](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [adapters/README.md](https://github.com/lee77840/omniconductor/blob/main/adapters/README.md)
- [adapters/claude/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/claude/transform.sh)
- [adapters/claude/transform-spec.md](https://github.com/lee77840/omniconductor/blob/main/adapters/claude/transform-spec.md)
- [adapters/claude/metadata.json](https://github.com/lee77840/omniconductor/blob/main/adapters/claude/metadata.json)
- [adapters/claude/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/claude/SUPPORTED-FEATURES.md)
- [adapters/codex/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/codex/transform.sh)
- [adapters/codex/transform-spec.md](https://github.com/lee77840/omniconductor/blob/main/adapters/codex/transform-spec.md)
- [adapters/codex/metadata.json](https://github.com/lee77840/omniconductor/codex/transform.sh)
- [adapters/codex/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/codex/SUPPORTED-FEATURES.md)
- [adapters/gemini/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/gemini/transform.sh)
- [adapters/gemini/metadata.json](https://github.com/lee77840/omniconductor/blob/main/adapters/gemini/metadata.json)
- [adapters/gemini/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/gemini/SUPPORTED-FEATURES.md)
- [adapters/cursor/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/cursor/transform.sh)
- [adapters/cursor/metadata.json](https://github.com/lee77840/omniconductor/blob/main/adapters/cursor/metadata.json)
- [adapters/cursor/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/cursor/SUPPORTED-FEATURES.md)
- [adapters/copilot/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/copilot/transform.sh)
- [adapters/copilot/metadata.json](https://github.com/lee77840/omniconductor/blob/main/adapters/copilot/metadata.json)
- [adapters/copilot/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/copilot/SUPPORTED-FEATURES.md)
- [adapters/aider/transform.sh](https://github.com/lee77840/omniconductor/blob/main/adapters/aider/transform.sh)
- [adapters/aider/metadata.json](https://github.com/lee77840/omniconductor/blob/main/adapters/aider/metadata.json)
- [adapters/aider/SUPPORTED-FEATURES.md](https://github.com/lee77840/omniconductor/blob/main/adapters/aider/SUPPORTED-FEATURES.md)
- [bin/omniconductor.js](https://github.com/lee77840/omniconductor/blob/main/bin/omniconductor.js)
- [lib/doctor.js](https://github.com/lee77840/omniconductor/blob/main/lib/doctor.js)
</details>

# 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.

| Tool | Adapter dir | Manifest path emitted | Hook events surfaced | Mode-aware | Plugin-rule aware |
|------|-------------|------------------------|----------------------|------------|-------------------|
| claude | `adapters/claude/` | project plugin manifest + `.conductor-manifest.json` | PreToolUse, Stop, UserPromptSubmit, SessionStart | yes (`full`/`minimal`/`strict`/`recipes-only`/`reflector-only`) | yes (Hookify rules, `enabled: false` accepted as warning) |
| codex | `adapters/codex/` | Codex instructions file + `.conductor-manifest.json` | Pre/Post command hooks (subset) | yes | n/a |
| gemini | `adapters/gemini/` | Gemini config dir + `.conductor-manifest.json` | PreToolUse-equivalent | yes | n/a |
| cursor | `adapters/cursor/` | `.cursorrules` + hooks dir + `.conductor-manifest.json` | Stop, before-shell | yes | n/a |
| copilot | `adapters/copilot/` | Copilot instructions + `.conductor-manifest.json` | PreToolUse-equivalent | yes | n/a |
| aider | `adapters/aider/` | `CONDUCTOR.md` + `.conductor/aider/` + `.conductor-manifest.json` | (pre-commit shell hook) | yes | n/a |

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.

---

<a id='page-3'></a>

## CLI Commands, Install Modes, Model Routing & Doctor

### Related Pages

Related topics: [Project Overview & Three-Layer Architecture](#page-1), [Adapter System & Per-Tool Coverage Matrix](#page-2), [Recipes, Hooks, Reflector & Anti-Drift Tooling](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [bin/omniconductor.js](https://github.com/lee77840/omniconductor/blob/main/bin/omniconductor.js)
- [bin/model-routing.js](https://github.com/lee77840/omniconductor/blob/main/bin/model-routing.js)
- [bin/doctor.js](https://github.com/lee77840/omniconductor/blob/main/bin/doctor.js)
- [bin/claude-hookify.js](https://github.com/lee77840/omniconductor/blob/main/bin/claude-hookify.js)
- [bin/path-safety.js](https://github.com/lee77840/omniconductor/blob/main/bin/path-safety.js)
- [docs/MODEL-ROUTING.md](https://github.com/lee77840/omniconductor/blob/main/docs/MODEL-ROUTING.md)
</details>

# 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:

| Mode | Behavior |
|---|---|
| `full` | Default; emits agents, hooks, and the Reflector runtime (unchanged historical behavior). |
| `minimal` | Discipline text + docs only; skips agents, hooks, and Reflector runtime. |
| `recipes-only` | Ships the opt-in recipes (`loop-engineering`, `git-hygiene`, etc.) without the surrounding runtime. |
| `reflector-only` | Installs only the Reflector runtime surface. |
| `strict` | Aborts with exit 3 on policy violations rather than emitting files. |

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.

---

<a id='page-4'></a>

## Recipes, Hooks, Reflector & Anti-Drift Tooling

### Related Pages

Related topics: [Project Overview & Three-Layer Architecture](#page-1), [Adapter System & Per-Tool Coverage Matrix](#page-2), [CLI Commands, Install Modes, Model Routing & Doctor](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [core/recipes/README.md](https://github.com/lee77840/omniconductor/blob/main/core/recipes/README.md)
- [core/universal-rules/README.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/README.md)
- [core/hooks/README.md](https://github.com/lee77840/omniconductor/blob/main/core/hooks/README.md)
- [core/reflector/README.md](https://github.com/lee77840/omniconductor/blob/main/core/reflector/README.md)
- [core/anti-patterns/README.md](https://github.com/lee77840/omniconductor/blob/main/core/anti-patterns/README.md)
- [tools/check-stale-tokens.sh](https://github.com/lee77840/omniconductor/blob/main/tools/check-stale-tokens.sh)
- [tools/stale-tokens.txt](https://github.com/lee77840/omniconductor/blob/main/tools/stale-tokens.txt)
</details>

# 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:

| Recipe | Hook | Guardrails (G-numbers) | Purpose |
|---|---|---|---|
| `loop-engineering` (v0.6.0) | `pretool-loop-guard` (PreToolUse) | G1–G6 | Bounded, externally-verified agent loops with explicit done-criterion, iteration/token budgets, require-progress, stall escalation, and an oscillation guard. Verifies externally — never by self-judgment. |
| `git-hygiene` (v0.5.0) | `stop-git-hygiene-guard` (Stop) | G1–G7 | Shared-repo discipline: no unrequested worktrees, push-don't-hoard, merge-equals-delete-branch, backup-does-not-equal-applied, no reckless force/rebase, session-end check. |

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

```mermaid
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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: lee77840/omniconductor

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/lee77840/omniconductor

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/lee77840/omniconductor

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/lee77840/omniconductor

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/lee77840/omniconductor

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/lee77840/omniconductor

<!-- canonical_name: lee77840/omniconductor; human_manual_source: deepwiki_human_wiki -->