Contents
- 01Start From Zero and Choose the Right Surface
- 02Turn Intent Into Verifiable Work
- 03Configure Codex and Teach It the Project
- 04Bound Authority With Sandbox and Approvals
- 05Make the Change and Prove It
- 06Work Across Environments and Worktrees
- 07Delegate With Subagents
- 08Build the Extension Stack
- 09Automate, Embed, and Run Long Work Safely
- 10Capstone: From Command to Receipt
Capstone: From Command to Receipt
Use the complete Codex operating system to turn one real business request into a scoped, safe, tested, reviewable, and independently verifiable result.
By the end
A production-quality delivery packet that connects business intent, repository truth, bounded authority, implementation, parallel work, user-flow proof, release state, and rollback.
Choose a real vertical slice
The capstone should solve a workflow you understand, not demonstrate technology for its own sake. Good examples include an internal intake and approval flow, a searchable operating guide, a reporting correction, a customer self-service action, or a small automation with review gates. The slice must cross enough layers to require judgment while remaining completable and reversible.
Name one primary user and one outcome they can demonstrate. Exclude adjacent ambitions. A narrow slice that is secure, tested, documented, and operable teaches more than a broad prototype whose data, permissions, and deployment cannot be trusted.
Build the operating packet before implementation
Select the right Codex surface and environment. Record the canonical repository, branch, dirty state, runtime, data, integration, identity, and deployment path. Write the task contract with business rules, negative cases, proof, non-goals, and decision boundaries. Confirm that repository guidance is accurate and concise.
Then create the authority plan. Investigation should begin read-only. Implementation should be limited to the necessary workspace and commands. Release authority should be a separate explicit gate with an exact target, rollback, and post-release check.
Implement with controlled parallelism
Use subagents only where they improve independence or review. An explorer can map the current path and official constraints. An implementer can own the narrow source change in an isolated worktree. A verifier can test the finished behavior against the original contract. Keep one integration owner and no overlapping write scopes.
If a repeated method is central to the capstone, capture it as a small skill. If current external data is required, connect it through a narrowly scoped MCP tool. If one safety condition must always run, use a deterministic hook. Do not add extensions merely to satisfy a checklist.
Prove each required layer
Review the final diff and run risk-matched static, unit, integration, build, and user-flow checks. For web work, complete the critical path in the browser and inspect the console. For native work, verify the actual application. Test one negative or failure case that matters to the business rule or security boundary.
If release is in scope, capture the exact deployed version and verify the live route independently after propagation. If release is not in scope, say so clearly. Never convert a source or preview success into an implied production claim.
Handoff an operable system
Delivery is not only the feature. Leave behind the task contract, architecture trace, updated durable guidance, source history, test commands, deployment or handoff receipt, known limitations, and rollback. Another person should be able to operate or review the result without reading the original conversation.
End with a retrospective: what Codex discovered, which human decisions mattered, where proof was strongest, which assumption failed, and what should be automated next only after more supervised runs. The goal is not maximum autonomy. It is a trustworthy system that can earn more autonomy through evidence.
Working reference
Commands and patterns
Open the capstone from a known state
git rev-parse --show-toplevel git branch --show-current git status --short git worktree list codex --config 'default_permissions=":read-only"'
This capstone chooses the newer permission-profile engine. Before launching, confirm no loaded config or CLI argument selects the older sandbox engine; move to a custom workspace permission profile only after the task and authority contracts are approved.
Audit the final source change
git status --short git diff --check git diff --stat git diff
These checks expose the changed file set, whitespace errors, overall size, and exact patch. They do not replace application tests or browser/native proof.
When the happy path breaks
Failure modes
Symptom
The capstone becomes a large platform rebuild and never reaches a verifiable user outcome.
Likely cause
The project was framed around a technology or full vision rather than one complete vertical slice.
Recovery
Return to one user, one workflow, one bounded data path, and one observable result; move all adjacent ideas into explicit non-goals or later milestones.
Symptom
Every checklist item is present, but the feature still feels unsafe or unusable.
Likely cause
Artifacts were created mechanically without tying tests, permissions, and evidence to the actual business risks.
Recovery
Revisit the user's critical path and failure consequences, remove ceremonial evidence, and add checks that would catch the real ways the workflow can harm or disappoint someone.
Symptom
Parallel work creates an impressive amount of output but a difficult integration.
Likely cause
Subagents were used to maximize activity rather than isolate independent responsibilities.
Recovery
Reduce lanes, restore one writer per shared area, integrate from a clean base, and use independent agents primarily for exploration and verification where write overlap is unnecessary.
Symptom
The handoff claims completion but omits release state, rollback, or remaining risk.
Likely cause
The final narrative summarizes implementation rather than reconciling every acceptance criterion and proof layer.
Recovery
Use the command-to-receipt packet, state the exact highest verified environment, include recovery, and label any missing proof as unfinished work.
Hands-on lab
Deliver one trustworthy vertical slice
Complete a real change using every relevant layer of the guide, then have a second reviewer reproduce the result from the handoff packet alone.
- 01Choose one real user workflow and write the outcome, scope, non-goals, examples, negative cases, and business risk.
- 02Audit every loaded config layer, choose the newer permission-profile engine for this capstone, and confirm that no older sandbox key or `--sandbox` flag is active. Run the opening commands under `:read-only` to map repository, environment, data, identity, integration, tests, deployment, and existing changes with exact evidence.
- 03Create or audit AGENTS.md, user config, any config overlay, and project config. Keep config overlays distinct from permission profiles, place only durable guidance there, and verify which layer wins.
- 04Start a desktop Worktree or an explicit Git worktree for implementation. Record its branch or detached state, owned files, runtime port, and handoff path.
- 05Select the custom `project-edit` permission profile without passing `--sandbox`, then define investigation, implementation, verification, and release authority as separate stages. Rehearse one expected denial before implementation.
- 06Ask the built-in explorer to map the risky path and a worker to own the bounded patch; use the project `evidence_reviewer` agent after implementation. Inspect lanes with `/agent`.
- 07If the workflow repeats, invoke `$verification-receipt`; if it needs live data, inventory one read-only MCP connection; if it needs deterministic enforcement, demonstrate one trusted hook. Omit mechanisms that add no value.
- 08Implement a narrow diff, add the smallest meaningful regression and negative-case coverage, and run the final source-audit commands.
- 09For web work, first satisfy Chapter 5's clean-account prerequisite: install Browser from the Plugins Directory and verify it is available. Then use `@Browser` on the exact URL to complete the user flow, inspect console output, and capture before/after screenshots. For another interface, prove that actual surface instead.
- 10If release is authorized, capture the exact provider version and independently verify the live target. Otherwise state that deployment was not performed. Demonstrate rollback or recovery in a safe environment.
- 11Run `$verification-receipt`, give the complete packet to an independent reviewer, resolve every reproducibility gap, and identify the next supervised repetition required before automation or broader authority.
Deliverable: A complete command-to-receipt packet and a second-reviewer verification showing that the result can be understood, reproduced, and recovered without the original chat.
Reusable artifact
Command-to-receipt delivery packet
The final operating artifact for a Codex-led change from business request through safe handoff.
# Outcome - User and observable result: [who can now do what] - Scope and non-goals: [boundary] # Current truth - Repository, branch, worktree, and dirty state: [evidence] - System path: [interface -> logic -> state -> identity -> integration] - Environment layers: [source / local / cloud / preview / production] # Authority - Filesystem, network, tools, and external actions: [scopes] - Human gates: [consequential decisions] # Implementation - Changed files: [path -> reason] - Decisions: [choice -> evidence -> tradeoff] - Parallel lanes or extensions used: [why and boundaries] # Verification - Automated checks: [command -> result] - Critical user flow: [steps -> result] - Negative case: [steps -> safe result] - Release proof: [version and live target, or explicitly not released] # Operations - Rollback or recovery: [procedure and proven point] - Known limitations and unverified risk: [plain statement] - Owner and next review: [person + date]
Before you move on
Receipt checklist
- The capstone solves one observable user workflow with explicit non-goals.
- Repository and environment claims are tied to current source, command, or provider evidence.
- Authority is staged and consequential actions have visible human gates.
- The final diff is narrow, reviewable, and preserves unrelated work.
- Automated checks and the actual user flow prove the highest-risk acceptance criteria, including one negative case.
- The exact release state is proven or explicitly stated as not released.
- Rollback or recovery is documented and demonstrated safely.
- An independent reviewer can reproduce the result from the delivery packet alone.
Primary sources
