@cluesmith/codev 3.0.6 → 3.1.1

package/skeleton/protocols/pir/prompts/review.md

@@ -4,7 +4,7 @@ You are executing the **REVIEW** phase of the PIR protocol.
 
 ## Your Goal
 
-Write a retrospective at `codev/reviews/{{artifact_name}}.md` including **Summary**, **Architecture Updates**, and **Lessons Learned Updates** sections. Push, open a PR using the review file as the PR body, record the PR with porch, then signal completion — **porch runs CMAP-2 (Gemini + Codex) once** via the verify block. CMAP is a *single advisory pass* (`max_iterations: 1`): its verdicts are surfaced to the human at the `pr` gate, **not** an iterate-until-APPROVE loop. After the single pass the `pr` gate fires regardless of verdict; you notify the architect (leading with any REQUEST_CHANGES) and wait at the gate while the human merges on GitHub.
+Write a retrospective at `codev/reviews/{{artifact_name}}.md` including **Summary**, **Architecture Updates**, and **Lessons Learned Updates** sections. Push, open a PR using the review file as the PR body, record the PR with porch, then signal completion — **porch runs 3-way consultation (Gemini, Codex, Claude) once** via the verify block. The consultation is a *single advisory pass* (`max_iterations: 1`): its verdicts are surfaced to the human at the `pr` gate, **not** an iterate-until-APPROVE loop. After the single pass the `pr` gate fires regardless of verdict; you notify the architect (leading with any REQUEST_CHANGES) and wait at the gate while the human merges on GitHub.
 
 The retrospective ships with the merged PR — it's durable team knowledge, searchable in `codev/reviews/` on `main`.
 
@@ -38,7 +38,7 @@ Fixes #{{issue.number}}
 
 ## Files Changed
 
-Output of `git diff --stat main`, formatted as a list:
+Output of `git diff --stat "$MERGE_BASE"`, formatted as a list (resolve once: `DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'); DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}; MERGE_BASE=$(git merge-base "$DEFAULT_BRANCH" HEAD)`. Anchoring at the merge-base keeps the file list scoped to *your* changes, not commits the base branch absorbed after you branched.):
 
 - `path/to/file.ts` (+12 / -3)
 - `path/to/new-file.ts` (+45 / -0)
@@ -123,7 +123,7 @@ gh pr edit <PR-number> --body-file codev/reviews/{{artifact_name}}.md
 
 ### 4a. Record the PR with Porch
 
-Immediately after creating the PR, tell porch about it so `status.yaml` carries the PR number and branch. This is a metadata-only call — it does NOT advance the phase or trigger CMAP:
+Immediately after creating the PR, tell porch about it so `status.yaml` carries the PR number and branch. This is a metadata-only call — it does NOT advance the phase or trigger the consultation:
 
 ```bash
 porch done {{project_id}} --pr <PR-number> --branch "$(git branch --show-current)"
@@ -131,7 +131,7 @@ porch done {{project_id}} --pr <PR-number> --branch "$(git branch --show-current
 
 Without this, porch's `history:` for the project stays empty and downstream tooling (status views, analytics, audit trails) can't link the porch project to its GitHub PR.
 
-### 5. Signal Completion to Porch (porch runs CMAP-2)
+### 5. Signal Completion to Porch (porch runs 3-way consultation)
 
 ```bash
 porch done {{project_id}}
@@ -139,14 +139,14 @@ porch done {{project_id}}
 
 Porch will:
 1. Run the `pr_exists` / `review_has_arch_updates` / `review_has_lessons_updates` checks.
-2. **Execute CMAP-2 (Gemini + Codex) automatically** via the protocol's `verify` block. Outputs land in `codev/projects/{{project_id}}-<slug>/{{project_id}}-gemini.txt` and `<id>-codex.txt`.
-3. CMAP runs **exactly once** (`max_iterations: 1`). Whatever the verdicts, porch records them in `status.yaml` and advances to the `pr` gate — there is **no automated re-review pass and no "stays in the review phase" loop**. `APPROVE` and `REQUEST_CHANGES` differ only in what you must surface to the human (steps 6–7), not in whether the gate fires. The output of `porch done` surfaces the verdicts.
+2. **Run 3-way consultation (Gemini, Codex, Claude) automatically** via the protocol's `verify` block. Outputs land in `codev/projects/{{project_id}}-<slug>/{{project_id}}-gemini.txt`, `<id>-codex.txt`, and `<id>-claude.txt`.
+3. The consultation runs **exactly once** (`max_iterations: 1`). Whatever the verdicts, porch records them in `status.yaml` and advances to the `pr` gate — there is **no automated re-review pass and no "stays in the review phase" loop**. `APPROVE` and `REQUEST_CHANGES` differ only in what you must surface to the human (steps 6–7), not in whether the gate fires. The output of `porch done` surfaces the verdicts.
 
