codex-quota-optimizer

# Codex Quota Optimizer Optimize for **useful work per unit of Codex allowance**, not for the shortest answer. ## 0. Operating principle Use the cheapest execution path that can still meet the acceptance criteria. Escalate only when evidence shows the cheaper path is insufficient. Never claim an exact remaining quota unless the current Codex client/account exposes it. If quota state matters, tell the user to check `/status` or the usage dashboard, then continue with the best available strategy. ### Zero-friction invariant The optimizer must not become the overhead. - Do not make an additional model call just to classify or budget a task. - Do not add network requests for CQO classification, journaling, or auditing. - Do not put a blocking budget gate in front of normal Codex execution. - Do not ask the user for confirmation merely because a soft budget was exceeded. - Do not spawn subagents on CQO's behalf. - The Skill must remain fully useful when the optional `cqo` CLI is never installed or run. See `references/zero-friction.md`. ## 1. Read only what you need Before broad exploration: 1. Inspect the task request, current diff, and repository instructions (`AGENTS.md`). 2. Prefer targeted search (`rg`, file-specific reads, manifests, changed files) over recursive reading. 3. If the repository is unfamiliar, run `scripts/repo_snapshot.py --compact` once before opening many files. 4. Do not re-read unchanged files already understood in the current task unless a contradiction appears. 5. Read generated/vendor/build directories only when directly relevant. See `references/context-policy.md` for detailed rules. ## 2. Classify the task before execution Assign one class internally as part of the existing reasoning turn. Do not call another model solely to perform classification. - **XS** — one-file, mechanical, obvious acceptance criteria. - **S** — narrow feature/fix, 1–3 files, known pattern. - **M** — several files, modest design judgment or integration. - **L** — cross-cutting change, unclear architecture, migration, complex debugging. - **XL** — high-risk redesign, multi-system work, security-critical or ambiguous end-to-end task. Then choose the lowest adequate model/reasoning path: - **XS/S:** prefer Luna or the fastest/cheapest available setting, low reasoning. - **M:** prefer Terra, low/medium reasoning. - **L:** Terra medium first; escalate to Sol only for unresolved design/debugging complexity. - **XL:** Sol medium/high; Astra only when the task truly needs strongest multi-step/tool reasoning and the account exposes it. Availability varies by plan/client. If a named model is unavailable, choose the nearest cheaper/faster model with the same role. Do not use Max/Ultra by default. Do not spawn subagents merely because they are available. See `references/model-routing.md`. ## 3. Use an execution budget For every non-trivial task, maintain this internal budget: - **Discovery budget:** enough reads/searches to locate the change surface. - **Edit budget:** minimum files required to satisfy acceptance criteria. - **Verification budget:** targeted checks first; broad checks only at the final gate or when evidence demands them. These are **soft budgets**, never execution gates: - Stop discovery once the relevant dependency path is understood. - Stop editing once acceptance criteria are met; avoid opportunistic refactors. - Stop verification after relevant tests/type/lint checks pass unless the change is high risk. - If another file, test, or reasoning step is required for correctness, continue without interrupting the user. - If scope expands, reclassify internally and keep moving; do not request permission just because the initial budget was too small. ## 4. Plan economically For S/M/L/XL tasks, state or maintain a compact plan with: 1. target behavior, 2. likely files, 3. minimal verification, 4. escalation trigger. Do not create a long speculative plan before reading the minimum repository evidence. Prefer one coherent implementation turn over repeated micro-turns that each reload context. ## 5. Edit minimally - Change the smallest coherent surface. - Reuse existing helpers, patterns, components, and tests. - Avoid formatting unrelated files. - Avoid dependency upgrades unless required. - Avoid generated-file churn unless generation is part of the task. - Batch logically related edits rather than repeatedly opening/editing the same file. When a task can be solved by configuration or a small local patch, do not introduce a framework or abstraction layer. ## 6. Verify in layers Run checks in this order: 1. syntax/format check for touched files, 2. focused unit/component test for touched behavior, 3. focused type/lint check, 4. broader package/app test only if needed, 5. full suite only for cross-cutting/high-risk changes or before a release gate. Do not repeatedly run the same expensive full suite after tiny edits. If a broad test fails for an unrelated pre-existing reason, record it and continue with focused verification. See `references/test-policy.md`. ## 7. Control context growth At natural checkpoints, compress working state into a short handoff note: - goal, - decisions, - files changed, - tests run/results, - remaining issue. Use the checkpoint instead of restating the entire conversation or repository history. For long tasks, create/update a small local scratch note only if it prevents repeated exploration. Remove it before finalizing unless the project wants it committed. ## 8. Avoid expensive anti-patterns Never do these by default: - scan the entire repository when a targeted search can locate the feature, - open large lockfiles, minified bundles, generated output, or vendor trees without need, - run full test suites before identifying the change surface, - use high/xhigh/max/ultra reasoning for routine edits, - use multiple subagents for a task one agent can do cheaply, - ask Codex to rewrite whole files when a patch is sufficient, - repeatedly summarize information already present in the current context, - refactor adjacent code “while here” without user value, - browse the web when repository/local docs are enough, - perform duplicate searches with equivalent queries. See `references/anti-patterns.md`. ## 9. Escalate deliberately Escalate model/reasoning/tool breadth only when at least one trigger is present: - two focused attempts fail for reasons not explained by local evidence, - architecture is ambiguous and wrong choice would cause broad rework, - failure spans multiple subsystems, - security/data-loss/migration risk is meaningful, - acceptance criteria conflict, - targeted verification exposes hidden coupling. Before escalation, summarize what is known so the stronger model does not need to rediscover it. ## 10. Plus vs Pro behavior Do not hardcode plan quotas into decisions. Use the same efficiency policy for both plans, with different default aggressiveness: - **Plus:** default to `economy` behavior — Luna/Terra first, focused checks, strict scope control. - **Pro:** default to `balanced` behavior — Terra first, Sol when complexity justifies it; still avoid waste because Pro allowance is finite and may be shared with other agentic features. If the user says quota is nearly exhausted, enter **emergency mode**: - no broad exploration, - no optional refactors, - no subagents, - cheapest adequate model, - one implementation path, - focused verification only, - produce a concise continuation note if completion is impossible in the current turn. ## 11. User-facing output When useful, end with a compact **Usage choices** note containing only actionable items such as: - “This is an S task; Luna/low is sufficient.” - “Use Terra/medium for implementation; reserve Sol for the migration edge case.” - “Run the focused test now; defer the full suite until final review.” Do not clutter every answer with quota commentary if the skill is operating successfully in the background. ## 12. Optional local observability The `cqo` CLI is optional. It provides task-level classification, soft budgets, a local journal, and a local audit: - `cqo start <task>` - `cqo status` - `cqo audit` - `cqo history` The journal is local-only under `~/.cqo` (or `CQO_HOME`). It does not inspect private account pages or estimate hidden quota. **Never run `cqo` automatically just to collect analytics.** The CLI is an inspection layer, not a runtime dependency. If the user did not opt into a CQO session, normal Skill behavior continues with zero CLI overhead. ## 13. Optional helper scripts - `scripts/repo_snapshot.py --compact` — compact project map without reading the whole repo. - `scripts/change_scope.py` — summarize current Git change surface and suggest verification scope. - `scripts/cqo.py` — optional zero-network local CLI for task-level budgeting and auditing. Use scripts only when they save model context/tool calls or the user explicitly wants observability; do not run them ritualistically.