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

package/skeleton/protocols/spike/builder-prompt.md

@@ -37,7 +37,7 @@ Follow this 3-step workflow. You can skip or reorder steps as the investigation
 - Write findings to `codev/spikes/<id>-<name>.md` using the template
 - Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats
 - Commit the findings document
-- Notify the architect: `af send architect "Spike <id> complete. Verdict: [verdict]"`
+- Notify the architect: `afx send architect "Spike <id> complete. Verdict: [verdict]"`
 
 ## Key Principles
 

package/skeleton/protocols/spike/protocol.md

@@ -25,8 +25,8 @@ Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What wo
 ## Spawning a Spike
 
 ```bash
-af spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
-af spawn --task "What would it take to support SQLite FTS?" --protocol spike
+afx spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
+afx spawn --task "What would it take to support SQLite FTS?" --protocol spike
 ```
 
 Spikes are always soft mode — no porch orchestration, no gates, no consultation.
@@ -83,7 +83,7 @@ POC code from the iterate step is committed to the spike branch alongside the fi
 
 In all cases, notify the architect:
 ```bash
-af send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
+afx send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
 ```
 
 ## Git Workflow

package/skeleton/protocols/spir/builder-prompt.md

@@ -54,11 +54,11 @@ Follow the implementation plan at: `{{plan.path}}`
 {{/if}}
 
 ## Notifications
-Always use `af send architect "..."` to notify the architect at key moments:
-- **Gate reached**: `af send architect "Project {{project_id}}: <gate-name> ready for approval"`
-- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"`
-- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
-- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `afx send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
+- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`
 
 ## Handling Flaky Tests
 

package/skeleton/protocols/spir/protocol.json

@@ -53,7 +53,7 @@
       },
       "checks": {
         "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md",
-        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md",
+        "has_phases_json": "grep -qE '\"phases\"\\s*:' codev/plans/${PROJECT_TITLE}.md",
         "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
       },
       "gate": "plan-approval",

package/skeleton/protocols/spir/protocol.md

@@ -9,10 +9,10 @@
 ## Prerequisites
 
 **Clean Worktree Before Spawning Builders**:
-- All specs, plans, and local changes **MUST be committed** before `af spawn`
+- All specs, plans, and local changes **MUST be committed** before `afx spawn`
 - Builders work in git worktrees branched from HEAD — uncommitted files are invisible
 - This includes `codev update` results, spec drafts, and plan approvals
-- The `af spawn` command enforces this (use `--force` to override)
+- The `afx spawn` command enforces this (use `--force` to override)
 
 **Required for Multi-Agent Consultation**:
 - The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`)

package/skeleton/resources/commands/agent-farm.md

@@ -1,11 +1,11 @@
-# af - Agent Farm CLI
+# afx - Agent Farm CLI
 
-The `af` (agent-farm) command manages multi-agent orchestration for software development. It spawns and manages builders in isolated git worktrees.
+The `afx` (agent-farm) command manages multi-agent orchestration for software development. It spawns and manages builders in isolated git worktrees.
 
 ## Synopsis
 
 ```
-af <command> [options]
+afx <command> [options]
 ```
 
 ## Global Options
@@ -18,18 +18,18 @@ af <command> [options]
 
 ## Commands
 
-### af workspace
+### afx workspace
 
 Workspace commands - start/stop the workspace for this project.
 
-> **Deprecation note:** `af dash` is a deprecated alias for `af workspace`. It still works but prints a deprecation warning.
+> **Deprecation note:** `afx dash` is a deprecated alias for `afx workspace`. It still works but prints a deprecation warning.
 
-#### af workspace start
+#### afx workspace start
 
 Start the workspace.
 
 ```bash
-af workspace start [options]
+afx workspace start [options]
 ```
 
 **Options:**
@@ -53,16 +53,16 @@ The workspace overview is accessible via browser at `http://localhost:<port>`.
 
 ```bash
 # Start with defaults
-af workspace start
+afx workspace start
 
 # Start with custom port
-af workspace start -p 4300
+afx workspace start -p 4300
 
 # Start with specific command
-af workspace start -c "claude --model opus"
+afx workspace start -c "claude --model opus"
 
 # Start on remote machine
-af workspace start --remote user@host
+afx workspace start --remote user@host
 ```
 
 #### Remote Access
@@ -71,13 +71,13 @@ Start Agent Farm on a remote machine and access it from your local workstation w
 
 ```bash
 # On your local machine - one command does everything:
-af workspace start --remote user@remote-host
+afx workspace start --remote user@remote-host
 
 # Or with explicit project path:
-af workspace start --remote user@remote-host:/path/to/project
+afx workspace start --remote user@remote-host:/path/to/project
 
 # With custom port:
-af workspace start --remote user@remote-host --port 4300
+afx workspace start --remote user@remote-host --port 4300
 ```
 
 This single command:
