@cluesmith/codev 3.0.0-rc.1 → 3.0.0-rc.11

package/scripts/forge/gitea/repo-archive.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Forge concept: repo-archive (Gitea via tea CLI)
+# Input: CODEV_REPO (owner/repo), CODEV_REF (tag/branch/sha, empty for default), CODEV_OUTPUT_DIR
+# Output: Extracts repository archive into CODEV_OUTPUT_DIR
+REF_PART="${CODEV_REF:-main}"
+# Gitea API: GET /repos/:owner/:repo/archive/:ref.tar.gz
+tea api "repos/${CODEV_REPO}/archive/${REF_PART}.tar.gz" > /tmp/codev-archive-$$.tar.gz
+mkdir -p "${CODEV_OUTPUT_DIR}"
+tar xzf /tmp/codev-archive-$$.tar.gz -C "${CODEV_OUTPUT_DIR}" --strip-components=1
+rm -f /tmp/codev-archive-$$.tar.gz
+echo '{"status":"ok"}'

package/scripts/forge/gitea/user-identity.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: user-identity (Gitea via tea CLI)
+tea whoami --output json | jq -r ".login"

package/scripts/forge/github/auth-status.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Forge concept: auth-status (GitHub via gh CLI)
+# Output: text + exit code (0 = authenticated)
+exec gh auth status

package/scripts/forge/github/issue-comment.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: issue-comment (GitHub via gh CLI)
+# Input: CODEV_ISSUE_ID, CODEV_COMMENT_BODY
+# Output: exit code only
+exec gh issue comment "$CODEV_ISSUE_ID" --body "$CODEV_COMMENT_BODY"

package/scripts/forge/github/issue-list.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Forge concept: issue-list (GitHub via gh CLI)
+# Output: JSON [{number, title, url, labels, createdAt, author}]
+exec gh issue list --limit 200 --json number,title,url,labels,createdAt,author

package/scripts/forge/github/issue-view.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: issue-view (GitHub via gh CLI)
+# Input: CODEV_ISSUE_ID
+# Output: JSON {title, body, state, comments[]}
+exec gh issue view "$CODEV_ISSUE_ID" --json title,body,state,comments

package/scripts/forge/github/on-it-timestamps.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Forge concept: on-it-timestamps (GitHub via gh CLI)
+# Input: CODEV_GRAPHQL_QUERY, CODEV_REPO_OWNER, CODEV_REPO_NAME
+# Output: raw GraphQL JSON response
+exec gh api graphql \
+  -f query="$CODEV_GRAPHQL_QUERY" \
+  -f owner="$CODEV_REPO_OWNER" \
+  -f name="$CODEV_REPO_NAME"

package/scripts/forge/github/pr-diff.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Forge concept: pr-diff (GitHub via gh CLI)
+# Input: CODEV_PR_NUMBER, CODEV_DIFF_NAME_ONLY (optional, "1" for name-only)
+# Output: raw diff text
+
+if [ "$CODEV_DIFF_NAME_ONLY" = "1" ]; then
+  exec gh pr diff "$CODEV_PR_NUMBER" --name-only
+else
+  exec gh pr diff "$CODEV_PR_NUMBER"
+fi

package/scripts/forge/github/pr-exists.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Forge concept: pr-exists (GitHub via gh CLI)
+# Input: CODEV_BRANCH_NAME
+# Output: "true" or "false"
+# Returns true for OPEN or MERGED PRs only. CLOSED-not-merged PRs are excluded.
+# (bugfix #568: --state all is needed to catch merged PRs; #653: filter out CLOSED)
+exec gh pr list --state all --head "$CODEV_BRANCH_NAME" --json number,state --jq '[.[] | select(.state == "OPEN" or .state == "MERGED")] | length > 0'

package/scripts/forge/github/pr-list.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Forge concept: pr-list (GitHub via gh CLI)
+# Output: JSON [{number, title, url, reviewDecision, body, createdAt, author}]
+exec gh pr list --json number,title,url,reviewDecision,body,createdAt,author

package/scripts/forge/github/pr-merge.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: pr-merge (GitHub via gh CLI)
+# Input: CODEV_PR_NUMBER
+# Output: exit code only
+exec gh pr merge "$CODEV_PR_NUMBER" --merge

