@cluesmith/codev 2.0.0-rc.3 → 2.0.0-rc.32

package/skeleton/protocols/spider/protocol.json

@@ -1,147 +1,96 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "spider",
-  "version": "1.0.0",
-  "description": "Specification-driven development with multi-agent consultation",
+  "alias": "spir",
+  "version": "2.2.0",
+  "description": "SPIR: Specify → Plan → Implement → Review with build-verify cycles",
+  "input": {
+    "type": "spec",
+    "required": false,
+    "default_for": ["--project", "-p"]
+  },
   "phases": [
     {
       "id": "specify",
       "name": "Specify",
-      "description": "Collaborative design exploration and specification",
-      "type": "once",
-      "steps": [
-        "clarifying_questions",
-        "problem_analysis",
-        "solution_exploration",
-        "open_questions",
-        "success_criteria",
-        "spec_draft",
-        "consultation_1",
-        "human_review",
-        "consultation_2",
-        "spec_final"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Write specification with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "specify.md",
+        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "spec-review",
-        "parallel": true,
-        "max_rounds": 3
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "spec-approval",
-        "description": "Human approves specification before planning",
-        "requires": ["spec_final", "consultation_2"],
-        "next": "plan"
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "spec-approval",
+      "next": "plan"
     },
     {
       "id": "plan",
       "name": "Plan",
-      "description": "Implementation planning with phased breakdown",
-      "type": "once",
-      "steps": [
-        "analyze_spec",
-        "identify_phases",
-        "define_steps",
-        "plan_draft",
-        "consultation",
-        "human_review",
-        "plan_final"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Write implementation plan with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "plan.md",
+        "artifact": "codev/plans/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "plan-review",
-        "parallel": true,
-        "max_rounds": 2
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "plan-approval",
-        "description": "Human approves plan before implementation",
-        "requires": ["plan_final", "consultation"],
-        "next": "implement"
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "plan_exists": "test -f codev/plans/${PROJECT_ID}-*.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_ID}-*.md",
+        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_ID}-*.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
+      },
+      "gate": "plan-approval",
+      "next": "implement"
     },
     {
       "id": "implement",
       "name": "Implement",
-      "description": "Code implementation following the plan",
+      "description": "Implement code with 3-way review per plan phase",
       "type": "per_plan_phase",
-      "steps": [
-        "read_phase",
-        "implement_code",
-        "self_review",
-        "commit"
-      ],
+      "build": {
+        "prompt": "implement.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx}"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
       "checks": {
         "build": {
           "command": "npm run build",
           "on_fail": "retry",
           "max_retries": 2
         },
-        "typecheck": {
-          "command": "npm run typecheck",
-          "on_fail": "retry",
-          "max_retries": 2
-        }
-      },
-      "transition": {
-        "on_complete": "defend",
-        "on_fail": "implement"
-      }
-    },
-    {
-      "id": "defend",
-      "name": "Defend",
-      "description": "Testing and verification",
-      "type": "per_plan_phase",
-      "steps": [
-        "write_tests",
-        "run_tests",
-        "fix_failures",
-        "commit"
-      ],
-      "checks": {
         "tests": {
-          "command": "npm test",
-          "on_fail": "implement",
-          "max_retries": 1
-        },
-        "lint": {
-          "command": "npm run lint",
+          "command": "npm test -- --exclude='**/e2e/**'",
+          "description": "Unit tests only - e2e tests run in review phase",
           "on_fail": "retry",
-          "max_retries": 1
+          "max_retries": 2
         }
       },
-      "consultation": {
-        "on": "complete",
-        "models": ["gemini", "codex", "claude"],
-        "type": "impl-review",
-        "parallel": true,
-        "max_rounds": 2
-      },
-      "transition": {
-        "on_complete": "evaluate",
-        "on_fail": "implement"
-      }
-    },
-    {
-      "id": "evaluate",
-      "name": "Evaluate",
-      "description": "Verify implementation against spec",
-      "type": "per_plan_phase",
-      "steps": [
-        "check_spec_compliance",
-        "check_success_criteria",
-        "document_deviations"
-      ],
-      "gate": {
-        "name": "phase-complete",
-        "description": "Plan phase implementation is verified",
-        "requires": ["all_checks_pass", "spec_compliance"],
-        "next": "implement"
-      },
       "transition": {
         "on_complete": "implement",
         "on_all_phases_complete": "review"
@@ -150,55 +99,54 @@
     {
       "id": "review",
       "name": "Review",
-      "description": "Final review and lessons learned",
-      "type": "once",
-      "steps": [
-        "create_review_document",
-        "document_lessons",
-        "final_consultation",
-        "create_pr"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Final review and PR with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "review.md",
+        "artifact": "codev/reviews/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "pr-ready",
-        "parallel": true,
-        "max_rounds": 1
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "pr-ready",
-        "description": "Implementation ready for PR",
-        "requires": ["review_complete", "all_tests_pass", "consultation"],
-        "next": null
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "e2e_tests": {
+          "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'",
+          "description": "Full e2e test suite - only runs in review phase",
+          "optional": true
+        }
+      },
+      "gate": "pr-ready",
+      "next": null
     }
   ],
   "signals": {
     "PHASE_COMPLETE": {
-      "description": "Signal current phase is complete",
-      "transitions_to": "next_phase"
+      "description": "Signal current build phase is complete",
+      "transitions_to": "verify"
     },
     "BLOCKED": {
       "description": "Signal implementation is blocked",
       "requires": "reason"
-    },
-    "REVISION_NEEDED": {
-      "description": "Signal changes requested",
-      "transitions_to": "current_phase"
-    },
-    "APPROVED": {
-      "description": "Signal gate approval received"
     }
   },
+  "phase_completion": {
+    "build_succeeds": "npm run build 2>&1",
+    "tests_pass": "npm test 2>&1",
+    "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'"
+  },
   "defaults": {
-    "consultation": {
-      "enabled": true,
+    "mode": "strict",
+    "max_iterations": 7,
+    "verify": {
       "models": ["gemini", "codex", "claude"],
       "parallel": true
-    },
-    "checks": {
-      "build": "npm run build",
-      "test": "npm test"
     }
   }
 }

package/skeleton/protocols/spider/protocol.md

@@ -1,4 +1,10 @@
-# SPIDER Protocol
+# SPIR Protocol (formerly SPIDER)
+
+> **Also known as**: SPIDER (legacy name)
+>
+> **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.
 
@@ -40,13 +46,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 +68,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 +238,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**:

package/skeleton/protocols/spider/templates/plan.md

@@ -17,6 +17,20 @@
 - [ ] Zero critical security issues
 - [ ] Documentation complete
 
+## Phases (Machine Readable)
+
+<!-- REQUIRED: porch uses this JSON to track phase progress. Update this when adding/removing phases. -->
+
+```json
+{
+  "phases": [
+    {"id": "phase_1", "title": "Phase 1 Title Here"},
+    {"id": "phase_2", "title": "Phase 2 Title Here"},
+    {"id": "phase_3", "title": "Phase 3 Title Here"}
+  ]
+}
+```
+
 ## Phase Breakdown
 
 ### Phase 1: [Descriptive Name]

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

@@ -0,0 +1,51 @@
+# {{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 run {{project_id}}`
+- Follow porch signals and gate approvals
+{{/if}}
+
+## Protocol
+Follow the TICK protocol: `codev/protocols/tick/protocol.md`
+
+TICK is for amendments to existing SPIDER 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": "soft",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],

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:**
@@ -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,19 +116,17 @@ 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:**
@@ -306,16 +308,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 +330,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 +358,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 +391,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.
 
 #### af tower start
 
@@ -422,6 +403,7 @@ af tower start [options]
 
 **Options:**
 - `-p, --port <port>` - Port to run on (default: 4100)
+- `-w, --web` - Enable web access mode (requires CODEV_WEB_KEY)
 
 #### af tower stop
 

package/skeleton/resources/commands/overview.md

@@ -21,7 +21,7 @@ codev adopt
 codev doctor
 
 # Start the architect dashboard
-af start
+af dash start
 
 # Consult an AI model about a spec
 consult -m gemini spec 42
@@ -46,7 +46,6 @@ This installs all three commands globally: `codev`, `af`, and `consult`.
 | `codev doctor` | Check system dependencies |
 | `codev update` | Update codev templates and protocols |
 | `codev import <source>` | AI-assisted protocol import from other projects |
-| `codev tower` | Cross-project dashboard |
 
 See [codev.md](codev.md) for full documentation.
 
@@ -54,14 +53,15 @@ See [codev.md](codev.md) for full documentation.
 
 | Command | Description |
 |---------|-------------|
-| `af start` | Start the architect dashboard |
-| `af stop` | Stop all agent farm processes |
+| `af dash start` | Start the architect dashboard |
+| `af dash 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 util` | Spawn a utility shell |
+| `af shell` | Spawn a utility shell |
+| `af tower` | Cross-project dashboard |
 
 See [agent-farm.md](agent-farm.md) for full documentation.
 

package/skeleton/resources/workflow-reference.md

@@ -77,7 +77,7 @@ AI agents must stop and wait for human action at these gates.
 
 ```bash
 # Start the dashboard
-af start
+af dash start
 
 # Spawn a builder for a project
 af spawn -p 0044
@@ -95,7 +95,7 @@ af open codev/specs/0044-name.md
 af cleanup -p 0044
 
 # Stop everything
-af stop
+af dash stop
 ```
 
 ### Builder Commands