Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codex/agents/architect.toml
Original file line number Diff line number Diff line change
@@ -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 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.
"""
2 changes: 1 addition & 1 deletion .codex/agents/explorer.toml
Original file line number Diff line number Diff line change
@@ -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 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.
"""
5 changes: 0 additions & 5 deletions .codex/agents/implementer.toml

This file was deleted.

3 changes: 2 additions & 1 deletion .codex/agents/reviewer.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
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 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."
"""
16 changes: 5 additions & 11 deletions .codex/config.toml
Original file line number Diff line number Diff line change
@@ -1,26 +1,20 @@
model = "gpt-6-luna"
model_reasoning_effort = "xhigh"
model = "gpt-6-sol"
model_reasoning_effort = "medium"

[mcp_servers.codegraph]
command = "uv"
args = ["run", "--no-project", "python", "scripts/agent/codegraph_mcp.py"]

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-sol"
default_subagent_reasoning_effort = "medium"
max_concurrent_threads_per_session = 2

[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.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."
description = "Independently review a provided change for concrete invariant violations."
config_file = "./agents/reviewer.toml"

[agents.architect]
Expand Down
114 changes: 36 additions & 78 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,87 +31,45 @@ 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:

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.

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.
- 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.

Escalate execution only for:

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 coordinator owns routing, synthesis, and final decisions. It must delegate
work to the configured named specialist when the task meets a role trigger
below.

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.

- 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,
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.
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

Expand Down
58 changes: 38 additions & 20 deletions AGENT_HARNESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,47 @@ 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.

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 compact:

- 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.

Run independent review alongside CI or pull request administration when
possible.

## Code navigation and output

Expand Down
Loading