@cluesmith/codev 3.2.4 → 3.3.1

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.

package/skeleton/protocols/air/consult-types/impl-review.md

@@ -1,43 +1,32 @@
 # Implementation Review Prompt
 
 ## Context
-You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices.
 
-## CRITICAL: Verify Before Flagging
+You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce.
 
-Before requesting changes for missing configuration, incorrect patterns, or framework issues:
-1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
-2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
-3. **Do not assume** your training data reflects the version in use — verify against project files
+## Verify before flagging
+
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
+
+- Check `package.json` for the actual dependency versions — framework conventions change between major versions.
+- Read the actual config files (or confirm their deliberate absence) before flagging a missing config.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Issue Adherence**
-   - Does the implementation fulfill the issue requirements?
-   - Are the described acceptance criteria met?
-
-2. **Code Quality**
-   - Is the code readable and maintainable?
-   - Are there obvious bugs or issues?
-   - Are error cases handled appropriately?
-
-3. **Test Coverage**
-   - Are the tests adequate?
-   - Do tests cover the main paths AND edge cases?
-
-4. **Scope**
-   - Is the change under 300 LOC? If not, should this be escalated to ASPIR?
-   - Does the implementation stay focused on the issue, or does it include unrelated changes?
+- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria.
+- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled.
+- **Test Coverage** — tests are adequate and cover main paths and edge cases.
+- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -51,14 +40,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Implementation looks good, ready for PR
-- `REQUEST_CHANGES`: Issues that must be fixed
-- `COMMENT`: Minor suggestions, can proceed but note feedback
-
-## Notes
+- `APPROVE`: implementation looks good, ready for PR.
+- `REQUEST_CHANGES`: issues that must be fixed.
+- `COMMENT`: minor suggestions; can proceed but note the feedback.
 
-- AIR has no spec or plan — review against the GitHub issue
-- Focus on "does this feature work correctly" not "is this architecturally perfect"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback
+AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect".

package/skeleton/protocols/air/consult-types/pr-review.md

@@ -1,48 +1,30 @@
 # PR Ready Review Prompt
 
 ## Context
-You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body.
+
+You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Are the issue requirements implemented?
-   - Is the PR body review section filled out (summary, key decisions, test plan)?
-   - Are commits properly formatted?
-
-2. **Test Status**
-   - Do all tests pass?
-   - Is test coverage adequate for the changes?
-   - Are there any skipped or flaky tests?
-
-3. **Code Cleanliness**
-   - Is there any debug code left in?
-   - Are there any TODO comments that should be resolved?
-   - Is the code properly formatted?
-
-4. **Scope**
-   - Is the change under 300 LOC?
-   - Does the implementation stay focused on the issue?
-   - Are there unrelated changes bundled in?
-
-5. **PR Quality**
-   - Does the PR link to the issue?
-   - Is the PR body review section informative?
-   - Is the branch up to date with its base (the integration branch the PR targets)?
+- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out.
+- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for.
+- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted.
+- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in.
+- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets).
 
 ## Scope
 
-- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
+Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -56,13 +38,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready for architect review
-- `REQUEST_CHANGES`: Issues to fix before review
-- `COMMENT`: Minor items, can proceed but note feedback
-
-## Notes
+- `APPROVE`: ready for architect review.
+- `REQUEST_CHANGES`: issues to fix before review.
+- `COMMENT`: minor items; can proceed but note the feedback.
 
-- AIR has no spec, plan, or review files — review the PR body and code diff
-- Focus on "is this ready for someone else to review" not "is this perfect"
-- Any issues found here are cheaper to fix than during integration review
+AIR has no spec, plan, or review files — review the PR body and the code diff.

package/skeleton/protocols/air/prompts/implement.md

@@ -2,9 +2,9 @@
 
 You are executing the **IMPLEMENT** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC.
+Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts.
 
 ## Baked Decisions
 
@@ -17,79 +17,26 @@ If two baked decisions contradict each other, do not pick one — pause, flag th
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## What must be true when you finish
 
-### 1. Read the Issue
+- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions.
+- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.)
+- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling.
+- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on.
 
