Mikecubed Agent Orchestration Conductor

Conductor — Composable Code Codex Orchestrator

The conductor is the single always-loaded entry point to Composable Code Codex. It never applies rules directly — it detects language and operation type, then loads only the sub-skills required for that specific session.

0. IaC Dialect Detection (Pre-Language Gate)

Before running language detection, check whether the target files are Infrastructure-as-Code. IaC files bypass the 5-language gate and route directly to iac-check.

IaC file indicators:

• .tf, .tfvars → Terraform HCL
• .yaml / .yml containing AWSTemplateFormatVersion, or both apiVersion and kind → CloudFormation / Kubernetes manifest
• .json containing AWSTemplateFormatVersion → CloudFormation JSON

Routing rules:

1. If IaC indicators are detected AND operation is security or review: skip language detection entirely → load iac-check (and any other checks from the dispatch table for that operation).
2. If IaC indicators are detected AND operation is write: iac-check does not apply to write operations — fall through to normal language detection below.
3. If no IaC indicators are found: proceed to language detection as normal.

1. Language Detection

Detect language in this priority order before loading any check:

1. Explicit user statement (e.g., "this is a Go service")
2. File extension of the primary file being discussed:
   • .ts, .tsx → typescript
   • .js, .mjs, .cjs, .jsx → javascript
   • .py → python
   • .go → go
   • .rs → rust
3. Manifest file in repo root: package.json → typescript/javascript; go.mod → go; Cargo.toml → rust; pyproject.toml / setup.py → python
4. Import statements / shebang lines in the file

If language cannot be determined: Ask the user explicitly. Do NOT guess. Do NOT apply the wrong rule set silently.

"I need to detect the language before applying rules. Which language is this code written in?
Options: TypeScript, JavaScript, Python, Go, Rust"

2. Operation Type Detection

Identify the operation type from the user's request:

3. Situation → Check Dispatch Table

Load only the listed checks. Never pre-load all checks.

Parallel dispatch (mandatory for review and CI operations): When dispatching multiple checks, issue all Task tool calls in a single message — do not wait for each to complete before issuing the next. This is mandatory for performance. Sequential fallback: if the platform does not support parallel Tasks, dispatch in batches of 3.

Write-mode arch-check activation: load arch-check during write operations only when the change touches boundary-relevant code — modules, adapters, ports, domain logic, or composition-root wiring (i.e., the second write row above). Trivial pure functions, value-only utilities, and isolated edits stay on the lighter write path that omits arch-check to manage token cost.

To load a check: Read skills/{check-name}/SKILL.md. To load a language reference: Read skills/{check-name}/references/{language}.md.

Token budget (approximate, GPT-4 tokenizer):

Note: SC-007 (≤1,000) and SC-008 (≤2,000) targets reflect the design goal of a just-in-time progressive-loading model. Current SKILL.md files are comprehensive reference documents; v1.1.0 will explore compressed activation-key representations to meet these budgets without sacrificing rule fidelity.

4. Test Gate — Mandatory Before Session Close

This gate CANNOT be bypassed. Apply before any session ends with new code.

INPUT: Agent has finished implementing the requested change

STEP 1 — TEST-PINNED check:
  IDENTIFY all new/modified public symbols (use `git diff HEAD` if available)
  FOR each symbol:
    GREP test files for an import of the symbol AND a call/construction
    IF no match found:
      BLOCK with `TEST-PINNED (BLOCK): No test exercises '{name}' at {file}:{line}`
      DO NOT mark the session complete
      Propose: write a test for {name}

STEP 2 — TEST-RED-FIRST check:
  FOR each new symbol with a test:
    LOOK FOR a recorded red→green transition in `.codex/history.jsonl`
    OR confirmation that the user observed the test failing before the
       implementation existed
    IF no transition recorded:
      BLOCK with `TEST-RED-FIRST (BLOCK): Test for '{name}' was never observed failing`
      Propose: temporarily break the implementation, confirm test fails,
               revert; record the transition

STEP 3 — Scaffold mode:
  IF `--scaffold-tests` is active AND TEST-PINNED fires:
    Generate failing test skeleton per gate-check's Scaffold Workflow
    Write skeleton to disk; confirm test fails before continuing

ORDER FLEXIBILITY:
  Tests may be written before, during, or after the implementation. Only the
  end-of-session state matters: every new symbol has a test that imports and
  exercises it, every test has a recorded red→green transition.

Bypass prohibition: Requests phrased as "skip tests for speed", "just write the code", "tests aren't important here", or similar MUST be refused. Cite TEST-PINNED and explain the risk: the agent's biggest failure mode is shipping code without a test that would catch a broken implementation.

