@cluesmith/codev 2.0.0-rc.9 → 2.0.1

package/skeleton/protocols/{spider → spir}/protocol.md

@@ -1,9 +1,19 @@
-# SPIDER Protocol
+# SPIR Protocol
+
+> **SPIR** = **S**pecify → **P**lan → **I**mplement → **R**eview
+>
+> Each phase has one build-verify cycle with 3-way consultation.
 
 > **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
 ## Prerequisites
 
+**Clean Worktree Before Spawning Builders**:
+- All specs, plans, and local changes **MUST be committed** before `af 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)
+
 **Required for Multi-Agent Consultation**:
 - The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`)
 - At least one consultation backend: `claude`, `gemini-cli`, or `codex`
@@ -14,17 +24,17 @@
 ### Multi-Agent Consultation (ENABLED BY DEFAULT)
 
 **DEFAULT BEHAVIOR:**
-Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIDER protocol.
+Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIR protocol.
 
 **DEFAULT AGENTS:**
 - **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality
 - **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches
 
 **DISABLING CONSULTATION:**
-To run SPIDER without consultation, say "without consultation" when starting work.
+To run SPIR without consultation, say "without consultation" when starting work.
 
 **CUSTOM AGENTS:**
-The user can specify different agents by saying: "use SPIDER with consultation from [agent1] and [agent2]"
+The user can specify different agents by saying: "use SPIR with consultation from [agent1] and [agent2]"
 
 **CONSULTATION BEHAVIOR:**
 - DEFAULT: MANDATORY consultation with GPT-5 and Gemini Pro at EVERY checkpoint
@@ -40,13 +50,21 @@ The user can specify different agents by saying: "use SPIDER with consultation f
 - **Review**: After review document
 
 ## Overview
-SPIDER is a structured development protocol that emphasizes specification-driven development with iterative implementation and continuous review. It builds upon the DAPPER methodology with a focus on context-first development and multi-agent collaboration.
+SPIR is a structured development protocol that emphasizes specification-driven development with iterative implementation and continuous review. It builds upon the DAPPER methodology with a focus on context-first development and multi-agent collaboration.
+
+**The SPIR Model**:
+- **S - Specify**: Write specification with 3-way review → Gate: `spec-approval`
+- **P - Plan**: Write implementation plan with 3-way review → Gate: `plan-approval`
+- **I - Implement**: Execute each plan phase with build-verify cycle (one cycle per phase)
+- **R - Review**: Final review and PR preparation with 3-way review
+
+Each phase follows a build-verify loop: build the artifact, then verify with 3-way consultation (Gemini, Codex, Claude).
 
 **Core Principle**: Each feature is tracked through exactly THREE documents - a specification, a plan, and a review with lessons learned - all sharing the same filename and sequential identifier.
 
-## When to Use SPIDER
+## When to Use SPIR
 
-### Use SPIDER for:
+### Use SPIR for:
 - New feature development
 - Architecture changes
 - Complex refactoring
@@ -54,7 +72,7 @@ SPIDER is a structured development protocol that emphasizes specification-driven
 - API design and implementation
 - Performance optimization initiatives
 
-### Skip SPIDER for:
+### Skip SPIR for:
 - Simple bug fixes (< 10 lines)
 - Documentation updates
 - Configuration changes
@@ -224,25 +242,21 @@ Each phase should be:
 **Template**: `templates/plan.md`
 **Review Required**: Yes - Technical lead approval AFTER consultations
 
-### (IDE) - Implementation Loop
-
-Execute for each phase in the plan. This is a strict cycle that must be completed in order.
+### I - Implement (Per Plan Phase)
 
-**⚠️ MANDATORY**: The I-D-E cycle MUST be completed for EACH PHASE, not just at the end of all phases. Skipping D (Defend) or E (Evaluate) for any phase is a PROTOCOL VIOLATION.
+Execute for each phase in the plan. Each phase follows a build-verify cycle.
 
 **CRITICAL PRECONDITION**: Before starting any phase, verify the previous phase was committed to git. No phase can begin without the prior phase's commit.
 
