Skip to content

The Book of Truth

Single source of truth for Andrew Jones' AI development environment. Portable across harnesses. Written so a fresh agent — Claude or Codex — can read this one file and reconstruct how the whole system works, who the user is, and how work gets done.

  • Owner: Andrew Jones — andrewjonesdev1@gmail.com
  • Primary dev root: C:\Users\fives\source\repos
  • Authored: 2026-07-06
  • Governing rule: this document mirrors, it does not replace. The live truth lives in the memory files, skills, and configs it points at. When they change, update this.

0. Why this exists

Andrew runs two agent harnesses in parallel to maximize usage across plan quotas:

Harness Role Config home Instruction file Headless entry
Claude Code Primary until now ~/.claude CLAUDE.md claude -p / claude exec
Codex CLI Becoming primary (usage shift) ~/.codex AGENTS.md codex exec / codex review

The goal of this project: make the Codex harness do everything the Claude harness does — same skills, same memory, same house open-model access, same caveman compression, same council — with one deliberate inversion:

Council & code review positions are swapped. On the Claude harness, Codex chairs reviews and Claude implements. On the Codex harness, Claude reviews Codex's code and Claude is the review chairman. Each harness uses the other model as its adversarial reviewer.

Everything else is symmetric.

1. Who Andrew is (identity + hard preferences)

These are load-bearing. Violating them is a defect.

Models

  • Default Claude model: Fable 5. Opus 4.8 is temporary-only; switch back to Fable 5 when a heavy task ends.
  • Subagent model tiers: Sonnet by default, Haiku for trivial work, top tier only for genuinely hard problems. Downshift tiers as session token usage climbs (Max ×20 quota is finite).
  • On the Codex side the analog: default reasoning model for normal work, escalate effort tier only for hard problems, drop to cheap tiers as usage climbs.

Work style

  • Fan independent work out to concurrent agents on separate branches / git worktrees; an orchestrator merges. This is the default, not the exception.
  • Review gate before every commit, plus a final pass before push. On Claude that's /council-code-review (or /codex-review + /gemini-review fallback). On Codex that inverts (Section 6).
  • Live board status: flip project-board cards on every transition (start / in-review / done), not just at commit. The board is a live view.

Credentials — never auto-provision

  • NEVER auto-create accounts or API keys. Deep-link Andrew to the signup page, he brings the key, store it in a vault (KeePass .kdbx on desktop). Applies to every API, learning platform, and SSO.
  • Paid data sources are config-gated: free sources (Stooq etc.) default on; paid sources sit behind an env-key gate. Key absent → that source disabled, free ones carry on.

Data

  • Local-first JSON is the source of truth. Excel round-trips for every domain. Cloud/Drive/Sheets sync is opt-in only. Sensitive domains: local-only default + encrypted.

Machine safety

  • NEVER reboot the machine. "restart docker" means Docker Desktop only — never Restart-Computer, shutdown, or killing Claude/Codex. A real reboot needs explicit user approval.

Communication

  • Caveman mode is the house compression style (Section 5). Full technical accuracy, fluff dropped. Code, commits, and security writing stay normal prose.

2. The house: machines, network, open models