package/scripts/forge/github/pr-search.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: pr-search (GitHub via gh CLI)
+# Input: CODEV_SEARCH_QUERY
+# Output: JSON [{number, headRefName}]
+exec gh pr list --search "$CODEV_SEARCH_QUERY" --json number,headRefName

package/scripts/forge/github/pr-view.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Forge concept: pr-view (GitHub via gh CLI)
+# Input: CODEV_PR_NUMBER, CODEV_INCLUDE_COMMENTS (optional, "1" to include)
+# Output: JSON or text (with comments)
+
+if [ "$CODEV_INCLUDE_COMMENTS" = "1" ]; then
+  exec gh pr view "$CODEV_PR_NUMBER" --comments
+else
+  exec gh pr view "$CODEV_PR_NUMBER" \
+    --json title,body,state,author,baseRefName,headRefName,additions,deletions
+fi

package/scripts/forge/github/recently-closed.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Forge concept: recently-closed (GitHub via gh CLI)
+# Input: CODEV_SINCE_DATE (optional, ISO date)
+# Output: JSON [{number, title, url, labels, createdAt, closedAt}]
+
+if [ -n "$CODEV_SINCE_DATE" ]; then
+  exec gh issue list --state closed \
+    --search "closed:>$CODEV_SINCE_DATE" \
+    --json number,title,url,labels,createdAt,closedAt \
+    --limit 1000
+else
+  exec gh issue list --state closed \
+    --json number,title,url,labels,createdAt,closedAt \
+    --limit 1000
+fi

package/scripts/forge/github/recently-merged.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Forge concept: recently-merged (GitHub via gh CLI)
+# Input: CODEV_SINCE_DATE (optional, ISO date)
+# Output: JSON [{number, title, url, body, createdAt, mergedAt, headRefName}]
+
+if [ -n "$CODEV_SINCE_DATE" ]; then
+  exec gh pr list --state merged \
+    --search "merged:>$CODEV_SINCE_DATE" \
+    --json number,title,url,body,createdAt,mergedAt,headRefName \
+    --limit 1000
+else
+  exec gh pr list --state merged \
+    --json number,title,url,body,createdAt,mergedAt,headRefName \
+    --limit 1000
+fi

package/scripts/forge/github/repo-archive.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Forge concept: repo-archive (GitHub via gh CLI)
+# Input: CODEV_REPO (owner/repo), CODEV_REF (tag/branch/sha, empty for default), CODEV_OUTPUT_DIR
+# Output: Extracts repository archive into CODEV_OUTPUT_DIR
+REF_PART="${CODEV_REF:-HEAD}"
+gh api "repos/${CODEV_REPO}/tarball/${REF_PART}" > /tmp/codev-archive-$$.tar.gz
+mkdir -p "${CODEV_OUTPUT_DIR}"
+tar xzf /tmp/codev-archive-$$.tar.gz -C "${CODEV_OUTPUT_DIR}" --strip-components=1
+rm -f /tmp/codev-archive-$$.tar.gz
+echo '{"status":"ok"}'

package/scripts/forge/github/team-activity.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: team-activity (GitHub via gh CLI)
+# Input: CODEV_GRAPHQL_QUERY
+# Output: raw GraphQL JSON response
+exec gh api graphql -f query="$CODEV_GRAPHQL_QUERY"

package/scripts/forge/github/user-identity.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Forge concept: user-identity (GitHub via gh CLI)
+# Output: plain text username
+exec gh api user --jq .login

package/scripts/forge/gitlab/auth-status.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: auth-status (GitLab via glab CLI)
+exec glab auth status

package/scripts/forge/gitlab/issue-comment.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: issue-comment (GitLab via glab CLI)
+exec glab issue note "$CODEV_ISSUE_ID" --message "$CODEV_COMMENT_BODY"

package/scripts/forge/gitlab/issue-list.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: issue-list (GitLab via glab CLI)
+exec glab issue list --per-page 200 --output json

package/scripts/forge/gitlab/issue-view.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: issue-view (GitLab via glab CLI)
+exec glab issue view "$CODEV_ISSUE_ID" --output json

package/scripts/forge/gitlab/pr-diff.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: pr-diff (GitLab via glab CLI)
+exec glab mr diff "$CODEV_PR_NUMBER"

