Skip to content
CoDev

Architecture

Purpose

Section titled “Purpose”

CoDev separates workflow maintenance from workflow use. The canonical bundle lives in the CoDev repository; agents consume ordinary, repository-local files in each software project. CoDev’s install, update, and remove machinery never runs while product code is being built. The codev task lifecycle commands are the one exception: they may run during a build session, are strictly read-only with respect to product source, and only read or write their own state under .codev/task/ (see ADR-0001 and ADR-0023).

CoDev source -> versioned Python package -> explicit CLI command -> target repo
       |                                                    |
       +---- tests and behavioral evaluations               +---- local agent discovery

Components

Section titled “Components”

Bundle

Section titled “Bundle”

src/codev_workflow/bundle mirrors target-relative paths. It contains the skills, and the OpenCode, Junie, Antigravity, and Claude Code agents, documentation, validators, and evaluation catalog. Junie and Antigravity carry a single narrow-tier assistant agent rather than the full workflow (ADR-0031); OpenCode and Claude Code carry the complete role set.

Every bundled skill carries a skill-card.md alongside its SKILL.md — owner, license, use case, dependencies, and known risks — and a license frontmatter field on SKILL.md itself.

AGENTS.md and .opencode/opencode.json are integrations rather than copied files. CoDev owns one marked block in AGENTS.md and selected missing values in OpenCode configuration, preserving all project-owned content. Junie’s assistant agent is an ordinary managed Markdown file under .junie/agents/, while Antigravity’s uses its official .agents/agents/ location alongside CoDev’s .agents/skills/ directory. Claude Code agents use its official .claude/agents/ location; unlike Antigravity, Claude Code has no configurable skills path, so the shared skills are mirrored into .claude/skills/ at install time instead of referenced in place. Claude Code additionally ships a .claude/settings.json and three guardrail hooks — a category no other adapter has: require_plan.py defaults new sessions into Plan Mode and pauses for confirmation before the first source edit, or the first repository-mutating git command, when no design or plan document exists yet for the active branch; require_wave_shape.py asks (never denies) when a wave plan’s “Later waves” section already holds a populated task table, enforcing rolling-wave planning’s detail-only-the-current-wave rule; require_small_change.py asks when a task’s diff exceeds its review.max_lines/review.max_files budget at codev git open-pr. All three fail open on any internal error and log their decisions to a local, gitignored gate-decision log.

Installer

Section titled “Installer”

The standard-library CLI performs a complete preflight before mutation. It computes SHA-256 hashes over bundled bytes and records them in .codev/lock.json. Files are written atomically in their destination directories.

Lock file

Section titled “Lock file”

The lock file records schema version, bundle version, selected platforms, source hashes, and integration state. It is committed to the consumer repository so CI and other developers observe the same installation.

Update algorithm

Section titled “Update algorithm”

For each managed file, CoDev compares:

  1. the source hash recorded at the last successful install;
  2. the current target file; and
  3. the source file in the running CoDev version.
State Action
Target matches old source; source changed Update
Target matches new source Adopt as current
Target and source both match old source Keep
Target differs; upstream is unchanged Report local drift
Target differs and upstream changed Conflict; write nothing
New upstream file is absent locally Add
New upstream file collides locally Conflict; write nothing
Upstream removed an old file Retain locally and stop managing it

Retaining removed files is conservative: an update cannot unexpectedly delete repository instructions. The explicit codev remove command preflights and removes only unchanged managed files and integrations; it remains opt-in.

A conflict left unresolved (--on-conflict skip, the conflict wizard’s skip, or simply no resolution supplied for that path) stays a visible conflict: codev status keeps reporting it as a managed file with local changes until a real resolution (override or keep) supersedes it, rather than the file quietly falling out of management the moment an update chooses not to touch it. delete is the one exception — it adopts upstream’s removal, so nothing is left to compare a future hash against, and the path stops being tracked the same way an ordinary upstream removal does.

Invariants

Section titled “Invariants”
  • Every multi-file change is atomic at the decision level: conflicts prevent all planned writes.
  • A target repository never imports CoDev as a runtime dependency.
  • Provider and model selection remain project-owned.
  • Installed instruction changes are reviewable source changes.
  • Deterministic checks run without network access or model calls.
  • Behavioral model evaluations remain externally observed and separately run.
  • codev task lifecycle commands are read-only with respect to product source; they only mutate their own state under .codev/task/ (see ADR-0001 and ADR-0023).

Compatibility

Section titled “Compatibility”

Lock schema changes require a migration before managed files are touched. Bundle behavior follows semantic versioning. Patch releases preserve artifact contracts; minor releases may add compatible files or behaviors; major releases may require an explicit migration and review.

Full decision history

Section titled “Full decision history”

Durable, cross-cutting decisions are recorded as append-only Architecture Decision Records in the repository: docs/adr/.