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

v3.0.0-rc.13

v3.0.0-rc.13

Released: 2026-04-26

Summary

Three build-tooling hygiene fixes plus the dashboard backlog assignee column shipped in #701 (which was on main but never made it into the rc.12 tarball — see #702).

New Features

• #700 — Backlog rows show assignees alongside reporters. The dashboard's Work view backlog now renders r: @<reporter> a: @<assignee> (or a: none when unassigned, comma-separated when multiple). The data layer was extended end-to-end: GitHub issue-list.sh now requests assignees, the forge contract and BacklogItem/OverviewBacklogItem interfaces carry the new field, and unit + component tests cover the no-assignee, single-assignee, and multi-assignee cases.

Bug Fixes

• #702 — pnpm build now fails fast when local main is behind origin/main. Surfaced when rc.12 was packaged from a main that hadn't pulled the PR #701 merge — the build silently produced stale artifacts. New scripts/check-main-fresh.sh is prefixed onto the root build script. Override with SKIP_GIT_FRESHNESS_CHECK=1. Skips silently on non-main branches (worktrees, builders), when there's no origin remote, or when HEAD is up-to-date or ahead.
• #703 — build:dashboard no longer nests dashboard-dist/dist/ on re-run. cp -r dist <target> flips behavior when the target directory exists; we now rm -rf first.
• #704 — local-install.sh is no longer a silent no-op on same-version reinstall. npm uninstall -g followed by npm install -g could leave stale files when versions matched, masking PR-merged-but-not-shipped bugs. Added rm -rf "$GLOBAL_ROOT/@cluesmith/codev" between uninstall and install.

Install

npm install -g @cluesmith/codev@next

Contributors

• Human + AI collaboration via Codev

v3.0.0-rc.12

v3.0.0-rc.12

Released: 2026-04-24

Summary

Adds a new RESEARCH protocol for multi-agent research: scope → 3-way parallel investigation → synthesis → 3-way critique. Output lives in codev/research/<topic>.md.

New Features

• RESEARCH protocol (codev/protocols/research/). Three-phase workflow that triangulates across Gemini, Codex, and Claude. Investigations run in parallel so no model anchors on another's findings; the synthesis merges by topic (not by model) and flags consensus vs. single-source claims; the critique phase sends the synthesis back to all three models to check coverage against the brief, flag bias, and surface gaps. Designed for competitive analysis, technology evaluation, and "state of X" questions where no single model's knowledge is authoritative. Includes protocol.json, protocol.md, and builder-prompt.md in both codev/protocols/ (self-hosted) and codev-skeleton/protocols/ (consumer template). Protocol listings and the cheatsheet table updated in both locations.

Install

npm install -g @cluesmith/codev@next

Contributors

• Human + AI collaboration via Codev

v3.0.0-rc.11

v3.0.0-rc.11

Released: 2026-04-21

Summary

Two bugfix RCs rolled into one: Gemini PR-review no longer crashes on large diffs, and every protocol's builder prompt now requires a GitHub close-keyword so merged PRs auto-close their driving issues. Plus a release-protocol update that addresses the workspace-dependency publish-order gap that broke rc.10 on first try.

Bug Fixes

• #684 — Gemini consult fails on large PR diffs (PR #686). buildPRQuery now writes the raw diff to an owner-only temp file (mkdtempSync + 0o600 + flag: 'wx') and points the model at the path instead of inlining ~800KB of diff into the prompt. Mirrors the filesystem pattern already used by buildImplQuery. Fixes the Unexpected end of JSON input crash Shannon hit on PR #796; also shrinks prompts for Claude/Codex. Hardening adopted from Codex's CMAP REQUEST_CHANGES on the original implementation.
• #685 — Builder prompts now require Closes/Fixes keyword (PR #687). SPIR, ASPIR, AIR, experiment, and maintain prompts each gained a close-keyword directive (with an explicit partial-fix exception pointing builders at Refs #N / Part of #N). Caught a pre-existing bug along the way: AIR's prompt was emitting Implements #N, which GitHub does not treat as a close keyword. Also migrated bugfix's prompt from {{issue.number}} (which porch never substituted — its regex rejects dotted paths) to an explicit <N> placeholder with a "substitute this yourself" note. codev-skeleton/ mirrored.

Process improvements

• Release protocol updated to publish workspace dependencies before the main package. rc.10 was initially broken because @cluesmith/codev-core (a runtime dependency of @cluesmith/codev used by the VS Code extension) was never published to npm — the release protocol only ran pnpm publish on the main package. The protocol now uses pnpm publish --filter '@cluesmith/codev-core' --filter '@cluesmith/codev-types' ahead of the main publish, and documents when to bump core/types versions.

Install

npm install -g @cluesmith/codev@next

Contributors

• Human + AI collaboration via Codev