package/scripts/forge/gitlab/pr-exists.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Forge concept: pr-exists (GitLab via glab CLI)
+# Returns true for open or merged MRs only. Closed-not-merged MRs are excluded.
+# --all fetches MRs in all states (open, merged, closed); without it, only open MRs are returned.
+glab mr list --all --source-branch "$CODEV_BRANCH_NAME" --output json | jq '[.[] | select(.state == "opened" or .state == "merged")] | length > 0'

package/scripts/forge/gitlab/pr-list.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: pr-list (GitLab via glab CLI — merge requests)
+exec glab mr list --output json

package/scripts/forge/gitlab/pr-merge.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: pr-merge (GitLab via glab CLI)
+exec glab mr merge "$CODEV_PR_NUMBER" --yes

package/scripts/forge/gitlab/pr-search.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: pr-search (GitLab via glab CLI)
+exec glab mr list --search "$CODEV_SEARCH_QUERY" --output json

package/scripts/forge/gitlab/pr-view.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: pr-view (GitLab via glab CLI)
+exec glab mr view "$CODEV_PR_NUMBER" --output json

package/scripts/forge/gitlab/recently-closed.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: recently-closed (GitLab via glab CLI)
+exec glab issue list --state closed --per-page 1000 --output json

package/scripts/forge/gitlab/recently-merged.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: recently-merged (GitLab via glab CLI)
+exec glab mr list --state merged --per-page 1000 --output json

package/scripts/forge/gitlab/repo-archive.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Forge concept: repo-archive (GitLab via lab/glab CLI)
+# Input: CODEV_REPO (owner/repo), CODEV_REF (tag/branch/sha, empty for default), CODEV_OUTPUT_DIR
+# Output: Extracts repository archive into CODEV_OUTPUT_DIR
+REF_PART="${CODEV_REF:-main}"
+# GitLab API: GET /projects/:id/repository/archive
+PROJECT_ENCODED=$(echo "${CODEV_REPO}" | sed 's/\//%2F/g')
+glab api "projects/${PROJECT_ENCODED}/repository/archive?sha=${REF_PART}" > /tmp/codev-archive-$$.tar.gz
+mkdir -p "${CODEV_OUTPUT_DIR}"
+tar xzf /tmp/codev-archive-$$.tar.gz -C "${CODEV_OUTPUT_DIR}" --strip-components=1
+rm -f /tmp/codev-archive-$$.tar.gz
+echo '{"status":"ok"}'

package/scripts/forge/gitlab/user-identity.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Forge concept: user-identity (GitLab via glab CLI)
+glab auth status --show-token 2>&1 | grep "Logged in" | sed "s/.*as //" | sed "s/ .*//"

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

