@cluesmith/codev 3.0.0 → 3.0.2

package/skeleton/templates/arch.md

@@ -1,56 +1,126 @@
 # Architecture
 
-High-level architecture documentation for this project. Updated during MAINTAIN protocol runs.
+The architecture document for this project. Skim it to orient yourself; reach for the meta-specs under `codev/architecture/` (if any) or the relevant subsystem section for depth.
 
-## Overview
+> **How to use this template**: Each section below is a stub with a one-line "skip if N/A" hint. Delete sections that don't apply to your project — small projects often only need TL;DR, Repository Layout & Stack, and Updating This Document. Bigger systems will fill in more. The goal is orientation, not completeness.
 
-<!-- Brief description of the project and its purpose -->
+## TL;DR
 
-## Directory Structure
+A 2–4 sentence summary of what this project is, the language/stack, the deployment shape, and the single most important mental model a new contributor needs.
+
+*Example*: "A monorepo of TypeScript packages and a CLI. The CLI talks to a long-running orchestrator process (Tower) over WebSockets. The orchestrator manages git worktrees, one per builder. The mental model is: 'CLI = thin client; Tower = state owner.'"
+
+## Repository Layout & Stack
+
+The shape of the repo and the languages/frameworks in use. Not a per-file enumeration — a `tree -L 2` view plus 2–3 lines on each top-level directory's role is plenty.
+
+> *Skip if N/A: a single-package project that's well-served by `package.json` alone.*
 
 ```
 project-root/
-├── codev/           # Development methodology
-│   ├── specs/       # Feature specifications
-│   ├── plans/       # Implementation plans
-│   └── reviews/     # Post-implementation reviews
-└── [your code]      # Project source code
+├── packages/        # Workspace packages
+├── codev/           # Specs, plans, reviews, protocol files
+├── docs/            # User-facing documentation
+└── ...
 ```
 
-## Key Components
+**Stack**: language version(s), framework(s), package manager. Avoid pinning exact patch versions; the lockfile is authoritative for those.
+
+## Per-Subsystem Mechanism
+
+For each subsystem with **unique mechanism** — something a reader cannot derive from reading the code in 5 minutes — give it a section here. Mechanism means: how the pieces fit together, what invariants hold, what surprised the team.
+
+> *Skip if N/A: subsystems whose mechanism is well-conveyed by the code itself or by a meta-spec under `codev/architecture/<domain>.md`. In that case, replace this section with a 1-paragraph summary + pointer.*
+
+### [Subsystem name]
+
+**Purpose**: One sentence on what this subsystem owns.
+
+**Mechanism**: How it works. Invariants. Failure modes worth knowing.
+
+**Pointer**: `codev/architecture/<domain>.md` (if a meta-spec exists).
+
+## Apps Roster
+
+For projects that ship multiple deployable apps — a CLI, a web service, a worker, etc. List them with a one-liner each.
+
+> *Skip if N/A: single-app projects.*
 
-<!-- Document major modules, services, or subsystems -->
+| App | Purpose | Entry point |
+|---|---|---|
+| `cli` | Command-line interface | `packages/cli/src/index.ts` |
+| `worker` | Background job runner | `apps/worker/src/main.ts` |
 
-### Component 1
+## Packages Roster
 
-**Location**: `src/...`
+For monorepos. List the workspace packages with a one-liner each. Do not duplicate `pnpm-workspace.yaml` or `package.json` — link to them.
 
-**Purpose**: ...
+> *Skip if N/A: non-monorepo projects.*
 
-**Key Files**:
-- `file1.ts` - ...
-- `file2.ts` - ...
+| Package | Purpose |
+|---|---|
+| `@org/core` | Domain logic, no I/O |
+| `@org/cli` | CLI entry point, depends on core |
 
-## Data Flow
+## Verified-Wrong Assumptions
 
-<!-- How data moves through the system -->
+System-shape surprises that have been verified wrong in production. Each entry is one or two sentences: *"It looks like X but is actually Y. We learned this when ..."*. This section earns its keep by saving future readers from the same mistake.
 
-## External Dependencies
+> *Skip if N/A: nothing has surprised you yet. Add entries as they're discovered.*
 