@@ -92,16 +92,16 @@ The workspace and all terminals work identically to local development. Press Ctr
 
 **Port Selection:**
 
-The port is determined by the global port registry (`af ports list`). Each project gets a consistent 100-port block (e.g., 4200-4299, 4600-4699). The same port is used on both local and remote ends for the SSH tunnel.
+The port is determined by the global port registry (`afx ports list`). Each project gets a consistent 100-port block (e.g., 4200-4299, 4600-4699). The same port is used on both local and remote ends for the SSH tunnel.
 
 ```bash
 # Check your project's port allocation
-af ports list
+afx ports list
 ```
 
 **Prerequisites:**
 - SSH server must be running on the remote machine
-- Agent Farm (`af`) must be installed on the remote machine
+- Agent Farm (`afx`) must be installed on the remote machine
 - **Passwordless SSH required** - set up with `ssh-copy-id user@host`
 - Same version of codev on both machines (warnings shown if mismatched)
 
@@ -112,23 +112,23 @@ If the remote can't find `claude` or other commands, ensure they're in your PATH
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-**Limitation**: File annotation tabs (`af open`) use separate ports and won't work through the tunnel. Use terminals for file viewing, or forward additional ports manually.
+**Limitation**: File annotation tabs (`afx open`) use separate ports and won't work through the tunnel. Use terminals for file viewing, or forward additional ports manually.
 
 **Legacy mode** (deprecated):
 
 ```bash
 # DEPRECATED: Exposes workspace without authentication
-af workspace start --allow-insecure-remote
+afx workspace start --allow-insecure-remote
 ```
 
 The `--allow-insecure-remote` flag binds to `0.0.0.0` with no authentication. Use `--remote` instead for secure access via SSH.
 
-#### af workspace stop
+#### afx workspace stop
 
 Stop all agent farm processes for this project.
 
 ```bash
-af workspace stop
+afx workspace stop
 ```
 
 **Description:**
@@ -137,16 +137,16 @@ Stops all running agent-farm processes including:
 - Terminal sessions (shellper processes)
 - Workspace servers
 
-Does NOT clean up worktrees - use `af cleanup` for that.
+Does NOT clean up worktrees - use `afx cleanup` for that.
 
 ---
 
-### af spawn
+### afx spawn
 
 Spawn a new builder.
 
 ```bash
-af spawn [issue-number] --protocol <name> [options]
+afx spawn [issue-number] --protocol <name> [options]
 ```
 
 **Arguments:**
@@ -181,19 +181,19 @@ Creates a new builder in an isolated git worktree. The builder gets:
 
 ```bash
 # Spawn builder for issue #42 — --protocol is REQUIRED
-af spawn 42 --protocol spir
+afx spawn 42 --protocol spir
 
 # Spawn builder for a bugfix
-af spawn 42 --protocol bugfix
+afx spawn 42 --protocol bugfix
 
 # Spawn with task description (no --protocol needed)
-af spawn --task "Fix login bug in auth module"
+afx spawn --task "Fix login bug in auth module"
 
 # Spawn bare Claude session (no --protocol needed)
-af spawn --shell
+afx spawn --shell
 
 # Spawn with context files
-af spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts"
+afx spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts"
 ```
 
 **Common Errors:**
@@ -202,16 +202,16 @@ af spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts"
 |-------|-------|-----|
 | "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, tick, etc.) |
 | "Dirty worktree" | Uncommitted changes | Run `git status`, commit changes, retry |
-| "Builder already exists" | Worktree collision | Use `--resume` to resume, or `af cleanup` first |
+| "Builder already exists" | Worktree collision | Use `--resume` to resume, or `afx cleanup` first |
 
 ---
 
-### af status
+### afx status
 
 Show status of all agents.
 
 ```bash
-af status
+afx status
 ```
 
 **Description:**
@@ -237,12 +237,12 @@ Status values:
 
 ---
 
-### af cleanup
+### afx cleanup
 
 Clean up a builder worktree and branch.
 
 ```bash
-af cleanup -p <id> [options]
+afx cleanup -p <id> [options]
 ```
 
 **Options:**
@@ -257,20 +257,20 @@ Removes a builder's worktree and associated resources. By default, refuses to de
 
 ```bash
 # Clean up completed builder
-af cleanup -p 42
+afx cleanup -p 42
 
 # Force cleanup (may lose work)
-af cleanup -p 42 --force
+afx cleanup -p 42 --force
 ```
 
 ---
 
-### af send
+### afx send
 
 Send instructions to a running builder.
 
 ```bash
-af send [builder] [message] [options]
+afx send [builder] [message] [options]
 ```
 
 **Arguments:**