@@ -0,0 +1,144 @@
+---
+name: afx
+description: Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks. ALWAYS consult this skill BEFORE running any `afx` command to get the exact syntax. This prevents wasting time guessing flags that don't exist. Use this whenever you need to spawn a builder, check status, send messages, clean up worktrees, manage Tower, or run cron tasks. If you're about to type `afx` followed by anything, check here first.
+---
+
+# Agent Farm CLI
+
+## afx spawn
+
+Spawns a new builder in an isolated git worktree.
+
+```
+afx spawn [number] [options]
+```
+
+**The ONLY flags that exist:**
+
+| Flag | Description |
+|------|-------------|
+| `--protocol <name>` | Protocol: spir, aspir, air, bugfix, maintain, experiment. **Required for numbered spawns.** |
+| `--task <text>` | Ad-hoc task (no issue number needed) |
+| `--shell` | Bare Claude session |
+| `--worktree` | Bare worktree session |
+| `--files <files>` | Context files, comma-separated. **Requires `--task`.** |
+| `--no-comment` | Skip commenting on the GitHub issue |
+| `--force` | Skip dirty-worktree and collision checks |
+| `--soft` | Soft mode (AI follows protocol, you verify) |
+| `--strict` | Strict mode (porch orchestrates) — this is the default |
+| `--resume` | Resume builder in existing worktree |
+| `--no-role` | Skip loading role prompt |
+
+**There is NO `-t`, `--title`, `--name`, or `--branch` flag.** The branch name is auto-generated from the issue title.
+
+**Examples:**
+```bash
+afx spawn 42 --protocol spir           # SPIR builder for issue #42
+afx spawn 42 --protocol aspir          # ASPIR (autonomous, no human gates)
+afx spawn 42 --protocol air            # AIR (small features)
+afx spawn 42 --protocol bugfix         # Bugfix
+afx spawn 42 --protocol spir --soft    # Soft mode
+afx spawn 42 --resume                  # Resume existing builder
+afx spawn --task "fix the flaky test"  # Ad-hoc task (no issue)
+afx spawn 42 --protocol spir --force   # Skip dirty-worktree check
+```
+
+**Pre-spawn checklist:**
+1. `git status` — worktree must be clean (or use `--force`)
+2. Commit specs/plans first — builders branch from HEAD and can't see uncommitted files
+3. `--protocol` is required for numbered spawns
+
+## afx send
+
+Sends a message to a running builder.
+
+```
+afx send [builder] [message]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Send to all builders |
+| `--file <path>` | Include file content |
+| `--interrupt` | Send Ctrl+C first |
+| `--raw` | Skip structured formatting |
+| `--no-enter` | Don't press Enter after message |
+
+```bash
+afx send 0042 "PR approved, please merge"
+afx send 0585 "check the test output" --file /tmp/test-results.txt
+```
+
+## afx cleanup
+
+Removes a builder's worktree and branch after work is done.
+
+```
+afx cleanup [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --project <id>` | Builder project ID (no leading zeros: `585` not `0585`) |
+| `-i, --issue <number>` | Cleanup bugfix builder by issue number |
+| `-t, --task <id>` | Cleanup task builder (e.g., `task-bEPd`) |
+| `-f, --force` | Force cleanup even if branch not merged |
+
+```bash
+afx cleanup -p 585              # Clean up project 585
+afx cleanup -p 585 -f           # Force (unmerged branch)
+```
+
+**Note:** `afx cleanup` uses plain numbers (`585`), not zero-padded (`0585`). But `afx send` uses zero-padded IDs (`0585`).
+
+## afx status
+
+```bash
+afx status                      # Show all builders and workspace status
+```
+
+No flags needed. Shows Tower status, workspace, and all active builders.
+
+## afx 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
+```

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

@@ -1,6 +1,6 @@
 ---
 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 `af` which have their own skills). Use when setting up new projects, adding codev to existing repos, updating framework files, or diagnosing missing dependencies.
+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
@@ -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/, af-config.json, .gitignore.
+Creates a **new directory** with the full codev structure: specs/, plans/, reviews/, protocols, CLAUDE.md, AGENTS.md, .claude/skills/, .codev/config.json, .gitignore.
 
 ```bash
 codev init my-app              # Interactive setup
@@ -53,7 +53,7 @@ codev doctor
 
 ## Common mistakes
 
-- There is NO `codev tower` command — use `af tower start/stop`
+- 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

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

@@ -30,7 +30,7 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 -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, tick, maintain
+--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

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

@@ -1,6 +1,6 @@
 ---
 name: porch
-description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, TICK, 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.
+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
@@ -31,7 +31,7 @@ Gates are human-only approval checkpoints. The `--a-human-explicitly-approved-th
 |------|----------|------|
 | `spec-approval` | SPIR | After spec is written |
 | `plan-approval` | SPIR | After plan is written |
-| `pr` | SPIR, TICK, AIR | After PR is created |
+| `pr` | SPIR, AIR | After PR is created |
 
 ```bash
 porch approve 42 spec-approval --a-human-explicitly-approved-this

package/skeleton/DEPENDENCIES.md

@@ -218,7 +218,7 @@ Ensure no firewall is blocking the ports (default: 4200-4299):
 lsof -i :4200
 
 # Clean up stale port allocations
-af ports cleanup
+afx ports cleanup
 ```
 
 ### gh authentication issues

package/skeleton/builders.md

@@ -1,6 +1,6 @@
 # Active Builders
 
-> **Note**: Builder status is now tracked automatically via SQLite database and the Tower dashboard. Use `af status` to check all builders. This file is retained as a reference for status values only.
+> **Note**: Builder status is now tracked automatically via SQLite database and the Tower dashboard. Use `afx status` to check all builders. This file is retained as a reference for status values only.
 
 ## Status Values
 
