Codex Advisor Integration
Relevant source files
The following files were used as context for generating this wiki page:
Codex Advisor Integration provides an independent review and verification mechanism within the production repository change workflow. It functions as a specialized delegate that challenges design decisions, scope questions, and implementation integrity at specific checkpoints. The system enforces strict architectural standards by enumerating load-bearing promises and identifying material failure classes that could falsify those promises.
The integration uses a dedicated Bash wrapper as the sole production transport to communicate with the advisor. It operates in two primary phases: a preflight phase for design validation and a final review phase for code verification. The advisor remains isolated from live repository tools during phased consults, relying exclusively on provided workflow evidence like diffs, original requests, and advisor projections.
Sources: skills/codex-advisor/SKILL.md:1-25, skills/repo-production-workflow/SKILL.md:120-130, CLAUDE.md:164-180
Architecture and Transport
The integration relies on scripts/ask-codex-advisor.sh as the exclusive transport layer. This wrapper manages session persistence, payload construction, and provider communication.
Transport Flow
The wrapper executes the following sequence during a consult:
- Validation: Validates input arguments, budgets (max 1200 words), and phase-specific requirements.
- Identity Resolution: Determines the repository root and session identity via
hooks/lib/repo_identity.py. - Evidence Collection: Queries
workflow.pyfor phase-specific checkpoints, including advisor projections and current-pass diffs. - Execution: Invokes the
claudeCLI with a specific system role and isolated tool configuration. - Recording: Captures and records the UTF-8 response and its digest as immutable finding intake in the workflow ledger.
Sources: skills/codex-advisor/scripts/ask-codex-advisor.sh:8-250, skills/codex-advisor/SKILL.md:80-100
This diagram illustrates the flow from an initial request through the transport wrapper to the advisor delegate and back to the workflow ledger.
Sources: skills/codex-advisor/scripts/ask-codex-advisor.sh
Operational Phases
The Codex Advisor is invoked at two critical stages of the Repo production workflow.
1. Preflight Advice
This phase occurs after repository context forge but before production edits. It is triggered when a request raises design or scope questions. The advisor:
- Derives load-bearing promises from the original request.
- Challenges the governing design (or notes its absence).
- Enumerates operations (e.g., cancellation, shared-state writers) that could falsify promises.
- Identifies material promises lacking a planned attack vector.
Sources: skills/codex-advisor/SKILL.md:7-40, skills/repo-production-workflow/SKILL.md:46-60
2. Final Review
This phase follows implementation and lead code review. It acts as an independent challenge to the lead's review. The advisor checks:
- Whether the public Interface promises are met.
- If production operations can falsify implemented promises.
- If any finding disposition loses part of its original domain.
- Module shape, minimality, security boundaries, and visible regression coverage.
Sources: skills/codex-advisor/SKILL.md:42-70, skills/repo-production-workflow/SKILL.md:144-155
Phase Comparison
| Phase | Requirement | Primary Payload | Primary Output |
|---|---|---|---|
preflight-advice | Optional (Design-sensitive) | Original Intent, Advisor Projection | Scope/Design Findings |
final-review | Mandatory | Intent, Projection, Candidate Diff | Verdict (commit-ready, fix-before-commit) |
Sources: skills/codex-advisor/SKILL.md:7-75, skills/codex-advisor/scripts/ask-codex-advisor.sh:130-150
Finding and Disposition Logic
The advisor returns structured findings that the lead agent must validate and disposition. Findings are immutable once recorded.
Finding Structure
Findings must follow the schemaVersion: 1 JSON format:
{
"id": "SPEC-1",
"claim": "Direct explanation of the defect or risk",
"material": true,
"kind": "behavioral"
}
- Material: Indicates if the finding names a concretely reachable failure.
- Kind: Either
behavioral(requires a code/test change) ornonbehavioral(design/doc issues).
Sources: skills/codex-advisor/SKILL.md:65-75, skills/repo-production-workflow/SKILL.md:135-140
Disposition States
The lead agent records dispositions for material findings using workflow.py advisor-disposition.
| Disposition Status | Requirement |
|---|---|
fixed | Requires a zero-count complete-domain occurrence; Behavioral findings must have a GREEN attack. |
rejected-with-evidence | Requires a quoted measurement or proof that the premise is false. |
accepted-follow-up | Requires an external reference to a tracked issue or PR. |
report-only | Requires proof of false material consequence; does not authorize code changes. |
Sources: skills/codex-advisor/SKILL.md:105-130, skills/repo-production-workflow/SKILL.md:65-80
Integration Constraints
The Design Declaration
Every phased consult requires a governing-design declaration. You must provide either --design-file (a path to a durable design artifact) or --design-absent (a string explanation of why no design exists). The transport refuses a consult if neither is provided.
Sources: skills/codex-advisor/SKILL.md:16-30, skills/codex-advisor/scripts/ask-codex-advisor.sh:65-80
Tool Isolation
During phased consults, the advisor is stripped of all live repository tools (e.g., Bash, Read, WebSearch). It can only consume the supplied projection and diff evidence. This prevents the advisor from performing live measurements, which remains the responsibility of the lead agent.
Sources: skills/codex-advisor/SKILL.md:100-104, skills/codex-advisor/scripts/ask-codex-advisor.sh:175-185
Verdict Rules
A commit-ready verdict is only valid if no material findings remain open and the candidate context matches the diff provided. A context-mismatch verdict occurs if the supplied tree OID does not describe the diff, requiring a re-consultation.
Sources: skills/codex-advisor/SKILL.md:70-75, skills/repo-production-workflow/SKILL.md:155-165
This sequence shows the interaction between the lead agent, the transport wrapper, and the workflow state to reach a terminal disposition.
Sources: skills/codex-advisor/scripts/ask-codex-advisor.sh, skills/repo-production-workflow/SKILL.md
Conclusion
Codex Advisor Integration ensures that every production change is challenged by an independent review layer. By forcing the enumeration of load-bearing promises and requiring measured evidence for every disposition, it prevents speculative fixes and ensures implementation integrity within the repository's production workflow.