@@ -295,26 +295,26 @@ Sends text to a builder's terminal. Useful for:
 
 ```bash
 # Send message to builder
-af send 42 "Focus on the auth module first"
+afx send 42 "Focus on the auth module first"
 
 # Interrupt and send new instructions
-af send 42 --interrupt "Stop that. Try a different approach."
+afx send 42 --interrupt "Stop that. Try a different approach."
 
 # Send to all builders
-af send --all "Time to wrap up, create PRs"
+afx send --all "Time to wrap up, create PRs"
 
 # Include file content
-af send 42 --file src/api.ts "Review this implementation"
+afx send 42 --file src/api.ts "Review this implementation"
 ```
 
 ---
 
-### af open
+### afx open
 
 Open file annotation viewer.
 
 ```bash
-af open <file>
+afx open <file>
 ```
 
 **Arguments:**
@@ -327,17 +327,17 @@ Opens a web-based viewer for annotating files with review comments. Comments use
 **Example:**
 
 ```bash
-af open src/auth/login.ts
+afx open src/auth/login.ts
 ```
 
 ---
 
-### af shell
+### afx shell
 
 Spawn a utility shell terminal.
 
 ```bash
-af shell [options]
+afx shell [options]
 ```
 
 **Options:**
@@ -354,20 +354,20 @@ Opens a general-purpose shell terminal in the workspace overview. Useful for:
 
 ```bash
 # Open utility shell
-af shell
+afx shell
 
 # Open with custom name
-af shell -n "test-runner"
+afx shell -n "test-runner"
 ```
 
 ---
 
-### af rename
+### afx rename
 
 Rename a builder or utility terminal.
 
 ```bash
-af rename <id> <name>
+afx rename <id> <name>
 ```
 
 **Arguments:**
@@ -377,21 +377,21 @@ af rename <id> <name>
 **Example:**
 
 ```bash
-af rename 42 "auth-rework"
+afx rename 42 "auth-rework"
 ```
 
 ---
 
-### af ports
+### afx ports
 
 Manage global port registry.
 
-#### af ports list
+#### afx ports list
 
 List all port allocations.
 
 ```bash
-af ports list
+afx ports list
 ```
 
 Shows port blocks allocated to different projects:
@@ -401,73 +401,73 @@ Port Allocations
 4300-4399: /Users/me/project-b
 ```
 
-#### af ports cleanup
+#### afx ports cleanup
 
 Remove stale port allocations.
 
 ```bash
-af ports cleanup
+afx ports cleanup
 ```
 
 Removes entries for projects that no longer exist.
 
 ---
 
-### af tower
+### afx tower
 
 Manage the cross-project tower dashboard. Tower shows all agent-farm instances across projects and provides cloud connectivity via codevos.ai.
 
-#### af tower start
+#### afx tower start
 
 Start the tower dashboard.
 
 ```bash
-af tower start [options]
+afx tower start [options]
 ```
 
 **Options:**
 - `-p, --port <port>` - Port to run on (default: 4100)
 
-#### af tower stop
+#### afx tower stop
 
 Stop the tower dashboard.
 
 ```bash
-af tower stop [options]
+afx tower stop [options]
 ```
 
 **Options:**
 - `-p, --port <port>` - Port to stop (default: 4100)
 
-#### af tower register
+#### afx tower register
 
 Register this tower with codevos.ai for remote access.
 
 ```bash
-af tower register [options]
+afx tower register [options]
 ```
 
 **Options:**
 - `--reauth` - Re-authenticate without changing tower name
 - `-p, --port <port>` - Tower port to signal after registration (default: 4100)
 
-#### af tower deregister
+#### afx tower deregister
 
 Remove this tower's registration from codevos.ai.
 
 ```bash
-af tower deregister [options]
+afx tower deregister [options]
 ```
 
 **Options:**
 - `-p, --port <port>` - Tower port to signal after deregistration (default: 4100)
 
-#### af tower status
+#### afx tower status
 
 Show tower status including cloud connection info.
 
 ```bash
-af tower status [options]
+afx tower status [options]
 ```
 
 **Options:**
@@ -478,27 +478,27 @@ af tower status [options]
 
 ---
 
-### af db
+### afx db
 
 Database debugging and maintenance commands.
 
-#### af db dump
+#### afx db dump
 
 Export all tables to JSON.
 
 ```bash
-af db dump [options]
+afx db dump [options]
 ```
 
 **Options:**
 - `--global` - Dump global.db instead of project db
 
-#### af db query
+#### afx db query
 
 Run a SELECT query.
 
 ```bash
-af db query <sql> [options]
+afx db query <sql> [options]
 ```
 
 **Options:**
@@ -507,27 +507,27 @@ af db query <sql> [options]
 **Example:**
 
 ```bash
-af db query "SELECT * FROM builders WHERE status = 'implementing'"
+afx db query "SELECT * FROM builders WHERE status = 'implementing'"
 ```
 
-#### af db reset
+#### afx db reset
 
 Delete database and start fresh.
 
 ```bash