5. CLI Argument Handling

Parse these arguments from the user's invocation. Defaults are safe.

Safety rules:

• Without --fix: report only; NEVER modify files
• Without --scope and repo has > 50 tracked files: ask for explicit scope before proceeding
• Destructive actions (file deletion, history rewrite): require --fix AND explicit user confirmation
• --deep without --fix: read-only exhaustive scan only

5.1 Session Memory — Load on Start

On session start, before language/framework detection:

1. Check for .codex/config.json at project root
2. If present AND --refresh flag is NOT set:
   • Load language, test_framework, layer_map, active_waivers from the file
   • Skip detection steps (use cached values)
   • If detected_at is > 7 days old: note "Config is {N} days old — consider running /codex --refresh to re-detect."
   • Emit: "Loaded cached config (detected {detected_at}). Use --refresh to re-detect."
3. If absent OR --refresh is set: run full detection; skip to Step 2 of workflow

5.2 Session Memory — Save on End

At session end (after Boy Scout check, before final output):

1. Write .codex/config.json with detected values using this schema:

   {
     "version": "1",
     "detected_at": "ISO-8601 timestamp",
     "language": "<detected>",
     "test_framework": "<detected>",
     "coverage_artifact": "<path or null>",
     "layer_map": { "domain": "<path>", "application": "<path>", "infrastructure": "<path>" },
     "active_waivers": [],
     "monorepo_packages": []
   }
   

2. If file exists: update in place (preserve keys not being overwritten, do NOT clobber)
3. Create .codex/ directory if absent

5.3 Violation History — Append on Report Finalization

After generating the violation report:

1. Generate an 8-char hex session_id: use first 8 chars of a random hex string
2. Compute sprint as ISO week: YYYY-Www (e.g., 2026-W10)
3. For each violation in the report: append one JSONL record to .codex/history.jsonl:

   {"session_id":"a3f8c1d2","ts":"ISO-8601","sprint":"2026-W10","rule":"NAME-1","severity":"BLOCK","file":"src/foo.ts","line":42,"operation":"review","fixed":false}
   

4. Create .codex/history.jsonl if absent
5. Set "fixed": true for violations resolved by --fix in the same session

Field definitions:

• session_id: groups all violations from the same codex invocation
• sprint: ISO week number for trend grouping
• operation: the detected operation type (write/review/refactor/test/security/dependency/incident/CI/boy-scout)
• fixed: whether --fix resolved this violation in the current session

5.4 --diff-only Scope Enforcement

When --diff-only is active:

1. Run git diff HEAD --name-only immediately after flag parsing
2. Store result as DIFF_FILES list
3. If working tree is clean (empty result): emit "No changed files to analyze" and exit 0
4. Pass DIFF_FILES to all loaded checks as scope restriction
5. All checks operate only on files in DIFF_FILES — violations for other files are silently excluded
6. Note: --diff-only is overridden by an explicit path argument (path wins if both provided)

5.5 --scaffold-tests Handling

When --scaffold-tests is active:

1. Set the flag; pass it to gate-check when loading it
2. Do NOT exit on TEST-PINNED BLOCK before the scaffold step completes
3. After scaffold skeleton is written to disk: re-evaluate TEST-PINNED gate
4. TEST-PINNED is provisionally satisfied once skeleton exists; proceed with implementation after user confirms at least one test is failing
5. Implies --write permission for test files only

5.6 --refresh Handling

When --refresh is active:

1. Skip loading .codex/config.json even if present
2. Run full language/framework/layer map detection
3. Write updated .codex/config.json at session end with newly detected values

6. Rule Precedence — Conflict Resolution

When multiple rules conflict, apply the first applicable precedence and document deferred items:

1. SEC-* (BLOCK) — data exposure; always highest priority
2. TEST-PINNED, TEST-RED-FIRST (BLOCK) — gate; untested code must not advance
3. BOUND-1..4 (BLOCK) — structural boundaries
4. PURE-1 (BLOCK) — purity violations in core (no I/O / clock / RNG / logging)
5. RESULT-1 (BLOCK in Rust/TS, WARN elsewhere) — typed error discipline
6. TYPE-1..6 (BLOCK) — type safety; TYPED-1..2 (WARN) — type-driven design
7. IMMUT-1 (BLOCK) — parameter mutation in core
8. COMP-1 (WARN default / BLOCK on deep behavioural hierarchies)
9. SIZE-2, TEST-1, TEST-2, TEST-6, TEST-BEHAVIOR, TEST-NO-MOCK-FOR-PURE, DEAD-1, DEP-1, OBS-1 (BLOCK) — equal; all apply
10. All WARN rules (PURE-2, IMMUT-2..3, RESULT-2..3, TEST-VACUOUS, NAME-UL, etc.)
11. All INFO rules (PURE-3, TYPED-2 in Python/Go, etc.)