-> **Why CMAP-2, not CMAP-3?** PIR's design parallels BUGFIX/AIR's consult footprint. The human already approved the *running* implementation at the `dev-approval` gate; CMAP at PR is a pre-merge hygiene + code-quality pass, not a functional review.
+> **Why consult after the human already approved the running code?** The human approved the *running* implementation at the `dev-approval` gate; the 3-way consultation at the PR is a pre-merge hygiene + code-quality pass, not a functional review.
 
 ### 6. Handle a REQUEST_CHANGES Verdict (single-pass — no automated re-review)
 
-PIR's CMAP is one advisory pass (`max_iterations: 1`). If a reviewer returns `REQUEST_CHANGES`, porch does **not** loop or re-run CMAP — it records the verdict and proceeds to the `pr` gate. There is no iter-2. The correctness backstop for a CMAP-flagged issue is therefore **(a)** your fix + a regression test and **(b)** the human's `pr`-gate review — *not* an independent model re-review. Treat that as load-bearing: a substantive finding you "address and rebut" gets no second AI opinion.
+PIR's consultation is one advisory pass (`max_iterations: 1`). If a reviewer returns `REQUEST_CHANGES`, porch does **not** loop or re-run it — it records the verdict and proceeds to the `pr` gate. There is no iter-2. The correctness backstop for a consultation-flagged issue is therefore **(a)** your fix + a regression test and **(b)** the human's `pr`-gate review — *not* an independent model re-review. Treat that as load-bearing: a substantive finding you "address and rebut" gets no second AI opinion.
 
 For any `REQUEST_CHANGES`:
 
@@ -154,22 +154,23 @@ For any `REQUEST_CHANGES`:
 2. **Assess it honestly:**
    - **Real defect** (correctness / cancellation / security / data-loss): fix it in code, add a regression test that fails without the fix, commit + push (the PR updates automatically — no new `gh pr create`). Then document the finding, your fix, and the pinning test in the review file's **"Things to Look At During PR Review"** section.
    - **False positive / out of scope**: write a brief rebuttal in that same section explaining why no change is warranted.
-3. Do **not** re-run `porch done` expecting another CMAP — `max_iterations: 1` means it will not re-review. Proceed to step 7.
+3. Do **not** re-run `porch done` expecting another consultation pass — `max_iterations: 1` means it will not re-review. Proceed to step 7.
 
 Whether you fixed it or rebutted it, a `REQUEST_CHANGES` that PIR will never re-check **must be escalated to the human at the `pr` gate** (step 7) — they are the only remaining reviewer of that decision.
 
-### 7. Notify the Architect (after the single CMAP pass — gate is now pending)
+### 7. Notify the Architect (after the single consultation pass — gate is now pending)
 
