@cluesmith/codev 3.0.0-rc.8 → 3.0.0-rc.9

package/skeleton/resources/workflow-reference.md

@@ -26,7 +26,7 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 │                               IMPLEMENTATION                                        │
 ├─────────────────────────────────────────────────────────────────────────────────────┤
 │  → 4. IMPLEMENTING                                                                  │
-│         Architect spawns builder: af spawn XXXX                                  │
+│         Architect spawns builder: afx spawn XXXX                                  │
 │         Builder reads spec and plan                                                 │
 │         For each phase: Implement → Defend → Evaluate                               │
 │         Builder commits after each phase                                            │
@@ -78,38 +78,38 @@ AI agents must stop and wait for human action at these gates.
 
 ```bash
 # Start the workspace
-af workspace start
+afx workspace start
 
 # Spawn a builder for a project
-af spawn 44 --protocol spir
+afx spawn 44 --protocol spir
 
 # Check all builder statuses
-af status
+afx status
 
 # Send message to builder
-af send 44 "Check PR comments and address feedback"
+afx send 44 "Check PR comments and address feedback"
 
 # Open a file for review
-af open codev/specs/44-name.md
+afx open codev/specs/44-name.md
 
 # Clean up after merge
-af cleanup -p 44
+afx cleanup -p 44
 
 # Stop everything
-af workspace stop
+afx workspace stop
 ```
 
 ### Builder Commands
 
 ```bash
 # Check your own status
-af status
+afx status
 
 # Send message to architect
-af send architect "Question about the spec..."
+afx send architect "Question about the spec..."
 
 # Open a file in the annotation viewer
-af open src/path/to/file.ts
+afx open src/path/to/file.ts
 ```
 
 ### Protocol Import
@@ -212,7 +212,7 @@ gh pr merge N --merge --delete-branch
 ### Post-Merge Cleanup (Architect)
 ```bash
 git pull                    # Get merged changes
-af cleanup -p XXXX          # Clean up builder worktree
+afx cleanup -p XXXX          # Clean up builder worktree
 ```
 
 ## Troubleshooting
@@ -221,7 +221,7 @@ af cleanup -p XXXX          # Clean up builder worktree
 
 1. Check builder terminal for blocker message
 2. Review any `// REVIEW(@architect):` comments in code
-3. Provide guidance via `af send XXXX "guidance here"`
+3. Provide guidance via `afx send XXXX "guidance here"`
 4. Builder will resume work after receiving help
 
 ### PR Has Conflicts
@@ -238,7 +238,7 @@ af cleanup -p XXXX          # Clean up builder worktree
 git worktree list
 
 # Force cleanup (only if work is committed/pushed)
-af cleanup -p XXXX --force
+afx cleanup -p XXXX --force
 ```
 
 ## Related Documentation

package/skeleton/roles/architect.md

@@ -8,7 +8,7 @@ The Architect is the **project manager and gatekeeper** who decides what to buil
 
 Builders work autonomously in isolated git worktrees. The Architect:
 1. **Decides** what to build
-2. **Spawns** builders via `af spawn`
+2. **Spawns** builders via `afx spawn`
 3. **Approves** gates (spec-approval, plan-approval) when in strict mode
 4. **Reviews** PRs for integration concerns
 
@@ -16,8 +16,8 @@ Builders work autonomously in isolated git worktrees. The Architect:
 
 | Mode | Command | Use When |
 |------|---------|----------|
-| **Strict** (default) | `af spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `af spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance |
+| **Strict** (default) | `afx spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `afx spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance |
 
 **Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention.
 
@@ -25,34 +25,34 @@ Builders work autonomously in isolated git worktrees. The Architect:
 
 ### Pre-Spawn Checklist
 
-**Before every `af spawn`, complete these steps:**
+**Before every `afx spawn`, complete these steps:**
 
 1. **`git status`** — Ensure worktree is clean (no uncommitted changes)
 2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible
-3. **`af spawn N --protocol <name>`** — `--protocol` is **REQUIRED** (spir, bugfix, tick, etc.)
+3. **`afx spawn N --protocol <name>`** — `--protocol` is **REQUIRED** (spir, bugfix, tick, etc.)
 
 The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files).
 
 ## Key Tools
 
-### Agent Farm CLI (`af`)
+### Agent Farm CLI (`afx`)
 
 ```bash
