@cluesmith/codev 2.0.0-rc.10 → 2.0.0-rc.12

package/skeleton/protocols/spider/prompts/implement.md

@@ -4,7 +4,7 @@ You are executing the **IMPLEMENT** phase of the SPIDER protocol.
 
 ## Your Goal
 
-Write clean, well-structured code that implements the current plan phase.
+Write clean, well-structured code AND tests that implement the current plan phase.
 
 ## Context
 
@@ -15,14 +15,54 @@ Write clean, well-structured code that implements the current plan phase.
 - **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
 - **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
 
-## Consultation Context
+## What Happens After You Finish
 
-**Implementation does NOT require consultation checkpoints** - that happens after Defend.
+When you signal `PHASE_COMPLETE`, porch will:
+1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation
+2. Check that tests exist and pass
+3. If reviewers request changes, you'll be respawned with their feedback
+4. Once approved, porch commits and moves to the next plan phase
 
-However, you should be aware:
-- Spec and Plan have already been reviewed by GPT-5 Codex and Gemini Pro
-- After you complete Implement + Defend, your work will be reviewed
-- Implementation must strictly follow the approved spec and plan
+## Spec Compliance (CRITICAL)
+
+**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
+
+### Trust Hierarchy
+
+```
+SPEC (source of truth)
+  ↓
+PLAN (implementation guide derived from spec)
+  ↓
+EXISTING CODE (NOT TRUSTED - must be validated against spec)
+```
+
+**Never trust existing code over the spec.** Previous implementations may have drifted.
+
+### Pre-Implementation Sanity Check (PISC)
+
+**Before writing ANY code:**
+
+1. ✅ "Have I read the spec in the last 30 minutes?"
+2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?"
+3. ✅ "Does my approach match the spec's Technical Implementation section?"
+4. ✅ "If the spec has code examples, am I following them?"
+5. ✅ "Does the existing code I'm building on actually match the spec?"
+
+**If ANY answer is "no" or "unsure" → STOP and re-read the spec.**
+
+### Avoiding "Fixing Mode"
+
+A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to:
+- Cargo-culting patterns that may be wrong
+- Building on broken foundations
+- Implementing something different from the spec
+
+**When you catch yourself "fixing" code:**
+1. STOP
+2. Ask: "What does the spec say about this?"
+3. Re-read the spec's Traps to Avoid section
+4. Verify existing code matches the spec before building on it
 
 ## Prerequisites
 
@@ -48,7 +88,7 @@ Read the current phase in the plan:
 - Check that previous phase is committed: `git log --oneline -5`
 - Ensure build passes before starting: `npm run build` (or equivalent)
 
-### 3. Implement
+### 3. Implement the Code
 
 Write the code following these principles:
 
@@ -62,60 +102,72 @@ Write the code following these principles:
 **Implementation Approach**:
 - Work on one file at a time
 - Make small, incremental changes
-- Test as you go (manual verification is fine here)
 - Document complex logic with comments
 
-### 4. Self-Review
+### 4. Write Tests
 
-Before signaling completion:
-- Read through all changes
-- Check for obvious bugs
-- Verify code matches the spec requirements
-- Ensure no accidental debug code
+**Tests are required.** For each piece of functionality you implement:
 
-### 5. Build Verification
+- Write unit tests for core logic
+- Write integration tests if the phase involves multiple components
+- Test error cases and edge conditions
+- Ensure tests are deterministic (no flaky tests)
 
-Run build checks using **project-specific commands**:
+**Test file locations** (follow project conventions):
+- `tests/` or `__tests__/` directories
+- `*.test.ts` or `*.spec.ts` naming
+
+### 5. Verify Everything Works
+
+Run both build and tests:
 
 ```bash
-# Check package.json scripts or Makefile for actual commands
-# Common patterns:
-npm run build      # Node.js/TypeScript projects
-npm run typecheck  # TypeScript type checking
-npm run lint       # Linting (ESLint, etc.)
-cargo build        # Rust projects
-go build ./...     # Go projects
-make build         # Projects using Makefiles
+npm run build      # Must pass
+npm test           # Must pass
 ```
 
