@cluesmith/codev 3.2.4 → 3.3.0

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

@@ -144,7 +144,20 @@ afx cron enable <name>          # Enable
 afx cron disable <name>         # Disable
 ```
 
-There is NO `afx cron add` — create YAML files in `.af-cron/` directly.
+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
 

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

@@ -63,7 +63,11 @@ 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 → suggest /clear → human /clears → /arch-init → …
+/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
@@ -99,17 +103,26 @@ plus the most recent dated section*, so a save must leave exactly that behind:
 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 `/clear`.** Save first, *then* tell the human
-it is a good time to clear. You cannot clear your own context and must never
-decide unilaterally to lose it; keeping the irreversible step behind a human
-keystroke 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.:
+**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 `/clear` if this
+> 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 to `/clear` at any other time.
+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)
 

package/skeleton/.codex/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/.codex/skills/codev/SKILL.md

@@ -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/.codex/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/protocols/air/builder-prompt.md

@@ -4,33 +4,33 @@ You are implementing {{input_description}}.
 
 {{#if mode_soft}}
 ## Mode: SOFT
-You are running in SOFT mode. This means:
-- You follow the AIR protocol yourself (no porch orchestration)
-- The architect monitors your work and verifies you're adhering to the protocol
-- Consultation is optional — use your judgement based on complexity
-- You have flexibility in execution, but must stay compliant with the protocol
+
+You follow the protocol yourself; the architect verifies compliance.
 {{/if}}
 
 {{#if mode_strict}}
 ## Mode: STRICT
-You are running in STRICT mode. This means:
-- Porch orchestrates your work
-- Run: `porch next` to get your next tasks
-- Follow porch signals and gate approvals
-
-### ABSOLUTE RESTRICTIONS (STRICT MODE)
-- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
-- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+
+Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. Never
+hand-edit `status.yaml` — only porch commands modify project state.
 {{/if}}
 
 ## Protocol
-Follow the AIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
+
+The full protocol text is inlined below under **## Protocol Reference (full text)** — you do not
+need to fetch it.
 
 ## Baked Decisions
 
-If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review.
+If the issue body contains a section named "Baked Decisions" (any heading level,
+case-insensitive), treat its contents as fixed architectural decisions baked in by the
+architect. Do not autonomously override them in your spec, plan, or implementation. If you
+discover a serious reason to question a baked decision, surface that concern to the architect
+via `afx send` rather than relitigating it inside the spec/plan/review.
 
-If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding.
+If the architect's baked-decisions section contains internal contradictions (e.g., two different
+language choices), do not pick one — pause, flag the contradiction to the architect via
+`afx send`, and wait for resolution before proceeding.
 
 {{#if issue}}
 ## Issue #{{issue.number}}
@@ -38,44 +38,25 @@ If the architect's baked-decisions section contains internal contradictions (e.g
 
 **Description**:
 {{issue.body}}
+{{/if}}
 
 ## Your Mission
-1. Read the issue requirements carefully
-2. Implement the feature (< 300 LOC)
-3. Write tests for the feature
-4. Create PR with review in the PR body (NOT as a separate file)
-5. Notify architect via `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
 
-**IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body.
+1. Implement the feature from the issue (<300 LOC)
+2. Write tests for it
+3. Open a PR with the review **in the PR body**, not as a separate file
+4. Notify: `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
+
+**AIR produces no spec, plan, or review files.** That is the whole economy of the protocol.
+
+If the feature turns out larger than AIR fits (>300 LOC, or an architectural decision the issue
+does not make), stop and say so rather than growing it quietly:
 
-If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
 afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
 ```
 
 ## Notifications
-Always use `afx send architect "..."` to notify the architect at key moments:
-- **PR ready**: `afx send architect "PR #N ready for review (implements #{{issue.number}})"`
-- **PR merged**: `afx send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `afx send architect "Blocked on issue #{{issue.number}}: [reason]"`
-{{/if}}
-
-## Handling Flaky Tests
-
-If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in the PR body under a "Flaky Tests" section
-5. Commit the skip and continue with your work
-
-## Getting Started
-1. Read the AIR protocol
-2. Review the issue details
-3. Implement the feature
-
----
-
-## Protocol Reference (full text)
 
-{{protocol_reference}}
+The architect is not watching. `afx send architect "..."` at each of: gate reached, PR ready, PR
+merged, blocked.