Build packets
A build packet is one change to your code, from the reason for it to the pull request that ships it. Retain keeps the packet; your coding agent builds it. This page explains what is in a packet and how it moves from a design to shipped work.
What is in a packet
A packet has four parts, written in order. Each one builds on the one before.
- Proposal. Why the change is needed, what changes, and what is left out.
- Design. The decision, and how the work fits the code that exists.
- Requirements. What the finished change must do, written against your real code.
- Tasks. The steps to build it, ticked off as the build goes.
The proposal and the design are written first, by Retain from a meeting or by your coding agent from a conversation with you. Your coding agent writes the requirements and tasks when you start the build, because only it can read your code.
Where a packet comes from
- From a meeting. Ask Retain for a design after a discussion and attach the codebase it is for. Retain writes the proposal and design from what was said and from your code. Without a codebase it writes a single design document, not a packet. See From a meeting to a design doc.
- From your coding agent. Run /retain:explore to think a change through with the code open, then /retain:design to write it up. Nothing reaches Retain until both parts are valid.
The states a packet moves through
- Being written. Retain is still writing the design.
- Ready to build. The proposal and design are done. Nobody has started building.
- Planned. The agent has written requirements and tasks.
- Building. The agent is working through the tasks. The Work list shows the count, such as Building 12/25.
- Built. The tasks are done.
- Archived or Dropped. A finished packet you have filed away, or one you decided not to build. Both leave the live Work list and can be read later.
Start a build
Open the packet and select the Build tab. It shows what to type in your coding agent, ready to copy. In Claude Code:
/retain:apply your-packet-name
In Codex:
$retain-apply your-packet-name
The agent pulls the packet, writes the requirements and tasks against your code, sends them back to Retain, and then builds. You can run the command from any checkout of the repository.
Watch it from the Build tab
Once a build starts, the Build tab shows where it stands:
- Which agent is building, on which computer, and how recently it reported.
- The branch of each build, and a link back to the agent's session.
- The packet's pull requests, each with its number and whether it is a draft, open or merged.
- When the packet is built: the commits it covers, how many files changed, and any tasks left open.
Packets that depend on other packets
Some work has to land in order. A packet can name the packets it builds on, and the Build tab shows them under Depends on, with whether each is ready and why. The packets waiting on this one are listed under Needed by.
A dependency is ready once it has a pull request that is open, a draft or merged, or once it is built or archived. It does not need to be merged first: the agent stacks the new build on the open pull request's branch.
You don't manage dependencies by hand. When you write a design with /retain:design, the agent asks whether the change builds on another packet. To change it later, tell your agent in plain words, such as "make this packet depend on build-claims", and it updates Retain for you.
Choose what to build next
Run /retain:next and Retain picks the next packet for this repository, leaving out any that are waiting on a dependency or already being built by someone else. You confirm the pick, and the agent builds it in its own worktree.
Need help?
Can't find what you're looking for? Contact our support team for a quick reply.
Contact Support