@cluesmith/codev 3.2.3 → 3.3.0

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

@@ -0,0 +1,90 @@
+---
+name: codev
+description: Codev project management CLI — init, adopt, update, and doctor commands. Check this skill before running any `codev` command (except `consult`, `porch`, or `afx` which have their own skills). Use when setting up new projects, adding codev to existing repos, updating framework files, or diagnosing missing dependencies.
+---
+
+# codev - Project Management CLI
+
+## Commands
+
+```
+codev init [project-name]      Create a new codev project directory
+codev adopt                    Add codev to the current directory
+codev update                   Update protocols, roles, skills from package
+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/`, `.codex/skills/`, .codev/config.json, and .gitignore.
+
+```bash
+codev init my-app              # Interactive setup
+codev init my-app -y           # Non-interactive with defaults
+```
+
+## codev adopt
+
+Adds codev to the **current directory** (existing project). Run from the project root. If CLAUDE.md or AGENTS.md already exists, creates `.codev-new` versions and spawns Claude to merge.
+
+```bash
+codev adopt                    # Interactive
+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. Missing Claude and Codex skills are added, while existing skill directories are preserved.
+
+```bash
+codev update                   # Interactive update
+codev update --dry-run         # Preview changes
+codev update --force           # Overwrite all framework files
+codev update --agent           # Agent mode: JSON stdout, no interactive merge
+```
+
+## codev doctor
+
+Checks all required dependencies: Node.js (>=18), git (>=2.5), gh (authenticated), and at least one AI CLI (Claude, Gemini, or Codex).
+
+```bash
+codev doctor
+```
+
+## Common mistakes
+
+- There is NO `codev tower` command — use `afx tower start/stop`
+- `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/consult/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: consult
+description: AI consultation CLI — query Gemini, Codex, or Claude for reviews and analysis. ALWAYS check this skill before running any `consult` command. Use when reviewing specs, plans, implementations, or PRs with external models, running parallel 3-way reviews (cmap), or checking consultation stats. The `-m` model flag is always required except for `consult stats`.
+---
+
+# consult - AI Consultation CLI
+
+Query external AI models for reviews and analysis. Supports Gemini, Codex, and Claude.
+
+## Synopsis
+
+```
+consult -m <model> [options]
+consult stats [options]
+```
+
+The `-m` / `--model` flag is **always required** except for `consult stats`.
+
+## Models
+
+| Flag value | Alias | Notes |
+|------------|-------|-------|
+| `gemini` | `pro` | Antigravity CLI (`agy`); agentic file access (`--sandbox`), OAuth login; skips non-blockingly if unavailable |
+| `codex` | `gpt` | Thorough (~200-250s), shell exploration |
+| `claude` | `opus` | Agent SDK with tool use (~60-120s) |
+
+## All flags
+
+```
+-m, --model <model>         Model to use (required except stats)
+--prompt <text>              Inline prompt (general mode)
+--prompt-file <path>         Prompt file path (general mode)
+--protocol <name>            Protocol: spir, aspir, air, bugfix, maintain
+-t, --type <type>            Review type (see below)
+--issue <number>             Issue number (required in architect context)
+--output <path>              Save result to file
+--plan-phase <phase>         Scope review to a plan phase (porch use)
+--context <path>             Context file with feedback (porch use)
+--project-id <id>            Project ID for metrics (porch use)
+--days <n>                   Stats: limit to last N days (default: 30)
+--project <id>               Stats: filter by project ID
+--last <n>                   Stats: show last N invocations
+--json                       Stats: output as JSON
+```
+
+## Review types (`--type`)
+
+| Type | When to use |
+|------|-------------|
+| `spec` | Review a specification for completeness |
+| `plan` | Review an implementation plan |
+| `impl` | Review code implementation |
+| `pr` | Review a pull request before merge |
+| `phase` | Phase-scoped review (builder context only) |
+| `integration` | Architect's integration review of a PR |
+
+## Usage patterns
+
+**General query:**
+```bash
+consult -m gemini --prompt "What's the best way to structure auth?"
+consult -m codex --prompt-file review-checklist.md
+```
+
+**Protocol review:**
+```bash
+consult -m gemini --type spec --issue 42
+consult -m codex --type plan --issue 42
+consult -m claude --type integration --issue 42
+```
+
+**3-way parallel review (cmap):**
+Always use `--output` for background runs — without it, results go to a temp file that may be garbage-collected.
+
+```bash
+consult -m gemini --type integration --issue 42 --output /tmp/cmap-gemini-42.md &
+consult -m codex --type integration --issue 42 --output /tmp/cmap-codex-42.md &
+consult -m claude --type integration --issue 42 --output /tmp/cmap-claude-42.md &
+wait
+```
+
+**Stats:**
+```bash
+consult stats                     # 30-day summary
+consult stats --days 7 --json     # Last 7 days as JSON
+consult stats --project 42        # Filter by project
+```
+
+## Rules
+
+- `-m` is required for all non-stats commands
+- `--prompt` and `--type` are mutually exclusive (different modes)
+- `--prompt` and `--prompt-file` are mutually exclusive
+- `--protocol` requires `--type`
+- From architect context (outside `.builders/`), `--issue` is required for protocol reviews
+- From builder context (inside `.builders/`), project auto-detects from porch state

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: generate-image
+description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+---
+
+# generate-image - AI Image Generation
+
+Uses Google Gemini to generate images from text prompts.
+
+## Synopsis
+
+```
+codev generate-image "<prompt>" [options]
+```
+
+Note: this is a `codev` subcommand, not standalone.
+
+## All flags
+
+```
+-o, --output <file>        Output file path (default: output.png)
+-r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
+-a, --aspect <ratio>       Aspect ratio (default: 1:1)
+--ref <image>              Reference image (repeatable, max 14)
+```
+
+## Aspect ratios
+
+`1:1` | `16:9` | `9:16` | `3:4` | `4:3` | `3:2` | `2:3`
+
+## Examples
+
+```bash
+codev generate-image "A sunset over mountains"
+codev generate-image "A futuristic city" -r 4K -a 16:9 -o city.png
+codev generate-image "Same style but with cats" --ref style.png --ref layout.png
+codev generate-image prompt.txt -o result.png    # Prompt from .txt file
+```
+
+## Notes
+
+- Prompt must be quoted if it contains spaces
+- Prompt can be a `.txt` file path (auto-detected by extension)
+- Reference images must exist on disk
+- Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable

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

