Improve arch.md / lessons-learned.md governance: agent→skill, MAINTAIN discipline, richer template

[waleedkadous]

Background

arch.md and lessons-learned.md are append-only by default. Every spec adds; nothing removes. Over time both files balloon — per-spec changelog sections, exhaustive file enumerations, retired-component graveyards, duplication of meta-spec content. The current MAINTAIN protocol asks the architecture-documenter agent to be thorough, which biases it toward adding rather than editing.

This issue groups several improvements that together shift the governance-doc workflow from "append by default" to "audit, then update."

Scope

1. Convert architecture-documenter agent → skill, invoke from MAINTAIN

The agent today gets invoked ad hoc. Move it to a skill so MAINTAIN invokes it as part of its standard flow. The skill rewrite is the natural place to bake in the discipline that the current prompt lacks.

Skill should explicitly include:

• A "What NOT to include" section: no per-file enumerations that go stale, no per-spec changelog sections, no specs/plans tables, no aspirational state, no date-stamped narrative, no duplication of meta-specs.
• Purpose-driven sizing guidance — the right size for each section is determined by purpose, not by current state.
• Two-doc framing: arch.md and lessons-learned.md are siblings with different purposes. arch.md owns system shape + unique mechanism + pointers; lessons-learned.md owns durable engineering wisdom; system-shape surprises ("looks like X but isn't") live in arch.md not lessons-learned.
• Two invocation modes: diff-mode (apply a specific change to the smallest section that needs updating) and audit-mode (read against the principles, identify what to cut, ask for confirmation before removing).

Apply to both codev-skeleton/ (template) and codev/ (self-hosted).

2. Replace codev-skeleton/codev/templates/arch.md

Current template is a 56-line scaffold with no opinion. Replace with a richer template that includes:

• A preface explaining how to read the doc, what NOT to put in it, and that sections should be skipped if they don't apply
• Section stubs for: TL;DR, Repository Layout & Stack, per-subsystem mechanism, Apps Roster, Packages Roster, Verified-Wrong Assumptions, Updating This Document
• Explicit "skip what doesn't apply" framing so small projects don't feel obligated to fill everything in

Write the template from scratch using Codev's own examples and idioms.

3. Ship a sibling codev/templates/arch-md-guide.md

A short (30-60 line) guide that ships alongside arch.md, covering: purpose, when to update, how to update, what NOT to put in, sanity-check checklist. This is the file that tells future maintainers (human or AI) how to keep arch.md healthy.

4. Add "Lives where" matrix to MAINTAIN

A reference matrix that routes each fact/insight to the right home:

Type of fact/insight	Lives in
Current system shape (services, transports, mental models)	arch.md
Mechanism for a unique subsystem	arch.md (subsystem section) OR a meta-spec
A durable engineering pattern that applies across specs	lessons-learned.md
A spec-narrow fix recipe	Spec review only
A system-shape surprise verified-wrong in production	arch.md § Verified-Wrong Assumptions
Aspirational architectural direction	The relevant meta-spec, NOT arch.md body
A changelog of "we shipped X in spec Y on date Z"	git log + spec review

(Categories and exact rows to be refined during implementation.)

5. Add audit-pass-before-update-pass to MAINTAIN

Currently MAINTAIN's "Update arch.md" task runs as a single pass that adds. Split into two phases:

• Audit pass: read both files against the principles, produce a list of sections that should be absorbed, retired, or compressed
• Update pass: apply audit conclusions, then add new content

Ship a sample audit prompt as part of the protocol — a checklist invocation that asks the skill to identify sections to cut, not just to add.

6. Add pruning discipline checklists to MAINTAIN

Concrete per-section / per-entry questions for the audit pass:

For each arch.md section:

• Does it describe current state? (If aspirational, move to a meta-spec.)
• Does it duplicate a meta-spec? (If yes, replace with a 1-paragraph summary + pointer.)
• Is it a per-file enumeration that's gone stale? (If yes, prune to top-level tree + key files.)
• Is it a changelog/narrative section? (If yes, absorb the architecturally-relevant facts; remove the spec-numbered framing.)

For each lessons-learned.md entry:

• Is it cross-applicable beyond the spec that produced it? (If no, remove.)
• Is it terse (1-3 sentences)? (If multi-paragraph, split or compress.)
• Is the topic section the right one? (If "Architecture (continued)" or spec-numbered, move.)
• Is it a duplicate of an adjacent entry? (If yes, fold.)

Constraints

• Apply changes to both codev-skeleton/ and codev/.
• Write all template/skill/protocol content from Codev's own perspective and examples — do not copy structure or wording from other projects.
• Keep guidance scale-agnostic. Avoid hard line-count budgets in shipped docs; if sizing guidance is included, frame it as purpose-driven rather than absolute numbers.

Out of scope (separate issues to follow)

• Surfacing the four general framework principles ("be opinionated about where facts live"; "ship guidance for what NOT to include alongside what to include"; "make pruning first-class"; "distinguish system-shape from engineering-wisdom") in top-level Codev framework guidance — the skill rewrite bakes these into the architecture-documenter discipline implicitly, but framework-wide articulation is a separate concern

• First-class documentation of the codev/architecture/<domain>.md meta-spec pattern (needs its own discovery)

• current-thread.md save-state convention (separate, smaller proposal)

• "Doc maintenance" checklist item in spec review templates (separate, lighter touch)

• Line-count diff visibility / threshold-based MAINTAIN flagging (could fold into the audit pass; defer until the audit pass exists)