How to write a plan file a coding agent can finish

Last updated 2 November 2026 · Gravity Control

A coding agent finishes a goal when each step is one small, checkable line in a plain Markdown file. Write the goal at the top, one checkbox per step, mark what blocks, and keep a short Now block that says where the work stands.

This is the format Gravity Control reads. It also works when you drive the agent yourself: the agent reads the same file and knows what to do next.

Why a file, and not a chat message?

A chat message lives in one session. When the session ends, runs out of context or restarts, the plan is gone. A file in the project stays. Every new session reads it, and every finished step leaves a tick and the evidence next to it.

A file also lets a tool see the state. Gravity reads only the unticked checkbox lines, so it knows which step is next without reading the conversation.

What goes at the top?

Start with the goal in one heading, then a ## Now block of at most 15 lines:

the current item,
what blocks it, if anything,
the next step.

The agent reads this block first, so it never has to re-read the whole history to find its place.

How small is one item?

One item is one change that you can check: a test passes, a page answers 200, a pull request is merged. "Improve the app" is not an item. "Add CSV export to the orders page, with a test" is.

A good test: could someone else tick this line from a command output or a URL? If not, split it or make it sharper.

How do you mark what blocks?

Most stalls happen because the agent keeps trying a step it cannot do. Mark those steps so they are skipped:

- [ ] Item 2: export as CSV
- [ ] [blocked: NEED API key] Item 3: sync to the CRM
- [ ] NEED: test on the phone
- [ ] [wait: CI 39406535793] Item 4
- [ ] [wait until 2026-10-21T07:30Z] Item 5: compare 24 h of logs

Mark	What happens
`- [ ]` with no mark	Open. The first open item goes to the agent.
`[blocked: reason]`	Skipped. The reason shows in the status.
`NEED` at the start	Skipped. It is a task for you, not for the agent.
`[wait: CI …]`	Skipped until CI is done.
`[wait until ISO-UTC]`	Skipped until that time, then the agent wakes.
`- [x]`	Done.

With these marks, a blocked step never stops the whole plan. The agent moves on to the next open line.

How do you tick an item?

Change [ ] to [x] and add the evidence on the same line:

- [x] Item 1 — DONE 2026-10-19: PR 12 live

Never delete a done line. The ticks are the history of the goal, and the evidence lets you check the work later in seconds.

What about failed attempts?

Log each attempt as one line under an ## Attempts heading: the approach, the result and the evidence. When the same approach fails twice, the next attempt must be different. The log makes that rule easy to follow, for the agent and for you.

FAQ

Does the plan need a special tool? No. It is plain Markdown in your repository. Any agent that can read files can follow it.

How many plans can one project have? As many as you like. Gravity keeps a queue of plan files per project and sends the first open item of the first plan that has one.

Where do tasks for me go? As NEED lines, in the plan or in one shared list. When you tick one, the blocked step can continue.

Try it

Gravity Control watches your coding agents on your own machine and sends the next open item when an agent stops. Gravity is in a private beta, and the free plan covers one device. Sign in to the control room or read how Gravity works.