-<!-- Third-party services, APIs, databases -->
+- *Example*: "It looks like the CLI talks to Tower over HTTP, but the WebSocket bidirectional channel is the actual transport — the HTTP routes are only used for `/health` and one-off lookups. We learned this when adding a new command broke because we wrote it as a fetch call."
 
-| Dependency | Purpose | Documentation |
-|------------|---------|---------------|
-| Example | ... | [docs](url) |
+## Updating This Document
 
-## Configuration
+This is a single-page orientation doc, not a wiki. Keep it sized to its purpose.
 
-<!-- Environment variables, config files -->
+### When to update
 
-## Conventions
+- After a MAINTAIN run that changed system shape.
+- When a subsystem's mechanism changes meaningfully (not when one file gets renamed).
+- When a verified-wrong assumption is discovered.
+- *Not* every spec; specs already produce reviews and git history. Don't duplicate that here.
 
-<!-- Coding standards, naming conventions, patterns used -->
+### How to update
 
----
+Use the `update-arch-docs` skill. It runs in two modes:
+
+- **diff-mode**: apply a specific change to the smallest section that needs updating.
+- **audit-mode**: read the doc end-to-end against the discipline below and propose cuts with reasons.
+
+The skill edits this file directly via normal file-edit tooling. It does not invoke destructive shell commands; everything goes through Edit. The MAINTAIN PR diff is the human-confirmation step.
+
+### What NOT to put in
+
+The main pressure on this document is unchecked growth. Reject all of the following:
+
+- **Per-file enumerations** that go stale. Document directory shape and key files; let `git ls-files` be authoritative for the rest.
+- **Per-spec changelog sections** ("Spec 0042 added X"). The git log + the spec/review docs own this framing. Architecture is current state, not history.
+- **Specs/plans tables** that mirror `codev/specs/` and `codev/plans/`. Link to the directory; do not paginate it here.
+- **Aspirational state** ("we plan to…"). That's a meta-spec or a roadmap doc, not architecture.
+- **Date-stamped narrative** ("As of 2026-Q2…"). Looks fresh; ages worse than a calendar.
+- **Duplication of meta-spec content**. If a subsystem has a meta-spec, this doc carries a 1-paragraph summary plus a pointer.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` keeps the history.
+
+### Sanity-check checklist
+
+Before committing an arch.md change, run through these:
+
+1. Does the section describe **current state**, not aspiration?
+2. Does it duplicate a meta-spec? If yes, replace with a summary + pointer.
+3. Is the section orienting (worth a reader's 30 seconds), or is it exhaustive?
+4. Could a future reader skip this section without losing anything load-bearing?
+5. If audit-mode produced cuts, does each cut have a one-line reason in the MAINTAIN run file?
+6. Does the doc still feel like it can be skimmed end-to-end in under 5 minutes?
+
+### Note on propagation
+
+By design, **`codev init`, `codev adopt`, and `codev update` do not copy framework templates** (including this `arch.md` template) into the consuming project's filesystem. They are framework files that resolve at runtime from the installed `@cluesmith/codev` npm package — see `packages/codev/src/commands/init.ts` and `adopt.ts` (the `// Framework files ... are NOT copied` comments).
+
+To opt into this richer template for a project's *living* `codev/resources/arch.md`, copy it manually:
+
+```bash
+cp $(node -p 'require.resolve("@cluesmith/codev/skeleton/templates/arch.md")') codev/resources/arch.md
+```
 
-*Generated by MAINTAIN protocol. To update: run MAINTAIN or edit directly.*
+(Or, if developing inside the codev repo itself, simply `cp codev-skeleton/templates/arch.md codev/resources/arch.md` and edit from there.)

package/skeleton/templates/cheatsheet.md

@@ -41,7 +41,7 @@ Just like structuring a human team—clear roles, defined processes, explicit ha
 
 | Component | Purpose |
 |-----------|---------|
-| Protocols | Define HOW work happens (SPIR, TICK, etc.) |
+| Protocols | Define HOW work happens (SPIR, ASPIR, etc.) |
 | Roles | Define WHO does what (Architect, Builder, Consultant) |
 | Parallelism | Scale by running multiple builders simultaneously |
 