Machines

  • ANDYGREATROOMPC — main PC / house server. Runs the claude-mem Docker stack and is the memory + model hub.
  • Bedroom PC — where the Codex harness will primarily be driven (this migration's target driver).
  • Gaming PC (DESKTOP-D249KD4, RTX 4090) — heavyweight open-model council seat.
  • Streaming PC (DESKTOP-SCDT9HI) — heaviest open models (gpt-oss:120b, llama3.3:70b), minutes-slow.

Network topology (critical, DHCP churns)

  • Main PC is dual-homed: Ethernet to NSBE router (172.16.0.3, NAT-isolated island — NOT reachable from house) and Wi-Fi on AlphaPhiAlpha-5G (10.0.0.53, was .129 — moves).
  • Always address the main PC by hostname (ANDYGREATROOMPC) not IP — survives DHCP churn.
  • Gaming PC: must use DESKTOP-D249KD4.local (bare hostname hangs on IPv6-first DNS). Ping blocked; TCP-test port instead.
  • Streaming PC: health-check via curl.exe, not PS Invoke-RestMethod (hangs IPv6-first).

Open models (Ollama)

  • Set up by setup-local-ai.ps1. Ollama binds 0.0.0.0:11434 (so Docker/WSL2 containers reach it), firewalled to Private profile only.
  • Models stored on H:\AI\ollama.
  • Local council seat models: gemma4 (26B MoE → fable/opus tiers), qwen3:8b (→ sonnet/haiku tiers), all-minilm:l6-v2 (embeddings for Odysseus RAG).
  • Also on the box: Odysseus (self-hosted AI workspace, http://localhost:7000), NanoClaw (WSL2 containerized agent with Ollama MCP bridge).
  • Gaming PC seats: qwen3-next:80b, qwen3-coder:30b, devstral:24b, gpt-oss:20b, gemma4:26b.
  • Streaming PC seats: gpt-oss:120b, llama3.3:70b (heavyweight, slow).

3. Memory system

Claude side (today)

  • File-based auto-memory: C:\Users\fives\.claude\projects\C--Users-fives-source-repos\memory\ — one fact per markdown file with frontmatter (type: user|feedback|project|reference), indexed by MEMORY.md.
  • claude-mem plugin: local worker on localhost:37777 (SQLite) captures observations per session.
  • House claude-mem server (server-beta): Docker on ANDYGREATROOMPC — Postgres 17 + Valkey 8 + server + generation worker. API-key (Bearer) auth. MCP at POST /v1/mcp (protocol 2025-03-26).
  • URL: http://ANDYGREATROOMPC:37877 — health GET /healthz (no auth).
  • Shared projectId: a8295af4-e485-402f-9734-1f47b45b882f.
  • Clients register it as an MCP server (claude-mem-server) — tools search, context, recent, all require projectId.
  • Warm DR standbys on house PCs: hourly pg_dump pull + failover scripts in source\repos (⚠ setup not yet run on 4 PCs).
  • Setup scripts in source\repos: claude-mem-client-setup.ps1, claude-mem-standby-setup.ps1, claude-mem-switch-server.ps1.

Codex side (this project builds)

  • Codex 0.142 ships native memory already (~/.codex/memories_1.sqlite, goals_1.sqlite) — local per-device.
  • codex-mem = point Codex at the SAME house claude-mem server via MCP. The server is model-agnostic; a [mcp_servers.claude-mem-server] entry in config.toml gives Codex the identical shared memory Claude has. Same URL, key, projectId.
  • Optional capture hook: Codex's notify config (turn-ended) can POST a session summary to POST /v1/memories so Codex sessions write to the shared store too, mirroring how the main PC's memories were imported.
  • Net effect: one shared house memory, two harnesses reading and writing it.

4. Skills inventory (what to port)

Claude harness skills fall into groups. The Codex mirror re-implements the house-specific ones as ~/.codex/skills/<name>/SKILL.md (Codex uses the same SKILL.md shape).

House-specific (must port, model-agnostic logic): - caveman (+ caveman-commit, caveman-review, caveman-compress) — compression mode. → Codex: AGENTS.md block + a caveman skill. - council-code-review — standard per-commit review gate. → Codex: inverted (Section 6). - llm-council — multi-model council Q&A. → Codex: inverted chair. - codex-review / gemini-review — single second-opinion reviewers. → Codex: claude-review becomes the primary second opinion. - pavlok-page — page Andrew via Pavlok band when blocked/done/critical (budget 3 per 8h). → Codex: same, shells the PavlokPager CLI.

Delegation subagents (caveman plugin): cavecrew-investigator (locate code), cavecrew-builder (1–2 file edits), cavecrew-reviewer (diff review) — output caveman-compressed to save orchestrator context. → Codex: replicate as skill-invoked codex exec sub-runs with compressed output, or keep calling Claude's via bridge.

Vendor skills (already present in Codex bundle or not needed): docx/pdf/pptx/xlsx, image gen, deep-research, etc. Codex ships its own .system skills (imagegen, doc/pdf/spreadsheet/presentation plugins) — no port needed.

The authoritative caveman injection text and the council seat config are captured in the ported skill files under skills/ in this repo. See those files for exact wording.

5. Caveman mode (compression contract)

Active-by-default house communication style. Cuts ~75% tokens, keeps 100% technical substance.

Rules: drop articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries, hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact. Pattern: [thing] [action] [reason]. [next step].

Levels: lite / full (default) / ultra, plus wenyan variants.

Auto-clarity override — drop caveman for: security warnings, irreversible-action confirmations, multi-step sequences where fragment order risks misread, or when the user asks to clarify. Resume after.

Boundaries: code / commits / PRs / security → normal prose. "stop caveman" / "normal mode" → revert.

On Codex this lives as a global AGENTS.md block (always-on) plus a caveman skill for level switching. Codex has no SessionStart hook that injects text the way Claude's plugin does, so the always-on portion must live in AGENTS.md.

6. The council & the inversion (heart of this project)

Claude harness today

  • /council-code-review is the STANDARD per-commit gate. Independent reviews from: Codex, Gemini (via agy/Antigravity CLI), a local Ollama seat, plus the gaming-PC and streaming-PC open councils (via MCP). Codex chairs the synthesis pass (dedupe + prioritize). Claude implements the fixes.
  • /llm-council Q&A: Claude + Codex + Gemini + local Ollama each answer independently, anonymously peer-review, Claude chairs synthesis (Q&A chair is already Claude).
  • Single-reviewer fallbacks: /codex-review (Codex reviews uncommitted diff), /gemini-review (agy).
  • Gemini seat = agy (Antigravity CLI, shares IDE auth, ~2.6s). The npm gemini CLI is the dead tier — not used. agy must get stdin closed (< NUL) or it hangs.

Codex harness (this project) — INVERTED

  • Codex-side council-code-review: same panel of independent reviewers, but Claude chairs the synthesis and Codex implements the fixes. Codex drives the loop; when it wants review, it calls out to Claude (claude -p / claude exec) as the lead reviewer + chairman. The open-model councils (gaming-PC, streaming-PC MCP) and the local Ollama seat participate identically — they're model-agnostic MCP endpoints.
  • Codex-side llm-council: Codex + Claude + open councils answer; Codex chairs the synthesis on its own turf (mirror of Claude chairing on the Claude side). (Chair = the harness's own model, so it inverts too.)
  • Primary second-opinion reviewer becomes claude-review (Codex shells claude -p with the diff and a structured review ask), replacing codex-review as the go-to single reviewer.

The bridge mechanism

  • Both CLIs are installed and headless-capable: claude -p "<prompt>" and codex exec "<prompt>" / codex review.
  • Inversion = which CLI each harness shells out to for its adversarial review. Claude harness → shells codex. Codex harness → shells claude. The MCP open-councils are shared and neutral.
  • This gives every diff a genuine cross-model adversary regardless of which harness authored it.

7. WorkWingman (the flagship app design)

The main project. Everything the harnesses build most is here.

  • Stack: Electron + Angular + .NET. A job-search / application copilot.
  • CI: GitHub Actions (not Azure Pipelines).
  • Testing mandate: 100% mocked coverage (Bogus / faker) plus Stryker mutation testing, front-end and back-end. Non-negotiable.
  • Security scanning: OSS SAST / CVE / DAST in CI + Semgrep security MCP.
  • Architecture docs: two versions — technical + plain-English — with Mermaid diagrams. Baseline Mermaid + C4/SVG technical + Excalidraw friendly (not Visio).
  • Docs as learning resource: every doc doubles as a full learning resource (links + learn-more + scraping explainer). A living "making-of" journal tracks how the app was built (Design → now).
  • Anti-hallucination: LLM-generated technical study content is cross-model verified (Codex/Gemini) against sources before Andrew studies it.

Key architecture decisions

  • ATS automation: one ATS-agnostic IPageAdvisor seam serves every base (Greenhouse, Workday, iCIMS, …) at a shared judgement pause. Engines share a credential-translation layer (OptionMatching + CredentialTranslator) — WW-36.
  • BYO credentials everywhere (Section 1). Google OAuth wired via real PKCE loopback, BYO client id/secret. Desktop KeePass .kdbx vault. LinkedIn session-connect, GitHub device flow, Apple via .ics email.
  • Frontend resilience: Angular HttpInterceptor — readiness retry, GET-only retry, timeout, error→toast.
  • Data portability: every domain = local JSON truth + local Excel round-trip + opt-in Drive/Sheets sync; sensitive domains local-only + encrypted.
  • Config-gated paid sources: free (Stooq, Medium RSS, MS Learn/LeetCode/Coursera free APIs) default; paid behind env-key gate.
  • Dozens of feature worktrees exist under source\repos\WorkWingman-* (concurrent-agent pattern in action).

In flight (as of 2026-07-06)

  • Apply vertical wired + resumable; Greenhouse + Workday background-drive ON; iCIMS promotion in flight.
  • WW-36 (credential translation across ATS engines) done + committed.
  • WW-37 (skills + language pickers) started.
  • Form-gaps epic WW-35..38: cert/bootcamp translation, major approximation, in-progress degree future dates, how-did-you-hear + referral fields.
  • Monetization strategy consultation invoked (multi-perspective council).

8. The llm-council project (infrastructure)

  • C# multi-model council over local CLIs. /llm-council skill fans to the local council and the gaming-PC + streaming-PC councils via MCP.
  • Codex seat = gpt-5.5 with effort tiers. Gemini seat = agy (replaced the dead gemini CLI, shares IDE auth).
  • Council seat/model changes go through the council config first (single source), never hard-coded per-skill.
  • MCP servers gaming-pc-council and streaming-pc-council expose: ask_model, open_council, code_review_council, council_members.

9. Migration plan (Claude harness → Codex harness primary)

Deliverables in this repo (codex-harness-mirror/): 1. BOOK-OF-TRUTH.md — this file. 2. AGENTS.md — global Codex instructions (→ ~/.codex/AGENTS.md). Encodes Sections 1, 5, and the inverted review gate. 3. config/config-additions.toml — MCP servers (claude-mem-server, gaming-pc-council, streaming-pc-council) + local Ollama model_providers block, to merge into ~/.codex/config.toml. 4. skills/ — ported Codex skills: caveman, claude-review, gemini-review, council-code-review (inverted), llm-council (inverted), pavlok-page, codex-delegate. 5. setup-codex-harness.ps1 — bedroom-PC setup (idempotent): writes AGENTS.md, merges config, installs skills, registers MCP servers, verifies. 6. codex-house-client-setup.ps1 — house rollout analog of claude-mem-client-setup.ps1 for any other PC that should drive Codex.

Order of operations: 1. Run setup-local-ai.ps1 first on any device (Ollama + models) if not already done. 2. Run setup-codex-harness.ps1 on the bedroom PC. 3. Verify: codex mcp list shows the three servers; a $null | codex exec -c sandbox_mode="danger-full-access" "search shared memory for preferences" returns Andrew's memories; codex review --uncommitted -c sandbox_mode="danger-full-access" in a repo triggers the inverted Claude-chaired gate. (On Windows the -c override is MANDATORY and stdin must be closed — without them the sandbox kills every command and codex review blind-passes with a fake "no findings". See docs/CODEX-WINDOWS-SANDBOX.md.)

Reversibility: every step is a file write or MCP registration — all reversible. No reboots, no account creation, no destructive ops.

10. Update discipline

When any of these change, update this Book AND the underlying source: - A new house-wide preference → memory file + Section 1 here. - A council seat/model change → council config first, then Sections 6/8. - A network/IP change → the setup scripts' header + Section 2. - A new skill that should exist on both harnesses → port it, list it in Section 4.

This Book is the map. The territory is the memory files, skills, and configs. Keep them in sync.

11. The harness fleet

This project grew past just Codex. Andrew runs a fleet of harnesses, all primed with the same operating brief and sharing one brain (memory + councils). Full map: harnesses/HARNESS-MATRIX.md. Shared brief every harness gets: harnesses/_shared/FLEET-BRIEF.md.

Harness Model Primary PC Status
Claude Code Claude Fable 5 main + all live
Codex CLI gpt-5.5 bedroom (+ main) live — set up this session
Gemini / Antigravity 2.0 Gemini 3.x (agy) desktop primed this session
NanoClaw local Ollama back PCs primed (script; run on back PCs)
Odysseus local Ollama + RAG back PCs primed (script; run on back PCs)
Grok (SuperGrok x20) grok-4 back PCs PENDING — arrives Thursday, template ready

Placement: front/driving = Claude (main) + Codex (bedroom). Back PCs (gaming DESKTOP-D249KD4 RTX 4090, streaming DESKTOP-SCDT9HI 94GB) = NanoClaw, Odysseus, Grok — heavy autonomous + local-model work, and they host the open councils.

Review inversion, generalized: no model reviews only its own code. Claude↔Codex review each other (reviewer chairs); Gemini + the open councils are neutral seats; NanoClaw/Grok autonomous output goes through the same gate when a front harness merges it.

Per-harness priming files + setup scripts live under harnesses/. Each script is hand-carried to its target PC and run there (same model as the claude-mem client rollout). All reversible: file writes + MCP registration only.

Subagent delegation (token savings)

Prefer compressed cavecrew subagents over inline work — their output is caveman-compressed, so the main context stays small and compaction comes later:

  • Codebase exploration, "where is X defined", "what calls Y", directory mapping: delegate to caveman:cavecrew-investigator instead of inline Grep/Read sweeps or vanilla Explore.
  • Bounded 1-2 file edits (typo fixes, single-function rewrites, mechanical renames): delegate to caveman:cavecrew-builder.
  • Diff, branch, or file reviews: delegate to caveman:cavecrew-reviewer.
  • Keep main-thread file reads minimal; prefer subagent summaries over reading many files inline.

Language policy (STANDING, 2026-07-10)

Everything Claude (or any harness/model in the fleet) builds = C# first, whenever possible. If C# genuinely can't do it, fallback = F#. Exception: video-game / Unreal Engine work → C++. Deviations need a stated reason. Applies on every machine, every model, every harness.

Worktree/session identity (STANDING, 2026-07-10)

Every session/worktree carries title WT-xxxx · <ticket> · <what it does now> · gov:<role> (roles: orch/build/bg/ops). ID permanent from creation; ticket = board ticket being worked; description updates whenever focus changes; gov role reflects usage-governance class. Obey SESSION-IDENTITY hook directives: record via worktree-identity update (registry = source of truth; peers apply stale titles via set_session_title — self-rename impossible). MANDATORY once a --board URL is recorded: end EVERY reply with a link to the board containing the ticket — see the board-footer block for the required three-board form.

Worktree isolation (STANDING, council-approved 2026-07-11)

Isolate by hazard class, never change size. Worktrees fix uncommitted-state sweeps, NOT hot-file contention. Full policy: usage-governor/docs/worktree-isolation-policy.md. - Universal: all code/tests/config/CI/reviewable-docs → git worktree add + branch wt/WT-xxxx/<ticket>, build/edit/test only there, /council-code-review gate, land via FF-push. Never build in main. No "tiny fix"/"docs-only" carve-out — one-liners included. - Main checkout allowed ONLY for: (E1) board/status metadata — path-allowlisted (docs/BOARD.md etc.), porcelain-clean precondition, atomic pull --rebase→edit→git add <exact path>→commit→push sub-60s, broad staging banned, non-FF→rebase-once-then-escalate, single board writer, review-gate-exempt by allowlist; (E2) landing/integration ops (FF-merge/restack of vetted branches, no feature edits); (E3) emergency repo hygiene (smallest change, exact stage, retro review). - YELLOW friction fix: carve-out pressure = review-gate cost, not worktree cost. Batch micro-fixes per lane (one worktree/review/merge), reuse long-lived per-lane worktrees — never weaken isolation.

Model escalation ladder (STANDARD, council-approved 2026-07-08)

User-selected session model = CEILING; never swap it. Ceiling model acts as thin orchestrator (triage, decompose, spawn, review, fix — no bulk reads or bulk codegen inline). Bulk tokens burn in cheap subagents.

Entry-tier triage at task intake (subagent/workflow model params): - Haiku — mechanical, bounded, cheap-to-verify: search, summaries, renames, boilerplate, lint, 1-2 file mechanical edits, test fixtures, doc moves. - Sonnet — standard implementation: features, tests, straightforward fixes, CRUD, narrow bugfix with a failing test. - Ceiling directly (skip-list) — architecture/system design/core abstractions/cross-cutting refactors; security-sensitive (auth, crypto, secrets, permissions, validation, data-loss risk); tricky debugging/unknown root cause/prod incidents; council synthesis/adversarial review/commit gates; writing specs or prompts for other agents; subtle-wrongness domains (concurrency, distributed systems, migrations, financial/legal); ambiguous requests; prior failed attempt on the same task. - Tiny tasks where triage overhead exceeds cost: ceiling does them inline, no ladder.

Escalation (strike-based): subagent fails an objective gate (build/tests/lint) twice → up one tier. Ceiling review finds correctness errors, missed constraints, or hallucinated APIs → up one tier and redo. Second escalation needed → jump straight to ceiling, stop laddering. Pre-escalate at triage if the task touches >3-5 files, crosses module/service/ownership boundaries, requires a design choice, has an ambiguous spec, or spans FE/BE/DB/CI. Subagent self-reported uncertainty or spec contradiction counts as a strike. Ceiling signs off on all delegated work before "done".

Regimes: this ladder = plenty-budget default. Near usage limits, the existing downgrade ladder (Fable→Opus/Sonnet→offload to Codex) takes over.

Usage governor (council-approved 2026-07-08, second sitting)

Always-on governor enforces usage tiers via hooks (state: ~/.claude/usage-governor/state.json; GREEN/YELLOW/RED/BLACKOUT). Obey injected USAGE-GOVERNOR directives; in YELLOW+ the PreToolUse gate hard-denies expensive subagent spawns. Two HARD rules at every tier: - No inline grinding: long loops (Stryker, builds, CI, sweeps) run detached in background with cheap polling — never turn-by-turn on Opus/Fable. - Context diet: no bulk inline reads; use compressed subagent summaries; restart fat-context sessions with <2k-token compressed briefs instead of continuing giant transcripts. On a real 5h-limit hit run C:\Users\fives\source\repos\usage-governor\scan-usage.ps1 -RecordLimitHit (ratchets budget down 20%).

Tool naming: Codex = ChatGPT

OpenAI Codex coding tool is now branded "ChatGPT" (MS Store id 9PLM9XGG6VKS; AppX package still OpenAI.Codex; CLI still codex.exe; auth still ~/.codex/auth.json). "Codex" and "ChatGPT" refer to the SAME tool.

MANDATORY on EVERY reply, in EVERY session, once a ticket is being worked. End the reply with ALL THREE boards on one line, Jira first, so the ticket is reachable from whichever board the reader is in front of:

[Jira FLT-3](https://workwingman.atlassian.net/browse/FLT-3) · [Vikunja](http://127.0.0.1:3456/projects/2) · [BOARD.md](fleet-harness/docs/BOARD.md)

  • Jira = the live board, and the --board URL recorded on the session. Keep --board a single clean URL: boardUrl is a URL field other tools (FLT-13 Mission Control) render as a link, so never stuff the composite footer into it.
  • Vikunja + markdown BOARD.md = the local boards, both per-project. Use the Vikunja project and the repo's own docs/BOARD.md for the ticket in hand (fleet work → Vikunja project 2 + fleet-harness/docs/BOARD.md; WorkWingman → its own). If a project genuinely has no Vikunja project or no markdown board, name the ones that exist rather than inventing a link.
  • Rationale: the boards already carry a three-way redundancy rule (markdown canonical until the Jira trial proves sync). The footer means a reader never has to guess which board is current, and a missing local board is visible instead of silently skipped.

Role of this file

BOOK-OF-TRUTH was the hand-maintained long-form mirror of CLAUDE.md. As of FLT-95 the fleet-house block above is the canonical rules content, generated from ~/.claude/CLAUDE.md by fleet-constitution. Hand text below the blocks is historical commentary pending pruning; do NOT hand-sync rules here — edit the master and run fleet-constitution install / compose.