Curated, always-on guidance — consult before deciding. Use each "consult when…" map to open the full arch.md / lessons-learned.md when relevant.
@codev/resources/arch-critical.md @codev/resources/lessons-critical.md
The block above is auto-generated from the hot tier by
codev init/codev update— edit those source files, not the block. Their COLD counterparts (codev/resources/arch.md,lessons-learned.md) are on-demand archives; the "consult when…" maps point into them. New facts are routed by tier at review time and policed during MAINTAIN.
AGENTS.md is a byte-identical twin of this file for tools that read the AGENTS.md standard. Any edit here must be applied there.
Two trees, and the distinction governs almost every change:
| Tree | What it is | When you edit it |
|---|---|---|
codev/ |
Our instance — our specs, plans, reviews, resources | Implementing a feature for Codev |
codev-skeleton/ |
The template shipped to adopters — protocols, roles, templates, agents | Changing what other projects receive |
A framework change usually belongs in both. codev-skeleton/ carries no specs or
plans — those are created by the projects that install it.
Protocols, prompts, roles and templates resolve at runtime through four tiers, highest
first: .codev/<path> → codev/<path> → runtime cache → installed package skeleton.
The absence of codev/protocols/<name>/ is normal, not a missing reference — it means the
protocol resolves from the installed package. Only protocols you customize need a local copy.
When codev update merges a template that references a protocol you don't have locally, keep
the reference.
Deliver framework content; don't instruct an agent to fetch it by path. A builder-facing
prompt or role doc must not say "read codev/protocols/…" — that bypasses the resolver and
fails in fresh installs. protocol.md is inlined into the spawn prompt; phase prompts and
their templates arrive via porch. Naming a codev/... path in prose for orientation is fine;
the rule is about fetching. (codev/resources/arch.md and lessons-learned.md are
user-evolved files, not framework files — referencing those by path is correct.)
Verify an unfamiliar protocol against the CLI rather than assuming: afx spawn --protocol <name> --help succeeds if it is registered, including via the skeleton fallback.
These are not style preferences. Each one is here because an agent destroyed work or bypassed a human decision.
- Never
git add -A/--all/.— stage each file explicitly by path. - Never destroy builder worktrees (
git worktree remove,git branch -Don builder branches,afx cleanup+ respawn). Useafx spawn <id> --resume; if it fails, ask the human — what is expendable is never your call. - Never run
git reset --hard,git checkout -- .,git clean -fd, orgit stashwithout explicit human permission — they destroy uncommitted work. - Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
- Never hand-edit
status.yaml— only porch commands modify project state. - Run
afxcommands only from the main workspace root, never from inside a builder worktree — spawning from a worktree nests builders and breaks the workspace. - Never kill a shellper process without verifying it is an orphan (match each PID to its workspace via Tower) — an 'extra' shellper may be a live architect session.
- Never restart or stop Tower without explicit human permission — it kills every running builder session.
Two human approval gates plus the PR gate. Only a human transitions
conceived → specified and committed → integrated. Stop and wait at each; do not infer
approval from silence.
Approved specs and plans need frontmatter and must be committed to main before spawning.
Porch runs the full protocol from specify, but treats an artifact carrying this as done:
---
approved: 2026-01-29
validated: [gemini, codex, claude]
---Pick by the nature of the work, not its size. Full definitions in codev/protocols/<name>/
(or the package skeleton).
| Protocol | Use when |
|---|---|
| BUGFIX | A bug in a GitHub issue; isolated fix; no spec/plan needed |
| AIR | Small feature fully described in an issue; no architectural decisions |
| PIR | The approach needs review before coding, or the change must be tested running (mobile, UI, hardware, OAuth) before a PR exists |
| SPIR | New feature from scratch, new protocol, architecture change |
| ASPIR | SPIR without the spec/plan human gates — trusted, low-risk work |
| EXPERIMENT | Proof of concept, model/library evaluation, research spike |
| MAINTAIN | Dead code, dependency cleanup, doc sync (arch/lessons, CLAUDE↔AGENTS) |
| RESEARCH | Competitive/technology analysis; output to codev/research/ |
Skip protocol ceremony for README typos, template one-liners, and dependency bumps.
Issues are the source of truth for tracking. spec and plan labels mark approved
artifacts; porch status <id> gives live phase detail; close the issue when the PR merges.
Three documents per feature, same filename in three directories — spec defines what, plan defines how, review captures what was learned:
codev/specs/42-feature-name.md
codev/plans/42-feature-name.md
codev/reviews/42-feature-name.md
Sequential numbering, no leading zeros. Keep specs and plans separate; they answer different questions.
area/* is the primary organizing axis — group, audit and bulk-move issues by area first.
Exactly one area/* per issue. Multi-area work uses area/cross-cutting alone. There
are no type:* labels.
area/: docs · vscode · dashboard · consult · tower (includes afx; there is no
area/agent-farm) · porch · protocols (definitions, distinct from porch orchestration) ·
config · terminal · scaffold · release · web · core · cross-cutting
Enabled by default. Three reviewers: Gemini via the Antigravity CLI (agy, skips
non-blockingly if unauthenticated), GPT-5.6 Sol (gpt-5.6-sol — the -sol suffix is
load-bearing) via the Codex SDK, and Claude Opus 5 via the Agent SDK. Disable only when
the user says "without consultation".
Consult after writing implementation code and after writing tests, before presenting results. "cmap" means run all three in parallel in the background and return control immediately.
Commit messages:
[Spec 42] Initial specification draft
[Spec 42][Phase: user-auth] feat: Add password hashing
[Bugfix #42] Fix: URL-encode username before API call
Branches: spir/42-feature-name/phase-name, builder/bugfix-42-description.
Merge PRs with gh pr merge <n> --merge — never squash. Individual commits document the
development process; squashing destroys it.
Architects create specs and plans and review work; builders implement in isolated worktrees
under .builders/<id>/. Commit everything before afx spawn — builders branch from HEAD, so
uncommitted work is invisible to them.
Agents message each other with afx send:
| Form | Meaning |
|---|---|
afx send <builder-id> "…" |
A specific builder |
afx send architect "…" |
From a builder: its spawning architect. From anyone else: the architect named main, else the first registered |
afx send architect:<name> "…" |
A named architect. Architects may address any architect; a builder may only use this for its own spawning architect — mismatches are rejected as spoofing |
afx send <workspace>:architect "…" |
Cross-workspace |
afx send requires the workspace active in Tower (afx workspace start).
Each builder keeps a narrative log at codev/state/<builder-id>_thread.md — in-flight at
.builders/<id>/codev/state/, and on main after the PR merges.
Each CLI has a skill carrying its commands and flags — check the skill before running the
command rather than guessing: afx (spawn, status, send, dev, cleanup, Tower),
codev (init, adopt, update, doctor, local build/test), porch (status, run, approve),
consult (reviews, cmap, stats), runnable-worktrees (making builder
worktrees runnable), update-arch-docs.
afx open <file> opens the annotation viewer — it is not the system open.
Run anything slower than ~5s in the background (run_in_background: true, not a trailing
&): tests, consultations, installs, e2e suites.
Configuration lives in .codev/config.json.
UI changes (tower, dashboard, terminal) must be verified in a browser via Playwright before
being called done — see codev/resources/testing-guide.md.
Say "Let's release v1.6.0"; the RELEASE protocol (codev/protocols/release/protocol.md)
carries the procedure.