@@ -61,9 +61,9 @@ A **protocol** is a structured workflow that defines how work progresses from id
 | Protocol | Use For | Phases |
 |----------|---------|--------|
 | **SPIR** | New features | Specify → Plan → Implement → Review |
-| **TICK** | Amendments to existing specs | Task Identification → Coding → Kickout |
 | **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync |
 | **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude |
+| **RESEARCH** | Multi-agent research | Scope → Investigate (3-way) → Synthesize → Critique (3-way) |
 
 ### Roles
 
@@ -105,21 +105,21 @@ Project management commands. Typically used by **humans** to set up and maintain
 | `codev update` | Update Codev framework |
 | `codev import` | Import specs from another project |
 
-### agent-farm (af)
+### agent-farm (afx)
 
 Architect-Builder orchestration. Used by both **humans and agents**—agents use it more frequently.
 
 | Command | Description |
 |---------|-------------|
-| `af workspace start` | Start workspace (port 4200, 4300, etc.) |
-| `af workspace stop` | Stop all processes |
-| `af spawn <id> --protocol spir` | Spawn a builder for project |
-| `af status` | Check status of all builders |
-| `af send <target> <msg>` | Send message (builder↔architect) |
-| `af cleanup -p <id>` | Clean up a builder worktree |
-| `af shell` | Spawn a utility shell |
-| `af open <file>` | Open file in workspace viewer |
-| `af tower start` | Start cross-project tower |
+| `afx workspace start` | Start workspace (port 4200, 4300, etc.) |
+| `afx workspace stop` | Stop all processes |
+| `afx spawn <id> --protocol spir` | Spawn a builder for project |
+| `afx status` | Check status of all builders |
+| `afx send <target> <msg>` | Send message (builder↔architect) |
+| `afx cleanup -p <id>` | Clean up a builder worktree |
+| `afx shell` | Spawn a utility shell |
+| `afx open <file>` | Open file in workspace viewer |
+| `afx tower start` | Start cross-project tower |
 
 ### consult
 

package/skeleton/templates/lessons-learned.md

@@ -1,28 +1,66 @@
 # Lessons Learned
 
-> Extracted from `codev/reviews/`. Last updated: YYYY-MM-DD
+Engineering wisdom that applies *across multiple specs*, extracted from review documents during MAINTAIN runs.
+
+> **How to read this doc**: Skim by topic section. Each entry is 1–3 sentences and states a general principle. If you need the full story behind a lesson, follow the link to the originating review.
+
+## What goes here, what does not
+
+This file is a sibling to `codev/resources/arch.md`. They have different purposes:
+
+- `arch.md` owns **system shape** — services, transports, mental models, verified-wrong assumptions about *this* system.
+- `lessons-learned.md` owns **durable engineering wisdom** — patterns that apply across specs, projects, and time.
+
+When you have a fact that's specific to one feature, it belongs in that feature's review, not here.
+
+### Add an entry when
+
+- A pattern surfaced in two or more specs/reviews.
+- A failure mode is general enough that future contributors will hit it on unrelated work.
+- A practice was confirmed (the team adopted it after trying alternatives).
+
+### Do NOT add an entry when
+
+- **Spec-narrow recipes** that only matter inside the originating feature. Those belong in the spec's review document.
+- **Multi-paragraph entries**. If a lesson needs more than 1–3 sentences, it is either two lessons or it is documentation that belongs elsewhere.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one entry.
+- **Spec-numbered narrative** ("Lesson from #0468:…"). Link to the review if useful; state the lesson itself as a general principle.
+
+### Sanity-check checklist
+
+Before adding or keeping an entry, run through these:
+
+1. Is it cross-applicable beyond the spec that produced it?
+2. Is it terse (1–3 sentences)?
+3. Is the topic section the right home? (If "Architecture (continued)" or spec-numbered, move it.)
+4. Is it a duplicate of an adjacent entry? (If yes, fold them.)
+5. Could the lesson be stated as a general principle, independent of the originating feature?
+
+If any answer is "no," either reshape the entry or move it to the originating spec's review.
+
+---
 
 ## Testing
 