-af db reset [options]
+afx db reset [options]
 ```
 
 **Options:**
 - `--global` - Reset global.db
 - `--force` - Skip confirmation
 
-#### af db stats
+#### afx db stats
 
 Show database statistics.
 
 ```bash
-af db stats [options]
+afx db stats [options]
 ```
 
 **Options:**
@@ -537,7 +537,7 @@ af db stats [options]
 
 ## Configuration
 
-Customize commands via `af-config.json` at the project root:
+Customize commands via `.codev/config.json` at the project root:
 
 ```json
 {
@@ -552,8 +552,8 @@ Customize commands via `af-config.json` at the project root:
 Or override via CLI flags:
 
 ```bash
-af workspace start --architect-cmd "claude --model opus"
-af spawn 42 --protocol spir --builder-cmd "claude --model haiku"
+afx workspace start --architect-cmd "claude --model opus"
+afx spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 ```
 
 ---
@@ -564,7 +564,7 @@ af spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 |------|-------------|
 | `.agent-farm/state.db` | Project runtime state (SQLite) |
 | `~/.agent-farm/global.db` | Global port registry (SQLite) |
-| `af-config.json` | Agent Farm configuration (project root) |
+| `.codev/config.json` | Agent Farm configuration (project root) |
 
 ---
 

package/skeleton/resources/commands/codev.md

@@ -171,6 +171,6 @@ codev update --force
 
 ## See Also
 
-- [af](agent-farm.md) - Agent Farm commands
+- [afx](agent-farm.md) - Agent Farm commands
 - [consult](consult.md) - AI consultation
 - [overview](overview.md) - CLI overview

package/skeleton/resources/commands/consult.md

@@ -196,5 +196,5 @@ consult stats --days 7 --json
 ## See Also
 
 - [codev](codev.md) - Project management commands
-- [af](agent-farm.md) - Agent Farm commands
+- [afx](agent-farm.md) - Agent Farm commands
 - [overview](overview.md) - CLI overview

package/skeleton/resources/commands/overview.md

@@ -5,7 +5,7 @@ Codev provides three CLI tools for AI-assisted software development:
 | Tool | Description |
 |------|-------------|
 | `codev` | Project setup, maintenance, and framework commands |
-| `af` | Agent Farm - multi-agent orchestration for development |
+| `afx` | Agent Farm - multi-agent orchestration for development |
 | `consult` | AI consultation with external models (Gemini, Codex, Claude) |
 
 ## Quick Start
@@ -21,7 +21,7 @@ codev adopt
 codev doctor
 
 # Start the workspace
-af workspace start
+afx workspace start
 
 # Consult an AI model about a spec
 consult -m gemini --protocol spir --type spec
@@ -33,7 +33,7 @@ consult -m gemini --protocol spir --type spec
 npm install -g @cluesmith/codev
 ```
 
-This installs all three commands globally: `codev`, `af`, and `consult`.
+This installs all three commands globally: `codev`, `afx`, and `consult`.
 
 ## Command Summaries
 
@@ -49,19 +49,19 @@ This installs all three commands globally: `codev`, `af`, and `consult`.
 
 See [codev.md](codev.md) for full documentation.
 
-### af - Agent Farm
+### afx - Agent Farm
 
 | Command | Description |
 |---------|-------------|
-| `af workspace start` | Start the workspace |
-| `af workspace stop` | Stop all agent farm processes |
-| `af spawn` | Spawn a new builder |
-| `af status` | Show status of all agents |
-| `af cleanup` | Clean up a builder worktree |
-| `af send` | Send instructions to a builder |
-| `af open` | Open file annotation viewer |
-| `af shell` | Spawn a utility shell |
-| `af tower` | Cross-project dashboard |
+| `afx workspace start` | Start the workspace |
+| `afx workspace stop` | Stop all agent farm processes |
+| `afx spawn` | Spawn a new builder |
+| `afx status` | Show status of all agents |
+| `afx cleanup` | Clean up a builder worktree |
+| `afx send` | Send instructions to a builder |
+| `afx open` | Open file annotation viewer |
+| `afx shell` | Spawn a utility shell |
+| `afx tower` | Cross-project dashboard |
 
 See [agent-farm.md](agent-farm.md) for full documentation.
 
@@ -86,7 +86,7 @@ All codev commands support:
 
 ## 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`.
 
 ## Related Documentation
 

package/skeleton/resources/risk-triage.md

@@ -77,7 +77,7 @@ Low-risk test fix. Corrects assertion in foo.test.ts.
 ---
 Architect review"
 
-af send 0042 "PR approved, please merge"
+afx send 0042 "PR approved, please merge"
 ```
 
 ### Medium Risk: New Feature (180 lines, 3 files, commands/)