-Read the full issue description. Identify:
-- What is the desired behavior?
-- What are the acceptance criteria?
-- Are there examples or mockups?
-- What files/modules are likely affected?
-
-### 2. Implement the Feature
-
-Apply a focused implementation:
-- Implement what the issue describes — no more, no less
-- Do NOT refactor surrounding code
-- Do NOT add features beyond what's described in the issue
-- Do NOT fix unrelated bugs you happen to notice (file separate issues)
-
-**Code Quality**:
-- Self-documenting code (clear names, obvious structure)
-- No commented-out code or debug prints
-- Follow existing project conventions
-
-### 3. Add Tests
-
-Write tests that:
-- Cover the main happy path
-- Cover key edge cases
-- Are deterministic (not flaky)
-
-Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.).
-
-### 4. Verify the Build
-
-Run build and tests:
-
-```bash
-npm run build      # Must pass
-npm test           # Must pass
-```
-
-Fix any failures before proceeding. If build/test commands don't exist, check `package.json`.
-
-### 5. Commit
-
-Stage and commit your changes:
-- Use explicit file paths (never `git add -A` or `git add .`)
-- Commit message: `[Air #{{issue.number}}] feat: <brief description>`
+Commit with an explicit staged path and the message `[Air #{{issue.number}}] feat: <brief description>`.
 
 ## Signals
 
-When implementation and tests are complete and passing:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If the feature is too complex for AIR (> 300 LOC or architectural):
-
-```
-<signal>TOO_COMPLEX</signal>
-```
-
-If you're blocked (missing context, unclear requirements, etc.):
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
-
-## Important Notes
-
-1. **Stay focused** — Implement what the issue describes, nothing else
-2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only)
-3. **Build AND tests must pass** — Don't signal complete until both pass
-4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX`
-5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/`
+- Implementation and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Too complex for AIR (> ~300 LOC or architectural):
+  ```
+  <signal>TOO_COMPLEX</signal>
+  ```
+- Blocked (missing context, unclear requirements):
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

package/skeleton/protocols/air/prompts/pr.md

@@ -2,32 +2,20 @@
 
 You are executing the **PR** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect.
+Open the PR with the review embedded in its body, optionally run CMAP, and notify the architect.
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## Create the PR
 
-### 1. Create the Pull Request
+**The PR body IS the review for AIR** — do not create a file in `codev/reviews/`. Include a summary, the key decisions, and a test plan in the body itself.
 
-Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan.
-
-**PR body requirements**: The PR body MUST include `Closes #<N>` (where `<N>` is
-the driving issue number) so GitHub auto-closes the issue on merge. If the PR
-closes multiple issues (e.g. duplicates consolidated), include one `Closes #<N>`
-per issue. Without this, GitHub will not auto-close the issue.
-
-**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
-or `Part of #<N>` instead of `Closes` — the issue stays open until a
-follow-up PR closes it.
-
-**Note**: substitute the real issue number for `<N>` — do not leave the
-placeholder or any `{{...}}` template tag in the committed PR body.
+The body must carry `Closes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #<N>` or `Part of #<N>` instead. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
 gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
@@ -35,15 +23,15 @@ gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF
 
 <1-2 sentence description of the feature>
 
-Closes #<N>  <!-- Substitute <N> with the real issue number -->
+Closes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 
 ## What Changed
 
-<Brief explanation of the implementation approach>
+<the implementation approach>
 
 ## Key Decisions
 
-<Any notable decisions made during implementation, or "None — straightforward implementation">
+<notable decisions, or "None — straightforward implementation">
 
 ## Test Plan
 
@@ -53,16 +41,14 @@ Closes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## Review Notes
 
-<Anything the reviewer should pay special attention to, or "Standard implementation — no special concerns">
+<anything the reviewer should focus on, or "Standard implementation — no special concerns">
 EOF
 )"
 ```
 
-**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR.
+## Optional CMAP review
 
-### 2. Optional CMAP Review
-
-If the implementation is non-trivial, run 3-way consultation:
+CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules:
 
 ```bash
 consult -m gemini --protocol air --type pr &
@@ -70,41 +56,23 @@ consult -m codex --protocol air --type pr &
 consult -m claude --protocol air --type pr &
 ```
 
-All three should run in the background (`run_in_background: true`).
-
-**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it.
+If you run it, wait for all three, record each verdict, fix real issues, and push.
 
-### 3. Address Feedback (if CMAP was run)
-
-If you ran CMAP:
-- Wait for all consultations to complete
-- Record each model's verdict
-- Fix any issues identified
-- Push updates to the PR branch
-
-### 4. Notify Architect
-
-Send notification with PR link:
+## Notify the architect
 
 ```bash
 afx send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
 ```
 
-If CMAP was run, include verdicts:
-```bash
-afx send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
-```
+If you ran CMAP, include the verdicts: `CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>`.
 
 ## Signals
 
-When PR is created and ready for review:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If you're blocked:
-
-```
-<signal>BLOCKED:reason goes here</signal>
-```
+- PR created and ready for review:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```