/builder-refresh — save, clear, and come back knowing where you are
You are a builder that has reached a protocol boundary. Your context can be discarded
here safely, because everything that matters is already on disk: the spec, the plan,
status.yaml, your thread narrative, and git history. A fresh context re-orients from
those artifacts rather than from memory.
The enforcement is in the command, not in this document. afx self-refresh refuses to
clear on an unverified save, refuses when the re-entry cannot be scheduled, and refuses
when your worktree has uncommitted tracked changes. This skill sequences the steps and
explains the judgement calls; it cannot and does not decide whether the clear is safe.
When NOT to run this
Porch chooses the moment. You do not. Run this when porch's refresh task tells you to,
or when the architect directs it. Do not invoke it mid-task on your own judgement — a
boundary is a point a fresh context can resume from, and a mid-task snapshot resumes into
confusion.
If you are not at a boundary and think you need a refresh anyway, say so to the architect
rather than doing it: afx send architect "...".
The procedure
1. Use the commands porch gave you
Porch's refresh task contains the exact two commands for this boundary, including the
--boundary flag. Run those, verbatim.
Do not retype them from memory and do not omit the flag. --boundary binds the challenge
to the boundary it was issued at, so a challenge left behind by an aborted refresh cannot
be used to clear you at a later boundary, against a save describing work that has since
moved on. That guard has been silently disabled twice by an instruction that dropped the
flag, which is why this document deliberately does not restate the commands.
If you arrived here without a porch task — an architect-directed refresh, say — there is no
boundary to bind, and the flagless form is correct. Run afx self-refresh --help for the
exact spelling rather than guessing it.
2. Write your working state
The first command prints a save request naming a file and a marker line. Write that file.
The marker must be the FIRST LINE, reproduced exactly. A save whose nonce appears
further down is refused — that check exists because echoing the request back into the file
otherwise passed every gate, and echoing instructions is something agents do by accident.
Write for a cold reader — a competent agent that wakes up with your worktree, your
branch, and no memory of this conversation. Most of your state is already on disk, so do
not restate the spec or the plan. Carry only what the artifacts do not contain:
- receipts — what is done and verified, with paths and commit hashes, distinguishing
"written" from "verified";
- deviations from the plan, and why;
- flaky or skipped tests, and what you did about them;
- deferred work, and the reason;
- standing orders from the architect you are still bound by, including anything you
were told NOT to do;
- the next concrete action.
Pointers, not prose. The save has a minimum size, and it is not a word count to pad — a
file below it is indistinguishable from a stub. If you genuinely have less than that to
say, you are probably omitting receipts or standing orders.
3. Run the execute command, then stop
The second command verifies your save, writes a re-orientation to disk, schedules your
re-entry, and clears you — in that order, and only if every step succeeds.
Then end your turn. Do not start new work. The clear takes effect when the turn ends.
If it refuses
Most refusals happen before anything destructive, and those leave your context
untouched. One does not. Read which you got.
Pre-clear refusals — your context is intact
| Refusal | What it means |
|---|
| state file missing / too small / wrong nonce | Your save did not satisfy the gate — check the marker is on line 1 |
| worktree has uncommitted tracked changes | Commit first; a refreshed context re-orients from git, so uncommitted work is invisible to it |
| Tower is not running, or did not schedule the re-entry | Clearing would strand you, so it refused |
| challenge missing / already consumed / for a different boundary | Run the begin step again |
| invalid parameters | A flag is out of range — nothing was read or written |
| challenge could not be marked consumed | Nothing was cleared, but a re-entry is already queued and will arrive; ignore it. Retrying queues a second one |
For any of these: report it and carry on.
afx send architect "Context refresh refused at <boundary>: <the reason it printed>"
Then run porch next for your normal tasks. The refresh never blocks your work — the
boundary is recorded as consumed either way, so a failed refresh costs you some context and
nothing else.
clear-failed — you cannot assume anything
If the command reports that the clear was attempted but may still have landed, do not
treat that as a pre-clear refusal. Sending /clear can succeed on the wire and still report
an error, so from inside this turn it is genuinely unknown whether your context survives.
- A re-entry message is already queued and will arrive shortly. If your context was
cleared, that message is your re-orientation. If it was not, the message is harmless and
can be ignored.
- Do not start new work in this state.
- Tell the architect explicitly that the outcome is ambiguous:
afx send architect "Self-refresh clear-failed at <boundary> — clear may or may not have landed; re-entry is queued"
After the clear
A re-entry message arrives shortly, identifying itself as an automatic context refresh. It
carries your identity, protocol, project, worktree and branch, and points at
.builder-reorient.md — the full spawn-quality frame, on disk.
It will tell you to run porch next. Do that; porch's state is untouched by the clear and
its next task emission is your re-orientation.
If the re-entry never arrives, nothing is lost. .builder-reorient.md is on disk and
the architect can send you back with one message. Say so if you notice.
What this does not do
- It does not write
status.yaml. Only porch does, and the boundary is already recorded
there before you are asked to refresh.
- It does not decide whether to refresh. Porch decided that.
- It does not retry. A boundary is refreshed at most once, so a refusal means this boundary
simply does not get a refresh.