Codex Session Lifecycle: carrying verified work safely between AI coding dialogs.

Why AI coding sessions need a lifecycle

The engineering task usually outlives the chat window

Long-running Codex work rarely fits inside one dialog. Over hours or days, the project accumulates decisions, verified and unverified changes, an active ExecPlan, local constraints, open questions and explicit boundaries around what must not be changed. The chat remains temporary: it may end because a fresh dialog is needed, the project changes, or the context must be cleared while the actual task is still unfinished.

The practical failure is broader than “lost memory.” A fresh session can repeat completed discovery, select an obsolete plan, miss an unresolved blocker, confuse a visible UI with proof of deployment or describe partially checked work as complete. As the project grows, those mistakes become more expensive because they consume time and quietly corrupt the history of decisions.

A transcript dump is not a reliable fix. It mixes permanent policy, current state, historical rationale and temporary noise. The next context becomes larger without making it clear what is true now, which evidence supports the state and which action should happen next.

The core idea: two sides of one transition

end-session closes the work; new-session resumes it

I designed the lifecycle around two orchestrator skills. end-session closes the current dialog honestly. It settles active work, collects verification results, keeps verified, partially verified, failed, blocked and not-run states separate, then updates only the project artifacts that actually own the durable knowledge discovered during the session.

new-session solves the inverse problem. It does not begin by reading the entire project. It validates the project root, lifecycle state and compact restart map, selects one relevant ExecPlan, and loads architecture or diary context only when the current continuation needs it. That reduces noise and prevents old history from silently controlling new work.

The connecting contract is Summarizations.md. It is written last, after the other gated updates, so it records the settled state: what changed, what was verified, what remains, where to continue and which blockers must stay visible. It is not a transcript, a new backlog or an authority token for external or destructive action.

Why one summary skill was not enough

Project memory needs owners and different durability levels

A project does not have one universal memory. Repository instructions, architecture contracts, decision history, an active plan, reusable lessons and a short handoff answer different questions. When everything is written into one file, a temporary detail can become permanent policy and a local workaround can begin to look like an architectural decision.

The orchestrators therefore coordinate specialised skills rather than replacing them. Dedicated skills own the project diary, architecture, ExecPlans, repository guidance, verification and the promotion of genuinely reusable lessons. Every layer has its own gate: a write happens only when new durable knowledge exists and only in the artifact that owns it.

The public system contains 16 complete skill folders. Alongside new-session andend-session, it includes skills for creating and updating ExecPlans, reading and writing the project diary, maintaining architecture and repository instructions, running the verification gate, preparing the final summary and diagnosing context fundamentals, degradation, optimisation and compression.

How a session is closed

Evidence first, durable updates second, handoff last

Shutdown begins by determining the real state of the work. If a build, deployment or asynchronous check is still running, the lifecycle must not freeze a premature result. One conservative verification verdict is then reused by downstream updates so the plan, diary and handoff do not tell conflicting stories.

The system next decides what deserves to persist. A public API change may require an architecture update; an important decision may belong in the diary; an unfinished milestone belongs in the active ExecPlan. If no durable lesson exists, the corresponding file stays unchanged. This default-to-no-change rule prevents project memory from becoming an endless collection of session recaps.

Only then is the restart map created. It contains the current objective, confirmed result, incomplete checks, exact continuation point and relevant paths. The next session receives an operational map, not the history of a conversation.

How the next session begins

Minimum sufficient context instead of a full project scan

At startup, new-session checks that the current working directory is the expected project root and that the handoff belongs to this project and remains actionable. It then identifies the active plan and reads only the documents required to execute the nearest safe step.

This ordering is central to context engineering. Architecture is useful when contracts or runtime flows are changing; the diary matters when the reason behind a decision must be recovered; repository guidance applies when local rules govern the work. Loading every layer on every request is expensive and forces historical detail to compete with the current task.

The lifecycle also preserves the authority boundary. A record of an earlier deployment does not authorize another deployment, and an old plan to delete a file does not become a current command. The handoff transfers state and evidence without expanding user scope.

Engineering boundaries and privacy

An open-source method must not publish the private projects that produced it

Preparing the public version required separating the reusable workflow from the contents of real projects. Credentials, secrets, private URLs, local absolute paths, internal artifacts and project-specific data are excluded. The repository publishes each skill contract and its requiredagents/, references/ and scripts/, not a user’s project memory.

Another boundary concerns claims. The system can prove that the repository exists, the skills are available, the atlas builds and the production route responds. It cannot prove broad third-party adoption, search rankings or a universal productivity percentage. This case therefore records only verifiable outcomes and keeps expected practical value separate from measured evidence.

The delivered system

Source code for adoption and an atlas for understanding the whole

The result is published through two complementary proof surfaces. The GitHub repository contains all 16 skills so developers can inspect exact instructions, gates and supporting files. The interactive Vite + React atlas presents the system from above: lifecycle phases, dependency graph, artifact ownership, privacy boundaries and the data path from closing one session to starting the next.

This is a reference implementation that can be adopted incrementally. A developer can begin with thenew-session / end-session pair and introduce planning, diary, architecture or context diagnostics as the project grows. Its value is not a promise of perfect memory. It turns forgetting, verification and continuation into explicit engineering processes.

Verified result

Evidence available at publication time

• The public GitHub repository is reachable on main and contains all 16 documented skill directories.
• A clean checkout of the atlas passes npm run build and npm run test:sites with 4/4 tests.
• The production atlas responds at /end-new/ and loads assets from the intended base path.
• The published workflow excludes credentials, private project artifacts and local absolute paths by contract.

Explore the system in the interactive atlas ↗, then inspect or download the source from the public GitHub repository ↗. For the related durable-memory method, read Architecture Update: Project Memory for Codex.