Configure a small set of project roles once, then give every normal task to the main Codex agent. The main agent decides whether the task needs a narrow scout, a bounded implementation worker, an independent reviewer, or no delegation.
- Operating system: Windows (PowerShell 5.1 or later). The scripts use Windows path conventions and are not tested on macOS or Linux.
- Codex CLI: Version 0.144.0 or later, or the current supported Codex desktop release.
- Model access: Sol and Luna models require a Codex Plus subscription or higher. Free and Go users have access to Terra only; the kit will install without error but the Sol main-agent and Luna scout configurations will not be available at runtime.
- Plan tier guidance: Free/Go users should change
config.snippet.tomlandcrokit_scout.tomlto use Terra before merging into their config.
The kit uses the official user-scope paths:
~/.codex/agents/for three standalone custom-agent TOML files (crokit_scout,crokit_worker,crokit_reviewer).~/.codex/AGENTS.mdfor one marker-delimited managed instruction block.~/.agents/skills/crokit-orchestration/for the reusable workflow skill.~/.codex/role-orchestration.config.snippet.tomlfor a reviewable config snippet.
It does not inspect or copy authentication, cache, or catalog data. It does not overwrite an existing ~/.codex/config.toml.
Open PowerShell in this kit folder and first validate its contents:
.\Verify.ps1Preview all intended changes without writing anything:
.\Install.ps1 -WhatIfInstall after reviewing the preview:
.\Install.ps1The installer is user-scope, additive, backup-first, and idempotent. It replaces only the three named role files, the named skill folder, and this kit's exact managed AGENTS block. Existing replaced content is backed up under ~/.codex/role-orchestration-backups/ before replacement.
On first installation, the installer also saves pre-kit user state to a dedicated pre-kit-state/ folder so that the original files can be accurately restored even after multiple kit upgrades.
The scripts preserve UTF-8/UTF-16/UTF-32 BOM behavior for an existing global AGENTS.md. A legacy unmarked file that is not valid UTF-8 is rejected before any installation change instead of being rewritten with damaged text.
Review ~/.codex/role-orchestration.config.snippet.toml, then manually merge the desired settings into your existing ~/.codex/config.toml. This protects your current model choices and other configuration.
If no config.toml exists and you explicitly want the snippet to become the initial configuration, run:
.\Install.ps1 -CreateConfigRestart Codex or start a new task after installation so the new roles and skill can be discovered.
Give the main agent a normal prompt, for example:
Fix the failing export test and keep the change scoped to the approved plan.
Do not select a role for each task. The main agent classifies trivial, research-heavy, bounded normal, and critical work, keeps critical areas main-owned or requires a detailed bounded plan, and accepts work only after inspecting the real diff and evidence.
After installation, verify that the roles are active by giving a low-risk, inspection-only task:
Inspect the repository test structure using crokit_scout.
Do not modify files. Report the agent role used and the evidence found.
Check that the main agent delegates to crokit_scout and that the scout response is inspection-only. Use /agent in the Codex CLI to inspect active subagent threads.
Preview removal first, then remove only this kit's installed files and exact managed block:
.\Uninstall.ps1 -WhatIf
.\Uninstall.ps1The uninstaller first verifies that installed role and skill files still match this kit. It refuses to delete user-modified content. To restore your original pre-kit files after removing the kit, use:
.\Uninstall.ps1 -RestoreLatestBackupThe uninstaller prefers the pre-kit-state/ snapshot (your original files before the kit was first installed) over the latest timestamped upgrade backup. This prevents a kit upgrade from masking your original configuration.
The global AGENTS.md file is never restored wholesale; only this kit's exact managed block is removed, preserving unrelated instructions. The uninstaller never touches config.toml, authentication, cache, or the backup archive itself.
This is cost-aware routing, not a guarantee of the lowest possible cost or the best possible answer. Subagents add token use and should be used only when they materially improve confidence or speed. Availability can vary by Codex session; the main agent reports and applies the documented fallback rather than weakening permissions or changing unsupported configuration.
File allowlists and one-writer rules are orchestration instructions, not operating-system-level access controls. The workspace-write sandbox grants filesystem access within the workspace; the allowlist constrains the agent through its instructions, not through OS-level enforcement.
Do not use full-access or permissive runtime permission modes if you rely on the scout and reviewer being technically read-only. The TOML sandbox_mode sets the default, but the active session's runtime permission level can override it.
- Project-scope installation mode (
-Scope Project -ProjectPath <path>) to install roles and skills into a specific project rather than user-wide. - Single-source model manifest (
kit.manifest.json) so model changes require editing only one file. - GitHub Actions CI workflow for automated install/uninstall cycle, idempotency, CRLF/LF parity, and modified-file rejection tests.
- Free/Go profile with Terra-only agent and config templates.