/arch-save — save state, clear, and come back as yourself
Long sessions accumulate stale context. This is the deliberate cure: you choose the
moment, you choose what survives, and a fresh session resumes from what you wrote.
$ARGUMENTS carries the architect name, a next task for the session that comes back,
or both:
/arch-save save, clear, re-init, then wait
/arch-save file and spawn that issue … and start on that first, unprompted
/arch-save main file and spawn that issue explicit name, then the next task
The next task is how an owner who already knows what the refreshed session should do first
says so once, at the moment they direct the refresh, instead of watching for the re-init to
land and typing it again.
When NOT to run this
On the owner's direction, or when the owner runs it themselves. Do not invoke this
autonomously mid-task on your own judgement — the irreversible step is a human decision,
relocated from "press /clear" to "invoke /arch-save", not removed. If the owner tells
you to run it, run it; if you think it is time, suggest it and wait.
Only at a resumable boundary — a gate approval, a PR merge, a completed investigation,
the end of a long tool-heavy stretch. Never mid-task. Nothing here can check that; the
state file must describe a point a fresh session can resume from, not a half-finished
action. A mid-task snapshot resumes into confusion.
The procedure
Do these in order. The order is the feature — step 3 must precede step 4, because the
context that knows what to write is the one about to be destroyed.
1. Resolve your name, then split off the next task
Always run afx whoami first, whatever $ARGUMENTS holds — the split below cannot
tell a name from a task until it knows your name. The name rules are unchanged:
type: architect → the reported name is yours.type: builder → STOP. This terminal is a builder. Report the mismatch.- Non-zero exit → you have no name yet. A single-token
$ARGUMENTS that validates as a
name is still accepted as one; anything else → STOP and ask which architect you are.
Do not guess, and do not default to main — writing another architect's state file
is the exact failure /arch-init exists to prevent (#1094).
Validate the name before building any path: [a-z][a-z0-9-]*, at most 64 characters.
Reject slashes, .., uppercase, spaces. Never interpolate an unvalidated name into
codev/state/<name>.md.
Then split $ARGUMENTS:
$ARGUMENTS is empty → name from afx whoami, and there is no next task.- The first whitespace-separated token equals the whoami name (or, when whoami could
not resolve one, is a single token that validates as a name) → that token is the name,
and the remainder is the next-task text, which may be empty.
- Otherwise → the whole of
$ARGUMENTS is the next-task text, and the name comes
from afx whoami.
So /arch-save and /arch-save main behave exactly as they always have. The one
ambiguity — a next task whose first word happens to be your own architect name — is
accepted rather than worked around: lead with the explicit name
(/arch-save main main is stalled, look at it) to disambiguate.
If you had to ask which architect you are, the next task still stands. The answer
supplies the name; $ARGUMENTS already supplied the task. Do not make the owner retype it.
Guard, applied after the split: a leading token that names a different architect stops
you. If the first token validates as a name, differs from the name whoami reported, and
codev/state/<token>.md exists → STOP and ask which architect you are. Write nothing.
whoami can be wrong (#1094), and rule 3 would otherwise bury a real name-override inside
next-task text and save to whoami's file; a task that merely opens with a sibling's name is
the only case this costs, and it costs one clarification.
This is not how /arch-init resolves a name, and the asymmetry is deliberate:
/arch-init takes no next task, so any non-empty argument there is unambiguously a name
and overrides whoami outright. Here the first token is weighed against whoami, which is
why the guard above exists — never save into a name you did not verify.
2. Stop your own monitors
Enumerate every monitor, watcher or background task you armed, and stop it.
This is the half that only you can do. Monitors are session-bound, not
context-bound: they survive /clear and keep firing into a context that cannot evaluate
their alerts. pgrep cannot see them — they are harness background tasks, not shell
processes — so the instance after the clear has no handle on them. You do. Use it.
3. Write the pruned state file
Rewrite codev/state/<name>.md. Pruning is part of the save, not polish afterwards — a
save that only appends has not done its job.
- Rewrite the current-state / open-loops section in place. Do not accumulate stale
"current state" blocks. Never leave two sections with the same heading — a duplicated
"How to resume" means you appended where you should have overwritten.
- Delete resolved loops outright. A closed item's record is the log entry, not a
lingering line in current state.
- Append one short dated entry for what changed this stretch.
- Collapse older entries into one-line summaries that point at durable artifacts — the
merged PRs, closed issues and reviews where the detail actually lives.
- Aim for one screen. If the file has grown past easy reading, prune as part of this
save rather than leaving it for next time.
Prune by pointer, never by deletion. These files are gitignored (.gitignore:15), so
there is no history to recover from — pruned prose is gone for good. Replace detail with a
pointer to something durable; never delete the only record of something. Copying the file
first (cp codev/state/<name>.md codev/state/.<name>.bak.md) is cheap insurance.
Content guardrails. No secrets — tokens, keys, credentials. No transcript dumps, no
raw tool output. Only: current focus, open loops, and what a fresh session needs to resume.
Write the next task into the banner, if step 1 produced one. Add a single line to the
banner block, directly after the ⭐ THIS /clear IS INTENTIONAL line:
# ⏭ NEXT TASK (owner-directed at save, 2026-09-19T02:10Z): file and spawn that issue
- Verbatim. Collapse newlines to spaces; do not paraphrase, expand, or "helpfully"
plan it. Those are the owner's words, and the context writing them down is the one about
to be destroyed — this is the last moment at which a paraphrase can be caught.
- New text replaces any existing NEXT TASK line.
- No new text preserves an existing one. A NEXT TASK line still in the banner means the
previous cycle never came back to pick it up; dropping it silently would lose an owner
instruction that nothing else is holding. Mark it carried over when you preserve it:
append
[carried over — gloss orients only; re-confirm before acting] to the line (once;
a line already marked stays as it is). A gloss carries the owner's word only for the
cycle that wrote it.
Then resolve its referents — resolve, don't plan. After the clear, "them" points at
nothing; this context is the only one that knows what the owner meant. So pin every
referent in the owner's words to a concrete, durable identifier, and append it to the same
line, after the verbatim text, as a [resolved at save: …] gloss:
# ⏭ NEXT TASK (owner-directed at save, 2026-09-22T13:40Z): merge them all [resolved at save: PRs #1710, #1712, #1715]
- Every referent. Pronouns and deictics — "them", "that issue", "his PR", "the failing
one" — become PR numbers, issue numbers, builder ids, branch names, file paths.
- Resolution only. The gloss names what, never how: no steps, no ordering, no
caveats, no "after CI is green". A gloss that contains a plan has overstepped; the
resumed session plans.
- No referents → no gloss.
/arch-save review PR #1712 needs nothing; write the line
as above without one. Never add an empty or redundant gloss.
- Cannot resolve → do not clear. If any referent is ambiguous or unknown to you,
stop before step 4 and ask the owner which items are meant. Clearing with an
unresolved task destroys the only context that could have answered. This is the one
case where
/arch-save may pause its own cycle — it is cheap, and the alternative is a
wrong merge. Tell the owner your monitors are already stopped (step 2), and on their
answer resume from here: write the gloss, then continue to step 4.
The gloss is more than orientation: /arch-init treats the items it names as approved for
the act the owner's words name, so it is how the owner's word survives the clear.
Use the template at the end of this document.
4. Clear
afx send architect:<name> --raw '/clear'
architect:<name>, never bare architect. For a non-builder sender the bare form
resolves to main, or to the first registered architect — so a sibling architect
running this would clear main's terminal instead of its own. That destroys the context
of someone who never asked for anything, and it is one word away from correct.
--raw, never the escape channel. The escape route writes a bare ESC and discards the
message body, so /clear sent that way delivers an interrupt: the command appears to
succeed and nothing is cleared.
5. Schedule the re-init
afx send architect:<name> --delay 15 --raw '/arch-init <name>'
Tower holds this for 15 seconds and then delivers it. It has to come from outside the
session, because the clear destroys the context that would otherwise send it.
Tower does not know whether the clear landed — it waits out a delay, it does not
observe the result. 15 seconds is a value chosen because it works in practice, not a
guarantee about the clear's completion. If the timing is wrong the re-init arrives at the
wrong moment, which costs one manual message (see below) and nothing else. That is the
whole reason this cycle can be built on a delay rather than on machinery.
Delayed sends are persisted. The body is written to the durable mailbox at request time
with a not_before timestamp, so Tower keeps no timer for it and a restart inside the window
does not lose it — the re-init is delivered once the delay passes. The one thing a restart does
drop is the Ctrl+C nudge of a delayed --interrupt, which this cycle does not use.
That removes a failure mode this section used to warn about, but not the need for the recovery
path below: delivery still waits on an empty prompt, so a re-init can arrive late rather than
never.
If this send fails, do not end your turn. Step 4 queued the /clear, but it does not
take effect until your turn ends — so at this moment you still have your full context and
the failure is recoverable. Retry the send; if it keeps failing (Tower down, for example),
tell the owner that the clear is queued with no re-init scheduled, and give them the
command to send by hand once Tower is back. Ending the turn here is the one way to turn a
recoverable failure into a cleared session nobody is coming back for.
6. Stop
Do not start new work. End your turn so the clear can take effect.
After the clear
/arch-init will read your state file and resume. Two things it should do first, in this
order:
- Reconcile monitors. You stopped yours in step 2, but treat any alert you cannot
account for from the state block's monitor list as stale — disregard it, and stop
it if you can. An alert from a decommissioned target is indistinguishable from a live
one.
- Then re-arm the monitors the block lists, and let each one self-test once before
trusting its alerts. A freshly-armed monitor's first alert has been a false positive in
practice.
If /arch-init never arrives
Nothing is lost. The state file is on disk, the terminal is alive. Send it by hand:
afx send architect:<name> --raw '/arch-init <name>'
This is the recovery the whole design leans on, which is why the cycle can accept imprecise
timing rather than needing machinery to guarantee it.
If the clear did not take effect — you still have your full context and a stray
/arch-init arrived — nothing was destroyed. Check whether /clear was submitted as its
own message rather than merged into another one, and report it; a /clear that arrives as
literal text on the front of the next message never executes.
State block template
The structure below comes from a live run of this cycle. Every element earns its place;
keep them all, including a MONITORS: line even when the answer is "none armed" — an
omitted monitor list is indistinguishable from a forgotten one. The NEXT TASK line is the
single exception: it appears only when there is one.
# <lane> architect — state (vNN, <date> ~HH:MM UTC — <milestone>, DELIBERATE /clear cycle)
# ⭐ THIS /clear IS INTENTIONAL (owner-directed context refresh). On re-init: normal
# /arch-init flow, then:
# ⏭ NEXT TASK (owner-directed at save, <ISO timestamp>): <the owner's words, verbatim> [resolved at save: <referents>]
# — OPTIONAL; present only when the save carried one. The `[resolved at save: …]` gloss
# is optional too: present only when the words had referents to resolve. /arch-init
# starts here before the agenda below, then deletes this line and logs the pickup.
# 1. MONITORS: <what to stop if it is still firing, then what to re-arm> — watch target,
# cadence, alert pattern. Self-test once before trusting alerts. ("none armed" is a
# valid and complete answer.)
# 2. DONE pre-clear, with receipts: <PR> MERGED (<sha>, verified on origin/<branch>);
# <branch> PUSH-VERIFIED (<sha> local==origin). Distinguish "written" from "verified" —
# a cold reader cannot tell.
# 3. ACTIVE LANES: <builder-id> = <workstream> (<brief file on disk>; <standing rule>).
# Name the file, so no instruction lives only in the context being destroyed.
# 4. LATEST RESULTS: <the decision-relevant numbers>, so the first post-resume decision
# needs no archaeology.
# 5. QUEUED, with ordering: <item> — WAITS for <verdict>; <item> — <when>.
# 6. ENVELOPE: <standing authorization that survives>; <what expired with the completed
# work>.
Guardrails (architect-wide)
- Never auto-approve porch gates. A gate notification is for the human, not you.
- Touch only your own builders / spawns / filings.
- Never
cd into a builder worktree; use git -C and absolute paths.
- Stay on the default branch at the workspace root.