@cluesmith/codev 2.0.0-rc.2 → 2.0.0-rc.24

package/skeleton/protocols/spider/protocol.json

@@ -1,147 +1,91 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "spider",
-  "version": "1.0.0",
-  "description": "Specification-driven development with multi-agent consultation",
+  "alias": "spir",
+  "version": "2.1.0",
+  "description": "SPIR: Specify → Plan → Implement → Review with build-verify cycles",
   "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 +94,53 @@
     {
       "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,
+    "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/protocol.json

@@ -2,7 +2,7 @@
   "$schema": "../../protocol-schema.json",
   "name": "tick",
   "version": "1.0.0",
-  "description": "Amendment workflow for existing SPIDER specifications",
+  "description": "Amendment workflow for existing SPIR specifications",
   "phases": [
     {
       "id": "identify",