Lecture 06. Initializing Before Every Agent Session

You start a new agent session and say "add a search feature." It dives straight into coding — admirable enthusiasm. After 20 minutes, it discovers the test framework isn't configured correctly, spends another 10 minutes fixing that, then formats the database migration script wrong, fumbling around some more. The search feature eventually gets added, but the whole session was inefficient — most of the time was spent "figuring out how this project works" instead of writing the search feature.

A better approach: before letting the agent start working, use a dedicated phase to prepare the base environment, get verification commands passing, and establish an understood project structure. It's like building a house — you don't pour the foundation and raise the walls at the same time. If you do, the walls go up before the foundation has cured, and the whole building has to be torn down and started over. Pour the foundation first, let it cure, then raise the walls — clean and efficient.

This lecture explains why initialization must be a separate phase, not mixed in with implementation.

Foundation and Walls: Two Fundamentally Different Jobs

Initialization and implementation have completely different optimization goals. The implementation phase optimizes for: maximizing the quantity and quality of verified features. The initialization phase optimizes for: maximizing the reliability and efficiency of all subsequent implementation.

When you mix initialization and implementation, the agent faces a multi-objective optimization problem — simultaneously building infrastructure and writing feature code. Without a clear priority setting, the agent naturally leans toward writing code (since that's the directly visible outcome) while sacrificing infrastructure (since its value only shows up in later sessions). It's like telling a construction crew to simultaneously pour the foundation and build the walls — they'll likely rush to build the walls because walls are visible and demonstrable. But a house with a bad foundation has systemic problems down the road.

The Initialization Lifecycle

What Happens When You Mix Them

The most immediate problem: the foundation doesn't cure properly. The agent spends 80% of its effort on feature code and 20% haphazardly setting up some infrastructure. The test framework gets configured but never verified, lint rules get set up but too loose, no progress file gets created. These flaws aren't obvious in the first session (since the agent still remembers what it did), but they surface in the second session — the new agent doesn't know how to run things, test things, or where anything is. Sloppy foundation, shaky building.

An even more hidden cost is "unverified accumulation" — feature code written before the test framework is configured is code with no verification. When you eventually go back to add tests for that code, you might discover the design was flawed from the start — had you known earlier, you would have implemented it differently. It's like laying tile on wet concrete — when you discover the floor isn't level, all the tiles have to be pried up and redone.

Session budget is also being wasted. Initialization work (configuring the environment, setting up tests, understanding project structure) consumes significant budget, leaving less for actual feature implementation. Result: the first session only completes half a feature, and the second session has to start over understanding the project. Budget was spent on the foundation, but the foundation still isn't solid — neither goal gets achieved.

The easiest problem to overlook is the hidden assumption trap. Decisions the agent makes during initialization (which test framework, how to organize directories, dependency management) — if not clearly documented, later sessions can't understand these choices. Worse, later sessions might make conflicting choices. The first construction crew uses a concrete foundation, the second crew doesn't know and drives wooden stakes into it — the foundation cracks.

Anthropic's research on long-running application development specifically recommends separating initialization from implementation. Their empirical data: projects using a separate initialization phase show a 31% higher feature completion rate in multi-session scenarios compared to mixed approaches. Key insight — time invested in the initialization phase is fully recouped within the next 3-4 sessions. The more solid the foundation, the faster the walls go up.

OpenAI's Codex harness engineering guide also emphasizes the "repository as activity log" principle — establish clear operational structure from the very first run, or every new session has to re-infer the project's conventions.

Core Concepts

Initialization Phase: The first phase in an agent's lifecycle — no feature implementation, just establishing the prerequisites for all subsequent implementation phases. The output isn't code, it's infrastructure.
Bootstrap Contract: The conditions under which a project can be operated unambiguously by a new agent session — can start, can test, can see progress, can choose the next step. Four conditions, all necessary.
Cold Start vs. Warm Start: Cold start is from an empty directory where the agent must guess the project structure; warm start is from an existing template or project where infrastructure is already in place. Warm start is far superior to cold start — like starting work on a construction site that already has running water and electricity versus starting from raw wilderness.
Handoff Readiness: The state a project is in at any point where a new agent could take over. No verbal explanation needed — just the repo contents.
Time to First Verification: The time from project start to the first feature point passing verification. This is the core metric for measuring initialization effectiveness.
Downstream Usability: The best measure of initialization quality — the proportion of subsequent sessions that can successfully execute tasks without relying on hidden knowledge.

How to Initialize Correctly

Treat initialization as a separate phase. The first session does only initialization — no business feature code at all. Initialization produces:

1. A runnable environment. The project starts up, dependencies are installed, no environment issues. The foundation is poured, no cracks.

2. A verifiable test framework. At least one sample test passes. This proves the test framework itself is configured correctly — like standing a single column on the foundation to prove it can bear weight.

3. Bootstrap contract documentation. A clear document for later sessions:

# Initialization Contract

## Startup Commands
- Install dependencies: `make setup`
- Start dev server: `make dev`
- Run tests: `make test`
- Full verification: `make check`

## Current Status
- All dependencies installed and locked
- Test framework configured (Vitest + React Testing Library)
- Sample test passing (1/1)
- Lint rules configured (ESLint + Prettier)

## Project Structure
- src/ — Source code
- src/components/ — React components
- src/api/ — API client
- tests/ — Test files

4. Task breakdown. Split the entire project into an ordered task list, each with clear acceptance criteria:

# Task Breakdown

## Task 1: Basic User Authentication
- Implement JWT auth middleware
- Add login/register endpoints
- Acceptance: pytest tests/test_auth.py all passing

## Task 2: User Profile Page
- Implement user profile CRUD
- Add profile edit form
- Acceptance: pytest tests/test_profile.py all passing

## Task 3: Search Feature
- ...

5. Git commit as checkpoint. Once initialization is complete, commit a clean checkpoint. All subsequent work starts from this checkpoint.

Warm start strategy: Don't start from an empty directory. Use a project template (create-react-app, fastapi-template, etc.) to pre-establish standard directory structure, dependency configuration, and test framework. Bake the routine initialization steps into the template, leaving only project-specific initialization work. It's like starting work on a construction site that already has running water and electricity — ten thousand times better than starting from raw wilderness.

Initialization completion criteria: Not "how much code was written," but whether the four bootstrap contract conditions are met — can start, can test, can see progress, can choose the next step. Use this checklist to confirm initialization:

## Initialization Acceptance Checklist
- [ ] `make setup` succeeds from scratch
- [ ] `make test` has at least one passing test
- [ ] A new agent session can answer "how to run" and "how to test" using only the repo contents
- [ ] A task breakdown file exists with at least 3 tasks
- [ ] Everything is committed to git

Real-World Example

Two initialization approaches for a React frontend project:

Mixed approach (pouring the foundation and building walls at once): The agent simultaneously creates the project scaffolding and implements the first feature in session 1. At the end of the session, the repo has runnable code but: no clear start/test command documentation, no progress tracking file, no task breakdown. Session 2 spends ~20 minutes inferring the project structure, test framework, and build process — like a new construction crew arriving at the site, not knowing how far the foundation runs or where the plumbing is, having to dig test holes everywhere to find out.

Separate initialization (foundation first): Session 1 does only initialization — creates directory structure from a template, configures the test framework (Vitest + React Testing Library), writes and verifies a sample test, creates the bootstrap contract document and task breakdown file, commits the initial checkpoint. Session 2's rebuild cost is under 3 minutes, and it starts working directly from the task list — the crew arrives, looks at the blueprints, and knows exactly where to continue.

Comparing the full project cycle: total rebuild time (across all sessions) for the mixed approach is ~60% higher than the separate-initialization approach. The extra 20 minutes spent on initialization is recouped many times over in subsequent sessions. Just like a solid foundation lets walls go up faster — slow is fast.

Key Takeaways

Initialization and implementation have different optimization goals — mixing them only drags both down. Pour the foundation first, then raise the walls.
Initialization's output isn't code, it's infrastructure: a runnable environment, verifiable tests, bootstrap contract, task breakdown.
Confirm initialization with the four bootstrap contract conditions: can start, can test, can see progress, can choose the next step.
Warm start beats cold start. Use project templates to pre-establish standardized infrastructure.
Time invested in initialization is fully recouped within the next 3-4 sessions. This isn't overhead — it's an upfront investment. The more solid the foundation, the faster the building goes up.

Exercises

Design a bootstrap contract: Write a complete bootstrap contract for a project you're developing. Then open a completely new agent session, show it only the repo contents (no verbal context), and let it try to start the project, run tests, and understand current progress. Record every issue encountered — each one corresponds to a missing clause in your bootstrap contract.

Comparative experiment: Pick a new medium-sized project. Approach A: let the agent simultaneously initialize and perform the first implementation. Approach B: dedicate one session to separate initialization, start implementation in session 2. After 4 sessions, compare: time to first verification, rebuild cost, feature completion rate.

Initialization acceptance checklist: Design an initialization acceptance checklist for your project. Have a new agent session execute each item on the checklist and record which ones pass and which fail. The failing items are where your harness needs to be strengthened.