@@ -0,0 +1,60 @@
+---
+name: porch
+description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.
+---
+
+# porch - Protocol Orchestrator
+
+Porch manages the state machine behind development protocols. It tracks phases, gates, consultations, and transitions.
+
+## Commands
+
+```
+porch status [id]              Show current project state and phase
+porch run [id]                 Run the protocol loop (strict mode)
+porch next [id]                Get next tasks as JSON
+porch done [id]                Signal current phase is complete
+porch check [id]               Run checks for current phase
+porch gate [id]                Request human approval at a gate
+porch approve <id> <gate> --a-human-explicitly-approved-this
+porch rollback <id> <phase>    Rewind to an earlier phase
+porch init <protocol> <id> <name>   Initialize a new project
+```
+
+Project ID auto-detects from worktree path when inside a builder worktree.
+
+## Gate approvals
+
+Gates are human-only approval checkpoints. The `--a-human-explicitly-approved-this` flag is **required** — it exists to prevent AI agents from auto-approving.
+
+| Gate | Protocol | When |
+|------|----------|------|
+| `spec-approval` | SPIR | After spec is written |
+| `plan-approval` | SPIR | After plan is written |
+| `pr` | SPIR, AIR | After PR is created |
+
+```bash
+porch approve 42 spec-approval --a-human-explicitly-approved-this
+porch approve 42 plan-approval --a-human-explicitly-approved-this
+porch approve 42 pr --a-human-explicitly-approved-this
+```
+
+**ASPIR and BUGFIX have no spec/plan gates** — they run autonomously through those phases.
+
+## Checking pending gates
+
+```bash
+porch pending                  # List all gates waiting for approval
+```
+
+## Critical rules
+
+- **Builders must NEVER call `porch approve`** — only humans approve gates
+- **Never edit `status.yaml` directly** — porch manages all state
+- Builders signal completion with `porch done`, not `porch approve`
+- `porch run` is for strict mode only — soft mode builders follow the protocol document manually
+- When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`
+
+## State storage
+
+Project state lives in `codev/projects/<id>-<name>/status.yaml`, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

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"}`