# Incremental Sessions

Course: [Harness Engineering](https://www.devtutorials.ai/learn/harness-engineering) · Section: Long-Running Work
Source: https://www.devtutorials.ai/learn/harness-engineering/long-running/incremental-sessions

> Why an agent that does too much in one session runs out of room mid-feature and leaves a broken build, and how one feature per session plus a clean exit (green tests, a commit, nothing half-done, a progress note) keeps every session ready for the next.

## Small Steps, Clean Stops

The project now has a feature list, an `init.sh` script and a progress file.

The agent knows what to build. It knows how to start the app.

But nothing tells it how much to do in one session. So it does as much as it can.

**Incremental sessions** = each session does one small piece of work and then stops cleanly.

For example:

- In the React Taskboard, one session builds `filter`. The next one builds `search`.
- In the ASP.NET Core Pricing API, one session builds `List`. The next one builds `Filter`.

Each session ends with green tests, a commit and a note.

### A Real-World Example

Think about painting a house over several weekends.

One painter tries to do three rooms in one Saturday. At sunset, he is halfway through the third room.

The paint tins are open and the brushes are wet.

Next Saturday starts with an hour of cleaning up.

Another painter does one room each Saturday. She finishes it and closes the tins.

She writes a note: "Kitchen done. Next: bedroom." Next Saturday, she starts painting straight away.

Agent sessions work the same way:

1. Do **one** piece of work in each session.
2. **Clean up** before you stop.

Click the button and open the **Sessions & App** tab.

- **Session 1:** it builds two features and starts a third. Then it runs out of room.
- **The end of session 1:** the build is broken. Nothing is committed.
- **Session 2:** it must fix the half-done file before it can start new work.

**Simple lesson:** an agent that does too much in one session leaves a mess for the next one.

## What You Will Learn

In this lesson, you will learn:

1. Why a session can stop in the middle of a change.
2. Why "one feature per session" keeps every session small enough.
3. What a clean exit is.
4. How to write both rules for the Taskboard and the Pricing API.
5. How to check a session's exit against a checklist.
6. How this fits task scheduling for a team.

**Lab vs real tools**

- The lab's agent is simulated, so it does the same thing every run. That is how your work can be checked.
- A real agent is less predictable. Try each idea on your own project too.

## Why Sessions End With Work Left Over

### The Session Budget

**Session budget** = how much work fits in one session before it ends. In this lab, it is a fixed number of steps.

Every step uses some of it:

- reading the feature list
- starting the app
- reading code, editing files
- running the tests

In this lab, the session ends when the budget is used up.

Real tools rarely stop in the middle of an edit. But a session still ends: you close it, it hits a limit, or the chat gets compacted and loses the thread.

Whatever ends it, unfinished work is left behind.

Step through all three frames.

- **Frames 1 and 2:** what session 1 leaves behind, greedy and clean.
- **Frame 3:** session 2's first steps after each one.

**Simple lesson:** a clean exit costs a few steps now and saves many in the next session.

## One Feature, Clean Exit

### Rule 1: One Feature per Session

"Work on one feature per session" keeps each session well inside its budget.

The agent finishes one thing completely. It does not do three things partly.

This can feel slow, but it is not. Five finished features beat three half-features and a clean-up.

### Rule 2: A Clean Exit

**Clean exit** = the session stops with the project ready for the next session.

A clean exit has four parts:

1. **Tests green.** Run `pnpm test` or `dotnet test`. They must pass.
2. **Committed.** Now `git log` shows what was done.
3. **Nothing half-done.** No file is left in the middle of a change.
4. **Note updated.** A short entry goes into `progress.md`.

Here are both rules for each project:

```markdown
- Work on one feature per session.
- Before you stop: run `pnpm test`, commit, and append what you did to progress.md.
```

```markdown
- Work on one feature per session.
- Before you stop: run `dotnet test`, commit, and append what you did to progress.md.
```

**Name the real test command.**

"Run the tests and commit" is vague.

"Run `pnpm test`, commit" tells the agent exactly what to type.

### Watch Both Runs

Here are the greedy run and the clean run, session by session:

Step through all five frames.

- **Frame 1:** the greedy run. No session ends clean.
- **Frame 2:** session 2 opens on a red build. It fixes `sort` first.
- **Frame 3:** the new lines in the rules file.
- **Frames 4 and 5:** the clean run. Every session builds one feature and commits.

### Check Each Exit

You can check any session with the same four questions.

Step through all three frames.

- **Frame 1:** the greedy session. All four checks fail.
- **Frame 2:** one feature, but no exit rule. The tests pass, but nothing is committed.
- **Frame 3:** both rules. All four checks pass.

### Lab Exercise: One Feature, Clean Exit

Add the two rules lines to the rules file:

1. Work on one feature per session.
2. Before you stop: run the tests, commit, and append a note to `progress.md`.

Click the button, add the lines, then press **Check my harness**.

- **The check:** it runs 5 sessions on each of 3 versions. That is 15 sessions.
- **To pass:** every session must end with green tests and a commit.
- **And:** no session may redo work, and all 5 features must be built.
- **After the check:** open the Terminal tab and type `git log --oneline -5`. Each clean session left one commit.

**Simple lesson:** both rules are needed. Either one alone fails the check.

## Task Scheduling Across Sessions

### One Feature Is One Task

The feature list is the plan. One session is one work slot.

"One feature per session" means each slot gets one task.

A team uses the same idea on a task board. Each person takes one card at a time and finishes it.

For a team, the `owner` field from **Feature Lists** tells each session which items are its own.

### Frontend and Backend Sessions

What does "one feature" mean in each project?

- **React Taskboard:** one file in `src/features/`, one import line in `src/App.tsx`, and a green `pnpm test`.
- **ASP.NET Core Pricing API:** one file in `Pricing.Api/Features/`, one `app.Map<Id>();` line in `Program.cs`, and a green `dotnet test`.

Small, finished pieces are also easier to review. A reviewer reads one commit for one feature.

**Never stop on a red build "just for now".**

The next session does not know it was "just for now".

It only sees a broken project. It has to spend steps to fix it.

**Simple lesson:** small commits are easy to check and easy to undo.

## TL;DR

1. **Session budget** = the steps one session can use. When it runs out, the session stops mid-change.
2. **One feature per session** = finish one thing, then stop. One fits. Three do not.
3. **Clean exit** = tests green, committed, nothing half-done, note updated.
4. **Messy exit** = the next session pays for the clean-up from its own budget.
5. **Task scheduling** = one task per session, picked by need or by owner.

## Common mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| No limit per session | "More work per session is faster." | One feature per session. | The session runs out of room mid-feature. |
| No exit rule | "It will clean up by itself." | Test, commit and note before stopping. | The next session starts on a broken build. |
| Vague exit rule | "Run the tests." | "Run `pnpm test`" or "Run `dotnet test`". | The agent guesses the wrong command. |
| Only one of the two rules | "One feature is enough." | Limit the work and close the session. | Green tests, but nothing is committed. |
| No commit | "The files are saved anyway." | Commit every finished feature. | `git log` shows nothing, so work gets repeated. |
| Red build "for now" | "The next session will fix it." | Never stop on a failing build. | The next session spends its budget on clean-up. |

## Check Your Understanding

## Exercises

These exercises practise one feature per session and a clean exit.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- A session stops when its budget is used up, even in the middle of a change.
- Ask for one feature per session. One fits. Three do not.
- A clean exit is green tests, a commit, nothing half-done and a note in `progress.md`.
- You need both rules. Either one alone still leaves a mess.
- Name the real command: `pnpm test` for the Taskboard, `dotnet test` for the Pricing API.

## Further Reading

- [Effective harnesses for long-running agents, by Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): one feature per session, and leaving the project in a clean state with a commit and a progress note.
- [Harness engineering for coding agent users, on martinfowler.com](https://martinfowler.com/articles/harness-engineering.html): guides and sensors that keep agent work on track.
- [awesome-harness-engineering, by walkinglabs](https://github.com/walkinglabs/awesome-harness-engineering): more patterns for long-running agents.

Next: **End-to-End Testing**. Green unit tests can still hide a feature that is never turned on in the running app.