Multi-architect coordination: builder attribution, messaging docs, builder thread state, VSCode add-refresh

[waleedkadous]

Summary

Follow-up to #786. Four coherent deliverables that finish the multi-architect coordination story by making the who-spawned-whom relationship visible, documenting how architects and builders message each other, giving each builder a free-text thread file so the cohort has collective situational awareness, and closing a VSCode tree-refresh gap noted at PR-iter-3 of #786.

Run as a SPIR — items 3 + 4 have moderate design choices that benefit from spec + plan gates.

Deliverables

1. Dashboard builder attribution (when N>1)

When state.architects.length > 1, each builder card in the dashboard renders a small "spawned by <architect>" tag. Data already exists on Builder.spawnedByArchitect (added in #755, routed correctly in #774). Conditional render keeps the N=1 case visually identical to today.

VSCode parity is deliberately deferred to a follow-up — the dashboard surface is the higher-leverage one.

2. Inter-agent messaging docs in CLAUDE.md / AGENTS.md

Document what's already supported in code (no new behavior — surface the existing primitives):

• afx status lists architect names alongside builders
• afx send architect:<name> \"msg\" — works from any sender (architect or builder); explicit form
• afx send architect \"msg\" from a builder routes to the spawning architect via the affinity primitive (the Multi-architect routing: builder→architect messages misrouted to 'main' when worktree has its own state.db #774 fix)
• afx send <builder-id> \"msg\" — addresses any builder
• Architect ↔ sibling architect messaging already works today (per Multi-architect feature is underbaked — gaps in lifecycle, persistence, and UX #786 spec test scenario API Research Failures - AI Assumes APIs Exist Without Verification #8 — sender = architect bypasses the spoofing check, so main running afx send architect:ob-refine \"hi\" lands on ob-refine's terminal). It's in code; it's just undocumented. Surface it.

Both CLAUDE.md and AGENTS.md must stay synchronized.

3. codev/state/<builder-id>_thread.md — per-builder free-text thread

Each builder maintains a free-text markdown file at codev/state/<builder-id>_thread.md. Just a file. The builder (LLM) writes to it in natural language — phase transitions, decisions, blockers, anything it deems worth recording for collective situational awareness.

Trust the LLM. No structured schema, no porch hooks, no timestamp formatter. The thread is free text.

What the spec needs to pin: just location (codev/state/<builder-id>_thread.md) and an instruction in the builder's protocol prompt telling them to maintain it. Any architect or builder can read any thread file via plain file I/O — discoverability falls out of the markdown ecosystem (ls codev/state/, file browsers, etc.).

4. VSCode Architects tree auto-refresh on add (Co2 from #786 PR-iter-3 CMAP)

The VSCode WorkspaceProvider tree refreshes on remove (because codev.removeArchitect self-triggers the refresh) but does NOT refresh on add via CLI — Tower has no SSE event for architect lifecycle changes. Today the user sees a stale Architects tree until they click Refresh on the sidebar.

Fix shape:

• Tower-side: emit an architects-updated SSE event on add/remove (parallels worktree-config-updated)
• VSCode WorkspaceProvider: subscribe to that event, fire changeEmitter
• Dashboard parity: the dashboard's polling will pick it up naturally; verify

Already documented in verify-scenarios.md Scenario 11 as a known limitation; this deliverable closes the gap.

Why a SPIR (and not separate protocols)

Items 1+2+3+4 cohere as one "multi-architect coordination" feature pass:

• (1) makes you see who spawned whom
• (2) tells you how to talk to them
• (3) keeps a record of what they're doing
• (4) keeps the VSCode surface honest about who exists

Splitting into separate issues would lose that thread and risk shipping the easy parts while the design-heavier ones drift.

Out of scope

• VSCode parity for item 1 (builder attribution in tree) — separate follow-up
• Cross-workspace messaging — still deferred (per Multi-architect support: per-architect identity + builder-to-architect message routing #755 and Multi-architect feature is underbaked — gaps in lifecycle, persistence, and UX #786)
• Renaming architects — separate follow-up
• Workspace-scoping of state.db.architect (Co1 from Multi-architect feature is underbaked — gaps in lifecycle, persistence, and UX #786 PR-iter-3) — needs schema migration; defer until multi-workspace Tower architect routing becomes a goal

Suggested approach

Strict SPIR with the usual spec-approval and plan-approval gates.

Related

• Multi-architect support: per-architect identity + builder-to-architect message routing #755 — multi-architect primitive (v3.0.5)
• Surface multiple architects in Tower dashboard + VS Code extension + afx status #761 — dashboard tab strip (v3.0.6)
• Multi-architect routing: builder→architect messages misrouted to 'main' when worktree has its own state.db #774 — routing fix (v3.0.8)
• Multi-architect feature is underbaked — gaps in lifecycle, persistence, and UX #786 — current SPIR shipping lifecycle/persistence/UX. Multi-architect coordination: builder attribution, messaging docs, builder thread state, VSCode add-refresh #823 builds on the foundation Multi-architect feature is underbaked — gaps in lifecycle, persistence, and UX #786 lands.