Builder Refresh

/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.