From 74becf1554699eaa5aa43e16587a9b76280c595b Mon Sep 17 00:00:00 2001 From: Aryaman Todkar Date: Sat, 26 Sep 2026 15:20:34 +0530 Subject: [PATCH 1/2] chore: simplify Premove agent routing --- .codex/agents/architect.toml | 2 +- .codex/agents/explorer.toml | 2 +- .codex/agents/implementer.toml | 5 -- .codex/agents/reviewer.toml | 2 +- .codex/config.toml | 10 ++-- AGENTS.md | 95 +++++++++++----------------------- AGENT_HARNESS.md | 54 ++++++++++++------- 7 files changed, 70 insertions(+), 100 deletions(-) delete mode 100644 .codex/agents/implementer.toml diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml index 1ad99be..fe04c59 100644 --- a/.codex/agents/architect.toml +++ b/.codex/agents/architect.toml @@ -1,5 +1,5 @@ model = "gpt-6-astra" model_reasoning_effort = "medium" developer_instructions = """ -Resolve only an unanswered architectural decision or concrete repository-invariant conflict requested by the coordinator. Do not reconsider or reapprove an explicit user-accepted design merely because it touches a protected boundary. Inspect current code and contracts. Return a compact decision record: problem, current invariant, chosen design, reason, affected boundaries, rejected alternatives, required tests, and implementation constraints. Do not implement or edit files. +Resolve only an actually unresolved architectural decision or concrete invariant conflict. Do not reopen an explicit user-accepted design. Inspect current code and contracts. Do not implement or edit files. Return a compact record with the decision, reason, affected invariants, and required tests. """ diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml index 50c7f48..5b007d3 100644 --- a/.codex/agents/explorer.toml +++ b/.codex/agents/explorer.toml @@ -1,5 +1,5 @@ model = "gpt-6-luna" model_reasoning_effort = "high" developer_instructions = """ -Investigate only the bounded unresolved evidence question from the coordinator. Do not reinvestigate questions answered by an accepted user plan. Use CodeGraph first for indexed code, then targeted reads, git, and tests as needed. Report the implementation, direct consumers, relevant tests, and concrete evidence. Do not edit files or expand into architecture design. +Investigate only a bounded question that can run in parallel with root work, or a large investigation whose isolated context saves root context. Do not reinvestigate an accepted plan. Use CodeGraph first for indexed code, then targeted reads, git, and tests as needed. Do not edit files or expand into architecture design. Return only a finding, file and line evidence, and impact. Keep the report within 500 words. """ diff --git a/.codex/agents/implementer.toml b/.codex/agents/implementer.toml deleted file mode 100644 index a3365f0..0000000 --- a/.codex/agents/implementer.toml +++ /dev/null @@ -1,5 +0,0 @@ -model = "gpt-6-sol" -model_reasoning_effort = "medium" -developer_instructions = """ -The coordinator's supplied design and user-accepted plan are authoritative. Implement them with the smallest coherent change. Do not reopen settled design decisions. Read relevant implementation, callers, and tests. When the user requests test-first work or integration tests, use a test-first workflow. Run focused validation. Preserve unrelated work and frozen release evidence. Stop and return concrete evidence only if implementation reveals a conflict, missing consequential decision, violated invariant, or impossible assumption. Do not decide a new architecture or public contract silently. -""" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml index 5510f50..164e2f8 100644 --- a/.codex/agents/reviewer.toml +++ b/.codex/agents/reviewer.toml @@ -1,5 +1,5 @@ model = "gpt-6-sol" model_reasoning_effort = "high" developer_instructions = """ -Review whether the implemented behavior realizes the accepted plan and preserves Premove ITN invariants. Do not reopen settled design choices unless implementation or evidence shows a concrete contradiction, regression, or violated invariant. Check Rust/Python ownership, candidate validity, scoring and decoder authority, public result meaning, frozen prediction risk, and missing edge cases where relevant. Report actionable findings with file and line evidence, ordered by severity. Do not edit files. +Review whether the implementation realizes the accepted plan and preserves Premove ITN invariants. Do not reopen settled choices unless there is concrete evidence of a contradiction, regression, or violated invariant. Check relevant Premove ITN boundaries and edge cases. Do not edit files. Report actionable findings only, with severity, file and line, and why each matters. Order findings by severity. If there are no findings, report exactly: No findings. """ diff --git a/.codex/config.toml b/.codex/config.toml index 143a3e9..6e8b80e 100644 --- a/.codex/config.toml +++ b/.codex/config.toml @@ -1,5 +1,5 @@ -model = "gpt-6-luna" -model_reasoning_effort = "xhigh" +model = "gpt-6-sol" +model_reasoning_effort = "medium" [mcp_servers.codegraph] command = "uv" @@ -7,7 +7,7 @@ args = ["run", "--no-project", "python", "scripts/agent/codegraph_mcp.py"] [agents] enabled = true -max_concurrent_threads_per_session = 4 +max_concurrent_threads_per_session = 2 default_subagent_model = "gpt-5.6-sol" default_subagent_reasoning_effort = "medium" @@ -15,10 +15,6 @@ default_subagent_reasoning_effort = "medium" description = "Investigate bounded unresolved code questions and report evidence." config_file = "./agents/explorer.toml" -[agents.implementer] -description = "Implement accepted semantic code or workflow logic with focused tests." -config_file = "./agents/implementer.toml" - [agents.reviewer] description = "Review implementation against the accepted plan and invariants." config_file = "./agents/reviewer.toml" diff --git a/AGENTS.md b/AGENTS.md index 7dad0f2..b93b28b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,87 +31,52 @@ compatible edits. ## Plan authority -Treat an explicit user-supplied implementation plan as the accepted design -when the user asks to execute, apply, or implement it, or otherwise clearly -indicates that its decisions are settled. Do not treat a supplied plan as -accepted when the user asks to review, evaluate, compare, critique, validate, -or improve the plan itself. Those requests remain discovery work. - -In execution mode, verify the repository facts needed to apply the plan, -execute it, and run the smallest validation that establishes the result. Do -not reopen settled decisions or repeat investigation that the plan has already -answered. - -In execution mode, the coordinator performs small literal or mechanical -configuration, Git, GitHub, and workflow changes directly. Delegate meaningful -semantic code or workflow-logic work that requires software-engineering -judgment to `implementer` with the accepted plan and invariants. Do not route -to `explorer` or `architect`, or request pre-implementation review, merely -because a settled plan touches their domain. - -Spawn `reviewer` when the user explicitly requests semantic review, a -repository rule requires independent review for the affected boundary, the -implementation materially changes protected runtime or public behavior, or -focused mechanical evidence cannot establish semantic correctness. Do not -spawn `reviewer` merely because `implementer` was used, the diff is large, the -change is semantic, a pull request will be opened, or independent review would -be generally useful. - -Escalate execution only on concrete evidence of one of these conditions: +Treat an explicit implementation plan as settled when the user asks to apply +it. Do not rediscover or redesign settled decisions. Escalate only when there +is concrete evidence of one of these conditions: 1. Invariant conflict: the plan violates an explicit repository invariant. 2. Reality mismatch: code, API, or configuration materially differs from the plan's assumptions. 3. Insufficient specification: a consequential choice remains undecided. -4. Validation contradiction: focused tests or observed behavior contradict the - plan's stated result. +4. Validation contradiction: focused evidence contradicts the plan's result. -Report the specific evidence and route only the unresolved question. A plan -does not override repository invariants, observed code, or failing tests. -Enter discovery mode when the user asks Codex to determine what, why, how, -which design, whether a change is safe, or what caused a failure. +Report the evidence and resolve only the conflicting or undecided part. A plan +does not override repository invariants, observed code, or failing checks. ## Model routing -The coordinator owns routing, synthesis, and final decisions. It must delegate -work to the configured named specialist when the task meets a role trigger -below. +The root agent owns repository inspection, implementation, validation, Git, +GitHub, and final decisions. It handles work directly when steps depend on +shared context or must happen in sequence. Use the model and reasoning pins in `.codex/config.toml` and -`.codex/agents/*.toml`. Use only the four configured roles. Do not use untyped -or default subagents, or request per-run model or reasoning overrides. +`.codex/agents/*.toml`. Use only the configured specialist roles. Do not use +untyped or default subagents, or request per-run model or reasoning overrides. - Use CodeGraph directly for structural questions that it can answer without substantial source investigation. -- Spawn `explorer` for a bounded, unresolved investigation that requires - tracing behavior, comparing implementations, or inspecting multiple source - or test files. Its output is evidence, not design authority. -- Spawn `implementer` for meaningful semantic code or workflow-logic work that - requires software-engineering judgment when the design and invariants are - settled. -- Spawn `reviewer` only for the explicit positive triggers in plan authority. - Review realization of the accepted plan. -- Spawn `architect` for an unresolved decision or concrete invariant conflict - involving candidate or GoldGraph semantics, the Rust/Python ownership - boundary, scoring or model inputs, structured loss or decoder legality, - training or evaluation policy, public context or result meaning, or model, +- Use `explorer` only for independent work that can run in parallel or for a + large investigation whose isolated context saves root context. +- Use `reviewer` when the user asks for independent review, or when a + high-risk semantic change cannot be established by deterministic evidence. +- Use `architect` only for an unresolved design decision or invariant conflict + involving candidate semantics, Rust/Python ownership, scoring or model + inputs, decoder legality, evaluation policy, public result meaning, or model, package, or release identity. -When work satisfies a named role's trigger, delegation to that role is -mandatory. The coordinator handles the direct execution work defined above -and structural lookups. Do not force every task through the full agent pipeline. - -Apply role triggers to specialist work required by the current task. Do not -spawn a specialist only because an existing branch, diff, or artifact contains -substantial prior work. The coordinator handles deterministic and administrative -operations such as status checks, branch comparisons, pushes, and opening or -integrating already-reviewed pull requests. Spawn a specialist only if that work -uncovers a new need for investigation, implementation, semantic review, or an -architectural decision. - -Delegate independent tasks only. Coordinate changes to shared files. -If two evidence-driven fixes fail and the cause remains unclear, stop the -implementation path and return the evidence to the coordinator. +Do not spawn a specialist for a simple edit, a single-file task, a sequential +step, or work that depends on the root's current context. Do not delegate work +that the root must wait for when the root can do it directly. Do not inspect +source merely to prepare a child task. Either handle the investigation +directly or delegate its bounded question before inspecting the same sources. + +Keep specialist tasks bounded and reports compact. Explorer reports a finding, +file and line evidence, and impact in at most 500 words. Reviewer reports only +actionable findings with severity, file and line, and why each matters; if +there are none, report `No findings.` Architect reports the decision, reason, +affected invariants, and required tests. When independent review is required, +run it alongside CI or pull request administration when possible. ## Git diff --git a/AGENT_HARNESS.md b/AGENT_HARNESS.md index 041f014..c3d4942 100644 --- a/AGENT_HARNESS.md +++ b/AGENT_HARNESS.md @@ -6,29 +6,43 @@ This guide summarizes the repository's Codex setup. The detailed rules live in ## Agents and when to use them -The coordinator is `gpt-6-luna` at `xhigh`. It routes work, combines results, -and handles small mechanical, configuration, Git, GitHub, and workflow tasks. -The four named specialists are configured in `.codex/agents/`: +The root agent is `gpt-6-sol` at `medium`. It owns repository inspection, +implementation, validation, Git, GitHub, and final decisions. Three named +specialists are configured in `.codex/agents/`: | Agent | Model | Use it for | | --- | --- | --- | -| `explorer` | `gpt-6-luna`, `high` | A bounded, unresolved investigation. It gathers evidence and does not edit. | -| `implementer` | `gpt-6-sol`, `medium` | Meaningful code or workflow logic when the design is settled. | -| `reviewer` | `gpt-6-sol`, `high` | Independent review when the user asks, a repository rule requires it, protected behavior changes, or tests cannot establish correctness. | -| `architect` | `gpt-6-astra`, `medium` | An unresolved high-impact design decision or a concrete invariant conflict. | - -## How `AGENTS.md` routes work - -An explicit plan is accepted when the user asks to execute it or clearly says -its decisions are settled. Requests to critique or compare a plan stay in -discovery mode. In execution mode, the coordinator verifies only the facts -needed to apply the plan. It escalates only for an invariant conflict, a -material mismatch with the repository, a consequential missing decision, or -validation that contradicts the plan. Specialists answer unresolved questions; -they do not reopen settled choices. - -The configured `reviewer` agent handles independent review when routing rules -call for it. +| `explorer` | `gpt-6-luna`, `high` | Independent investigation that can run in parallel, or a large investigation that benefits from context isolation. | +| `reviewer` | `gpt-6-sol`, `high` | Independent review when the user asks or a high-risk semantic change needs review beyond deterministic evidence. | +| `architect` | `gpt-6-astra`, `medium` | An unresolved design decision or concrete invariant conflict. | + +The session allows at most two concurrent subagents. + +## Plan authority and routing + +An explicit implementation plan is settled when the user asks to apply it. +The root checks only the facts needed to apply it. The root escalates only for +an invariant conflict, a material mismatch with the repository, a missing +consequential decision, or validation that contradicts the plan. + +Use a specialist only when separate context has a clear benefit: parallel work, +context isolation for a large investigation, independent high-risk review, or +an unresolved architecture decision. Handle simple, single-file, sequential, +and shared-context work in the root. Do not inspect source just to prepare a +child task. Either investigate directly or delegate the bounded question +before inspecting the same sources. + +## Subagent reports + +Keep specialist reports to 500 words or less: + +- Explorer: finding, file and line evidence, impact. +- Reviewer: actionable findings with severity, file and line, and why each + matters. Say `No findings.` when there are none. +- Architect: decision, reason, affected invariants, required tests. + +Run independent review alongside CI or pull request administration when +possible. ## Code navigation and output From 0c8f67e1bcf7b5141c29de1b61e0a635ced088b1 Mon Sep 17 00:00:00 2001 From: Aryaman Todkar Date: Sat, 26 Sep 2026 15:42:22 +0530 Subject: [PATCH 2/2] chore: align ITN agent policy with Premove --- .codex/agents/architect.toml | 2 +- .codex/agents/explorer.toml | 2 +- .codex/agents/reviewer.toml | 3 +- .codex/config.toml | 6 +-- AGENTS.md | 75 ++++++++++++++++-------------------- AGENT_HARNESS.md | 22 ++++++----- 6 files changed, 53 insertions(+), 57 deletions(-) diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml index fe04c59..4f1a7e4 100644 --- a/.codex/agents/architect.toml +++ b/.codex/agents/architect.toml @@ -1,5 +1,5 @@ model = "gpt-6-astra" model_reasoning_effort = "medium" developer_instructions = """ -Resolve only an actually unresolved architectural decision or concrete invariant conflict. Do not reopen an explicit user-accepted design. Inspect current code and contracts. Do not implement or edit files. Return a compact record with the decision, reason, affected invariants, and required tests. +Resolve only the assigned unanswered architecture decision or concrete invariant conflict. Do not reconsider or reapprove an explicit user-accepted design. Inspect current code and tests. Return a concise Decision, Reason, Affected invariants, and Required tests. Do not edit files. """ diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml index 5b007d3..4911aff 100644 --- a/.codex/agents/explorer.toml +++ b/.codex/agents/explorer.toml @@ -1,5 +1,5 @@ model = "gpt-6-luna" model_reasoning_effort = "high" developer_instructions = """ -Investigate only a bounded question that can run in parallel with root work, or a large investigation whose isolated context saves root context. Do not reinvestigate an accepted plan. Use CodeGraph first for indexed code, then targeted reads, git, and tests as needed. Do not edit files or expand into architecture design. Return only a finding, file and line evidence, and impact. Keep the report within 500 words. +Investigate only the assigned independent question while the root continues useful work, or a large investigation isolated to save root context. Do not reinvestigate an accepted plan or edit files. Use CodeGraph first for indexed code, then targeted reads, git, and tests as needed. Return at most 300 words: Finding; Evidence with file:line; Impact. Do not expand into architecture design. """ diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml index 164e2f8..eab7d85 100644 --- a/.codex/agents/reviewer.toml +++ b/.codex/agents/reviewer.toml @@ -1,5 +1,6 @@ model = "gpt-6-sol" model_reasoning_effort = "high" developer_instructions = """ -Review whether the implementation realizes the accepted plan and preserves Premove ITN invariants. Do not reopen settled choices unless there is concrete evidence of a contradiction, regression, or violated invariant. Check relevant Premove ITN boundaries and edge cases. Do not edit files. Report actionable findings only, with severity, file and line, and why each matters. Order findings by severity. If there are no findings, report exactly: No findings. +Review the provided change and directly affected callers and tests for concrete violations of Premove ITN's Rust/Python ownership, candidate validity, scoring and decoder authority, public result meaning, or frozen prediction invariants. Check missing edge cases where relevant. Do not edit files or reopen a settled design without a concrete contradiction. +Return findings only. For each finding, give severity, file:line, and why it matters. If there are no findings, say "No findings." """ diff --git a/.codex/config.toml b/.codex/config.toml index 6e8b80e..c4d1220 100644 --- a/.codex/config.toml +++ b/.codex/config.toml @@ -8,15 +8,13 @@ args = ["run", "--no-project", "python", "scripts/agent/codegraph_mcp.py"] [agents] enabled = true max_concurrent_threads_per_session = 2 -default_subagent_model = "gpt-5.6-sol" -default_subagent_reasoning_effort = "medium" [agents.explorer] -description = "Investigate bounded unresolved code questions and report evidence." +description = "Investigate independent or large isolated code questions and return compact evidence." config_file = "./agents/explorer.toml" [agents.reviewer] -description = "Review implementation against the accepted plan and invariants." +description = "Independently review a provided change for concrete invariant violations." config_file = "./agents/reviewer.toml" [agents.architect] diff --git a/AGENTS.md b/AGENTS.md index b93b28b..dd6fc14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,52 +31,45 @@ compatible edits. ## Plan authority -Treat an explicit implementation plan as settled when the user asks to apply -it. Do not rediscover or redesign settled decisions. Escalate only when there -is concrete evidence of one of these conditions: +- Treat an explicit user-approved plan as settled when asked to implement, apply, or execute it. +- Review, critique, compare, or evaluate a plan in discovery mode. Do not treat it as settled. +- Do not rediscover or redesign settled work. -1. Invariant conflict: the plan violates an explicit repository invariant. -2. Reality mismatch: code, API, or configuration materially differs from the - plan's assumptions. -3. Insufficient specification: a consequential choice remains undecided. -4. Validation contradiction: focused evidence contradicts the plan's result. +Escalate execution only for: -Report the evidence and resolve only the conflicting or undecided part. A plan -does not override repository invariants, observed code, or failing checks. +1. An explicit invariant conflict. +2. A material mismatch between the plan and repository reality. +3. A consequential unresolved choice. +4. Validation that contradicts the plan. + +Escalate only the unresolved question. Keep the rest of the plan settled. ## Model routing -The root agent owns repository inspection, implementation, validation, Git, -GitHub, and final decisions. It handles work directly when steps depend on -shared context or must happen in sequence. - -Use the model and reasoning pins in `.codex/config.toml` and -`.codex/agents/*.toml`. Use only the configured specialist roles. Do not use -untyped or default subagents, or request per-run model or reasoning overrides. - -- Use CodeGraph directly for structural questions that it can answer without - substantial source investigation. -- Use `explorer` only for independent work that can run in parallel or for a - large investigation whose isolated context saves root context. -- Use `reviewer` when the user asks for independent review, or when a - high-risk semantic change cannot be established by deterministic evidence. -- Use `architect` only for an unresolved design decision or invariant conflict - involving candidate semantics, Rust/Python ownership, scoring or model - inputs, decoder legality, evaluation policy, public result meaning, or model, - package, or release identity. - -Do not spawn a specialist for a simple edit, a single-file task, a sequential -step, or work that depends on the root's current context. Do not delegate work -that the root must wait for when the root can do it directly. Do not inspect -source merely to prepare a child task. Either handle the investigation -directly or delegate its bounded question before inspecting the same sources. - -Keep specialist tasks bounded and reports compact. Explorer reports a finding, -file and line evidence, and impact in at most 500 words. Reviewer reports only -actionable findings with severity, file and line, and why each matters; if -there are none, report `No findings.` Architect reports the decision, reason, -affected invariants, and required tests. When independent review is required, -run it alongside CI or pull request administration when possible. +The root agent owns investigation, implementation, validation, Git, GitHub, and final decisions. Use CodeGraph for structural navigation. + +Spawn a configured named subagent only when separate context provides a clear benefit: + +- Independent work can run in parallel with root work. +- A large investigation should be isolated from root context. +- An independent semantic review is required. +- An unresolved architecture decision requires stronger reasoning. + +Do not spawn for simple edits, sequential investigation or implementation, or work that depends on the root's current context. Do not inspect source merely to prepare a subagent task; either handle the work directly or delegate the bounded question immediately. + +- Independent investigation → `explorer`. +- Independent semantic review → `reviewer`. +- Unresolved architecture or invariant decision → `architect`. + +Use `reviewer` only when the user requests review or protected semantic behavior changes and deterministic evidence is insufficient. When review is needed, overlap it with CI or independent PR work when possible. An accepted plan alone does not trigger `architect`. + +For Premove ITN, unresolved architecture or invariant decisions may involve candidate or GoldGraph semantics, the Rust/Python ownership boundary, scoring or model inputs, structured loss or decoder legality, training or evaluation policy, public context or result meaning, or model, package, or release identity. + +Do not delegate a dependent step that the root can do directly. Keep subagent tasks bounded and returned context minimal. Pass the bounded task explicitly and use `fork_turns="none"` by default. Inherit only the minimum recent turns required by the task. + +Do not use default or untyped subagents or override configured models or reasoning levels. + +If two evidence-driven fixes fail and the cause remains unclear, stop and return the evidence. ## Git diff --git a/AGENT_HARNESS.md b/AGENT_HARNESS.md index c3d4942..1bf881f 100644 --- a/AGENT_HARNESS.md +++ b/AGENT_HARNESS.md @@ -25,21 +25,25 @@ The root checks only the facts needed to apply it. The root escalates only for an invariant conflict, a material mismatch with the repository, a missing consequential decision, or validation that contradicts the plan. -Use a specialist only when separate context has a clear benefit: parallel work, -context isolation for a large investigation, independent high-risk review, or -an unresolved architecture decision. Handle simple, single-file, sequential, -and shared-context work in the root. Do not inspect source just to prepare a -child task. Either investigate directly or delegate the bounded question -before inspecting the same sources. +The root performs sequential coding directly. It uses Explorer for independent +parallel investigation or large context isolation. Reviewer provides an +independent check when requested or when protected behavior changes and +deterministic evidence is insufficient. Review can overlap with CI or PR work. +Architect is reserved for an unresolved decision. A request to assess a plan +is discovery work until the user asks to execute it. + +Do not inspect source just to prepare a child task. Either investigate directly +or delegate the bounded question immediately. Pass a bounded task and use +`fork_turns="none"` by default. Inherit only the recent turns the task needs. ## Subagent reports -Keep specialist reports to 500 words or less: +Keep specialist reports compact: -- Explorer: finding, file and line evidence, impact. +- Explorer: at most 300 words, with Finding; Evidence with file:line; Impact. - Reviewer: actionable findings with severity, file and line, and why each matters. Say `No findings.` when there are none. -- Architect: decision, reason, affected invariants, required tests. +- Architect: Decision, Reason, Affected invariants, Required tests. Run independent review alongside CI or pull request administration when possible.