Ship Codex skills through the scaffold lifecycle

.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

.codex/skills/afx/SKILL.md

@@ -0,0 +1,179 @@
+---
+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, tick, maintain, experiment. **Required for numbered spawns.** |
+| `--task <text>` | Ad-hoc task (no issue number needed) |
+| `--shell` | Bare Claude session |
+| `--worktree` | Bare worktree session |
+| `--amends <number>` | Original spec number (TICK only) |
+| `--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 tick --amends 30  # TICK amendment to spec 30
+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
+```
+
+**Addressing forms** — the recipient isn't only a builder ID:
+
+| Form | Routes to |
+|------|-----------|
+| `afx send 0585 "…"` | Builder `0585` (zero-padded). |
+| `afx send architect "…"` | From a builder: its spawning architect. From an architect: the `main` architect (else first registered). |
+| `afx send architect:<name> "…"` | A specific named architect (sibling-architect messaging). Architects can address any architect; a builder may only use its own `spawnedByArchitect`. |
+| `afx send <workspace>:architect "…"` | The architect in **another workspace** (cross-workspace). |
+
+```bash
+afx send architect:ob-refine "PR-iter-2 feedback ready"   # sibling architect, same workspace
+afx send taqwabench:architect "use porch.checks, don't fork protocol.json"  # cross-workspace
+```
+
+**Find the exact workspace name first** — guessing fails with `NOT_FOUND`. The name is the basename of the workspace path, which can differ from how someone refers to it. List active workspaces via the Tower API:
+
+```bash
+curl -s http://localhost:4100/api/workspaces | python3 -m json.tool   # → each .name is a valid <workspace> address
+```
+
+## 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.
+
+## 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
+```

.codex/skills/afx/af-workspace/iteration-1/eval-1-spawn-naming/without_skill/output.txt

@@ -0,0 +1,3 @@
+Error: Claude Code cannot be launched inside another Claude Code session.
+Nested sessions share runtime resources and will crash all active sessions.
+To bypass this check, unset the CLAUDECODE environment variable.

.codex/skills/afx/af-workspace/iteration-1/eval-2-cleanup-format/without_skill/output.txt

@@ -0,0 +1,3 @@
+Error: Claude Code cannot be launched inside another Claude Code session.
+Nested sessions share runtime resources and will crash all active sessions.
+To bypass this check, unset the CLAUDECODE environment variable.

.codex/skills/afx/af-workspace/iteration-1/eval-3-send-with-file/without_skill/output.txt

@@ -0,0 +1,3 @@
+Error: Claude Code cannot be launched inside another Claude Code session.
+Nested sessions share runtime resources and will crash all active sessions.
+To bypass this check, unset the CLAUDECODE environment variable.

.codex/skills/afx/af-workspace/iteration-1/eval-4-tower-restart/without_skill/output.txt

@@ -0,0 +1,3 @@
+Error: Claude Code cannot be launched inside another Claude Code session.
+Nested sessions share runtime resources and will crash all active sessions.
+To bypass this check, unset the CLAUDECODE environment variable.

.codex/skills/afx/af-workspace/iteration-1/eval-5-tick-amends/without_skill/output.txt

@@ -0,0 +1,3 @@
+Error: Claude Code cannot be launched inside another Claude Code session.
+Nested sessions share runtime resources and will crash all active sessions.
+To bypass this check, unset the CLAUDECODE environment variable.

.codex/skills/afx/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "af",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Spawn a builder for issue 71 using the ASPIR protocol. I want to call it e2e-staging-tests.",
+      "expected_output": "Should run `af spawn 71 --protocol aspir` without trying -t, --title, --name, or any flag for naming. Should note that branch names are auto-generated.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Clean up the builder for project 42. The branch wasn't merged yet so force it.",
+      "expected_output": "Should run `af cleanup -p 42 -f` (plain number, not 0042).",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Send a message to builder 42 telling it to check the failing test and include the test output file at /tmp/test-results.txt",
+      "expected_output": "Should run `af send 0042 \"check the failing test\" --file /tmp/test-results.txt` (zero-padded ID for send).",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I need to restart Tower to pick up new code changes.",
+      "expected_output": "Should run `af tower stop && af tower start`. Should NOT try `af tower restart` which doesn't exist.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Spawn a TICK builder for issue 88 that amends spec 45. There are uncommitted changes but they're not relevant.",
+      "expected_output": "Should run `af spawn 88 --protocol tick --amends 45 --force`. Must include both --amends and --force.",
+      "files": []
+    }
+  ]
+}

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

@@ -0,0 +1,110 @@
+---
+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 → suggest /clear → human /clears → /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.
+2. **Append one short dated log entry** capturing what changed this stretch.
+3. **Keep it to one screen (compaction discipline).** The state file is a
+   summary, not a transcript. When you append, prune stale dated sections so
+   the file stays readable at a glance.
+
+**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 `/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.:
+
+> State saved to `codev/state/<name>.md` — good time to `/clear` if this
+> session is feeling heavy.
+
+Do not repeat it, and do not prompt to `/clear` at any other time.
+
+## 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.