Skip to content

v3.0.1-ionic.md

Latest commit

 

History

History
166 lines (118 loc) · 9.04 KB

v3.0.1-ionic.md

File metadata and controls

166 lines (118 loc) · 9.04 KB

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