-**Phase Completion Process**:
-1. **Implement** - Build the code for this phase
-2. **Defend** - Write comprehensive tests that guard functionality
-3. **Evaluate** - Assess and discuss with user
+**Build-Verify Cycle Per Phase**:
+1. **Build** - Implement code and tests for this phase
+2. **Verify** - 3-way consultation (Gemini, Codex, Claude)
+3. **Iterate** - Address feedback until verification passes
 4. **Commit** - Single atomic commit for the phase (MANDATORY before next phase)
 5. **Proceed** - Move to next phase only after commit
 
 **Handling Failures**:
-- If **Defend** phase reveals gaps → return to **Implement** to fix
-- If **Evaluation** reveals unmet criteria → return to **Implement**
-- If user requests changes → return to **Implement**
+- If verification reveals gaps → iterate and fix
 - If fundamental plan flaws found → mark phase as `blocked` and revise plan
 
 **Commit Requirements**:
@@ -586,12 +600,12 @@ Implements bcrypt-based password hashing with configurable rounds
 
 ### Branch Naming
 ```
-spider/####-<spec-name>/<phase-name>
+spir/####-<spec-name>/<phase-name>
 ```
 
 Example:
 ```
-spider/0001-user-authentication/database-schema
+spir/0001-user-authentication/database-schema
 ```
 
 

package/skeleton/protocols/spir/templates/review.md

