v3.1.3 Jacobean

v3.1.3 Jacobean

Released: 2026-05-24

Two structural ships and one cleanup, all in service of letting the panel-of-architects pattern run unattended for days at a time.

Workspace recover — survive machine reboots (PR #833, @amrmelsayed)

The missing piece in Tower's "leave it running" story. After a machine reboot or crash, in-flight builders go silent — worktrees and branches survive but the shellper processes don't. afx workspace recover enumerates porch projects, identifies builders whose shellper died, and respawns them.

afx workspace recover                  # dry-run preview (default)
afx workspace recover --apply          # actually respawn (with confirmation)
afx workspace recover --apply --yes    # unattended
afx workspace recover --max-age 30     # widen the recency window

• Builder conversation resume for SPIR / ASPIR / AIR / PIR / bugfix — the revived claude process picks up the prior session via --resume <uuid>, discovered from the on-disk jsonl store
• Main architect conversation resume after reboot, via the same jsonl-discovery mechanism (single-architect workspaces; multi-architect resume deferred to #832)
• Sequential respawn with bounded concurrency; idempotent — safe to re-run

Multi-architect: a panel, not a soloist

On large projects the work isn't one strand — it's several. UI to fix. Test infra to improve. Backend to refactor. Putting all of it in front of one architect agent makes a mess of the context — conventions, debugging strategies, and schema invariants all colliding. The agent gets worse at all three jobs as the day goes on.

Multi-architect treats the workspace as a panel. There's still a main "chief" architect with the broadest view, but you spin up sub-architects per subsystem:

afx workspace add-architect --name ui-refresh
afx workspace add-architect --name test-infra
afx workspace add-architect --name backend-cleanup

Each has its own context, its own thread, its own in-flight builders. When a builder finishes, it routes back to the architect that spawned it — not a single global inbox.

What you get in 3.1.3:

• afx workspace add-architect / remove-architect lifecycle
• Sibling architects survive afx workspace stop/start and afx tower stop/start
• Identity preservation across shellper auto-restart
• Cross-workspace isolation — sibling architects in workspace A no longer leak into workspace B
• Dashboard tabs + VS Code Architects tree with right-click Remove
• Per-builder attribution: builder cards show · <architect> when N>1
• Sibling-to-sibling messaging — afx send architect:ob-refine "..." from main or another sibling
• Per-builder thread files at codev/state/<builder-id>_thread.md for collective situational awareness

CLI cleanup: codev afx is no longer a thing (PR #847)

• codev afx <subcommand>, codev agent-farm <subcommand> removed (exit non-zero with a helpful stderr suggesting the right form)
• Standalone af bin removed — was deprecated since v3.0.1; afx is the canonical entrypoint
• Standalone afx bin path is unchanged
• Removes a cross-cutting process.argv[1] invocation-style fragility that surfaced in PR #833 integration review

VS Code extension (Amr Elsayed)

Multiple rounds across PRs #771, #779, #785:

• Per-builder file inspection — changed files inline; click for two-way diff
• Codev: View Diff — whole worktree delta in the Multi Diff Editor
• Accordion mode — expanding one builder auto-collapses the others
• Live-status dot for active builders, count badge on the activity-bar icon
• Idle-builder detection — chat-bubble after 5 min of silent waiting
• Backlog hides issues that already have a builder
• Image paste (Cmd+Alt+V)
• Architects tree with right-click Remove and live auto-refresh
• Dev URL rows in the sidebar (worktree.devUrls)
• Per-engineer .codev/config.local.json overrides

Also recent

• Multi-PR builders (Spec 653): worktree, branch, PR decoupled — one builder, multiple PRs; draft PRs mid-flight for early review
• Runnable worktrees: afx dev <builder-id> / afx dev main, swap-detection across slots
• PIR protocol: plan/implement/review with two pre-PR human gates — for design-sensitive or pre-PR-testable changes (mobile, UI, cross-platform)
• RESEARCH protocol: 3-way parallel investigation + synthesis + critique → codev/research/<topic>.md
• Linear hybrid forge: Linear issues + GitHub PRs
• Per-stage consults: each phase picks its own reviewer models
• Inter-agent messaging documented end-to-end — all four addressing forms with spoofing-check semantics

Breaking changes

• codev afx <…>, codev agent-farm <…>, codev af <…> no longer dispatch — they exit non-zero with a stderr pointing at the standalone afx bin. Workaround is a one-character edit (drop the codev prefix). External scripts that hardcoded codev afx will need to be updated.
• Standalone af bin removed (deprecated since v3.0.1). Use afx directly.

Install

npm install -g @cluesmith/codev@3.1.3
afx tower stop && afx tower start

Multi-workspace adopters: nothing new to do — the cross-workspace isolation migration landed in 3.1.2.

Contributors

• Amr Elsayed (@amrmelsayed) — afx workspace recover (PR #833) including 7 iterations of CMAP discipline that caught real bugs at every round; ongoing VS Code extension stewardship.
• M Waleed Kadous (@waleedkadous) — architect review, integration CMAP, the call to remove the codev afx wrapper surface rather than patch the spawn child.
• Builder working under AIR protocol on the CLI cleanup (PR #847).

v3.1.2 Jacobean

v3.1.2 Jacobean

Released: 2026-05-23

Critical patch on the Jacobean line. Fixes the cross-workspace sibling-architect leak introduced by v3.1.1's #786 lifecycle work — a release-blocker that surfaced within minutes of v3.1.1 going live (the architect's own machine experienced it during post-release verify of a new workspace).

Sibling architects no longer leak across workspaces (#826)

In v3.1.1, opening a workspace OTHER than the one that registered sibling architects caused those siblings to be re-spawned as fresh PTYs in the new workspace. Concrete symptom: shannon had ob-refine registered; opening manazil for the first time showed main + ob-refine + bug-backlog in manazil's terminal list, with new PIDs and real running claude processes none of which belonged to manazil.

Root cause

state.db.architect had no workspace_path column. The table was global per Tower-daemon (anchored to Tower's startup CWD). v3.1.1's #786 added a launchInstance reconcile loop that iterated this global table and re-spawned every architect it found — without any workspace-scoping check, because the data model didn't carry the scope. Pre-v3.1.1, the table was harmless because nothing iterated it; v3.1.1's new iterate-and-respawn loop turned the global table into an active cross-workspace leak.

The fix: schema-level workspace scoping

Migration v11 (in state.db):

• Add workspace_path TEXT NOT NULL column
• Composite primary key (workspace_path, id)
• Backfill workspace_path from global.db.terminal_sessions via ATTACH DATABASE, using architect.terminal_id as the disambiguation key (deterministic — the stable session UUID), with role_id LIMIT 1 as the fallback only when terminal_id has no matching session row
• Drop orphans (architects with no current terminal_session row)
• New index idx_architect_workspace on architect(workspace_path)

All state.ts accessors now require workspace context: getArchitects(workspacePath), setArchitect(workspacePath, …), setArchitectByName(workspacePath, name, …), removeArchitect(workspacePath, name), loadState(workspacePath). launchInstance and other callers thread workspacePath through.

All accessors canonicalize the passed workspacePath via realpathSync at the boundary — so symlinked workspace paths resolve to the same canonical key and the same architect row, regardless of which form the caller used.

Why per-site patching was rejected

The first three iterations of #827 tried to patch individual delete sites (deleteWorkspaceTerminalSessions, PtySession exit handlers, getTerminalsForWorkspace stale-cleanup) with isIntentionallyStopping guards to prevent the leaked rows from being preserved-then-deleted. Each iteration's CMAP caught the next delete site. After four sites and no clear stopping point, the architect-side review escalated to "the architecture is wrong, not the call sites" and the PR rewrote to Option A (schema-level scoping). The result is dramatically simpler — workspace isolation now falls out of the data model rather than depending on a maze of intent-flag guards.

Spec 786 stop+start MUST is preserved

The intentional-stop preservation mechanism from #786 stays — sibling architect rows still survive afx workspace stop + afx workspace start. With Option A, that preservation is now narrowly scoped to ONE concern (skip the architect-row delete on graceful stop), not "protect every site that could leak architects."

Migration ordering hotfix (#834, iter-7)

A late-cycle finding: an initial version of the migration placed CREATE INDEX idx_architect_workspace ON architect(workspace_path) in LOCAL_SCHEMA, which runs on every db.exec(LOCAL_SCHEMA) BEFORE migrations. On existing v10 databases, the architect table has no workspace_path column yet, so the index creation threw and the entire ensureLocalDatabase initialization aborted — breaking every upgrade install. Caught by the architect's local-install verification before publishing. Fixed by moving the CREATE INDEX out of LOCAL_SCHEMA and into the migration block itself (placed outside the alreadyMigrated guard so both fresh-install and upgrade-install paths land it). PR #834 ships alongside PR #827 in this release.

Process notes

This bug fix went through 7 iterations of CMAP-driven review across two PRs (#827 + #834). Each iteration's independent architect-side CMAP caught a finding the builder's own CMAP missed: the original race in the cross-workspace fix, then a stop+start regression, then exit-handler delete leakage, then getTerminalsForWorkspace stale-cleanup, then migration disambiguation non-determinism, then path-canonicalization mismatch, then the migration-ordering bug that broke upgrade installs. The two-CMAP discipline (builder runs one, architect runs an independent one) caught real bugs at every iteration — single-CMAP review on this PR would have shipped a regression.

Lesson saved in the architect's working memory: when builder's CMAP and architect's CMAP converge differently, the architect's CMAP isn't sloppiness — it's signal. Run both, trust the conjunction.

Breaking changes

None at the user-visible API level. The migration is automatic on first state.db read after upgrade.

For TypeScript consumers of @cluesmith/codev-core or internal state accessors: getArchitects, setArchitect, setArchitectByName, removeArchitect, loadState now require a workspacePath parameter. This is internal API; CLI / dashboard / VSCode extension consumers are unaffected.

Install

npm install -g @cluesmith/codev@3.1.2
afx tower stop && afx tower start

If you were running v3.1.1 with multiple workspaces, this release silently fixes the leak on Tower restart (migration v11 runs automatically). Confirm by opening a previously-unused workspace and verifying its architect list shows only the workspace's own architects.

Contributors

• M Waleed Kadous (@waleedkadous) — reported the leak within minutes of v3.1.1 install (own machine), drove the 7-iteration CMAP discipline that caught every issue including the migration-ordering release blocker.
• External Codev consumers — implicit pressure on multi-workspace correctness; the bug would have surfaced on every two-workspace adopter eventually.
• Builder working under BUGFIX protocol across PRs #827 and #834.

v3.1.1 Jacobean

v3.1.1 Jacobean

Released: 2026-05-23

First minor on the new Jacobean line. Bundles four substantial threads of work that landed since v3.0.7: a critical multi-architect routing fix that the v3.0.5 / v3.0.6 verify phases never caught, two large VS Code extension rounds from Amr, the multi-architect lifecycle/persistence/UX feature pass (Spec 786), and the multi-architect coordination follow-up (Spec 823 — dashboard attribution, inter-agent messaging docs, builder thread files, VS Code Architects tree refresh).

Note on numbering: this release skips v3.0.8 (locally built, never published — superseded by accumulated work) and v3.1.0 (briefly published as orphan dep-only packages under a since-rejected "Jugendstil" name; @cluesmith/codev never reached 3.1.0 and dist-tags.latest stayed at 3.0.7, so users see a clean 3.0.7 → 3.1.1 upgrade path).

Multi-architect routing — actually works now (#774 → PR #775)

The headline value prop of sibling architects ("a builder spawned by ob-refine, when it sends to architect, reaches ob-refine") was non-functional from v3.0.5 → v3.0.7. The primitive shipped in v3.0.5, the dashboard tabs in v3.0.6, but every builder→architect message routed to main regardless of which sibling spawned the builder. Reported by external adopter Shannon within hours of v3.0.7's install.

Root cause: detectCurrentBuilderId() opened the worktree's empty .agent-farm/state.db via the singleton getDb(), missed the canonical builder ID lookup, and fell back to the worktree directory name (e.g. bugfix-1599) instead of the canonical builder-bugfix-1599. Downstream lookupBuilderSpawningArchitect returned undefined for that short ID, the affinity branch was skipped, and routing defaulted to main.

The fix opens the workspace's state.db directly (readonly), mirroring the existing per-workspace-handle pattern in state.ts:lookupBuilderSpawningArchitect. End-to-end verified against shannon's real two-architect workspace before tagging: ob-refine-spawned builder's message landed on ob-refine's terminal 7e3dc4fe..., not main's 48784891....

Lesson saved: the v3.0.5 verify phase never ran the one sentence the spec promised. Going forward, release verification for any "X command does Y" claim must include literally running X and observing Y, on a real workspace, not just unit tests on the primitive. See feedback_e2e_headline_path in the architect's working memory.

Multi-architect lifecycle, persistence, and UX (#786 → PR #822)

A seven-phase feature pass that finishes the multi-architect coherence story started in v3.0.5/v3.0.6.

remove-architect is now a first-class lifecycle operation

afx workspace remove-architect <name>

Refuses to remove main. Refuses unknown names. With in-flight builders, removes anyway and routes their subsequent afx send architect calls to main via the existing fallback (OQ-A: remove-anyway design — minimal new state, matches crash-recovery semantics).

Dashboard parity: sibling architect tabs in the multi-architect tab strip now carry a close button (×) that invokes the same backend lifecycle, with a confirmation modal that surfaces any in-flight builders the sibling spawned (informational; doesn't block removal). main's tab has no close button.

VS Code parity: the workspace sidebar now has an expandable Architects tree node (per OQ-D); right-clicking a sibling shows Remove Architect in the context menu (viewItem == workspace-architect-sibling). main (workspace-architect-main) gets no remove option.

Sibling architects survive graceful stop/start

afx workspace stop followed by afx workspace start now preserves sibling architect rows. Previously the graceful-stop path deleted every row via clearState() (CLI side) and deleteWorkspaceTerminalSessions (server side), so siblings were lost on every stop. Now:

• Server side: an intentionallyStopping flag suppresses the exit-handler cascade that would otherwise delete the persisted state.db.architect row when the PTY is killed.
• CLI side: stop.ts calls a new clearRuntime() variant that skips DELETE FROM architect (preserving the registration) while still clearing builders/utils/annotations.
• Restart side: launchInstance reconciles persisted siblings, re-spawning their terminals with CODEV_ARCHITECT_NAME re-injected so affinity routing keeps working.

Race condition fix (post-PR Codex CMAP catch)

The initial implementation cleared intentionallyStopping in finally before the async PTY exit handlers had fired — leaving a timing window in which the handlers still saw the flag as cleared and deleted the row anyway. Caught at architect integration CMAP. Fixed by collecting once('exit', resolve) promises and awaiting all of them (with a 5s safety timeout) before clearing the flag. Same fix applied to handleWorkspaceStopAll. Behavioral test exercises the timing window; unit tests alone never caught it.

Identity preservation across shellper auto-restart

When shellper auto-restarts a sibling's claude process (max-restart loop), the new process now spawns with CODEV_ARCHITECT_NAME=<sibling-name> in env — previously restartOptions.env was built from process.env only, so a restarted sibling silently lost its affinity identity, and builders spawned afterward routed to main. The reconciliation path at tower-terminals.ts:559-567 and the workspace-status path at :773-776 both inject the name from dbSession.role_id.

Surface parity

afx status now enumerates ALL architects (post-#786):

[info] Architects:
[info]   main (pid=20807 terminal=a16f1b60-8250-...)
[info]   ob-refine (pid=66756 terminal=0ce8f578-9bf6-...)

The v1 "collapse all architects into a single Architect entry" logic at tower-terminals.ts:928-940 is removed. The Tower /status endpoint and dashboard both see the per-architect collection. validateArchitectName now rejects main as a reserved name (previously rejected only by collision with the running main architect).

Architect-to-architect messaging documented (already worked in code)

main can send to ob-refine via afx send architect:ob-refine "..." — sender-is-architect bypasses the spoofing check, so this has worked since v3.0.5. It just wasn't documented anywhere.

Mobile solo-architect tab label restored to "Architect" (#764)

Previously the mobile TabBar showed main instead of Architect on solo-architect workspaces. The N=1 label is now 'Architect'; N>1 uses the architect name. Folded into #786's useTabs.ts:buildArchitectTabs work.

Multi-architect coordination — attribution, messaging, threads, refresh (#823 → PR #824)

A four-deliverable follow-up to #786 that completes the coordination story.

Dashboard builder attribution (N>1)

When state.architects.length > 1, each builder card now shows a · <architect> separator-style attribution next to the builder ID:

● builder-spir-42
  #0042 · ob-refine
  feature: add support for X

N=1 workspaces stay DOM-identical to before. The OverviewBuilder.spawnedByArchitect field is now a required shape on @cluesmith/codev-types (TypeScript-facing change worth flagging for consumers).

Inter-agent messaging documented end-to-end

CLAUDE.md and AGENTS.md (kept synchronized) gain a new "Inter-agent messaging" section documenting all four addressing forms — afx send <builder-id>, afx send architect, afx send architect:<name>, afx send <workspace>:architect — with the spoofing-check constraint that's load-bearing for builders. Discovery patterns for sibling architects (afx status) and active builders (ls .builders/*/codev/state/*.md, post-merge ls codev/state/) are also surfaced. No code change — the primitives already existed; this release closes the documentation gap.

Per-builder thread file convention

Each builder now maintains a free-text markdown thread at codev/state/<builder-id>_thread.md. The builder writes natural-language notes — phase transitions, decisions, blockers — for collective situational awareness across the cohort. No structured schema, no porch hooks, no required format. Just a markdown file. Each builder's role prompt now contains the maintenance instruction; the file is committed at PR time so the thread joins the historical review record. The first dogfood thread (codev/state/spir-823_thread.md) is committed in this release.

VS Code Architects tree auto-refreshes on architect add

Previously the VS Code Architects tree refreshed on remove (the command self-triggered the refresh) but stayed stale on CLI-side afx workspace add-architect until the user clicked Refresh. The asymmetry was caused by Tower having no SSE event for architect lifecycle changes. This release adds:

• Tower side: an architects-updated SSE event emitted on every addArchitect / removeArchitect / launchInstance reconcile call, with { workspace: <path> } payload — same shape as the existing worktree-config-updated event.
• VS Code side: WorkspaceProvider subscribes via the existing onSSEEvent channel, fires changeEmitter.fire() unconditionally on receipt (matching the existing worktree-config-updated pattern; workspace-filtering is unnecessary since each VS Code window is rooted at one workspace).

Dashboard parity falls out of existing polling.

VS Code extension — two substantial Amr rounds (PR #771 + PR #779 + PR #785)

Big workflow improvements across two batches. Highlights:

Per-builder file inspection

• Per-builder changed files inline. A builder row in the Builders view is now expandable to the list of files it changed vs the default branch; clicking a file opens its two-way diff (read-only merge-base base ↔ worktree file). Rows use VS Code's native Source Control look — file-type icon plus a colored A/M/D/R/C/T status badge tinted via the theme's `...

v3.0.7 Ionic

v3.0.7 Ionic

Released: 2026-05-18

A patch on the Ionic line that fixes two regressions shipped in earlier 3.0.x releases — the multi-architect dashboard pane collapsing to ~1/4 height (introduced in 3.0.6), and the Gitea/Forgejo forge crashing Tower overview (since 3.0.3).

Multi-architect dashboard pane fills the SplitPane (#766 → PR #767)

PR #762 in v3.0.6 introduced .architect-pane / .architect-pane-body wrappers in the multi-architect (N>1) left-pane render path, but never added matching CSS. The wrappers collapsed to intrinsic height, shrinking the architect terminal to roughly 1/4 of the SplitPane left side.

The fix uses position: absolute; inset: 0 on .architect-pane so it fills the relatively-positioned parent regardless of the parent's height computation. Solo-architect workspaces (N=1) use a different render path that was never broken.

A Playwright regression test now pins the invariant: in an N=2 workspace, .architect-pane height must match .split-left within 2px, and .architect-pane-body must reach the bottom of the SplitPane left side. The test was written to fail against the v3.0.6 state and pass against the v3.0.7 fix.

Gotcha worth knowing: by default Playwright tests hit localhost:4100, which serves the globally-installed dashboard, not the worktree's built bundle. Setting TOWER_TEST_PORT=<unused-port> spawns a fresh Tower from the worktree — that's what you need for actual change verification. The architect-pane-layout test enforces this implicitly; future dashboard tests should follow the same pattern.

Gitea/Forgejo forge crashes and field-name normalization (#749 + #750 → PR #768)

External adopter Chris Dodge (@pseudoseed) reported two coupled regressions running Codev against a Forgejo instance:

#749 — labels.map is not a function 500 on Tower overview

Forgejo/Gitea returns labels: "" or null for unlabeled issues, where GitHub always returns []. parseLabelDefaults() in lib/github.ts called .map() unconditionally and crashed.

Fix: coerce non-array inputs to [] before mapping (Array.isArray(labels) ? labels.map(...) : []), widen the parameter type to reflect the cross-forge runtime shape, add 4 regression tests covering empty-string / null / undefined / array paths.

#750 — #undefined and NaNd in Tower overview for Gitea

Once the 500 was patched, Tower overview displayed #undefined for every issue number and NaNd for every age — the Gitea preset scripts piped raw tea --output json straight through, but tea's field names don't match the GitHub-compatible shape Tower expects.

Fix: each of the four affected forge scripts (issue-list.sh, pr-list.sh, recently-closed.sh, recently-merged.sh under scripts/forge/gitea/) now requests an explicit --fields list and normalizes via jq:

tea returns	Tower expects
index (string)	number (int)
created	createdAt
author (flat string)	author.login
labels (CSV or "")	labels[].name
assignees (CSV or "")	assignees[].login
description	body

recently-closed.sh maps updated → closedAt; recently-merged.sh filters select(.merged == true) and maps updated → mergedAt. jq was already a runtime dep of the Gitea preset (pr-exists.sh, user-identity.sh).

Verified end-to-end on the reporter's Forgejo instance. Acknowledged test debt: no committed fixture-based test for the jq filters; CMAP-Codex flagged this as a REQUEST_CHANGES, accepted as cost-benefit (4 unit tests cover the upstream TypeScript path, reporter verified runtime, fixture tests would add ~30 min for limited value).

Breaking changes

None.

Install

npm install -g @cluesmith/codev@3.0.7
afx tower stop && afx tower start

If you're running v3.0.6 with multiple architects, this release fixes the broken dashboard layout. If you're running Codev against a Forgejo / Gitea instance, this release fixes the Tower overview crash and the #undefined / NaNd rendering.

Contributors

• Chris Dodge (@pseudoseed) — reported #749 and #750 with verbatim suggested fix shapes; verified end-to-end against Forgejo.
• External Codev consumer (Shannon multi-architect testing) — surfaced the architect-pane layout regression.
• M Waleed Kadous (@waleedkadous) — architect review, release coordination.
• Builders working under BUGFIX protocol.

v3.0.6 Ionic

v3.0.6 Ionic

Released: 2026-05-18

A patch on the Ionic line that finishes the multi-architect work started in v3.0.5 (now usable from a browser) and lands Amr's PIR protocol plus a substantial VSCode-extension workflow round.

Multi-architect dashboard tabs (#761 → PR #762)

v3.0.5 shipped the multi-architect routing primitive but deferred the UI surface — the result was that humans could register sibling architects via afx workspace add-architect but had no clickable way to access them from the dashboard. That was correctly called out as half-shipped. This release fixes it.

What's new

• /api/state exposes the full architects collection alongside the existing scalar architect pointer (backward compatible). Each entry carries { name, terminalId, port, pid, persistent }.
• Dashboard renders one tab per architect when N > 1. A small tab strip appears inside the left pane on desktop; on mobile the architect tabs join the main TabBar.
• First architect tab uses bare id: 'architect' (stable across the N=1 ↔ N>1 transition); subsequent siblings use id: 'architect:<name>'.
• Active architect tab persists per workspace in localStorage (keyed by URL pathname to avoid cross-workspace collision).
• Deep links: ?tab=architect:<name> selects the named tab; unknown names fall back to the first architect; the bare ?tab=architect continues to work.
• Persistent WebSocket model preserved. Switching architect tabs does not unmount terminals — the existing activatedTerminals lazy-mount + keep-alive pattern from Bugfix #205 is extended to architect tabs, so there's no reconnect-flicker on click.
• Left-pane architect selection is independent of global activeTabId. Clicking an architect tab on the left doesn't blank the right pane. (Caught at plan-phase Codex review; implementation routes around the issue with a separate activeArchitectName state.)

Single-architect workspaces

Desktop solo-architect workspaces are DOM-snapshot-identical to pre-#762 — same bare terminal in the left pane, no tab strip. A known minor cosmetic regression affects mobile + solo-architect users only: the bottom TabBar tab labeled Architect is now labeled main. Tracked as #764 for a 1-line follow-up.

Why this matters

The sibling-architect pattern (driving multiple architect agents in one workspace) is now first-class through the browser. Customers using Codev for large multi-thread initiatives can switch between architect terminals with a click; messages from each architect's builders route to that architect via the v3.0.5 affinity primitive.

PIR protocol (#691 → PR #763)

Amr landed a new protocol: PIR — Plan → Implement → Review. Sits between BUGFIX/AIR (lightweight) and SPIR (full ceremony). The issue body is the implicit spec — there is no spec phase.

Three human gates:

• plan-approval — architect approves the plan before any code is written.
• dev-approval — architect reviews the running worktree (not a PR diff) before the PR is created. Use this for mobile/UI/cross-platform changes where the running code needs visual sign-off.
• pr — post-PR merge-synchronization gate (matches SPIR pattern).

PIR is the right choice when the issue is clear enough to skip spec ceremony but the work still needs design review before coding starts, or live verification before a PR exists.

VSCode extension workflow improvements (#737 → PR #763)

Amr expanded the VSCode extension significantly:

• Workspace dev server runner (codev.runWorkspaceDev) — counterpart to the existing Run Dev Server for builder worktrees, now for the main workspace itself.
• Open worktree in new VSCode window (codev.openWorktreeWindow) — sidebar context-menu action.
• View Issue (codev.viewIssue) — opens the GitHub issue for a builder directly from the sidebar.
• View Artifact (codev.viewArtifact) — opens the spec / plan / review for a project.
• Gate notification toasts — VSCode shows toast notifications when a builder hits a gate (plan-approval, pr-ready, etc.), with click-through to the relevant artifact.
• Plan-review comment integration — review comments on the plan can be authored directly in VSCode and pushed back to the builder.
• Backlog tree view rebuilt; Needs Attention view removed (subsumed into the new gate-toast notifications + Backlog view).
• Review-diff command consolidated into existing diff workflows.

This is a substantial refresh of the IDE side of Codev. See packages/vscode/CHANGELOG.md for the full list.

Other

• Team CLI: team activity now uses GitHub's search.issueCount for true per-member counts (previously paged results misreported).
• DB migration: reintroduced v10 local DB migration for the pir builder type (needed for the new protocol).
• Project paperwork: spec/plan/review for #761, plus iter rebuttals, committed for the historical record.

Breaking changes

None. Single-architect workspaces unchanged on desktop. PIR is additive — existing protocols are untouched.

Install

npm install -g @cluesmith/codev@3.0.6
afx tower stop && afx tower start

Contributors

• External Codev consumer (Shannon) — reported the multi-architect-routing-without-UI gap that motivated #761; previously reported the sibling-architect pattern and the 5 tier-1 issues shipped in v3.0.5.
• Amr Elsayed (@amrmelsayed) — PIR protocol design and implementation, VSCode workflow round, team activity fix.
• M Waleed Kadous (@waleedkadous) — architect role, driving spec/plan iterations.
• Builders working under SPIR and PIR protocols.

v3.0.5 Ionic

v3.0.5 Ionic

Released: 2026-05-18

A patch on the Ionic line driven almost entirely by an external Codev consumer's production use of the sibling-architect pattern. Two substantial new features (multi-architect message routing, baked architectural decisions) and three workflow bugfixes — all caught and reported via the team channel.

Version note: 3.0.4 was published to the VS Code marketplace only (codev-vscode side). This release moves the entire lockstep — @cluesmith/codev, @cluesmith/codev-core, @cluesmith/codev-types, and codev-vscode — to 3.0.5 together. Solo-architect users see no behavior change from 3.0.3.

Multi-architect message routing (#755 → PR #757)

Codev workspaces have always assumed a single architect terminal. The sibling-architect pattern — where one human operator drives two or more architect agents in the same workspace, each owning a disjoint slice of work — has emerged in production usage on a large customer project. With one architect, afx send architect from any builder lands in the shared singleton; humans then manually decide "is this mine?" and copy-paste the message to the right architect. This release makes that routing automatic.

What's new

• Multiple architect terminals per workspace. Tower's in-memory WorkspaceTerminals.architect and the local architect SQLite table (and terminal_sessions.role_id) now key on a stable name rather than a singleton row. The schema migration (v9 local, v13 global) is forward-only per the project convention; existing single-architect workspaces are rekeyed transparently.
• Naming policy. First architect started in a workspace defaults to main; subsequent siblings auto-number architect-2, architect-3, …. Either can be overridden with an explicit name via the new afx workspace add-architect [--name <name>] subcommand. Allowed charset: [a-z][a-z0-9-]*, max 64 chars; collisions rejected.
• Spawn-time capture. Every afx spawn now writes spawned_by_architect: <name> onto the builder's persisted row, detected automatically from the architect terminal's CODEV_ARCHITECT_NAME env var (injected by Tower at terminal-start). Spawns outside any architect terminal default to main.
• Affinity-aware routing. When a builder runs afx send architect "...", the resolver now looks up that builder's spawned_by_architect and delivers the message only to that architect's terminal — sibling architects do not receive it. Non-builder senders (cron-routed messages, manual sends from the workspace root) continue to resolve to main (or the first registered architect if main is absent).

Backward compatibility

Zero behavior change for solo-architect workspaces:

• /api/state.architect stays scalar (populated with main or first registered).
• The dashboard and VS Code extension see one architect tab, identical to today.
• Builders persisted before this release (no spawned_by_architect field) route to main if present, else fail with a clear error listing the registered architects.

Why a new subcommand instead of afx architect --name

The existing afx architect runs a local Claude session with stdio: 'inherit' and explicitly disclaims Tower — it works in any directory, even outside a workspace. Adding --name semantics would break that no-Tower contract for current users. The new Tower-aware subcommand lives under the workspace noun (next to start, stop, rename), which keeps the existing command intact.

Security

• A builder spoofing architect:<some-other-name> (a name that is not its own spawned_by_architect) is rejected with a clear, test-asserted error.
• Architect-gone (the spawning architect's terminal was killed) falls back to main if present; otherwise fails with a distinct error.

What's deferred

afx status --architect <filter>, surfacing all architects in /api/state, the THREAD.md template + lifecycle, cross-thread visibility, and thread-aware consult are tracked as follow-up issues. Issue #758 tracks the deferred end-to-end Tower-process integration test (the routing matrix is covered by 18 unit tests + direct SQLite + route-handler tests; the e2e is documented technical debt).

Baked architectural decisions for SPIR/AIR/ASPIR (#746 → PR #756)

Architects often have strong priors on a major decision (language, framework, deployment shape, key dependencies) before filing an issue. Until now those priors had nowhere structured to live — buried in prose, easy to miss, easy for CMAP reviewers to override in good faith. The result: spec drafted against an assumed default, iter-2 CMAP reviews that wrong assumption, architect intervenes at iter-3 to override — and iter-2's feedback becomes obsolete.

How to use it

Include a ## Baked Decisions section (any heading level, case-insensitive) in the GitHub issue body before spawning a SPIR/AIR/ASPIR builder. Example:

## Baked Decisions

- Language: Python (match shanutil)
- Framework: FastAPI
- Deployment: deferred to a follow-up spec

The builder treats those decisions as fixed inputs to the spec. CMAP reviewers (Codex, Gemini, Claude) are told to honor them — they may COMMENT with concerns about a baked decision, but REQUEST_CHANGES is reserved for the case where the spec fails to honor a stated decision. The architect retains authority to rescind or amend a baked decision at any time via afx send.

Design properties

• Optional by default. Empty or missing section = full exploration, identical to today's behavior.
• No code surface. Pure prompt + documentation change — the LLM finds the section in the issue body and honors it because the prompt tells it to. No regex parser, no template-context plumbing. Handles variant section names and inline-in-prose baked decisions more robustly than a parser would.
• Architect-override carveout woven through every prompt. Builder prompts say "do not autonomously override" (not "forbidden to question") — so the architect can always rescind a baked decision and the prompt language doesn't fight them.
• Contradiction handling. If two baked decisions contradict each other, the builder pauses and flags via afx send rather than picking one. Reviewers REQUEST_CHANGES and ask the architect to clarify.

Test coverage

An 808-line test file covers grep assertions for the required instruction language across all 12 affected prompts (SPIR/ASPIR builder-prompt + drafting prompt + spec-review + plan-review, AIR builder-prompt + implement + impl-review + pr-review), pure-addition diff against 12 recorded baselines (so any inadvertent edit elsewhere in the prompts fails the test), and codev/ ↔ codev-skeleton/ byte-identical parity.

Bugfixes (#742, #744, #745)

Three workflow bugs reported by a Codev consumer using the bugfix protocol heavily:

Codex misapplied SPIR criteria to BUGFIX PRs (#742)

The bugfix protocol's consult-types/pr-review.md and impl-review.md templates were byte-identical to the SPIR versions, causing Codex to REQUEST_CHANGES on legitimate BUGFIX PRs for missing codev/specs/plans/reviews artifacts, for [Spec NNNN] commit format (BUGFIX uses Fix #N:), and for status.yaml.build_complete: false (porch-managed, not builder-fixable). Each PR cost 2–3 iter cycles of the builder writing protocol-defending rebuttals.

The fix rewrites both bugfix templates around what BUGFIX actually produces (GitHub Issue + fix + regression test) and adds an explicit Out of Scope section naming each of the three SPIR-only criteria to forbid. A regression test pins divergence from the SPIR templates so accidental re-syncing fails CI.

SPIR/ASPIR builder-prompt allowed per-phase PRs (#744)

The SPIR/ASPIR builder-prompt.md did not explicitly state the one-PR-per-spec convention; builders interpreted the plan's "each phase commits independently" as "each phase opens its own PR." A new PR Strategy section now makes this explicit, with an architect-override carveout for cases where the architect requests a PR earlier (e.g., for spec review, mid-implementation feedback, or slicing a large spec into shippable PRs).

The carveout phrasing — "do not autonomously open a PR per implementation phase" rather than absolute prohibition — is the pattern we now reuse for any builder-constraining prompt rule. Memorized for future prompt edits.

afx spawn dirty-worktree check was too strict on untracked files (#745)

git status --porcelain flags untracked files (?? status) alongside modified-tracked ones. Repos with chronic untracked artifacts (e.g., bin/ from pnpm local-install, .claude/scheduled_tasks.lock, build outputs) forced --force on every spawn, defeating the safety check entirely.

The check now uses git status --porcelain --untracked-files=no — it still catches the case where an architect git add-ed a new spec but forgot to commit (the index entry shows as tracked), while ignoring chronic untracked artifacts. Documented tradeoff: a file that's created but never staged won't trigger the check; if the architect wants that protection, git add before spawn restores it.

Other improvements

• @openai/codex-sdk bumped 0.101.0 → 0.130.0 to clear an XProtect cert-revocation issue on macOS (#752, Amr).

Breaking changes

None. Solo-architect workspaces are unchanged. The new ## Baked Decisions section is opt-in (absence = no-op).

Install

npm install -g @cluesmith/codev@3.0.5
afx tower stop && afx tower start

Contributors

• External Codev consumer (Shannon) — reported the SPIR-vs-BUGFIX template mismatch, the SPIR one-PR ambiguity, the chronic-untracked spawn issue, the architect's-baked-decisions need, and the sibling-architect/multi-architect-routing pattern. Five tier-1 reports filed via team channel; this release ships every one.
• Amr Elsayed (@amrmelsayed) — codex SDK XProtect cert revocation fix.
• **M Waleed Kadous...

v3.0.3 Ionic

v3.0.3 Ionic

Released: 2026-05-12

A patch update on the Ionic line that turns .builders/<id>/ worktrees into runnable, reviewable environments — from both the CLI and the VS Code sidebar — and aligns the workspace on a single lockstep version. Almost all of this release is the work of Amr Elsayed (@amrmelsayed).

Runnable worktrees (#689 + #690, PR #731)

Builder worktrees were already isolated git checkouts. They are now first-class environments you can install, run, and review.

New worktree block in .codev/config.json

Opt-in, zero behavior change for repos that don't add it:

{
  "worktree": {
    "symlinks": [
      "apps/web/.env",
      "apps/server/.env"
    ],
    "postSpawn": [
      "pnpm install",
      "cd apps/server && uv sync"
    ],
    "devCommand": "pnpm dev:local"
  }
}

• symlinks — files/globs symlinked from the main worktree into the builder's worktree on spawn. Designed for .env files and other host-only secrets you don't want copied into a sibling checkout.
• postSpawn — commands run inside the builder's worktree right after creation. Output streams live to the spawn terminal via the new runStreaming helper, so pnpm install / uv sync progress is visible instead of buffered.
• devCommand — the command afx dev <builder-id> and Run Dev Server invoke.

New CLI commands

• afx dev <builder-id> — spawn the worktree's dev server as a Tower-managed PTY. Serial swap by design: only one builder's dev is running at a time, so OAuth callbacks, CORS allowlists, cookie scoping, and webhook URLs keep working without reconfiguration.
• afx setup <builder-id> — re-apply worktree.symlinks and re-run worktree.postSpawn against an existing worktree. Handy after lockfile changes, evolving config, or recovering from an aborted spawn.

Dev terminals are ephemeral by design — they die with Tower and are not persisted to SQLite. The 'dev' TerminalType was added to @cluesmith/codev-core/tower-client and gated at tower-routes.ts. Killing a dev PTY signals the entire process group (SIGTERM → SIGKILL after 5s), so a monorepo pnpm dev with N children gets cascade-killed by one syscall.

VS Code sidebar context menu

Right-click any builder row in Builders or Needs Attention:

Codev: Open Builder Terminal
─────────────────────────────────
Codev: Open Worktree Folder        ← OS file manager
─────────────────────────────────
Codev: View Diff                   ← unified main↔HEAD multi-file diff
─────────────────────────────────
Codev: Run Worktree Setup          ← shells out to `afx setup`
Codev: Run Dev Server              ← spawns the dev PTY
Codev: Stop Dev Server

View Diff uses vscode.changes for a single tab with a file-list pane, instead of opening N diff editors. The brand icon is now theme-aware (light/dark SVG pair) so it doesn't render as a black square on dark themes.

Plus command-palette tightening: hidden palette entries that need a builder-id argument, and a BuilderTreeItem subclass so context-menu commands resolve the right builder regardless of which row was right-clicked.

Recipes

CLAUDE.md and AGENTS.md gain a Runnable Worktrees section with copy-paste recipes for pnpm monorepo, npm, yarn, bun, cargo, poetry/uv, and go mod stacks.

Lockstep version bumps (#692, PR #732)

pnpm bump-version replaces the per-package pnpm version flow. Anchors on root package.json (Vue/Babel pattern), updates root + every publishable workspace package in one shot, and preserves byte-level JSON formatting (the regex-only rewrite avoids the JSON.stringify churn that would have rewritten compact arrays in packages/vscode/package.json).

Command	Effect
pnpm bump-version	Patch bump from the current root version
pnpm bump-version patch / minor / major	Semantic bumps
pnpm bump-version 3.1.0-rc.1	Explicit version (auto-skips packages/vscode because the VS Code Marketplace rejects pre-release suffixes)

This release is the one-time alignment that pulls @cluesmith/codev-core and @cluesmith/codev-types up from their stale 0.0.x values to match @cluesmith/codev. From now on, every workspace package ships at the same version — closing the class of bug where the main package shipped pointing at outdated internal deps.

prepublishOnly: pnpm build is now wired on packages/core and packages/types so dist/ can't be stale at publish time. The release protocol's Step 4 was rewritten around the new flow; the backport path keeps the per-package pnpm version semantics.

VS Code reliability and sidebar UX (PR #729)

Three themes in one bundle — Amr's PR #682 review follow-up, sidebar UX, and the #718/#728 bugfixes.

PR #682 follow-up

• Dropped the SSE rate limiter. Every consumer self-throttles where it matters (the overview-data loading guard, tree views' batched EventEmitters), so the 1s coalescer was solving a problem that wasn't there while creating a real one — a builder-spawned event arriving inside a coalesced overview-changed window was silently dropped. Removed entirely.
• openBuilder close-race fix. When a stale terminal is replaced under the same mapKey, the stale onDidCloseTerminal event can fire after registration; the new entry was being deleted from under itself. Identity-check the current map entry before deleting.
• Workspace path normalization in BuilderSpawnHandler so trailing-slash variants don't drop events. Plus new unit coverage for parsing/dedup/path-norm/mode-dispatch (builder-spawn-handler.test.ts, sse-client.test.ts) and a contract test pinning BuilderTerminalLinkProvider to a pure regex implementation.

Sidebar UX

• Clickable rows. Builders and Needs Attention rows now open the builder's terminal on click. Resolution goes through TerminalManager.openBuilderByRoleOrId — one shared path for link-provider, sidebar, and palette.
• Tail-match builder IDs. Fixes the "No active terminal for 153" toast: sidebar IDs were '153', Tower's runtime IDs were 'builder-spir-153'. resolveAgentName and stripLeadingZeros moved into a new @cluesmith/codev-core/agent-names subpath shared by agent-farm and vscode.
• Focus parameter threaded through the terminal-open path. Click paths opt in; auto-spawn paths don't steal focus mid-typing. Also primes new pseudoterminals with an empty write to work around microsoft/vscode#108298 (writes emitted before open() are dropped, leaving the pane blank until first input).
• Codev SVG terminal icons. Architect, builder, and shell tabs now show the Codev mark instead of >_.
• New Workspace sidebar view above Needs Attention: Open Architect and Open Web Interface entries, sharing codev.openArchitectTerminal with the palette and Cmd-K A keybinding.

Bugfixes #718, #728, #688

• #718 — VS Code extension wasn't showing builder terminals from Tower. Tower's wsTerminals rehydration is now centralised so /api/overview self-heals like /api/state. The extension also activates the workspace before announcing 'connected', and the sidebar gains refresh + reconnect buttons.
• #728 — Cold-start failures can leave VS Code stuck Offline. New codev.reconnect command + status-bar click; connect() has a re-entry guard; cold-start self-heal added.
• #688 — Review nits on local-install.sh addressed.

Breaking changes

None. The new worktree config block is opt-in; the version-bump scripting is internal; sidebar UX and bugfixes are purely additive.

Migration

npm install -g @cluesmith/codev@3.0.3
afx tower stop && afx tower start

To opt into runnable worktrees, add a worktree block to .codev/config.json and codev update. See the new Runnable Worktrees section in CLAUDE.md for stack-specific recipes.

Install

npm install -g @cluesmith/codev@3.0.3

Contributors

• Amr Elsayed (@amrmelsayed) — runnable worktrees, VS Code review tooling, lockstep version bumps, sidebar UX, PR #682 follow-up
• M Waleed Kadous (@waleedkadous) — release coordination
• MachineWisdomAI — bugfixes #718 / #728 / #688 follow-up under parallel agent
• Builders working under SPIR, ASPIR, AIR, and BUGFIX protocols

v3.0.2 Ionic

v3.0.2 Ionic

Released: 2026-05-07

A patch update on the Ionic line. Three notable additions — a Linear forge provider with hybrid GitHub fallback, an opt-in Bridge Mode for Tower, and a documentation governance pass that converts the architecture-documenter agent into a discoverable skill — plus a handful of bug fixes.

New (opt-in)

Hybrid forges: Linear issue tracking with GitHub PR fallback (#716, #719)

The forge layer now supports partial provider implementations. Linear-for-issues + GitHub-for-PRs is the canonical hybrid: a Linear provider supplies six issue concepts (auth-status, user-identity, issue-view, issue-list, issue-comment, recently-closed) while PR concepts fall through to GitHub.

The architectural improvement that unlocks this: buildPresetFromScripts now omits missing concepts instead of writing null, so unimplemented concepts cascade to the default provider. This benefits any partial-provider scenario, not just Linear.

Also in this work:

• Issue identifiers are widened to string | number throughout the agent-farm CLI, type system, and DB layer (so ENG-123 works alongside 42)
• db_builders.issue_number migrated from INTEGER → TEXT
• Forge config non-concept keys (e.g., linear-team) are exported to provider scripts as CODEV_LINEAR_TEAM

Configure in .codev/config.json:

{
  "forge": {
    "provider": "linear",
    "linear-team": "ENG"
  }
}

Set LINEAR_API_KEY in your environment.

Bridge Mode for Tower (#721)

Tower now has an opt-in path for binding to non-localhost addresses, intended for container-bridging scenarios where Tower runs inside a sandboxed Docker environment and the host browser/CLI needs to reach it.

Two environment variables, both required to expose Tower beyond localhost:

• BRIDGE_MODE=1 — explicit opt-in flag. Without it, Tower binds to 127.0.0.1 regardless of other settings.
• BRIDGE_TOWER_HOST — bind address when bridge mode is enabled (e.g. 0.0.0.0). Only consulted when BRIDGE_MODE=1. Accepts 127.0.0.1, 0.0.0.0, localhost, valid IPv4 literals, and bracketed IPv6 literals.

When bridge mode is enabled, Tower logs a startup warning. Tower has no built-in authentication — if you enable bridge mode, your firewall is the security boundary.

For remote access without container bridging, cloud.codevos.ai remains the recommended path.

Documentation governance (#723)

The architecture-documenter agent has been retired and replaced by an update-arch-docs skill, propagated to all projects via codev update. The MAINTAIN protocol now carries a "Lives where" routing matrix and an audit-then-update split (Step 3a / Step 3b) with concrete pruning checklists for arch.md and lessons-learned.md. The SPIR review phase now name-drops the skill and includes lessons-learned.md alongside arch.md.

Templates also picked up the discipline:

• templates/arch.md is a richer multi-section starter (TL;DR, Repository Layout & Stack, Per-Subsystem Mechanism, Apps Roster, Packages Roster, Verified-Wrong Assumptions, Updating This Document) with skip-if-N/A framing for small projects
• templates/lessons-learned.md gains a preface with "what NOT to add" guidance and a sanity-check checklist

The shipped templates resolve at runtime from the installed npm package; existing projects continue using their own arch.md and can opt into the richer template by manual copy.

Bug fixes

• #717 — afx attach can't find builders (PR #720): findShellperSocket now queries SQLite by workspace root, with fallback to Tower's terminal_sessions
• #712 — Stale af CLI references in resource docs after the af → afx rename (PR #713)
• #711 — porch lacked --version flag and pending command (PR #714)
• #710 — E2E tests depended on removed porch run orchestrator (PR #715)
• #725 — Bridge mode test misclassified as unit test in CI (PR #726): renamed to bridge-mode.e2e.test.ts

Breaking changes

None.

Migration

npm install -g @cluesmith/codev@3.0.2
afx tower stop && afx tower start

The new update-arch-docs skill lands automatically via codev update on existing projects. The user-global ~/.claude/agents/architecture-documenter.md agent file (if present) should be removed, since the skill replaces it.

Install

npm install -g @cluesmith/codev@3.0.2

Contributors

• M Waleed Kadous (@waleedkadous)
• @timeleft-- (Younes) — Linear forge provider, hybrid forge architectural insight
• @otherview — Bridge Mode for container deployments
• MachineWisdomAI — bugfix #725 and ongoing builder work
• Builders working under SPIR, ASPIR, AIR, and BUGFIX protocols

v3.0.1 Ionic

v3.0.1 Ionic

Released: 2026-04-30

Note: v3.0.0 was published briefly with a corrupted manifest (the @cluesmith/codev-core workspace dependency was dropped during publish). v3.0.0 has been deprecated on npm. Use v3.0.1, which is otherwise identical.

Summary

Ionic is the third major release of Codev, named after the Greek architectural order whose hallmark is the volute — the spiral scroll that distinguishes a column without overcomplicating it. Where Hagia Sophia (v2.0) rebuilt the foundations — Shellper, Tower, the dashboard, porch — Ionic refines the column. Three pillars define the release: a VS Code extension, flexibility and customizability (pluggable forges, harnesses, and per-stage consults), and the first real story for teams (a Teams tab and builders that can share their work-in-progress via mid-flight PRs).

Highlights

• VS Code Extension: A first-class IDE companion to the browser Tower UI, available now on the Marketplace
• Configurable Forges: GitHub, Gitea, and GitLab — pick your provider per project
• Configurable Harnesses: Claude, Codex, Gemini, and OpenCode — mix and match per project, or per phase
• Per-Stage Consults: "Claude writes, Codex reviews" — every protocol phase can pick its own reviewers
• Teams Tab: See who's working on what, with GitHub activity and review-blocking surfaces
• Multi-PR Builders: Builders can open draft PRs mid-flight to share specs/plans for review without waiting for completion

VS Code Extension (Spec 0602, PRs #656, #659, #666, #672, #682, #705)

A native VS Code companion alongside the browser Tower UI:

• Tower view inside VS Code: Browse projects, workspaces, and builders without leaving the editor
• Backlog view: GitHub Issues and PRs surfaced in the sidebar with reporter and assignee
• Team view: Same review-blocking surface available in the dashboard, scoped to the current workspace
• Builder terminal access: Open builder terminals as VS Code tabs
• Configurable enablement: Team view appears only when codev.teamEnabled is set
• Available on the Marketplace as cluesmith.codev-vscode (currently pre-release while awaiting Marketplace publisher approval)

Install:

code --install-extension cluesmith.codev-vscode --pre-release

Or search "Codev for VS Code" in the Extensions panel and choose Switch to Pre-Release Version.

Flexibility & Customizability

Configurable Forges (Specs 0589, 0612, 0618, PRs #593, #636, #624)

Codev no longer assumes GitHub. The forge layer is a pluggable abstraction with three first-class providers:

• GitHub — the original provider, still the default
• Gitea — full provider implementation (issues, PRs, merging, labels)
• GitLab — full provider implementation
• Provider selection lives in .codev/config.json; defaults to GitHub when unspecified
• All concept commands (issue-view, pr-list, pr-merge, etc.) are shell-scripted per provider in packages/codev/scripts/forge/{github,gitea,gitlab}/
• Pluggable CLI-based artifact resolver lets users wire additional forges without core changes

Configurable Harnesses (Spec 178, PR #663)

Four AI harnesses are now first-class:

• Claude (--append-system-prompt injection)
• Codex (-c model_instructions_file= injection)
• Gemini (GEMINI_SYSTEM_MD env var injection)
• OpenCode (worktree file injection)
• Custom harnesses declarable via .codev/config.json with template variables — no core code changes needed

Per-Stage Consults

The protocol schema now supports per-phase model assignment:

• Each phase in a protocol declares its own models array — e.g., spec phase uses [gemini, codex, claude], implement phase uses [codex]
• Mix and match: have Claude write the spec while Codex and Gemini review it
• Hermes consult backend (PR #670) added as an additional consultation transport

Teams (the beginnings of Sphere 7)

Teams Tab (Specs 587, 599, 650, 694, PRs #588, #600, #651, #695)

A new top-level view for teams using AI:

• Member cards showing GitHub activity, recent commits, and current focus
• Issue/PR details and activity feed per team member
• Review-blocking surface: see at a glance who is waiting on whom for review
• Standalone team CLI: team list, team message, team update, team add — extracted from afx team (which is now deprecated)
• Member management via team add PRs (Waleed and Nat Harward added during the cycle)

Multi-PR Builders (Spec 653, PR #674)

The headline structural change. Worktree, branch, and PR are now decoupled — one builder can open multiple PRs from a single worktree.

• Cut-and-merge loop: builder opens PR → merges → pulls main → cuts next branch
• "Share spec as PR" mid-flight: builders can open draft PRs at any phase to surface work-in-progress for human review
• PR history tracked in status.yaml: every PR opened or merged is recorded as part of the project's history
• Optional Verify phase: a human-gated post-review phase for projects that need production validation
• TICK protocol retired: amendments to shipped specs are now just another PR from the same worktree, making TICK redundant

Quality of Life

• af → afx rename (Spec 647, PR #649): the CLI is now afx; af remains as an alias
• Branch flag for afx spawn (Specs 609, 615, PRs #611, #617): builders can be spawned onto an existing branch or a fork
• RESEARCH protocol (rc.12): multi-agent research with 3-way investigation, synthesis, and critique — output to codev/research/<topic>.md
• MAINTAIN protocol simplified: collapsed from 4 phases to 2 (code hygiene + documentation sync)
• Terminal scroll management (Specs 627, 630, PRs #628, #631): scroll-to-top behavior and resize-race conditions fixed
• Local install script: pnpm -w run local-install for fast local validation without publishing
• pnpm migration (PR #669): workspace builds standardized on pnpm
• Multi-line afx send (PR #657): fixed three-stage send for multi-line messages

Bug Fixes

A non-exhaustive selection from the cycle:

• #706 — afx spawn --protocol falls back to skeleton on v3-cleaned projects (PR #707)
• #693 — Forge scripts lose executable bit after install (PR #696)
• #684 / #680 — Gemini consult crashes on large PRs (V8 heap exhaustion, fixed via temp-file diff staging)
• #676 — porch approve plan-approval fails when the artifact resolver looked outside the worktree (PR #679)
• #677 — afx spawn --protocol maintain requires --force even on a clean tree (PR #678)
• #667 — Dashboard E2E missing pack during CI (PR #668)
• #664 — Dashboard fails to extract issue number from certain branch names (PR #665)
• #664 — Porch auto-detection fails on certain CWDs (PRs #607, #608)
• #603 — Opaque string IDs not propagated through the spawn pipeline (PR #616)
• #625 — Terminal resize race condition (PR #626)
• #622 — porch status cannot find project with full path (PR #643)
• #511 — STL viewer model origin off-screen (PR #644)
• #584 — afx send multi-line messages stripped after the third newline (PR #657)
• #591 — afx workspace failure with code in CWD (PR #654)
• #615 — afx spawn --branch support for forks (PR #617)
• #605, #606 — Porch path handling (PRs #607, #608)

Breaking Changes

• af CLI renamed to afx: scripts and aliases that hardcode af should be updated; af remains as an alias for now
• TICK protocol removed: amendments to shipped specs use multi-PR workflow on the same worktree instead
• Forge scripts now executable: install must restore the executable bit (handled by local-install.sh and the install postinstall step)
• Local codev/protocols/ is optional: v3-cleaned projects rely on the global skeleton; afx spawn --protocol resolves through .codev/ → codev/ → cache → embedded skeleton
• afx team deprecated: use the standalone team CLI

Migration Notes

Upgrade with:

npm install -g @cluesmith/codev@3.0.1
afx tower stop && afx tower start

Per-project:

• Existing .codev/config.json files continue to work; forge defaults to GitHub
• To opt into Gitea or GitLab, add a forge block to .codev/config.json
• To pin per-phase consultation models, edit your protocol's YAML to set the models array per phase

Install

npm install -g @cluesmith/codev@3.0.1

For the VS Code extension:

code --install-extension cluesmith.codev-vscode --pre-release

Or install from the Marketplace.

Contributors

• M Waleed Kadous (@waleedkadous)
• Nat Harward (@nharward) — non-GitHub forge support and enterprise feedback
• MachineWisdomAI — pluggable artifact resolver and Hermes consult backend
• Builders working under SPIR, ASPIR, AIR, and BUGFIX protocols — every shipped spec in this release was implemented by an autonomous builder under architect review

v3.0.0-rc.14

v3.0.0-rc.14

Released: 2026-04-28

Summary

Critical bugfix for v3-cleaned projects: afx spawn --protocol <name> now correctly falls back to the global skeleton when the local codev/protocols/ directory has been pruned (the intended v3 design). Reported by ansari-multisage's architect; without this fix, any freshly v3-migrated project couldn't spawn builders at all.

Bug Fixes

• #706 — afx spawn --protocol fails on v3-cleaned projects (PR #707). Five hardcoded config.codevDir/protocols/... lookups in packages/codev/src/agent-farm/commands/spawn-roles.ts were replaced with the unified resolveCodevFile() helper from lib/skeleton.ts, which correctly walks .codev/ → codev/ → cache → embedded skeleton. A new listAvailableProtocols() aggregates protocol names across all three resolver tiers so the "Available protocols: ..." error message keeps working on projects with no local codev/protocols/. 145 new lines of test coverage exercising the fallback behavior. Reference implementation that already did this right: packages/codev/src/commands/porch/protocol.ts:loadProtocol().

Install

npm install -g @cluesmith/codev@next

Contributors

• Human + AI collaboration via Codev
• Bug report from ansari-multisage architect