-After the one CMAP pass + structural checks, porch fires the **`pr` gate** (pending) **regardless of the verdicts**. Read the verdicts from porch state and notify — and if any verdict is `REQUEST_CHANGES`, **lead with it and state the disposition**, because PIR will not re-review it and the human at the `pr` gate is the only remaining check:
+After the one consultation pass + structural checks, porch fires the **`pr` gate** (pending) **regardless of the verdicts**. Read the verdicts from porch state and notify — and if any verdict is `REQUEST_CHANGES`, **lead with it and state the disposition**, because PIR will not re-review it and the human at the `pr` gate is the only remaining check:
 
 ```bash
 GEMINI_VERDICT=$(grep -m1 -i '^\(approve\|request_changes\|comment\)' "codev/projects/{{project_id}}-"*/"{{project_id}}-gemini.txt" || echo UNKNOWN)
 CODEX_VERDICT=$(grep -m1 -i '^\(approve\|request_changes\|comment\)' "codev/projects/{{project_id}}-"*/"{{project_id}}-codex.txt" || echo UNKNOWN)
+CLAUDE_VERDICT=$(grep -m1 -i '^\(approve\|request_changes\|comment\)' "codev/projects/{{project_id}}-"*/"{{project_id}}-claude.txt" || echo UNKNOWN)
 
-if echo "$GEMINI_VERDICT $CODEX_VERDICT" | grep -qi request_changes; then
-  afx send architect "⚠️ PR #<M> (PIR #{{issue.number}}): CMAP returned REQUEST_CHANGES (gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT). Disposition: <one line — fixed in <sha> + regression test | rebutted, see review 'Things to Look At'>. PIR is single-pass — this was NOT independently re-reviewed; please verify the fix/rebuttal at the pr gate before approving. Full verdicts in codev/projects/{{project_id}}-*/."
+if echo "$GEMINI_VERDICT $CODEX_VERDICT $CLAUDE_VERDICT" | grep -qi request_changes; then
+  afx send architect "⚠️ PR #<M> (PIR #{{issue.number}}): 3-way consultation returned REQUEST_CHANGES (gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT, claude=$CLAUDE_VERDICT). Disposition: <one line — fixed in <sha> + regression test | rebutted, see review 'Things to Look At'>. PIR is single-pass — this was NOT independently re-reviewed; please verify the fix/rebuttal at the pr gate before approving. Full verdicts in codev/projects/{{project_id}}-*/."
 else
-  afx send architect "PR #<M> ready for review (PIR #{{issue.number}}). CMAP all clear: gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT. Awaiting human merge + pr gate approval. Full verdicts in codev/projects/{{project_id}}-*/."
+  afx send architect "PR #<M> ready for review (PIR #{{issue.number}}). 3-way consultation all clear: gemini=$GEMINI_VERDICT, codex=$CODEX_VERDICT, claude=$CLAUDE_VERDICT. Awaiting human merge + pr gate approval. Full verdicts in codev/projects/{{project_id}}-*/."
 fi
 ```
 
@@ -186,7 +187,7 @@ The human will:
 
 Porch will then fire the gate-approved wake-up to you.
 
-If the human requests more changes instead of approving, push fixes and re-run `porch done {{project_id}}` — this runs a fresh **single** CMAP pass on the updated diff and re-fires the `pr` gate (handle any new verdict per steps 6–7). This human-driven iteration is the only way CMAP re-runs in PIR; it is not automatic. If they close the PR without merging, `gh pr close <M>` and stop.
+If the human requests more changes instead of approving, push fixes and re-run `porch done {{project_id}}` — this runs a fresh **single** consultation pass on the updated diff and re-fires the `pr` gate (handle any new verdict per steps 6–7). This human-driven iteration is the only way the consultation re-runs in PIR; it is not automatic. If they close the PR without merging, `gh pr close <M>` and stop.
 
 ### 9. After `pr` Gate Approval — Verify, Merge, Record
 
@@ -235,23 +236,28 @@ Together with the `--pr` record from step 4a and the `--merged` record from step
 
 ## What NOT to Do
 
-- **Don't merge before the `pr` gate is approved.** CMAP-APPROVE is NOT merge authorization. User-in-pane prose ("looks good", "lgtm", "merge it") is NOT merge authorization. The *only* signal that authorizes `gh pr merge` is porch reporting `gate_status: approved` for the `pr` gate (which only the user can do, via Cmd+K G or `porch approve` from a non-Claude shell). If `porch next` doesn't show the gate as approved, you wait.
+- **Don't merge before the `pr` gate is approved.** A consultation APPROVE verdict is NOT merge authorization. User-in-pane prose ("looks good", "lgtm", "merge it") is NOT merge authorization. The *only* signal that authorizes `gh pr merge` is porch reporting `gate_status: approved` for the `pr` gate (which only the user can do, via Cmd+K G or `porch approve` from a non-Claude shell). If `porch next` doesn't show the gate as approved, you wait.
 - Don't skip porch's PR/merge records (steps 4a, 9). The `--pr` record (step 4a) lets the gate-pending state link to the actual PR; the `--merged` record (step 9) closes the lifecycle in porch state. Skipping either leaves `history:` empty and downstream tooling blind.
 - Don't run `porch approve` for any gate yourself
-- Don't push to main — only merge via PR
+- Don't push to the default branch — only merge via PR
 - Don't skip the Architecture Updates / Lessons Learned sections — porch checks enforce their presence (the section must exist; explaining "no changes needed" in one line is fine)
