@cluesmith/codev 3.2.3 → 3.3.0

package/skeleton/.claude/skills/arch-save/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: arch-save
+description: 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 not invoke it autonomously mid-task. Counterpart to /arch-init, which recovers the state this writes.
+argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+---
+
+# /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` is the architect name (e.g. `main`). Omit it to auto-detect.
+
+## 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
+
+If `$ARGUMENTS` is non-empty, that is your name. Otherwise run `afx whoami` and use the
+reported `name` when `type: architect`.
+
+- `type: builder` → **STOP.** This terminal is a builder. Report the mismatch.
+- Non-zero exit → **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`.
+
+### 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.
+
+Use the template at the end of this document.
+
+### 4. Clear
+
+```bash
+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
+
+```bash
+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 **not persisted** — if Tower restarts inside the window, the message is
+dropped. That is recoverable; see below.
+
+**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:
+
+1. **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.
+2. **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:
+
+```bash
+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.
+
+```
+# <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:
+# 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.**

package/skeleton/.claude/skills/codev/SKILL.md

@@ -16,7 +16,7 @@ codev doctor                   Check system dependencies
 
 ## codev init
 
-Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, .codev/config.json, .gitignore.
+Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, `.claude/skills/`, `.codex/skills/`, .codev/config.json, and .gitignore.
 
 ```bash
 codev init my-app              # Interactive setup
@@ -34,7 +34,7 @@ codev adopt -y                 # Skip conflict prompts
 
 ## codev update
 
-Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). Creates `.codev-new` versions for customized files.
+Updates framework files (protocols, roles, skills) from the installed `@cluesmith/codev` package. **Never touches user data** (specs, plans, reviews). Creates `.codev-new` versions for customized files. Missing Claude and Codex skills are added, while existing skill directories are preserved.
 
 ```bash
 codev update                   # Interactive update
@@ -57,3 +57,34 @@ codev doctor
 - `codev init` creates a new directory — use `codev adopt` for existing projects
 - Always run `codev adopt` and `codev update` from the project root
 - `codev update` only updates framework files — it never touches specs/plans/reviews
+
+## Local build and install (this repository)
+
+Test changes locally before publishing. Run from the repository root:
+
+```bash
+pnpm build                  # builds core first, then codev (including dashboard)
+pnpm -w run local-install   # packs both packages, installs globally, restarts Tower
+```
+
+`local-install` (`scripts/local-install.sh`) packs `@cluesmith/codev-core` and
+`@cluesmith/codev`, installs both in a single `npm install -g` (separate installs fail —
+`codev-core` is not on the public registry), restores the executable bit on
+`scripts/forge/**/*.sh` that `pnpm pack` strips, and restarts Tower last. Install runs while
+Tower is up; only the final restart causes downtime. **Do not stop Tower first**, and do not use
+`npm link` / `pnpm link` — it breaks global installs.
+
+`pnpm build` also runs `copy-skeleton`, which copies `codev-skeleton/` into
+`packages/codev/skeleton`. **Tests read that copy**, so after editing anything under
+`codev-skeleton/` you must rebuild before the suite reflects your change.
+
+### Where to run things
+
+- `pnpm install` — repository root (installs all workspace packages)
+- `pnpm build` / `pnpm test` — `packages/codev/`, or `pnpm --filter @cluesmith/codev build`
+- Unit tests `packages/codev/tests/unit/` · E2E `packages/codev/tests/e2e/`
+- Never run npm commands from the repository root unless told to
+
+### Measuring code size
+
+`tokei -e "tests/lib" -e "node_modules" -e ".git" -e ".builders" -e "dist" .`

package/skeleton/.claude/skills/runnable-worktrees/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: runnable-worktrees
+description: Make builder worktrees runnable — the `.codev/config.json` `worktree` block (symlinks, postSpawn, devCommand), the `afx dev` CLI, VSCode dev controls, and per-stack config recipes. Use when configuring a repo so reviewers can run a builder's branch, when `afx dev` fails to bind or start, when a dev process is orphaned holding a port, or when asked why worktree dev uses the same ports as main.
+---
+
+# Runnable worktrees
+
+When configured, each builder worktree (`.builders/<id>/`) becomes runnable: reviewers can run
+whatever your dev command starts — a dev server, `cargo run`, `expo start`, a test watcher, a
+build script — against the builder's branch without `cd`'ing, installing, or hunting for the
+command. Opt-in via `.codev/config.json`; unconfigured repos see zero behavior change.
+
+## Config: the `worktree` block
+
+```jsonc
+{
+  "worktree": {
+    "symlinks":   ["..."],   // globs symlinked from the workspace root into each new worktree
+    "postSpawn":  ["..."],   // shell commands run inside each new worktree after createWorktree
+    "devCommand": "..."      // consumed by `afx dev <builder-id|main>`
+  }
+}
+```
+
+- **`symlinks`** — globs resolve from the workspace root and link into the worktree at the same
+  relative path. Root `.env` and `.codev/config.json` are *always* symlinked regardless.
+  **Symlinks, not copies**, so edits to main's env files reflect instantly in a running dev
+  session. A directory match is silently skipped (a glob cannot mask the worktree's own source)
+  **unless** the entry ends in a slash: `".local-user-data/"` is treated as a literal path and
+  links the directory whole — shared with the parent, not branch-isolated. A dangling link is
+  fine if the source does not exist yet.
+- **`postSpawn`** — commands run sequentially with `cwd` = worktree path. A non-zero exit aborts
+  the spawn loudly; the half-built worktree stays for inspection.
+- **`devCommand`** — the foreground command that starts your dev process. Required for
+  `afx dev`.
+
+**Codev does not auto-detect your stack.** Pick a recipe below.
+
+## CLI
+
+```bash
+afx dev <builder-id>     # start dev in that builder's worktree
+afx dev main             # start dev in the MAIN workspace (Codev-managed)
+afx dev --stop           # stop the running dev PTY (builder or main)
+afx setup <builder-id>   # re-apply symlinks + postSpawn to an existing worktree (idempotent)
+```
+
+**One dev PTY at a time**, across {main + all builders} — deliberate; see *URLs are
+load-bearing*. `main` is a reserved target running `worktree.devCommand` in the main checkout as
+a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to
+swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are
+**non-persistent** — a Tower restart or crash kills them; re-run to restart.
+
+**Start main's dev with `afx dev main`, not a bare `pnpm dev`.** A hand-run `pnpm dev` is
+invisible to Codev (which never kills what it did not spawn), so a builder dev started while it
+holds the ports either fails to bind or — worse — serves main's code under the worktree URL.
+`afx dev main` makes it a managed PTY that swap-detection can stop cleanly. This only helps if
+used consistently.
+
+## VSCode
+
+Right-click a builder row in the Codev sidebar (Builders or Needs Attention):
+
+- **Open Builder Terminal** — that builder's AI terminal in a tab (same as left-click).
+- **Open Worktree Folder** — `.builders/<id>/` in the OS file manager.
+- **Run Worktree Setup** — re-applies `worktree.symlinks` and `worktree.postSpawn` to an
+  existing worktree (the git steps are skipped). Idempotent. Use when the lockfile changed, when
+  `symlinks`/`postSpawn` grew after the builder spawned, when a link was deleted, or when the
+  original setup aborted. Streams install output in a fresh terminal. CLI: `afx setup <id>`.
+- **View Diff** — unified `main...HEAD` diff for that worktree with a file-list pane.
+- **Run Dev** / **Stop Dev** — spawn or kill the dev PTY as a `Codev: <name> (dev)` tab;
+  prompts to swap if another dev is running.
+
+The sidebar's **Workspace** view carries a dev control for whatever folder the window is rooted
+at — the main checkout resolves to `main`, a `.builders/<id>/` window resolves to that builder.
+The row tooltip names the resolved target. Commands are also in the palette (Cmd+Shift+P); no
+default keybindings.
+
+## URLs are load-bearing
+
+The dev PTY intentionally uses **the same ports and URLs as main**. OAuth callbacks, CORS
+allowlists, cookie scoping, CSP `connect-src` and webhook URLs are all keyed off origin, so
+running a worktree on a different port would break them.
+
+Consequence: stop main's dev before starting a builder's, or the spawned dev fails at bind time
+with `EADDRINUSE`.
+
+## Cleanup and orphan recovery
+
+`afx dev --stop` and the swap path kill the entire PTY **process group** (SIGTERM, then SIGKILL
+after 5s), which signals every grandchild of a monorepo orchestrator (`pnpm dev`, `turbo dev`,
+`pnpm -r --parallel run dev`) at once. Ports are reclaimed by the OS as a consequence — Codev
+never manipulates ports directly.
+
+If Tower hard-crashes mid-dev and a process is left holding a port outside Codev's records:
+
+```bash
+lsof -ti :<port> | xargs kill
+lsof -ti :3000,:3001,:4000 | xargs kill
+```
+
+## Recipes
+
+**pnpm monorepo (Next.js / Turbo)**
+```json
+{"worktree": {"symlinks": [".env.local", ".env.development.local", "packages/*/.env", "packages/*/.env.local", "turbo.json"], "postSpawn": ["pnpm install --frozen-lockfile"], "devCommand": "pnpm dev"}}
+```
+
+**npm** — `{"symlinks": [".env.local", ".env.development"], "postSpawn": ["npm ci"], "devCommand": "npm run dev"}`
+
+**yarn** — `{"symlinks": [".env.local"], "postSpawn": ["yarn install --frozen-lockfile"], "devCommand": "yarn dev"}`
+
+**bun** — `{"symlinks": [".env.local"], "postSpawn": ["bun install --frozen-lockfile"], "devCommand": "bun dev"}`
+
+**cargo** — `{"symlinks": [".env"], "postSpawn": [], "devCommand": "cargo run"}`
+
+**poetry / uv** — `{"symlinks": [".env", ".env.local"], "postSpawn": ["uv sync"], "devCommand": "uv run python -m myapp"}`
+
+**go mod** — `{"symlinks": [".env"], "postSpawn": ["go mod download"], "devCommand": "go run ./cmd/server"}`

package/skeleton/.codex/skills/afx/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: afx
+description: Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks. ALWAYS consult this skill BEFORE running any `afx` command to get the exact syntax. This prevents wasting time guessing flags that don't exist. Use this whenever you need to spawn a builder, check status, send messages, clean up worktrees, manage Tower, or run cron tasks. If you're about to type `afx` followed by anything, check here first.
+---
+
+# Agent Farm CLI
+
+## afx spawn
+
+Spawns a new builder in an isolated git worktree.
+
+```
+afx spawn [number] [options]
+```
+
+**The ONLY flags that exist:**
+
+| Flag | Description |
+|------|-------------|
+| `--protocol <name>` | Protocol: spir, aspir, air, bugfix, maintain, experiment. **Required for numbered spawns.** |
+| `--task <text>` | Ad-hoc task (no issue number needed) |
+| `--shell` | Bare Claude session |
+| `--worktree` | Bare worktree session |
+| `--files <files>` | Context files, comma-separated. **Requires `--task`.** |
+| `--no-comment` | Skip commenting on the GitHub issue |
+| `--force` | Skip dirty-worktree and collision checks |
+| `--soft` | Soft mode (AI follows protocol, you verify) |
+| `--strict` | Strict mode (porch orchestrates) — this is the default |
+| `--resume` | Resume builder in existing worktree |
+| `--no-role` | Skip loading role prompt |
+
+**There is NO `-t`, `--title`, `--name`, or `--branch` flag.** The branch name is auto-generated from the issue title.
+
+**Examples:**
+```bash
+afx spawn 42 --protocol spir           # SPIR builder for issue #42
+afx spawn 42 --protocol aspir          # ASPIR (autonomous, no human gates)
+afx spawn 42 --protocol air            # AIR (small features)
+afx spawn 42 --protocol bugfix         # Bugfix
+afx spawn 42 --protocol spir --soft    # Soft mode
+afx spawn 42 --resume                  # Resume existing builder
+afx spawn --task "fix the flaky test"  # Ad-hoc task (no issue)
+afx spawn 42 --protocol spir --force   # Skip dirty-worktree check
+```
+
+**Pre-spawn checklist:**
+1. `git status` — worktree must be clean (or use `--force`)
+2. Commit specs/plans first — builders branch from HEAD and can't see uncommitted files
+3. `--protocol` is required for numbered spawns
+
+## afx send
+
+Sends a message to a running builder.
+
+```
+afx send [builder] [message]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Send to all builders |
+| `--file <path>` | Include file content |
+| `--interrupt` | Send Ctrl+C first |
+| `--raw` | Skip structured formatting |
+| `--no-enter` | Don't press Enter after message |
+
+```bash
+afx send 0042 "PR approved, please merge"
+afx send 0585 "check the test output" --file /tmp/test-results.txt
+```
+
+## afx cleanup
+
+Removes a builder's worktree and branch after work is done.
+
+```
+afx cleanup [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --project <id>` | Builder project ID (no leading zeros: `585` not `0585`) |
+| `-i, --issue <number>` | Cleanup bugfix builder by issue number |
+| `-t, --task <id>` | Cleanup task builder (e.g., `task-bEPd`) |
+| `-f, --force` | Force cleanup even if branch not merged |
+
+```bash
+afx cleanup -p 585              # Clean up project 585
+afx cleanup -p 585 -f           # Force (unmerged branch)
+```
+
+**Note:** `afx cleanup` uses plain numbers (`585`), not zero-padded (`0585`). But `afx send` uses zero-padded IDs (`0585`).
+
+## afx status
+
+```bash
+afx status                      # Show all builders and workspace status
+```
+
+No flags needed. Shows Tower status, workspace, and all active builders.
+
+## afx whoami
+
+```bash
+afx whoami                      # Report this terminal's identity (workspace, type, name)
+afx whoami --json               # Same, as a single JSON object
+```
+
+Resolves identity from Tower/global.db's perspective: builder-worktree cwd
+match first, then the Tower-injected `CODEV_ARCHITECT_NAME` env var. Exits 1
+with an explanation when identity cannot be determined — it never guesses and
+never defaults to `main` (issue #1094). Builders also get an `architect:`
+field naming their spawning architect when recorded. Works without Tower.
+
+## afx tower
+
+```bash
+afx tower start                 # Start Tower on port 4100
+afx tower stop                  # Stop Tower
+afx tower log                   # Tail Tower logs
+afx tower status                # Check daemon and cloud connection status
+afx tower connect               # Connect to Codev Cloud
+afx tower disconnect            # Disconnect from Codev Cloud
+```
+
+There is NO `afx tower restart` — use `afx tower stop && afx tower start`.
+
+## afx workspace
+
+```bash
+afx workspace start             # Start workspace for current project
+afx workspace stop              # Stop workspace processes
+```
+
+`afx dash` is a deprecated alias — use `afx workspace` instead.
+
+## afx cron
+
+```bash
+afx cron list                   # List all cron tasks
+afx cron status <name>          # Check task status
+afx cron run <name>             # Run immediately
+afx cron enable <name>          # Enable
+afx cron disable <name>         # Disable
+```
+
+There is NO `afx cron add` — create YAML files in `.af-cron/` directly:
+
+```yaml
+name: Service Health Check      # required, unique per workspace
+schedule: "*/15 * * * *"        # required, cron expression (or @hourly/@daily/@startup)
+command: ./health-check.sh      # required, run via shell
+message: "Health alert: ${output}"  # required, ${output} = trimmed command output
+condition: "exitCode != 0"      # optional JS expression, see below
+target: architect               # optional, default architect
+timeout: 30                     # optional, seconds, default 30
+enabled: true                   # optional, default true
+```
+
+`condition` is a JavaScript expression with two variables in scope: `output` (string — the command's trimmed output) and `exitCode` (number — 0 on success, the command's exit code on non-zero exit, 124 on timeout, -1 on spawn failure). With a `condition`, the message is delivered exactly when it evaluates truthy — including on failed runs (e.g. `exitCode != 0` alerts when the command fails). Without a `condition`, the message is delivered only when the command exits 0.
+
+## Other commands
+
+```bash
+afx open <file>                 # Open file in annotation viewer (NOT system open)
+afx shell                       # Spawn utility shell
+afx attach                      # Attach to running builder terminal
+afx rename <name>               # Rename current shell session
+afx architect                   # Start architect session in current terminal
+```

package/skeleton/.codex/skills/arch-init/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: arch-init
+description: Adopt an architect identity and recover its state from codev/state/<name>.md. Use when an architect terminal needs to (re)establish which architect it is — after a restart, context loss, or session handoff — or when the user says "/arch-init", "you are the X architect", or "recover your architect state". Identity resolves via `afx whoami` (an explicit name argument overrides); if neither resolves, ask the human — never guess.
+argument-hint: "[name]   (e.g. main; omit to auto-detect via afx whoami)"
+---
+
+# /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, then follow the state file.** 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). Then carry out whatever the state file 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. 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.