Skip to content
Skills Library
AI & agents · Automation

builder-refresh

/builder-refresh

Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.

Repository
codev ↗
Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.

Triggers from the description

refresh your contextrun a self-refresh

Arguments

/builder-refresh (none — porch's refresh task supplies the commands)
Original author description

Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.

How it works

  1. When NOT to run this
  2. The procedure
  3. If it refuses
  4. After the clear
  5. What this does not do
Original SKILL.md headings · 134 lines, 1,124 words
SKILL.md preview
---
name: builder-refresh
description: Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.
argument-hint: "(none — porch's refresh task supplies the commands)"
---

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

```bash
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:

```bash
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.

Versions

The database has no other skills named builder-refresh.

Identical content appears in 3 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 8bb5b2707511 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100arch-save
    Save an architect's state, clear its context, and re-init automatically — the packaged save→clear→re-init refresh cycle. Use when the owner directs a context refresh, or says "/arch-save", "save and clear", "refresh your context". Runs on the owner's direction; an architect does…
  • 96context-management-context-save
    Use when working with context management context save
  • 100context-management-context-save
    Capture and serialize project state, architectural decisions, and working context. Use when preserving knowledge for later sessions, handoffs, or searchable context retrieval.
  • 100save-clear
    End-of-session ritual. Saves persistent memory and a verified SESSION-SUMMARY snapshot, arms the auto-resume, and (in "save and clear" mode) clears the context by itself so the next session starts from the summary. Use whenever the user says "save and clear", "save-clear",…
  • 96context-management-context-save
    Use when working with context management context save
  • 96context-management-context-save
    Use when working with context management context save

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.