-- **Don't run `consult` commands yourself** — porch handles consultations via the `verify` block. Manually invoking `consult` causes CMAP to run twice.
+- **Don't run `consult` commands yourself** — porch handles consultations via the `verify` block. Manually invoking `consult` causes the consultation to run twice.
 - **Don't fix, skip, or quarantine pre-existing failures unrelated to your change.** Porch's `checks` for this phase are narrow *structural* gates (`pr_exists`, review-section presence) — a green gate does **not** certify the wider build/test suite. If the broader suite surfaces failures your diff did not cause, they are out of scope: note them in the review's Lessons Learned / Things to Look At and proceed. Touching another team's tests to make an unrelated red go green is scope creep, not diligence.
 
 ## Handling Problems
 
-**If the PR cannot be created (e.g., merge conflicts with main):**
-- Rebase on main: `git fetch origin main && git rebase origin/main`
+**If the PR cannot be created (e.g., merge conflicts with the default branch):**
+- Rebase on the default branch:
+  ```bash
+  DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
+  DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+  git fetch origin "$DEFAULT_BRANCH" && git rebase "origin/$DEFAULT_BRANCH"
+  ```
 - Resolve conflicts (do NOT use destructive shortcuts)
 - Force-push with lease: `git push --force-with-lease`
 - Re-run `gh pr create`
 
-**If porch's CMAP consults fail (e.g., model unavailable):**
+**If porch's consultation fails (e.g., model unavailable):**
 - `porch done` will report the failure. Inspect `codev/projects/{{project_id}}-*/{{project_id}}-<model>.txt` for the failure details.
 - Re-run `porch done {{project_id}}` once — porch will retry the consult.
 - If the model is persistently unavailable, notify the architect and ask whether to proceed without that model's verdict. They may direct you to skip via a manual override.

package/skeleton/protocols/pir/protocol.json