@@ -13,7 +13,7 @@
 ## Commands
 
 ```bash
-af status              # Check all builder statuses
-af spawn <id>          # Spawn a new builder
-af cleanup -p <id>     # Clean up a completed builder
+afx status              # Check all builder statuses
+afx spawn <id>          # Spawn a new builder
+afx cleanup -p <id>     # Clean up a completed builder
 ```

package/skeleton/protocol-schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://codev.dev/protocol-schema.json",
   "title": "Codev Protocol Definition",
-  "description": "Schema for porch protocol definitions (SPIR, TICK, BUGFIX, etc.)",
+  "description": "Schema for porch protocol definitions (SPIR, BUGFIX, AIR, etc.)",
   "type": "object",
   "required": ["name", "phases"],
   "properties": {
@@ -12,7 +12,7 @@
     },
     "name": {
       "type": "string",
-      "description": "Protocol name (e.g., 'spir', 'tick', 'bugfix')",
+      "description": "Protocol name (e.g., 'spir', 'bugfix', 'air')",
       "pattern": "^[a-z][a-z0-9-]*$"
     },
     "alias": {

package/skeleton/protocols/air/builder-prompt.md

@@ -38,20 +38,20 @@ Follow the AIR protocol: `codev/protocols/air/protocol.md`
 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 `af send architect "PR #N ready for review (implements #{{issue.number}})"`
+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.
 
 If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via:
 ```bash
-af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
+afx send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR."
 ```
 
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **PR ready**: `af send architect "PR #N ready for review (implements #{{issue.number}})"`
-- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"`
+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

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

@@ -15,15 +15,27 @@ Create a pull request with the review embedded in the PR body, optionally run CM
 
 ### 1. Create the Pull Request
 
-Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan:
+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.
 
 ```bash
-gh pr create --title "[Air #{{issue.number}}] feat: <brief description>" --body "$(cat <<'EOF'
+gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the feature>
 
-Implements #{{issue.number}}
+Closes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## What Changed
 
@@ -75,12 +87,12 @@ If you ran CMAP:
 Send notification with PR link:
 
 ```bash
-af send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
+afx send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
 ```
 
 If CMAP was run, include verdicts:
 ```bash
-af send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
+afx send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
 ```
 
 ## Signals

package/skeleton/protocols/air/protocol.md

@@ -34,7 +34,6 @@ AIR is a minimal protocol for implementing small features (< 300 LOC) where the
 
 - Bug fixes → use **BUGFIX**
 - Features needing spec discussion → use **SPIR** or **ASPIR**
-- Amendments to existing specs → use **TICK**
 - Architectural changes → use **SPIR**
 - Complex features with multiple phases → use **SPIR** or **ASPIR**
 
@@ -67,7 +66,7 @@ The **PR gate** is preserved — a human reviews all code before merge.
 
 ```bash
 # Spawn a builder using AIR
-af spawn 42 --protocol air
+afx spawn 42 --protocol air
 
 # The builder implements autonomously and stops at the PR gate
 ```

package/skeleton/protocols/aspir/builder-prompt.md

@@ -27,7 +27,7 @@ You are running in STRICT mode. This means:
 {{/if}}
 
 ## Protocol
-Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
+Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
 Read and internalize the protocol before starting any work.
 
 {{#if spec}}
@@ -53,12 +53,34 @@ Follow the implementation plan at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
+## Multi-PR Workflow
+
+Your worktree is persistent — it survives across PR merges. You can produce multiple PRs sequentially:
+
+1. Cut a branch, open a PR, wait for merge
+2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
+3. Continue to the next phase, open another PR
+
+**Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
+
+Record PRs: `porch done {{project_id}} --pr <N> --branch <name>`
+Record merges: `porch done {{project_id}} --merged <N>`
+
+## Verify Phase
+
+After the final PR merges, the project enters the **verify** phase. You stay alive through verify:
+1. Pull main into your worktree
+2. Run `porch done {{project_id}}` to signal verification is ready
+3. The architect approves `verify-approval` when satisfied
+
+If verification is not needed: `porch verify {{project_id}} --skip "reason"`
+
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **Gate reached**: `af send architect "Project {{project_id}}: <gate-name> ready for approval"`
-- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"`
-- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."`
+- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`
 
 ## Handling Flaky Tests