Khaos-Brain: Instructions file for Codex

Repository expectations

Bootstrap

• If the user asks to install, enable, deploy, bootstrap, or set up this predictive KB system on any machine, your default first action is to run python scripts/install_codex_kb.py --json from the repository root.
• Immediately after installation, run python scripts/install_codex_kb.py --check --json and confirm the install is healthy before doing anything else.
• Treat the installer as idempotent. If the system may already be installed, rerun the installer anyway rather than asking the user to verify it manually.
• If this repository was moved to a new path or re-cloned, rerun the installer from the new clone so the Codex-side manifest points at the current KB root.
• The installed global preflight skill must enable implicit invocation, remind Codex to add phase-change KB checkpoints during long mixed tasks, and remind Codex to record KB postflight observations after meaningful work, including skill/plugin and subagent/delegation usage lessons when they materially affect task outcomes. Treat missing behavior as an installation defect and fix it.
• The installer must also refresh the repository-managed kb-sleep-maintenance, kb-dream-pass, kb-organization-contribute, kb-organization-maintenance, and khaos-brain-update skills under $CODEX_HOME/skills; these skills are explicit maintenance, organization, or update entry points and should not enable broad implicit invocation. khaos-brain-update is manual-only and has no automation binding.
• The installer must refresh exactly two scheduled composite automations under $CODEX_HOME/automations: KB Sleep owns the local Sleep-then-Dream cycle, and organization maintenance owns snapshot refresh, shared maintenance, and contribution. kb-dream-pass and kb-organization-contribute remain callable child Skills, not scheduled owners. The installer must permanently retire the exact legacy kb-architect-pass Skill, kb-architect automation, khaos-brain-system-update automation, and the former standalone Dream/contribution schedules on fresh installs and upgrades, without touching similarly named user assets.
• Every install or upgrade must run the versioned Chaos Brain maintenance migration, settle old lifecycle debt, archive retention-required cold evidence, prune only receipt-covered derivations, rescan for late reintroduced and Windows extended-length managed files, settle observations admitted by concurrent AI work through bounded post-commit receipts, rebuild the active index, preserve every surviving automation's user pause state, and remain rollbackable until current aggregate validation passes.
• Chaos Brain has zero normal-runtime compatibility and zero normal-runtime fallback. Exact retired formats may be read only by their versioned upgrade owner, which must rewrite or replace them directly, remove their old authority, prove zero residuals, and otherwise roll back while both retained composite automations remain paused. An incompatible residual is an unfinished upgrade-AI work item: derive one evidence-bound direct-to-current disposition and retry inside the rollbackable upgrade instead of adding a product reader. Missing current authority must fail visibly; never add a dual reader/writer, alias, alternate launcher/model, or silent downgrade.
• The installer must also write or refresh a repository-managed global defaults block under $CODEX_HOME/AGENTS.md so other machines inherit the strongest available session-wide KB preflight and postflight rules, not only the implicit skill layer.
• The install check must expose a structured machine-install checklist that explicitly verifies the global skill files, implicit invocation, phase-change KB checkpoint wording, postflight reminder wording, mistake-first highest-priority postflight wording, skill/plugin and subagent/delegation signal wording, managed global AGENTS block, repo-managed maintenance/organization/update skills, all repo-managed automations, and the final strong_session_defaults readiness signal.