-af spawn 1 --protocol spir               # Strict mode (default) - porch-driven
-af spawn 1 --protocol spir -t "feature"  # Strict mode with title (no spec yet)
-af spawn 1 --resume                      # Resume existing porch state
-af spawn 1 --protocol spir --soft        # Soft mode - protocol-guided
-af spawn --task "fix the bug"            # Ad-hoc task builder (soft mode)
-af spawn --worktree                      # Worktree with no initial prompt
-af status                                # Check all builders
-af cleanup -p 0001                       # Remove completed builder
-af workspace start/stop                  # Workspace management
-af send 0001 "message"                   # Short message to builder
+afx spawn 1 --protocol spir               # Strict mode (default) - porch-driven
+afx spawn 1 --protocol spir -t "feature"  # Strict mode with title (no spec yet)
+afx spawn 1 --resume                      # Resume existing porch state
+afx spawn 1 --protocol spir --soft        # Soft mode - protocol-guided
+afx spawn --task "fix the bug"            # Ad-hoc task builder (soft mode)
+afx spawn --worktree                      # Worktree with no initial prompt
+afx status                                # Check all builders
+afx cleanup -p 0001                       # Remove completed builder
+afx workspace start/stop                  # Workspace management
+afx send 0001 "message"                   # Short message to builder
 ```
 
 > **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it.
 
-**Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
+**Note:** `afx`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
 
 ### Porch CLI (for strict mode)
 
@@ -95,16 +95,16 @@ wait
 # 3. Spawn the builder (--protocol is REQUIRED)
 
 # Default: Strict mode (porch-driven with gates)
-af spawn 42 --protocol spir
+afx spawn 42 --protocol spir
 
 # With project title (if no spec exists yet)
-af spawn 42 --protocol spir -t "user-authentication"
+afx spawn 42 --protocol spir -t "user-authentication"
 
 # Or: Soft mode (builder follows protocol independently)
-af spawn 42 --protocol spir --soft
+afx spawn 42 --protocol spir --soft
 
 # For bugfixes
-af spawn 42 --protocol bugfix
+afx spawn 42 --protocol bugfix
 ```
 
 ### 2. Approving Gates (Strict Mode Only)
@@ -120,7 +120,7 @@ cat .builders/spir-0042-feature-name/codev/specs/0042-feature-name.md
 (cd .builders/spir-0042-feature-name && porch approve 0042 spec-approval --a-human-explicitly-approved-this)
 
 # IMPORTANT: Always message the builder after approving a gate
-af send 0042 "Spec approved. Continue to plan phase."
+afx send 0042 "Spec approved. Continue to plan phase."
 ```
 
 **plan-approval** - After builder writes the plan
@@ -132,13 +132,13 @@ cat .builders/spir-0042-feature-name/codev/plans/0042-feature-name.md
 (cd .builders/spir-0042-feature-name && porch approve 0042 plan-approval --a-human-explicitly-approved-this)
 
 # IMPORTANT: Always message the builder after approving a gate
-af send 0042 "Plan approved. Continue to implement phase."
+afx send 0042 "Plan approved. Continue to implement phase."
 ```
 
 ### 3. Monitoring Progress
 
 ```bash
-af status              # Overview of all builders
+afx status              # Overview of all builders
 porch status 0042      # Detailed state for one project (strict mode)
 ```
 
@@ -182,7 +182,7 @@ Low-risk change. [Summary of what changed and why.]
 ---
 Architect review"
 