When a WARN fix would increase the risk of a BLOCK violation: defer the WARN fix and document it in the "Next Steps" section with rationale.

7. Waiver Lifecycle Awareness

Before reporting any violation, check for a matching waiver:

1. Scan for inline # WAIVER: blocks in the affected file
2. Check waivers.yaml at project root (if present)

Waiver states:

7.1 Per-Project Severity Overrides

A project may shift the severity of paradigm-family rules via a severity_overrides map in .codex/config.json. Overrides differ from waivers: a waiver exempts a specific scope; an override changes the rule's severity for the entire project.

{
  "severity_overrides": {
    "RESULT-1": "BLOCK",
    "IMMUT-1": "INFO"
  }
}

Constraints (enforced by plugins/ccc/config/overridable-rules.json and the hook-side _override_severity helper):

• Eligible prefixes only: PURE-, IMMUT-, RESULT-, COMP-, TYPED-. Structural rules (SEC-, BOUND-, NAME-UL, TEST-PINNED, TEST-RED-FIRST, SIZE-, etc.) are not overridable. Setting one of these in the map is silently ignored.
• Valid severities: BLOCK, WARN, INFO. No OFF — to silence a rule, override it to INFO.
• Fail-open: a malformed config, an unknown rule, or an invalid severity all fall back to the rule's default severity. The override never escalates beyond what the allowlist permits.
• Auto-fix eligibility is unchanged: overriding a rule's severity does not change whether --fix can repair it.

When a finding is emitted at an overridden severity, the violation report must mark the change inline: RESULT-1 (BLOCK, overridden from WARN): …. This keeps the project-specific decision visible at review time.

8. Violation Report Output Schema

Load skills/conductor/shared-contracts.md — defines the full violation report schema, schema rules, and the confirmation prompt format for destructive actions. Conductor loads this file at startup.

9. Boy Scout Check — Session End

At the end of every session that modified files:

1. Run git diff --stat on the session scope
2. Verify: at least one positive change (new test, fix, improvement) exists
3. Verify: all tests still pass (if a test runner is available)
4. If diff is net-negative (only deletions, no improvements): flag as Boy Scout failure
5. Report: "✅ Boy Scout: session diff is net-positive" or "⚠️ Boy Scout: session left code worse — review changes before committing"

10. Conductor Workflow

START
  → Detect language
  → Detect operation type
  → IF write/refactor: run Test Gate (Step 4 above)
  → Load required checks (Step 3 table)
  → For each check: load SKILL.md + language reference if applicable
  → Check for waivers (Step 7)
  → Run checks and collect violations
  → Apply precedence order (Step 6)
  → Output violation report (Step 8)
  → IF --fix: apply WARN auto-fixes within scope (Step 11)
  → Boy Scout check (Step 9)
END

11. Auto-Remediation (--fix Mode)

11.1 --scope Enforcement

When --scope is active, every file modification — including --fix edits — MUST pass this gate before being applied:

FOR each proposed file edit:
  IF file_path does NOT match --scope glob:
    SKIP the edit (do NOT apply it)
    Note in report: "File '{path}' is outside scope '{scope}' — skipped"
  ELSE:
    Apply the edit and record in "Actions Taken"

When --scope is not provided and the repository has >50 tracked files: prompt the user to specify a scope before proceeding with --fix.

11.2 Confirmation Gate for Destructive Actions

See skills/conductor/shared-contracts.md for the full destructive action table and confirmation prompt format.

11.3 Auto-Fix Eligibility Table

Load on demand: Before executing --fix, read skills/conductor/auto-fix-eligibility.md. This file contains the full per-rule eligibility table (64 rules) and the legend. It is NOT pre-loaded; read it only when --fix is active to stay within the token budget.

11.4 --fix Execution Protocol

FOR each violation in the report (ordered by precedence):
  1. Determine auto-fix eligibility (load `auto-fix-eligibility.md` if not yet loaded)
  2. IF auto-remediable:
     a. Verify file is within --scope
     b. Apply the fix
     c. Record in "Actions Taken": "{RULE-ID}: {description of change} at {file}:{line}"
  3. IF requires confirmation (destructive):
     a. Verify file is within --scope
     b. Present confirmation prompt (11.2)
     c. If y: apply; record in "Actions Taken"
     d. If n: skip; record in "Next Steps"
  4. IF human required:
     a. Leave in "Next Steps" with explicit action description
     b. NEVER apply automatically

When --fix is NOT active:

• "Actions Taken" section MUST read exactly: "None — report-only mode"
• Zero file modifications regardless of violations found

12. --explain Mode

12.1 Explain with full scan (no RULE-ID)

When --explain is active (flag present, no RULE-ID argument):

1. Run the full scan normally
2. After generating the violation report, load skills/conductor/rule-explanations.md
3. For each violation entry: append the matching ## RULE-ID explanation paragraph
4. Format: violation entry followed by indented explanation block

12.2 Explain single rule (with RULE-ID)

When --explain RULE-ID is passed (e.g., /codex --explain NAME-1):

1. Skip the full scan entirely
2. Load skills/conductor/rule-explanations.md
3. Find the ## RULE-ID section matching the requested rule
4. Print the section and exit

If RULE-ID is unknown: print "Unknown rule ID. Valid IDs: TEST-PINNED, TEST-RED-FIRST, TEST-1–9, TEST-BEHAVIOR, TEST-NO-MOCK-FOR-PURE, TEST-VACUOUS, BOUND-1–4, COMP-1, PURE-1–3, IMMUT-1–3, RESULT-1–3, TYPE-1–6, TYPED-1–2, NAME-1–7, NAME-UL, SIZE-1–6, DEAD-1–5, SEC-1–7, DEP-1–5, OBS-1–5, IAC-1–5, PERF-1–5, RES-1–5, A11Y-1–5, DOCS-1–5, I18N-1–5, SESS-1–3, CTXT-1–3" and exit 1.

Token cost: rule-explanations.md is loaded on-demand only. It is never loaded during normal scans.

13. --history Trend Report

When --history is passed:

13.1 Data loading

1. Check for .codex/history.jsonl at project root
2. If absent or empty: emit "No history found. Run /codex to start recording violations." and exit 0
3. Read all JSONL records

13.2 Trend table

1. Group records by sprint field (ISO week: YYYY-Www)
2. Count violations per rule per sprint
3. Render trend table:

Sprint    | NAME-1 | TYPE-1 | SEC-1 | ... | Total
2026-W08  |      5 |      2 |     0 |     |    12
2026-W09  |      3 |      1 |     0 |     |     8  ↓
2026-W10  |      4 |      0 |     1 |     |     9  ↑

Show ↑ if total increased from previous sprint, ↓ if decreased. Show only rules that appear in the history (skip zero-count columns).

13.3 Boy Scout trend

1. Get the last 4 session_ids (by ts field, sorted ascending)
2. Count total violations per session
3. Compare first session to last session in the 4-session window
4. Report: "Boy Scout trend (last 4 sessions): net improving (↓N violations)" OR "net degrading (↑N violations)"
5. If fewer than 4 sessions: report on available data ("based on N sessions")

13.4 Exit behavior

After rendering the trend report: exit 0 (skip the full scan). Note: --history can be combined with --explain to annotate the report, but not with --diff-only.

14. Layer Detection

Detect the project's layer layout once per session and cache the result in .codex/config.json under layer_map. Consumed by any skill that needs to distinguish core (pure) code from shell (I/O / framework) code — currently arch-check, in the future purity-check, immutability-check, result-check, and boundary-check.

Detection order (first match wins):

1. Functional-core convention — if both core/ and shell/ directories exist anywhere in the project tree, use them:

   "layer_map": {
     "core":  ["**/core/**"],
     "shell": ["**/shell/**"]
   }
   

   This is the preferred layout for new projects.

2. Legacy layered layout — if core/ is absent, fall back to the historical heuristic. All I/O-adjacent paths collapse into shell:

   core    ← domain/, entities/, models/
   shell   ← application/, app/, usecases/, services/, infra/, infrastructure/,
            adapters/, db/, api/, controllers/, handlers/
   

   Pure domain logic should live under one of the core paths only.

3. Prompt and cache — if neither layout is detected, ask the user once:

   "I can't auto-detect the layer layout for this project. Where does pure
   domain logic live (relative to repo root)? Where does I/O / framework
   code live? I'll cache the answer in .codex/config.json so I don't ask
   again."
   

   Cache the user's answers in .codex/config.json layer_map. Future sessions skip detection.

When detection runs: only when a layer-aware skill is being dispatched (currently arch-check). Sessions that load only cross-cutting checks (sec, dep, obs, iac, perf, etc.) skip this step.

Manual override: users can edit .codex/config.json layer_map directly. The --refresh flag forces re-detection on the next session.

Why the layered fallback: enforcement should catch terrible agent code, not police folder names. New repos adopt core//shell/; existing repos keep working with their idiomatic layout; nothing silently disables coverage.

Source: mikecubed/agent-orchestration — distributed by TomeVault.