Plan your reading list.

In Part 1 you got the starter running. Nothing gets built in this part. You’ll write down what a person does with the app and what they see after each action, then save that plan where your agent can read it.

Why plan a small app

An agent will build whatever you ask for, including the parts you never thought about. If you say “make a reading list”, it has to guess whether removing a book asks for confirmation, whether an author is required and what an empty list looks like. It will guess confidently, and you’ll discover its choices one surprise at a time.

A plan replaces those guesses with your decisions. It also gives you something to check the result against: when the agent shows you its work, you can compare it with the steps you wrote, and you’ll know whether a difference is a mistake or an improvement. A plan for an app this size fits on one page.

1. Write the main flows

A user flow is the sequence of steps a person takes to get one thing done, together with what the app shows them along the way. Our reading list has four main flows.

Before reading further, try writing the Add flow yourself, in a note or on paper. Start from the moment someone decides to add a book and finish when they can see it in their list. Write what the person does and what they see, not how the app works inside.

A version might read:

1. I choose Add a book. A form opens.
2. I type a title. I can also add an author, a note and a reading status.
3. I choose Add to library. The form closes and my book appears in the list.

Writing even this much raises useful questions. Which details are required? The starter’s brief, in docs/brief.md, says only the title is. What status does a new book start with? “Want to read” is a sensible default, since most books are added before they are read. These are product decisions, and they are yours to make.

Now write the other three in the same way: View (what does the list show for each book, and how do you find one among fifty?), Edit (how do you correct a typo or mark a book as finished?) and Remove.

2. Decide what happens when it goes wrong

The steps above describe everything going well. Much of an app’s quality comes from the moments that don’t, so ask of each flow: what could the person do by mistake?

• They submit the form with no title. The app should keep the form open and explain that a title is needed. It should not add a blank book.
• They remove the wrong book. Asking “Are you sure?” every time soon becomes a button people press without reading. Our brief takes a friendlier approach: the book is removed immediately, and an Undo option brings the most recent one back with all its details.
• A search matches nothing. The list should say so, otherwise an empty screen looks like lost data.
• They open the app for the first time. An empty list should explain how to add the first book.

You don’t need to find every case. Finding a few now means you’ll recognise them later, and they become the basis for the tests in Part 6.

3. Sketch the screens

A rough mockup shows what each screen must contain. It doesn’t need colours, real text or neat lines, and it doesn’t need a design tool: a pen and the back of an envelope are enough. The starter already supplies the visual style and Pip, the mascot, so the sketch is about content and position only.

This app needs two screens: the list, and a form that opens over it for adding and editing.

Walk through your flows with a finger on the sketch. To add a book, is there a button to press? After removing one, where does Undo appear? If a step in a flow has nowhere to happen on the sketch, something is missing from one of them. This takes a minute and regularly finds a forgotten button.

4. Agree the plan with your agent

Now bring the agent in, as a reviewer of your plan. Open the project as you did in Part 1. Copy this prompt into the chat box, replace the bracketed last line with your four flows, then send it:

Read CLAUDE.md, docs/brief.md and docs/epics/02-plan.md. Follow that epic. I have drafted the main user flows for this app and will paste them below. Compare them with the brief: tell me what the brief requires that I missed, and what I included that the brief leaves out. Ask me what should happen when something goes wrong in each flow. Do not write or change any application code. When we agree, save the flows to docs/flows.md in plain language and show me the file.

My flows:
[paste your four flows here]

The prompt is bounded on purpose. It names one epic, says what to produce and says what not to touch. The agent may point out things from the brief that you left out, such as search, filtering by status or the example books a new visitor can choose to load. Decide whether each belongs in your flows. If you think of something the brief doesn’t include, such as book covers, ask the agent to list it under “Later ideas”. Keeping the first version small is what makes it finishable.

Read docs/flows.md when the agent has written it. Your agent’s file viewer can open it, and it is ordinary text. If a step doesn’t say what you meant, say so and have it changed. From now on the agent will read this file before building, so its wording matters more than anything you said in the conversation.

FAQ

Next: How your reading list works.