-<!-- Lessons about testing patterns, test isolation, mocking, etc. -->
+<!-- Patterns about test isolation, mocking, fixtures, regression coverage. -->
 
 ## Architecture
 
-<!-- Lessons about system design, state management, file organization -->
+<!-- Patterns about system design, state management, file organization. -->
 
 ## Process
 
-<!-- Lessons about protocol execution, consultation, PR workflow -->
+<!-- Patterns about protocol execution, consultation, PR workflow. -->
 
 ## Tooling
 
-<!-- Lessons about CLI tools, dependencies, build systems -->
+<!-- Patterns about CLI tools, dependencies, build systems. -->
 
 ## Integration
 
-<!-- Lessons about external APIs, third-party services, auth -->
+<!-- Patterns about external APIs, third-party services, auth. -->
 
 ---
 
 *Generated by MAINTAIN protocol from review documents.*
-*To add lessons: document them in review files, then run MAINTAIN.*
+*To add lessons: document them in review files, then run MAINTAIN with the `update-arch-docs` skill.*

package/templates/3d-viewer.html

@@ -12,7 +12,7 @@
     }
 
     body {
-      background: #000000;
+      background: #4D4D4D;
       color: #e0e0e0;
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
       overflow: hidden;
@@ -276,7 +276,7 @@
     function init() {
       // Scene
       scene = new THREE.Scene();
-      scene.background = new THREE.Color(0x000000);
+      scene.background = new THREE.Color(0x4D4D4D);
 
       // Cameras (Z-up coordinate system)
       const aspect = container.clientWidth / container.clientHeight;
@@ -378,21 +378,20 @@
           geometry.computeBoundingBox();
           const center = new THREE.Vector3();
           geometry.boundingBox.getCenter(center);
-          geometry.translate(-center.x, -center.y, -center.z);
+          // Only center in XY; Three.js translate() auto-updates boundingBox
+          geometry.translate(-center.x, -center.y, 0);
 
           // Move to sit on grid (Z=0 plane)
-          const minZ = geometry.boundingBox.min.z - center.z;
-          geometry.translate(0, 0, -minZ);
+          geometry.translate(0, 0, -geometry.boundingBox.min.z);
 
-          // Recalculate bounding box after translation
-          geometry.computeBoundingBox();
+          // Compute vertex normals for smooth Phong shading
+          geometry.computeVertexNormals();
 
           // Material
           const material = new THREE.MeshPhongMaterial({
             color: 0x3b82f6,
-            specular: 0x111111,
-            shininess: 30,
-            flatShading: false
+            specular: 0x222222,
+            shininess: 60
           });
 
           model = new THREE.Mesh(geometry, material);
@@ -775,21 +774,20 @@
         geometry.computeBoundingBox();
         const center = new THREE.Vector3();
         geometry.boundingBox.getCenter(center);
-        geometry.translate(-center.x, -center.y, -center.z);
+        // Only center in XY; Three.js translate() auto-updates boundingBox
+        geometry.translate(-center.x, -center.y, 0);
 
         // Move to sit on grid (Z=0 plane)
-        const minZ = geometry.boundingBox.min.z - center.z;
-        geometry.translate(0, 0, -minZ);
+        geometry.translate(0, 0, -geometry.boundingBox.min.z);
 
-        // Recalculate bounding box after translation
-        geometry.computeBoundingBox();
+        // Compute vertex normals for smooth Phong shading
+        geometry.computeVertexNormals();
 
         // Create new material
         const material = new THREE.MeshPhongMaterial({
           color: 0x3b82f6,
-          specular: 0x111111,
-          shininess: 30,
-          flatShading: false
+          specular: 0x222222,
+          shininess: 60
         });
 
         model = new THREE.Mesh(geometry, material);

package/templates/tower.html

@@ -1162,7 +1162,7 @@
           <div class="empty-state">
             <div class="icon">📭</div>
             <h2>No running workspaces</h2>
-            <p>Start a new workspace below or run <code>af dash start</code> in a workspace directory.</p>
+            <p>Start a new workspace below or run <code>afx workspace start</code> in a workspace directory.</p>
           </div>
         `;
       } else {