-**Important**: Don't assume `npm run build` exists. Check `package.json` or equivalent first.
+**Important**: Don't assume these commands exist. Check `package.json` first.
+
+Fix any errors before signaling completion.
+
+### 6. Self-Review
 
-Fix any errors before proceeding.
+Before signaling completion:
+- Read through all code changes
+- Read through all test changes
+- Verify code matches the spec requirements
+- Ensure no accidental debug code
+- Check test coverage is adequate
 
 ## Output
 
+When complete, you should have:
 - Modified/created source files as specified in the plan phase
+- Tests covering the new functionality
 - All build checks passing
-- Code ready for the Defend (testing) phase
+- All tests passing
 
 ## Signals
 
-Emit appropriate signals based on your progress:
+When implementation AND tests are complete and passing:
 
-- After implementation is complete and builds pass:
-  ```
-  <signal>PHASE_IMPLEMENTED</signal>
-  ```
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you encounter a blocker:
 
-- If you encounter a blocker:
-  ```
-  <signal>BLOCKED:reason goes here</signal>
-  ```
+```
+<signal>BLOCKED:reason goes here</signal>
+```
 
-- If you need spec/plan clarification:
-  ```
-  <signal>NEEDS_CLARIFICATION:specific question</signal>
-  ```
+If you need spec/plan clarification:
+
+```
+<signal type=AWAITING_INPUT>
+Your specific questions here
+</signal>
+```
 
 ## Important Notes
 
@@ -123,21 +175,21 @@ Emit appropriate signals based on your progress:
 2. **Don't over-engineer** - Simplest solution that works
 3. **Don't skip error handling** - But don't go overboard either
 4. **Keep changes focused** - Only touch files in this phase
-5. **Build must pass** - Don't proceed if build fails
+5. **Build AND tests must pass** - Don't signal complete until both pass
+6. **Write tests** - Every implementation phase needs tests
 
 ## What NOT to Do
 
-- Don't write tests yet (that's Defend phase)
 - Don't modify files outside this phase's scope
 - Don't add features not in the spec
 - Don't leave TODO comments for later (fix now or note as blocker)
-- Don't commit yet (that happens after Defend + Evaluate)
-- Don't use `git add .` or `git add -A` when you do commit (security risk)
+- Don't skip writing tests
+- Don't use `git add .` or `git add -A` when you commit (security risk)
 
 ## Handling Problems
 
 **If the plan is unclear**:
-Signal `NEEDS_CLARIFICATION` with your specific question.
+Signal `AWAITING_INPUT` with your specific question.
 
 **If you discover the spec is wrong**:
 Signal `BLOCKED` and explain the issue. The Architect may need to update the spec.
@@ -145,5 +197,5 @@ Signal `BLOCKED` and explain the issue. The Architect may need to update the spe
 **If a dependency is missing**:
 Signal `BLOCKED` with details about what's missing.
 
-**If build fails and you can't fix it**:
+**If build or tests fail and you can't fix it**:
 Signal `BLOCKED` with the error message.

package/skeleton/protocols/spider/protocol.json

@@ -1,8 +1,9 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "spider",
-  "version": "2.0.0",
-  "description": "Specification-driven development with build-verify cycles",
+  "alias": "spir",
+  "version": "2.1.0",
+  "description": "SPIR: Specify → Plan → Implement → Review with build-verify cycles",
   "phases": [
     {
       "id": "specify",
@@ -18,7 +19,7 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 3,
+      "max_iterations": 7,
       "on_complete": {
         "commit": true,
         "push": true
@@ -40,14 +41,15 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 3,
+      "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"
+        "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"
@@ -66,7 +68,7 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 3,
+      "max_iterations": 7,
       "on_complete": {
         "commit": true,
         "push": true
@@ -102,7 +104,7 @@
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 3,
+      "max_iterations": 7,
       "on_complete": {
         "commit": true,
         "push": true
@@ -127,7 +129,7 @@
     "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'"
   },
   "defaults": {
-    "max_iterations": 3,
+    "max_iterations": 7,
     "verify": {
       "models": ["gemini", "codex", "claude"],
       "parallel": true

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/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",