engineering note / Agentic Engineering
A two-role Codex workflow from specification to CI
Separating implementation from verification
Controlled agent work starts with a contract, role separation, and an external gate—not with the number of agents.
In brief
- The specification is a contract.
- Review should not be the implementer’s self-assessment.
- CI closes the loop with external evidence.
Why use two roles
An agent that wrote a change carries the same context and assumptions into self-review. A second role does not guarantee correctness, but it creates a separate critical step grounded in the specification and observable artifacts.
The split only works when the roles have different contracts. Two sessions following the same broad instruction do not create quality control.
The working contract
The implementation role receives scope, acceptance criteria, and allowed changes. The verification role receives the same criteria without the author's internal assumptions. It must point to evidence: a test, diff, log, or reproducible scenario.
specification → implementation → independent review → CI → human decisionWhat CI should cover
- formatting, lint, and types;
- unit tests for critical behaviour;
- data-contract validation;
- a browser test of the user journey;
- version and limitation records.
CI does not judge product value. It provides repeatable external evidence that one version satisfies its technical contract.
Common failure modes
The first is scope expansion during implementation. The second appears when review comments on style but never executes the acceptance scenario. The third is green CI backed by tests that do not touch the changed path.
Where the pattern helps
This workflow is useful for tasks with an explicit contract and testable outputs. When product direction remains unresolved, an owner decision is needed before more agents are added.
01 / METHOD
The question the test must answer
A two-role workflow is not a conversation between two characters. It separates the implementation contract from independent artifact checking, so a claim of ‘done’ does not replace a test, review, or merge decision. The value of the material is that a reader can separate the user question from a convenient tool metric and identify the point at which a result is no longer sufficient for the next stage of work.
02 / METHOD
Material and counterexamples
The specification states input, outcome, boundaries, test, and acceptance owner. A handoff carries state and evidence, not a private implementer narrative or undisclosed session data. Control material is not meant to confirm the author’s thesis; it should expose a case in which a plausible result is dangerously misleading for the workflow at hand.
03 / METHOD
Control method
The sequence is simple: specification, implementation, pull request, CI, independent review, and decision. An additional agent is not the goal; its role must add a distinct control criterion. The account includes step order, input, and result trace so an independent person can inspect what was measured and what the procedure does not measure at all.
04 / METHOD
Acceptance matrix
A PR evidence packet contains the diff, test results, limitations, reviewer decision, and rollback point. When a gate fails, the change returns to the responsible role rather than passing on a confident account. Criteria are stated before the result is read, so a single successful example cannot substitute for control of a critical failure type.
05 / METHOD
Handoff and rerun
A minimal runbook explains how to run the test, find the artifact, reproduce a defect, and use rollback. That makes continuation possible without dependence on a prompt author. Reproducibility also means showing why a subsequent run differs from an earlier one and who decides whether a new version may be used.
06 / METHOD
Boundary of the conclusion
Role separation does not create automatic independence: a shared error source or opaque test can weaken both roles. The workflow needs a genuine gate outside an agent narrative. The material is therefore methodological: it does not pose as a universal recipe or as an independent confirmation that has not been performed.
07 / METHOD
A worked check
A minimal run can be checked on one pull request: the specification names requirement and test, implementation supplies a diff, CI verifies the artifact, and a reviewer records an independent criterion and decision. When test or review fails, work returns to the responsible role rather than to another textual account.
08 / METHOD
Source and review record
An evidence packet contains only reproducible traces: PR link, diff scope, CI result, limitations, reviewer decision, and rollback point. Private prompts, session data, and credentials need not be published for another person to distinguish execution from approval.
LIM
Limitations and scope
One experiment does not prove an advantage for every repository or type of work.
SRC
Sources and external edition
Original or earlier Medium material
AI tools assisted with structure and editing. The final text underwent human editorial review of facts, sources, conclusions, and attribution.
LOG
Change history
- First expanded edition in the owned archive.
- Review of structure, limitations, and evidence links.