updated 7 September 2026
25 pages · 6 sections
questions: Discord ↗
Masterplans and stacks
A masterplan is a card that splits a job into subcards, runs them itself and tracks them on the board. It is the shape for anything too big for one session to hold in its head, and the only card type that owns other cards.
When to use one
Masterplan is a card type: pick it from the CARD TYPE tiles at capture, or file the card with --type master. Its difficulty is an ordinary rung (easy, normal, hard or very hard), chosen and read exactly as any other card's, and it is what decides the model the masterplan itself plans and integrates on. Use it for a migration that touches every service, a feature that lands in three repositories, or any job whose plan would otherwise be a list of other cards.
How it runs
| Stage | What the masterplan does |
|---|---|
| Prepare | The plan is the set of subcards. The masterplan's agent files the ones that are missing, writes each body as the brief its worker will read, and sets a difficulty on each: the hardest rung for anything that decides behaviour, an easy one for mechanical steps. It records which subcards wait on which. You approve that set. |
| Doing | The masterplan runs each subcard as a subagent on the model and effort the subcard's difficulty resolves to, in the masterplan's own worktree. Subcards that do not wait on each other run at the same time: Grid works the waits out into waves and hands the masterplan the order, and the masterplan starts every card in a wave in one turn rather than one after another. A subcard runs only after the cards it waits for are closed, and two subcards that edit the same files never run at once. Each subcard is one builder subagent that runs only the tests of the files it changed; there is no reviewer and no full project check per subcard. The full check, a reconciliation pass over the subcards against each other, and the adversarial review all run once, after the last subcard closes. The masterplan keeps its own model for planning and for integrating what comes back. |
| Review | One review for the whole job. The masterplan has written what changed into each subcard and the summary into its own body. |
| Verify and Closed | The masterplan's branch is the one that lands. Its subcards close with it. |
A masterplan cannot move on to Review while any of its subcards is still open. The board refuses the move and names the subcards that are still running.
Closing is the exception, and it goes the other way: closing a masterplan closes every subcard of its own that is still open, whether you drop it on Closed or its own agent writes the close. Each one gains a section saying it closed with its masterplan and which stage it was in, so a subcard reading Closed never quietly claims its own work was finished, and the masterplan gains a section listing what closed with it. Nothing is closed by a move that did not land: a close the board refuses for some other reason leaves every subcard where it was.
Subcards never sit behind their masterplan while it is in Prepare or Doing. A subcard is filed into Inbox, so the moment the masterplan is in Prepare every subcard still in Inbox moves to Prepare with it, and when the masterplan is in Doing every subcard in Inbox or Prepare moves to Doing. A subcard that is already further on, or closed, is left where it is. The inbox stays what it is for: cards nobody has looked at yet, rather than a masterplan's plan waiting to be worked.
Subcards
A subcard is a real card on the board with its own stage, so you can watch the job come apart and go back together. What it does not have is a session of its own: the masterplan that owns it does the work, writes what changed into the subcard's body, ticks its tasks and closes it. A question raised while a subcard is being worked is raised on the masterplan's card, and its model and effort come from the subcard's own difficulty.
The masterplan files subcards from the terminal, and you can file one by hand the same way:
grid card new "Move secrets to per-site stores" \
--type sub --parent <masterplan-ref> \
--difficulty hard --blocked-by <ref>
The parent is written into the subcard's parent_card front matter. Subcard is not offered on the capture sheet, because a subcard without a parent has nothing to run it.
On the board
Subcards fold into a stack under their masterplan's tile, with a strip that says how many are in this column. Because they follow the masterplan into Prepare and Doing, the whole plan usually sits in one stack. Open the stack to see each one at its own stage. Anything a subcard needs from you rolls up to the masterplan's tile, so the stack never hides a question.
Difficulty, not model
The masterplan's agent chooses only a difficulty per subcard. Grid resolves the model and effort from the workspace table, the same way it does for every other card, so a change of compute budget moves every subcard with it. See Difficulty and models.
Subcards run in the masterplan's worktree instead of trees of their own, and a masterplan's subagents are visible in the session's own transcript rather than as separate agents on the Agents page.