@cluesmith/codev 3.0.0-rc.1 → 3.0.0-rc.11

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,23 +137,23 @@ 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:**
 - `issue-number` - Issue number to build (positional, e.g., `42`)
 
 **Required:**
-- `--protocol <name>` - Protocol to use: spir, bugfix, tick, maintain, experiment. **REQUIRED** for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip this flag.
+- `--protocol <name>` - Protocol to use: spir, aspir, air, bugfix, maintain, experiment. **REQUIRED** for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip this flag.
 
 **Options:**
 - `--task <text>` - Spawn builder with a task description (no `--protocol` needed)
@@ -181,37 +181,37 @@ 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:**
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, tick, etc.) |
+| "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, air, 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

@@ -1,6 +1,6 @@
 # consult - AI Consultation CLI
 
-The `consult` command provides a unified interface for AI consultation with external models (Gemini, Codex, Claude). It operates in three modes: general (ad-hoc prompts), protocol-based (structured reviews), and stats.
+The `consult` command provides a unified interface for AI consultation with external models (Gemini, Codex, Claude, Hermes). It operates in three modes: general (ad-hoc prompts), protocol-based (structured reviews), and stats.
 
 ## Synopsis
 
@@ -22,6 +22,7 @@ consult stats [options]
 | `gemini` | `pro` | gemini-cli | File access via --yolo, fast |
 | `codex` | `gpt` | @openai/codex | Read-only sandbox, thorough |
 | `claude` | `opus` | Claude Agent SDK | Balanced analysis with tool use |
+| `hermes` | - | hermes CLI (`hermes chat -q`) | Uses Hermes agent as consult backend |
 
 ## Modes
 
@@ -45,7 +46,7 @@ Cannot combine `--prompt` with `--prompt-file` or `--type`.
 
 ### Protocol Mode
 
-Run structured reviews tied to a development protocol (SPIR, TICK, bugfix, maintain).
+Run structured reviews tied to a development protocol (SPIR, ASPIR, AIR, bugfix, maintain).
 
 ```bash
 # Review a spec (auto-detects project context in builder worktrees)
@@ -68,7 +69,7 @@ consult -m gemini --type integration
 ```
 
 **Options:**
-- `--protocol <name>` — Protocol: spir, bugfix, tick, maintain
+- `--protocol <name>` — Protocol: spir, aspir, air, bugfix, maintain
 - `-t, --type <type>` — Review type: spec, plan, impl, pr, phase, integration
 - `--issue <number>` — Issue number (required from architect context)
 
@@ -108,16 +109,21 @@ These flags are used by porch (the protocol orchestrator) when generating consul
 --project-id <id>       Project ID for metrics
 ```
 
-## Parallel Consultation (3-Way Reviews)
+## Parallel Consultation (Multi-Model Reviews)
+
+Default project configuration uses a 3-model set (`gemini`, `codex`, `claude`).
 
 For thorough reviews, run multiple models in parallel:
 
 ```bash
-# 3-way spec review
+# Default 3-way spec review
 consult -m gemini --protocol spir --type spec &
 consult -m codex --protocol spir --type spec &
 consult -m claude --protocol spir --type spec &
 wait
+
+# Optional: include Hermes as a 4th reviewer
+consult -m hermes --protocol spir --type spec
 ```
 
 ## Performance
@@ -183,12 +189,15 @@ consult -m codex --protocol spir --type pr --issue 42
 # Protocol: implementation review with bugfix protocol
 consult -m claude --protocol bugfix --type impl
 
-# 3-way parallel review
+# Default 3-way parallel review
 consult -m gemini --protocol spir --type spec &
 consult -m codex --protocol spir --type spec &
 consult -m claude --protocol spir --type spec &
 wait
 
+# Optional: include Hermes as an additional reviewer
+consult -m hermes --protocol spir --type spec
+
 # Stats
 consult stats --days 7 --json
 ```
@@ -196,5 +205,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,11 +86,10 @@ 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
 
 - [SPIR Protocol](../protocols/spir/protocol.md) - Multi-phase development workflow
-- [TICK Protocol](../protocols/tick/protocol.md) - Fast amendment workflow
 - [Architect Role](../roles/architect.md) - Architect responsibilities
 - [Builder Role](../roles/builder.md) - Builder responsibilities

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/)