/arch-init — become architect <name> and recover state

You are an architect agent in a codev workspace. This command tells you which architect you are and where your durable state lives, so you can resume mid-stream.

$ARGUMENTS is the architect name (e.g. main, or a sibling architect's name in a multi-architect workspace).

What to do

1. Resolve your name.

   • If $ARGUMENTS is non-empty, that is your name — the human named you explicitly, which removes all identity-resolution risk. Validate it first: an architect name must match [a-z][a-z0-9-]* and be at most 64 characters (lowercase letters, digits, hyphens; starts with a letter). Reject anything else — slashes, .., uppercase, spaces — and tell the human the rule. Never build a file path from an unvalidated name (path-traversal guard).
   • If $ARGUMENTS is empty, run afx whoami and read its output:
     • type: architect → adopt the reported name.
     • type: builder → STOP. This terminal is a builder, not an architect; report the mismatch to the human and do not adopt an architect identity.
     • Non-zero exit (identity unknown) → STOP and ask the human which architect you are. Do NOT guess, and do NOT default to main — adopting the wrong identity and writing to another architect's state file is the exact failure this command exists to prevent.

2. Read your state file: codev/state/<name>.md (relative to the workspace root).

   • If it does not exist: list the architect state files in codev/state/ — excluding *_thread.md files, which are builder thread logs that share the directory — tell the human the file is missing, and ask whether to start a fresh state file for <name>. Do not fabricate state.
   • The state file is authoritative free text. It typically opens with a role banner and may carry resume instructions; follow whatever it says.
   • Architect state files are per-person and gitignored (codev/state/*.md); never commit them. Builder *_thread.md files are the opposite: versioned, shipping with each builder PR.

3. Confirm identity + orient. In one tight block, report: who you now are (name + one-line role from the banner, if present), the file you read, and the current-state / open-loops summary from the most recent dated section (or the file's leading content if it has no dated sections). If the banner carries a NEXT TASK line, report both halves of it, as Next task from the owner at save time: <verbatim> → resolved: <gloss> (omit → resolved: … when the line carries no [resolved at save: …] gloss).

4. Start on the next task, if the banner carries one. It is the first action of the resumed session, ahead of the general resume agenda — the owner wrote it at save time precisely so it would not have to be typed again once you came back. Begin it without waiting for a further prompt.

   • It carries the owner's authority the way any owner message does, with the standard limits unchanged. A next task never by itself approves a porch gate, merges a PR, cuts a release, restarts Tower, or performs any other act that needs a per-occasion word. If the next task is such an act, prepare it and ask for the word live: a saved instruction is an instruction, not a pre-spent approval.
   • The gloss carries the word — for the items it names, and only them. Items named in a [resolved at save: …] gloss are approved for the act the owner's words name: "merge them all [resolved at save: PRs #1710, #1712]" means merge #1710 and #1712 without asking again. The owner gave the word at save time, and the saving session pinned it to those items. This narrows the rule above; it does not remove it — and a line with no gloss pre-approves nothing:
     • The act must be the one the owner's words say. A gloss never widens the verb — "merge" does not also approve a release.
     • Anything not in the gloss still needs the word live. A PR that appeared after the save, an item the gloss did not name, a gate the words did not mention → prepare and ask, exactly as above.
     • Porch gates are still relayed to the builder, never run by you: the gloss lets you relay the approval without re-asking; it does not change who runs porch approve.
     • Ordinary verification still applies: an approved merge still waits for green CI, and a gloss item you find already merged, closed, or changed is reported, not forced.
     • A line marked [carried over — …] is orientation only. Its gloss was written by an earlier cycle and carries no word: ask for it before any gated act.
   • This does not narrow the gate rule. The human decision was explicit at save time, and the gloss is its record. What the rule forbids — inferring approval from a gate notification, from silence, or from an agent's own judgment — stays forbidden; a gloss is none of those.
   • Once you have started, delete the NEXT TASK line from the banner and record the pickup as a log entry (picked up next task: <verbatim> → resolved: <gloss>, omitting → resolved: … when there was no gloss). A second re-init, or the next /arch-save, must not re-run it.

5. Then follow the state file. Carry out whatever it says to do on resume. Do not invent a new agenda — resume the one the state file describes.

Saving your state (and knowing when to /clear)

Recovery is only half the loop. /arch-init reads state; you write it. The state file is not crash insurance — it is your deliberate memory-management mechanism. Auto-compaction happens at an arbitrary moment with content you did not choose; a state save happens at a boundary you pick, with a summary you curate. That is strictly better, so use it:

/arch-init (recover) → work → save at a checkpoint → refresh → /arch-init (recover) → …
                                                       │
              packaged:  /arch-save  ─────────────────┤  stops monitors, saves, clears,
                                                       │  schedules /arch-init
              manual:    suggest /clear → human clears ┘  then human runs /arch-init

When to save. Save at a resumable boundary — a point a fresh session could pick up cleanly from. Good moments, judged by you: a gate approval, a PR merge, a completed investigation, the end of a long tool-heavy stretch. Never save mid-task. The state file must describe a point you can resume from, not a half-finished action; a mid-task snapshot resumes into confusion.

How to save (write format = read format). Recovery reads the role banner plus the most recent dated section, so a save must leave exactly that behind:

1. Rewrite the current-state / open-loops section in place — overwrite it with where things actually stand now (current focus + open loops + how to resume). Do not accumulate stale "current state" blocks, and never leave two sections with the same heading (a duplicated "How to resume" or "Open loops" means you appended where you should have overwritten). Delete resolved loops entirely — a closed item's record is the log entry, not a lingering line in current state.
2. Append one short dated log entry capturing what changed this stretch.
3. Compact — this is part of the save, not optional polish. Every save both adds AND removes: after writing, keep the recent dated log entries in full and collapse older ones into a single one-line summary that names where the detail lives (the closed PRs, issues, and reviews it covered). Remember these state files are gitignored — there is no git history to fall back on, so pruned prose is gone for good. Prune by replacing detail with pointers to durable artifacts, never by deleting the only record of something. The file is a summary a fresh session reads at a glance — one screen is the right order of magnitude, judged by you. If a save has grown it past easy readability, prune as part of that save rather than leaving it for next time.

Content guardrails. No secrets (tokens, keys, credentials). No transcript dumps or raw tool output. Include only: current focus, open loops, and the instructions a fresh session needs to resume.

Then — and only then — suggest the refresh. Save first, then tell the human it is a good time to clear. You must never decide unilaterally to lose your context; keeping the irreversible step behind a human decision means accepting the suggestion can never lose anything, because the save already happened. Make the suggestion advisory, never nagging, and only right after a save — e.g.:

State saved to codev/state/<name>.md — good time to refresh if this session is feeling heavy.

Do not repeat it, and do not prompt for it at any other time.

/arch-save packages this whole loop, and is the preferred path when the owner directs a refresh: it stops your monitors, writes the pruned state file, clears, and schedules /arch-init to bring you back — in that order, which is the part that matters. It also accepts a next task as free text (/arch-save file and spawn that issue), which it writes into the banner as a NEXT TASK line for step 4 above to pick up. The save discipline above is what it performs at its step 3, so this section remains the source of truth for how to write the file; /arch-save is the source of truth for the sequence. The manual path (save → human clears → /arch-init) stays valid and is the fallback when Tower is unavailable.

Guardrails (architect-wide; the state file may add more)

• Never auto-approve porch gates. A gate notification is for the human, not you.
• Touch only your own builders / spawns / filings. Sibling architects own theirs.
• Never cd into a builder worktree; use git -C + absolute paths.
• Stay on the default branch at the workspace root; verify with git branch if unsure.