Related lectures: Lecture 03. Make the repository your single source of truth · Lecture 04. Split instructions across files Starter kit (task prompt, feature list, handoff/docs templates, no app source): included in the course Template Pack. Download it from your account page.

Project 02. Make the Project Readable and Pick Up Where You Left Off

Illustrative composite. A four-person team let two agent sessions work the same feature two days apart. The first session got most of the document-import flow working, then stopped mid-function with no notes. The second session, a fresh conversation two days later, had nothing to go on but the code itself: no note on what had been tried and abandoned, no explanation for a half-written parser. It spent the first forty-five minutes of a ninety-minute session rediscovering ground the first session had already covered, then quietly reimplemented a function that already existed under a different name, three lines away. Nobody caught the duplicate until code review.

Decide now: what would the second session have needed to read, on day one, to skip that forty-five minutes?

What You Do

Add "readability" to the repo so a new agent can quickly understand the project structure, know the current progress, and pick up work. Specifically: implement document import, document detail view, and local persistence, completed across two sessions.

You run it twice from the checked-in directories: first with the thinner starter workspace and no session-handoff.md, second against the solution shape that has expanded ARCHITECTURE.md, PRODUCT.md, and session-handoff.md.

The Rule This Project Tests

Use a written handoff artifact, session-handoff.md plus an ARCHITECTURE.md/PRODUCT.md worth reading, whenever a task will outlive one sitting or one agent conversation; skip the ceremony when a single session finishes the task end to end and nobody else will ever need to pick it back up. The five fresh-session questions from Lecture 03 (what / how organized / how to run / how to verify / where are we) are the test: if a task cannot answer all five from the repo alone, it needs the handoff before the next session starts, not after.

Situation	No handoff artifact	Written handoff artifact
Task finishes in one sitting, one session	Fine — nothing to hand off	Wasted effort maintaining a file nobody reads
Task spans two sessions, same person	Second session re-derives or duplicates the first session's work	Second session resumes from where the first stopped
Task spans sessions and people	Verbal context does not survive a shift change	The repo, not a person's memory, is the source of truth

Tools

• Claude Code or Codex
• Git
• Node.js + Electron

Harness Mechanism

Agent-readable workspace + persistent state files

Use the Checked-In Project

Suggested workspace: projects/project-02/ in your own practice repo. Build the layout below as you work.

Directory	What it contains	What to compare
starter/	Project 01 code plus incomplete document import, detail view, and persistence. The docs exist but are intentionally thinner, and there is no session-handoff.md.	How much rediscovery a second agent session does.
solution/	The same slice completed, with expanded docs under projects/project-02/solution/ (plus feature_list.json and session-handoff.md).	Whether a fresh session can resume from repo state without oral context.

The product features are document import, full document detail/content loading, and persistence across restart. The harness feature is the handoff-readable workspace.

Brief

The starting point is the checked-in starter/ directory: Project 01's app plus incomplete document import, detail view, and persistence, with only a thin ARCHITECTURE.md stub, no PRODUCT.md, and no session-handoff.md at all. You run two sessions against it, back to back, under one hard rule: the second session gets no verbal briefing, only what the first left in the repo.

Session A works starter/ for one sitting: implement as much of document import, detail view, and persistence as you get through, then stop deliberately mid-feature, before anything is finished.

Session B starts fresh, a new agent conversation, same repo, and must resume from whatever session A left behind. Before starting session B, run the fresh session test from Lecture 03 against the repo as session A left it: can a brand-new session answer what this is, how it's organized, how to run it, how to verify it, and where things stand? Write down which of the five it fails.

diagramsource

drawing

Then repeat both sessions against solution/'s workspace, which adds the expanded ARCHITECTURE.md, PRODUCT.md, feature_list.json, and session-handoff.md. Same two-session split, same fresh-session test, on the improved workspace.

Steps

Steps 1-4 are fully scripted, run them exactly as written so both workspaces get the same treatment. Step 5 asks you to reason out the comparison yourself before checking your answer. The stretch goal at the end gives you no script at all.

1. Run session A against starter/. Implement what you can of document import, detail view, and persistence in one sitting; stop mid-feature. Output: a working tree with partial progress, no state files written.
2. Score the handoff with the fresh session test. Before opening session B, list which of Lecture 03's five questions (what / how organized / how to run / how to verify / where are we) the repo can answer with no human explanation. Output: harness/p02-workspace-notes.md, section one — the failing questions.
3. Run session B against the same repo, no briefing. Watch what it correctly re-derives versus what it wastes time re-exploring. Output: a note of minutes spent rediscovering versus minutes spent building.
4. Repeat both sessions against solution/. Same task, same stop point, now with ARCHITECTURE.md, PRODUCT.md, feature_list.json, and session-handoff.md in place. Output: a second pass through the same fresh-session test, this time on the expanded workspace.
5. Write the comparison. Which questions flipped from fail to pass, and which artifact caused each flip. Output: harness/p02-workspace-notes.md, section two.

6. Stretch: run it cold on a task of your own (not graded). Pick a task you are working on that will genuinely take more than one sitting. Before the second session starts, write nothing but what you would naturally leave behind in the repo, no course template this time, then run the fresh-session test cold. Score yourself against the same five questions.

Acceptance

• Session A and session B are genuinely separate agent conversations, not one long session pretending to restart.
• Session B never receives a verbal summary of what session A did — only what is written in the repo.
• The fresh session test is run twice: once against the thin starter/ workspace, once against the expanded solution/ workspace.
• harness/p02-workspace-notes.md names which of the five fresh-session-test questions failed on starter/ and which artifact fixed each one in solution/.
• The note distinguishes rediscovery time (re-exploring known ground) from real work time.

Rubric

Criterion	Weak	Strong
Session isolation	Session B secretly benefits from session A's context in the same chat	Session B is a demonstrably fresh conversation with no memory of session A
Fresh session test	Run once, informally, no question-by-question record	All five questions checked explicitly, on both workspaces, with a pass/fail per question
Attribution	"The solution workspace was better," no specifics	Each fixed question traced to the specific artifact that fixed it (session-handoff.md, PRODUCT.md, etc.)
Rediscovery cost	Not measured, or estimated after the fact	Minutes spent re-exploring recorded during the session, not reconstructed from memory afterward

Key Takeaways

• Run the fresh session test before and after, not only once at the end.
• Give session B zero verbal briefing; only repo contents may carry context.
• Attribute each fixed question to the specific artifact that fixed it.
• Measure rediscovery time during the session, not from memory afterward.
• Treat session-handoff.md and PRODUCT.md as answers to named fresh-session questions.

What You Have Now

A workspace an unfamiliar agent can orient in without you narrating it. harness/p02-workspace-notes.md sits beside harness/repo-map.md and AGENTS.md from the previous module, and is the first hard evidence, not an assumption, that the map drawn there actually works on an agent that has never seen the project before. The next module's continuity work assumes this orientation already succeeds before adding session-to-session state on top of it.