-af send 0042 "PR approved, please merge"
+afx send 0042 "PR approved, please merge"
 ```
 
 **Medium risk** — single-model review:
@@ -194,7 +194,7 @@ gh pr comment 83 --body "## Architect Integration Review
 ...
 Architect integration review"
 
-af send 0042 "PR approved, please merge"
+afx send 0042 "PR approved, please merge"
 ```
 
 **High risk** — full 3-way CMAP:
@@ -209,7 +209,7 @@ gh pr comment 83 --body "## Architect Integration Review
 ...
 Architect integration review"
 
-af send 0042 "PR approved, please merge"
+afx send 0042 "PR approved, please merge"
 ```
 
 ### 5. Cleanup
@@ -221,7 +221,7 @@ After builder merges and work is integrated:
 gh issue close 42
 
 # 2. Clean up the builder worktree
-af cleanup -p 0042
+afx cleanup -p 0042
 ```
 
 **Always close the GitHub Issue when the PR merges.** This is the architect's responsibility — builders don't close issues.
@@ -231,9 +231,9 @@ af cleanup -p 0042
 ### NEVER Do These:
 1. **DO NOT merge PRs yourself** - Let builders merge their own PRs
 2. **DO NOT commit directly to main** - All changes go through builder PRs
-3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
-4. **DO NOT run `af` commands from inside a builder worktree** - All `af` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything.
-5. **DO NOT `cd` into a builder worktree** - All CLI tools (`af`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`).
+3. **DO NOT use `afx send` for long messages** - Use GitHub PR comments instead
+4. **DO NOT run `afx` commands from inside a builder worktree** - All `afx` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything.
+5. **DO NOT `cd` into a builder worktree** - All CLI tools (`afx`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`).
 
 ### ALWAYS Do These:
 1. **Create GitHub Issues first** - Track projects as issues before spawning
@@ -261,9 +261,9 @@ Update status as projects progress:
 
 When a builder reports blocked:
 
-1. Check their status: `af status` or `porch status <id>`
+1. Check their status: `afx status` or `porch status <id>`
 2. Read their output in the terminal: `http://localhost:<port>`
-3. Provide guidance via short `af send` message
+3. Provide guidance via short `afx send` message
 4. Or answer their question directly if they asked one
 
 ## Release Management
@@ -295,10 +295,10 @@ Before approving implementations with UX requirements:
 
 | Task | Command |
 |------|---------|
-| Start feature (strict, default) | `af spawn <id> --protocol spir` |
-| Start feature (soft) | `af spawn <id> --protocol spir --soft` |
-| Start bugfix | `af spawn <id> --protocol bugfix` |
-| Check all builders | `af status` |
+| Start feature (strict, default) | `afx spawn <id> --protocol spir` |
+| Start feature (soft) | `afx spawn <id> --protocol spir --soft` |
+| Start bugfix | `afx spawn <id> --protocol bugfix` |
+| Check all builders | `afx status` |
 | Check one project | `porch status <id>` |
 | Approve spec | `porch approve <id> spec-approval` |
 | Approve plan | `porch approve <id> plan-approval` |
@@ -306,5 +306,5 @@ Before approving implementations with UX requirements:
 | Assess PR risk | `gh pr diff --stat N` |
 | Integration review (medium) | `consult -m claude --type integration pr N` |
 | Integration review (high) | 3-way CMAP (see Section 4) |
-| Message builder | `af send <id> "short message"` |
-| Cleanup builder | `af cleanup -p <id>` |
+| Message builder | `afx send <id> "short message"` |
+| Cleanup builder | `afx cleanup -p <id>` |

package/skeleton/roles/builder.md

@@ -8,12 +8,12 @@ Builders run in one of two modes, determined by how they were spawned:
 
 | Mode | Command | Behavior |
 |------|---------|----------|
-| **Strict** (default) | `af spawn XXXX` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `af spawn XXXX --soft` | AI follows protocol - architect verifies compliance |
+| **Strict** (default) | `afx spawn XXXX` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `afx spawn XXXX --soft` | AI follows protocol - architect verifies compliance |
 
 ## Strict Mode (Default)
 