@@ -70,7 +70,7 @@
     {
       "id": "review",
       "name": "Review",
-      "description": "Write retrospective (arch + lessons), push, open PR with review as body, run CMAP, then wait at pr gate while the human merges on GitHub",
+      "description": "Write retrospective (arch + lessons), push, open PR with review as body, run 3-way consultation, then wait at pr gate while the human merges on GitHub",
       "type": "build_verify",
       "build": {
         "prompt": "review.md",

package/skeleton/protocols/pir/protocol.md

@@ -101,7 +101,7 @@ The builder:
 2. Updates `codev/resources/arch.md` and/or `codev/resources/lessons-learned.md` if real changes need recording. If not, the review file's sections state "no changes needed" with a one-line explanation (the porch `checks` block enforces section presence, not content).
 3. Commits the review file (and arch / lessons updates if any) and pushes
 4. Opens a PR with `gh pr create`; PR body is the review file content + `Fixes #<N>`. Records the PR with `porch done <id> --pr <M> --branch <name>`.
-5. Runs `porch done <id>` — porch's `verify` block runs CMAP-2 (Gemini + Codex, type=impl) as a **single advisory pass** (`max_iterations: 1`); CMAP outputs land in `codev/projects/<id>-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir.
+5. Runs `porch done <id>` — porch's `verify` block runs 3-way consultation (Gemini, Codex, Claude; type=impl) as a **single advisory pass** (`max_iterations: 1`); consultation outputs land in `codev/projects/<id>-*/`. There is no iterate-until-APPROVE loop: whatever the verdicts, porch records them and advances to the `pr` gate. A `REQUEST_CHANGES` is not auto-re-reviewed — the builder addresses or rebuts it, adds a regression test if it's a real defect, and escalates it in the architect notification so the human verifies it at the `pr` gate. Outcomes are not auto-appended to the PR body; reviewers with the worktree read them from the projects dir.
 6. The `pr` gate fires (pending) regardless of verdict. Builder notifies the architect once — leading with any `REQUEST_CHANGES` and its disposition (since PIR will not re-review it) rather than burying it in a flat status line.
 7. Builder waits at the `pr` gate. The human reviews the PR on GitHub, then approves the `pr` gate (Cmd+K G or `porch approve <id> pr --a-human-explicitly-approved-this`). Porch wakes the builder.
 8. Builder verifies the gate is genuinely approved via `porch next` (defensive — typed prose can't trigger this branch, only real porch state does), then runs `gh pr merge --merge`, records via `porch done --merged <M>`, and sends the cleanup-ready notification. Protocol complete (`next: null`).
@@ -152,13 +152,11 @@ Without `worktree.devCommand`, `afx dev` won't work and the `dev-approval` gate
 
 - **plan**: human-only review. No AI consultation.
 - **implement**: no AI consult — the human at the `dev-approval` gate is the sole reviewer of the running code.
-- **review**: CMAP-2 (Gemini + Codex, type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same pattern as BUGFIX / AIR's PR-creation consult.
+- **review**: 3-way consultation (Gemini, Codex, Claude; type=impl) after the PR is opened, as a **single advisory pass** (`max_iterations: 1`). Same consult type (`impl`) as BUGFIX / AIR's PR-creation consult.
 
-CMAP at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger CMAP; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (CMAP does not re-check it).
+The consultation at the PR is a single pass — there is **no iterate-until-APPROVE loop**. A `REQUEST_CHANGES` does not block or re-trigger it; the builder addresses or rebuts it and escalates it to the human at the `pr` gate, who is the sole remaining reviewer of any resulting fix (the consultation does not re-check it).
 
-Net: PIR runs **two model calls per protocol run**, matching its BUGFIX/AIR peers — its distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density.
-
-**The 2-model footprint is a design invariant.** porch's model precedence is *config > protocol* (`porch.consultation.models` in `.codev/config.json` overrides a protocol's declared `verify.models`). A project-wide setting tuned for SPIR (gemini + codex + claude) will silently inflate PIR to a 3-model pass, breaking the BUGFIX/AIR-parity cost story. To keep PIR at CMAP-2, leave `porch.consultation.models` unset or scope it per-protocol.
+Net: PIR's distinguishing features are the two human gates (`plan-approval`, `dev-approval`), not AI-consult density.
 
 To disable consultation entirely, say "without multi-agent consultation" when starting work.
 

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

@@ -74,11 +74,11 @@ The architect MAY request a PR at any point — for spec review, mid-implementat
 Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
 
 1. Cut a branch, open a PR, wait for merge
-2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
+2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
 3. Continue to the next slice, open another PR
 4. Repeat
 
-**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.
+**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.
 
 Record PRs in status.yaml: `porch done {{project_id}} --pr <N> --branch <name>`
 Record merges: `porch done {{project_id}} --merged <N>`
@@ -86,7 +86,7 @@ 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
+1. Pull the integration branch into your worktree
 2. Run `porch done {{project_id}}` to signal verification is ready
 3. The architect approves `verify-approval` when satisfied
 

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

@@ -28,10 +28,14 @@ You are performing a final self-check during the Review phase. The builder has c
    - Are any new APIs documented?
 
 5. **PR Readiness**
-   - Is the branch up to date with main?
+   - Is the branch up to date with its base (the integration branch the PR targets)?
    - Are commits atomic and well-described?
    - Is the change diff reasonable in size?
 
+## 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.
+
 ## Verdict Format
 
 After your review, provide your verdict in exactly this format:

package/skeleton/roles/builder.md

@@ -140,6 +140,27 @@ porch status      # (strict mode) Your project status
 afx status         # All builders
 ```
 
+## Thread file
+
+You maintain a free-text markdown log at `codev/state/<builder-id>_thread.md` (relative to your worktree). This is the cohort's collective situational-awareness surface — architects and sibling builders can read it via plain file I/O.
+
+**Path resolution**: `<builder-id>` is the basename of your worktree path. Resolve it once with `basename "$(pwd)"`. Example: if your worktree is `.builders/spir-823/`, the path is `codev/state/spir-823_thread.md`.
+
+**Directory creation**: `codev/state/` likely doesn't exist when you start (it's greenfield). Your first write creates it — the Write tool's `mkdir -p` semantics handle this transparently. No need to pre-create the directory.
+
+**What to write**: phase transitions, decisions, blockers, anything worth recording for the cohort. Trust your own judgement about what's useful. There is no required schema, no required sections, no timestamp format. The thread is yours.
+
+**When to write**: at phase boundaries and at any other moment you think a future reader would want to know what happened. Don't over-engineer cadence — append when there's something to say.
+
+**Discovery**:
+- **In-flight** (while you're active): your thread lives in your worktree at `.builders/<builder-id>/codev/state/<builder-id>_thread.md` (from the main workspace root). Architects read it with `cat .builders/<id>/codev/state/<id>_thread.md`; they discover threads with `ls .builders/*/codev/state/*.md`.
+- **Sibling builders**: read each other's threads via `cat ../<sibling-id>/codev/state/<sibling-id>_thread.md` from your own worktree (the parent `.builders/` directory is shared between all builders in the workspace).
+- **Post-merge**: after your PR merges, your thread lands in `codev/state/` on `main` (parallel to `codev/reviews/`) and becomes part of the historical review record.
+
+**Commit/retention rule**: **the default disposition is COMMIT.** Stage and commit your thread file as part of your PR. The rare exception — when your thread turned out to be noise rather than useful narrative — is an explicit decision to strip it before PR (via gitignore for the PR or by not staging the file). Silently leaving the thread uncommitted by accident is a bug, not an exercise of the exception. The cohort's situational-awareness goal depends on threads surviving to `main`.
+
+**Scope reminder**: this is for the cohort's situational awareness, not porch's tracking. Porch does not read this file. There are no hooks, no validation, no enforcement.
+
 ## Notifications
 
 **ALWAYS notify the architect** via `afx send` at these key moments:

package/skeleton/templates/AGENTS.md

@@ -85,6 +85,26 @@ For complete reference, see `codev/resources/commands/`:
 - `codev/resources/commands/agent-farm.md` - Agent Farm commands
 - `codev/resources/commands/consult.md` - Consultation commands
 
+## Inter-agent messaging
+
+Agents within a workspace communicate through `afx send`. Four addressing forms are supported:
+
+| Form | Meaning | Allowed from |
+|---|---|---|
+| `afx send <builder-id> "msg"` | Send to a specific builder (e.g. `afx send 0042 "..."`). | Any sender. |
+| `afx send architect "msg"` | From a builder: routes to the spawning architect via affinity. From an architect (or any non-builder sender): routes to the architect named `main` if present, else the first registered architect. | Any sender. |
+| `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
+| `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
+
+**Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.
+
+**Builder spoofing-check**: a builder may only address its own spawning architect via `architect:<name>`. The spoofing check is enforced by Tower's message router; attempts to address a different architect from a builder are rejected.
+
+**Discovering active agents**:
+
+- `afx status` lists all architects alongside builders, with names, terminal IDs, and PIDs where available.
+- Each active builder maintains a free-text narrative log at `codev/state/<builder-id>_thread.md` (relative to its worktree). **In-flight discovery**: `ls .builders/*/codev/state/*.md` and `cat .builders/<id>/codev/state/<id>_thread.md`. **Post-merge discovery**: after a builder's PR merges, its thread lands in `codev/state/` on `main` — list with `ls codev/state/` and read with `cat codev/state/<builder-id>_thread.md` from the main checkout.
+
 ## Configuration
 
 Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.

package/skeleton/templates/CLAUDE.md

@@ -83,6 +83,26 @@ For complete reference, see `codev/resources/commands/`:
 - `codev/resources/commands/agent-farm.md` - Agent Farm commands
 - `codev/resources/commands/consult.md` - Consultation commands
 
+## Inter-agent messaging
+
+Agents within a workspace communicate through `afx send`. Four addressing forms are supported:
+
+| Form | Meaning | Allowed from |
+|---|---|---|
+| `afx send <builder-id> "msg"` | Send to a specific builder (e.g. `afx send 0042 "..."`). | Any sender. |
+| `afx send architect "msg"` | From a builder: routes to the spawning architect via affinity. From an architect (or any non-builder sender): routes to the architect named `main` if present, else the first registered architect. | Any sender. |
+| `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
+| `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
+
+**Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.
+
+**Builder spoofing-check**: a builder may only address its own spawning architect via `architect:<name>`. The spoofing check is enforced by Tower's message router; attempts to address a different architect from a builder are rejected.
+
+**Discovering active agents**:
+
+- `afx status` lists all architects alongside builders, with names, terminal IDs, and PIDs where available.
+- Each active builder maintains a free-text narrative log at `codev/state/<builder-id>_thread.md` (relative to its worktree). **In-flight discovery**: `ls .builders/*/codev/state/*.md` and `cat .builders/<id>/codev/state/<id>_thread.md`. **Post-merge discovery**: after a builder's PR merges, its thread lands in `codev/state/` on `main` — list with `ls codev/state/` and read with `cat codev/state/<builder-id>_thread.md` from the main checkout.
+
 ## Configuration
 
 Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.