@@ -0,0 +1,89 @@
+# Review: [Feature/Project Name]
+
+## Summary
+
+[1-3 sentences: what was built, how many phases, net outcome.]
+
+## Spec Compliance
+
+- [x] AC1: [Description] (Phase N)
+- [x] AC2: [Description] (Phase N)
+- [ ] ACn: [Not met — reason]
+
+## Deviations from Plan
+
+- **Phase N**: [What changed and why]
+
+## Key Metrics
+
+- **Commits**: [N] on the branch
+- **Tests**: [N] passing ([N] existing + [N] new)
+- **Files created**: [list]
+- **Files deleted**: [list]
+- **Net LOC impact**: [+/-N lines]
+
+## Timelog
+
+All times [timezone], [date range].
+
+| Time | Event |
+|------|-------|
+| HH:MM | First commit: [description] |
+| HH:MM | [Phase/milestone] |
+| — | **GATE: [gate-name]** (human approval required) |
+| HH:MM | Implementation begins |
+| HH:MM | Phase N complete after N iterations |
+| HH:MM | **GATE: pr-ready** |
+
+### Autonomous Operation
+
+| Period | Duration | Activity |
+|--------|----------|----------|
+| Spec + Plan | ~Nm | [Summary] |
+| Human gate wait | ~Nh Nm | Idle — waiting for approval |
+| Implementation → PR | ~Nh Nm | N phases, N consultation rounds |
+
+**Total wall clock** (first commit to pr-ready): **Xh Ym**
+**Total autonomous work time** (excluding gate waits): **~Xh Ym**
+**Context window resets**: [N] (resumed automatically / required manual restart)
+
+## Consultation Iteration Summary
+
+[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT.
+
+| Phase | Iters | Who Blocked | What They Caught |
+|-------|-------|-------------|------------------|
+| Specify | N | [Model] | [Brief description] |
+| Plan | N | [Model] | [Brief description] |
+| Phase 1 | N | [Model] | [Brief description] |
+| Phase N | N | [Model] | [Brief description] |
+| Review | N | [Model] | [Brief description] |
+
+**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern].
+
+### Avoidable Iterations
+
+Iterations that could have been prevented with better builder behavior:
+
+1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."]
+
+2. **[Pattern]**: [Another avoidable iteration pattern.]
+
+## Lessons Learned
+
+### What Went Well
+- [Specific positive observation — what worked and why]
+
+### Challenges Encountered
+- **[Challenge]**: [How it was resolved. How many iterations it cost.]
+
+### What Would Be Done Differently
+- [Actionable improvement for future builders]
+
+## Technical Debt
+
+- [Any shortcuts taken or inconsistencies introduced]
+
+## Follow-up Items
+
+- [Items identified for future work, outside this spec's scope]

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

@@ -0,0 +1,56 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are implementing {{input_description}}.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the TICK protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Run consultations manually when the protocol calls for them
+- You have flexibility in execution, but must stay compliant with the protocol
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch next` to get your next tasks
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the TICK protocol: `codev/protocols/tick/protocol.md`
+
+TICK is for amendments to existing SPIR specifications. You will:
+1. Identify the target spec to amend
+2. Update the spec with the amendment
+3. Update the plan
+4. Implement the changes
+5. Defend with tests
+6. Create review
+
+{{#if spec}}
+## Target Spec
+The spec to amend is at: `{{spec.path}}`
+{{/if}}
+
+{{#if plan}}
+## Target Plan
+The plan to amend is at: `{{plan.path}}`
+{{/if}}
+
+{{#if task}}
+## Amendment Description
+{{task_text}}
+{{/if}}
+
+## Getting Started
+1. Read the TICK protocol thoroughly
+2. Identify what needs to change in the existing spec
+3. Follow the amendment workflow

package/skeleton/protocols/tick/protocol.json

@@ -1,8 +1,12 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "tick",
-  "version": "1.0.0",
-  "description": "Amendment workflow for existing SPIDER specifications",
+  "version": "1.1.0",
+  "description": "Amendment workflow for existing SPIR specifications",
+  "input": {
+    "type": "spec",
+    "required": false
+  },
   "phases": [
     {
       "id": "identify",
@@ -138,6 +142,7 @@
     }
   },
   "defaults": {
+    "mode": "strict",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],

package/skeleton/protocols/tick/protocol.md

@@ -3,16 +3,16 @@
 
 ## Overview
 
-TICK is an **amendment workflow** for existing SPIDER specifications. Rather than creating new standalone specs, TICK modifies existing spec and plan documents in-place, tracking changes in an "Amendments" section.
+TICK is an **amendment workflow** for existing SPIR specifications. Rather than creating new standalone specs, TICK modifies existing spec and plan documents in-place, tracking changes in an "Amendments" section.
 
-**Core Principle**: TICK is for *refining* existing specs. SPIDER is for *creating* new specs.
+**Core Principle**: TICK is for *refining* existing specs. SPIR is for *creating* new specs.
 
-**Key Insight**: TICKs are not small SPIDERs - they're amendments to existing SPIDERs. This eliminates the "TICK vs SPIDER" decision problem and keeps related work together.
+**Key Insight**: TICKs are not small SPIRs - they're amendments to existing SPIRs. This eliminates the "TICK vs SPIR" decision problem and keeps related work together.
 
 ## When to Use TICK
 
 ### Use TICK when:
-- Making **amendments to an existing SPIDER spec** that is already `integrated`
+- Making **amendments to an existing SPIR spec** that is already `integrated`
 - Small scope (< 300 lines of new/changed code)
 - Requirements are clear and well-defined
 - No fundamental architecture changes
@@ -23,7 +23,7 @@ TICK is an **amendment workflow** for existing SPIDER specifications. Rather tha
   - Utility function additions to existing modules
   - Refactoring within an existing feature
 
-### Use SPIDER instead when:
+### Use SPIR instead when:
 - Creating a **new feature from scratch** (no existing spec to amend)
 - Major architecture changes (scope too large for amendment)
 - Unclear requirements needing exploration
@@ -31,8 +31,8 @@ TICK is an **amendment workflow** for existing SPIDER specifications. Rather tha
 - Multiple stakeholders need alignment
 
 ### Cannot Use TICK when:
-- No relevant SPIDER spec exists (create a new SPIDER spec instead)
-- Target spec is not yet `integrated` (complete the SPIDER cycle first)
+- No relevant SPIR spec exists (create a new SPIR spec instead)
+- Target spec is not yet `integrated` (complete the SPIR cycle first)
 
 ## Amendment Workflow
 
@@ -162,9 +162,9 @@ The format `[TICK ####-NNN]` identifies:
 - `####`: Parent spec number (e.g., 0002)
 - `NNN`: TICK amendment number (e.g., 001, 002, 003)
 
-## Key Differences from SPIDER
+## Key Differences from SPIR
 
-| Aspect | SPIDER | TICK |
+| Aspect | SPIR | TICK |
 |--------|--------|------|
 | Purpose | Create new features | Amend existing features |
 | File creation | Creates new spec/plan/review | Modifies spec/plan, creates review |
@@ -178,16 +178,16 @@ The format `[TICK ####-NNN]` identifies:
 
 ```
 Is there an existing spec to amend?
-├── NO → Use SPIDER (create new spec)
+├── NO → Use SPIR (create new spec)
 └── YES → Is it integrated?
-    ├── NO → Complete SPIDER cycle first
+    ├── NO → Complete SPIR cycle first
     └── YES → Is the change small (<300 LOC)?
         ├── YES → Use TICK (amend existing spec)
-        └── NO → Use SPIDER (scope too large)
+        └── NO → Use SPIR (scope too large)
 ```
 
 **Mental Model**:
-- SPIDER = Create new feature from scratch
+- SPIR = Create new feature from scratch
 - TICK = Refine/extend existing feature
 
 ## Example TICK Workflow
@@ -251,7 +251,7 @@ Existing standalone TICK projects (created before this protocol change) are gran
 1. **Single source of truth**: Spec file shows complete feature evolution
 2. **Clear history**: Amendments section documents all changes chronologically
 3. **Reduced fragmentation**: Related work stays together
-4. **Simpler mental model**: "New vs amendment" is clearer than "SPIDER vs TICK"
+4. **Simpler mental model**: "New vs amendment" is clearer than "SPIR vs TICK"
 5. **Preserved context**: Looking at a spec shows all refinements
 
 ## Limitations
@@ -264,14 +264,14 @@ Existing standalone TICK projects (created before this protocol change) are gran
 ## Best Practices
 
 1. **Verify spec is integrated**: Never TICK a spec that isn't complete
-2. **Keep TICKs small**: If scope grows, consider new SPIDER spec
+2. **Keep TICKs small**: If scope grows, consider new SPIR spec
 3. **Clear summaries**: Amendment entries should be self-explanatory
 4. **Test before review**: Always test functionality before presenting
 5. **Honest documentation**: Document all deviations in review
 
 ## Templates
 
-TICK uses the standard SPIDER templates with amendments sections:
-- Spec template: `codev/protocols/spider/templates/spec.md` (includes Amendments section)
-- Plan template: `codev/protocols/spider/templates/plan.md` (includes Amendment History section)
+TICK uses the standard SPIR templates with amendments sections:
+- Spec template: `codev/protocols/spir/templates/spec.md` (includes Amendments section)
+- Plan template: `codev/protocols/spir/templates/plan.md` (includes Amendment History section)
 - Review template: `codev/protocols/tick/templates/review.md` (TICK-specific)

package/skeleton/protocols/tick/templates/review.md

@@ -77,7 +77,7 @@
 
 ## TICK Protocol Feedback
 - **Autonomous execution**: [Worked well / Issues encountered]
-- **Single-phase approach**: [Appropriate / Should have used SPIDER]
+- **Single-phase approach**: [Appropriate / Should have used SPIR]
 - **Speed vs quality trade-off**: [Balanced / Too fast / Too slow]
 - **End-only consultation**: [Caught issues / Missed opportunities]
 

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

@@ -18,12 +18,16 @@ af <command> [options]
 
 ## Commands
 
-### af start
+### af dash
+
+Project dashboard commands - start/stop the architect dashboard for this project.
+
+#### af dash start
 
 Start the architect dashboard.
 
 ```bash
-af start [options]
+af dash start [options]
 ```
 
 **Options:**
@@ -39,7 +43,7 @@ af start [options]
 Starts the agent-farm dashboard with:
 - Architect terminal (Claude session with architect role)
 - Web-based UI for monitoring builders
-- tmux session management
+- Terminal session management (shellper processes)
 
 The dashboard is accessible via browser at `http://localhost:<port>`.
 
@@ -47,16 +51,16 @@ The dashboard is accessible via browser at `http://localhost:<port>`.
 
 ```bash
 # Start with defaults
-af start
+af dash start
 
 # Start with custom port
-af start -p 4300
+af dash start -p 4300
 
 # Start with specific command
-af start -c "claude --model opus"
+af dash start -c "claude --model opus"
 
 # Start on remote machine
-af start --remote user@host
+af dash start --remote user@host
 ```
 
 #### Remote Access
@@ -65,13 +69,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 start --remote user@remote-host
+af dash start --remote user@remote-host
 
 # Or with explicit project path:
-af start --remote user@remote-host:/path/to/project
+af dash start --remote user@remote-host:/path/to/project
 
 # With custom port:
-af start --remote user@remote-host --port 4300
+af dash start --remote user@remote-host --port 4300
 ```
 
 This single command:
@@ -112,26 +116,23 @@ export PATH="$HOME/.local/bin:$PATH"
 
 ```bash
 # DEPRECATED: Exposes dashboard without authentication
-af start --allow-insecure-remote
+af dash 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 dash stop
 
-### af stop
-
-Stop all agent farm processes.
+Stop all agent farm processes for this project.
 
 ```bash
-af stop
+af dash stop
 ```
 
 **Description:**
 
 Stops all running agent-farm processes including:
-- tmux sessions
-- ttyd processes
+- Terminal sessions (shellper processes)
 - Dashboard servers
 
 Does NOT clean up worktrees - use `af cleanup` for that.
@@ -306,16 +307,14 @@ af open src/auth/login.ts
 
 ---
 
-### af util
+### af shell
 
 Spawn a utility shell terminal.
 
 ```bash
-af util [options]
+af shell [options]
 ```
 
-**Aliases:** `af shell`
-
 **Options:**
 - `-n, --name <name>` - Name for the shell terminal
 
@@ -330,10 +329,10 @@ Opens a general-purpose shell terminal in the dashboard. Useful for:
 
 ```bash
 # Open utility shell
-af util
+af shell
 
 # Open with custom name
-af util -n "test-runner"
+af shell -n "test-runner"
 ```
 
 ---
@@ -358,25 +357,6 @@ af rename 0042 "auth-rework"
 
 ---
 
-### af tutorial
-
-Interactive tutorial for new users.
-
-```bash
-af tutorial [options]
-```
-
-**Options:**
-- `--reset` - Start tutorial fresh
-- `--skip` - Skip current step
-- `--status` - Show tutorial progress
-
-**Description:**
-
-Walks through the basics of using agent-farm with guided steps.
-
----
-
 ### af ports
 
 Manage global port registry.
@@ -410,7 +390,7 @@ Removes entries for projects that no longer exist.
 
 ### af tower
 
-Manage the tower dashboard.
+Manage the cross-project tower dashboard. Tower shows all agent-farm instances across projects and provides cloud connectivity via codevos.ai.
 
 #### af tower start
 
@@ -434,6 +414,43 @@ af tower stop [options]
 **Options:**
 - `-p, --port <port>` - Port to stop (default: 4100)
 
+#### af tower register
+
+Register this tower with codevos.ai for remote access.
+
+```bash
+af 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
+
+Remove this tower's registration from codevos.ai.
+
+```bash
+af tower deregister [options]
+```
+
+**Options:**
+- `-p, --port <port>` - Tower port to signal after deregistration (default: 4100)
+
+#### af tower status
+
+Show tower status including cloud connection info.
+
+```bash
+af tower status [options]
+```
+
+**Options:**
+- `-p, --port <port>` - Tower port (default: 4100)
+
+**Environment Variables:**
+- `CODEVOS_URL` - Override the codevos.ai server URL (default: `https://codevos.ai`). Useful for local development or staging.
+
 ---
 
 ### af db
@@ -495,7 +512,7 @@ af db stats [options]
 
 ## Configuration
 
-Customize commands via `codev/config.json`:
+Customize commands via `af-config.json` at the project root:
 
 ```json
 {
@@ -522,7 +539,7 @@ af spawn -p 0042 --builder-cmd "claude --model haiku"
 |------|-------------|
 | `.agent-farm/state.json` | Project runtime state |
 | `~/.agent-farm/ports.json` | Global port registry |
-| `codev/config.json` | Project configuration |
+| `af-config.json` | Agent Farm configuration (project root) |
 
 ---
 

package/skeleton/resources/commands/codev.md

@@ -95,7 +95,6 @@ Verifies that all required dependencies are installed and properly configured:
 
 **Core Dependencies (required):**
 - Node.js (>= 18.0.0)
-- tmux (>= 3.0)
 - ttyd (>= 1.7.0)
 - git (>= 2.5.0)
 - gh (GitHub CLI, authenticated)
@@ -123,7 +122,6 @@ Codev Doctor - Checking your environment
 Core Dependencies (required for Agent Farm)
 
   ✓ Node.js      20.10.0
-  ✓ tmux         3.4
   ✓ ttyd         1.7.4
   ✓ git          2.42.0
   ✓ gh           authenticated