-Spawned with: `af spawn XXXX`
+Spawned with: `afx spawn XXXX`
 
 In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**.
 
@@ -68,7 +68,7 @@ You must:
 
 ## Soft Mode
 
-Spawned with: `af spawn XXXX --soft` or `af spawn --task "..."`
+Spawned with: `afx spawn XXXX --soft` or `afx spawn --task "..."`
 
 In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly.
 
@@ -129,27 +129,27 @@ wait
 
 If you're blocked or need help:
 ```bash
-af send architect "Question about the spec..."
+afx send architect "Question about the spec..."
 ```
 
 ### Checking Status
 
 ```bash
 porch status      # (strict mode) Your project status
-af status         # All builders
+afx status         # All builders
 ```
 
 ## Notifications
 
-**ALWAYS notify the architect** via `af send` at these key moments:
+**ALWAYS notify the architect** via `afx send` at these key moments:
 
 | When | What to send |
 |------|-------------|
-| **Gate reached** | `af send architect "Project XXXX: <gate-name> ready for approval"` |
-| **PR ready** | `af send architect "PR #N ready for review"` |
-| **PR merged** | `af send architect "Project XXXX complete. PR merged. Ready for cleanup."` |
-| **Blocked/stuck** | `af send architect "Blocked on X — need guidance"` |
-| **Escalation needed** | `af send architect "Issue too complex — recommend escalating to SPIR/TICK"` |
+| **Gate reached** | `afx send architect "Project XXXX: <gate-name> ready for approval"` |
+| **PR ready** | `afx send architect "PR #N ready for review"` |
+| **PR merged** | `afx send architect "Project XXXX complete. PR merged. Ready for cleanup."` |
+| **Blocked/stuck** | `afx send architect "Blocked on X — need guidance"` |
+| **Escalation needed** | `afx send architect "Issue too complex — recommend escalating to SPIR/TICK"` |
 
 The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly.
 
@@ -158,7 +158,7 @@ The architect may be working on other tasks and won't know you need attention un
 If you encounter issues you can't resolve:
 
 1. **Output a clear blocker message** describing the problem and options
-2. **Use `af send architect "..."` to notify the Architect**
+2. **Use `afx send architect "..."` to notify the Architect**
 3. **Wait for guidance** before proceeding
 
 Example:

package/skeleton/templates/AGENTS.md

@@ -50,7 +50,7 @@ Commit messages format:
 Codev provides three CLI tools:
 
 - **codev**: Project management (init, adopt, update, doctor)
-- **af**: Agent Farm orchestration (start, spawn, status, cleanup)
+- **afx**: Agent Farm orchestration (start, spawn, status, cleanup)
 - **consult**: AI consultation for reviews (general, protocol, stats)
 
 For complete reference, see `codev/resources/commands/`:
@@ -61,7 +61,7 @@ For complete reference, see `codev/resources/commands/`:
 
 ## Configuration
 
-Agent Farm is configured via `af-config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.
+Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.
 
 ```json
 {

package/skeleton/templates/CLAUDE.md

@@ -48,7 +48,7 @@ Commit messages format:
 Codev provides three CLI tools:
 
 - **codev**: Project management (init, adopt, update, doctor)
-- **af**: Agent Farm orchestration (start, spawn, status, cleanup)
+- **afx**: Agent Farm orchestration (start, spawn, status, cleanup)
 - **consult**: AI consultation for reviews (general, protocol, stats)
 
 For complete reference, see `codev/resources/commands/`:
@@ -59,7 +59,7 @@ For complete reference, see `codev/resources/commands/`:
 
 ## Configuration
 
-Agent Farm is configured via `af-config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.
+Agent Farm is configured via `.codev/config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`.
 
 ```json
 {

package/skeleton/templates/cheatsheet.md

@@ -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/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 {