@cluesmith/codev 2.0.0-rc.6 → 2.0.0-rc.61

package/skeleton/protocols/{spider → spir}/prompts/review.md

@@ -1,14 +1,10 @@
 # REVIEW Phase Prompt
 
-You are executing the **REVIEW** phase of the SPIDER protocol.
+You are executing the **REVIEW** phase of the SPIR protocol.
 
 ## Your Goal
 
-Perform a comprehensive review, document lessons learned, run final consultation, and prepare for PR submission.
-
-## CRITICAL: Final Consultation Before PR
-
-The SPIDER protocol **requires** a final consultation with GPT-5 Codex AND Gemini Pro before submitting the PR. This ensures the complete implementation is reviewed.
+Perform a comprehensive review, document lessons learned, and prepare for PR submission.
 
 ## Context
 
@@ -92,7 +88,7 @@ Brief description of what was implemented.
 - [Insight 2]
 
 ### Methodology Improvements
-- [Suggested improvement to SPIDER protocol]
+- [Suggested improvement to SPIR protocol]
 - [Suggested improvement to tooling]
 
 ## Technical Debt
@@ -118,22 +114,9 @@ Before PR:
 - [ ] No uncommitted changes: `git status`
 - [ ] Review document complete
 
-### 6. MANDATORY: Final Consultation (PR-Ready Review)
-
-**Before creating the PR, run final consultation:**
-
-```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini --type pr-ready spec {{project_id}} &
-consult --model codex --type pr-ready spec {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Address any final issues identified
-- This is the last chance to catch problems before PR
+### 6. Create Pull Request
 
-### 7. Create Pull Request
+After the review document is complete, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
 
 Prepare PR with:
 
@@ -187,8 +170,7 @@ Emit appropriate signals based on your progress:
 
 ## Important Notes
 
-1. **Final consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews before PR
-2. **Be honest in lessons learned** - Future you will thank present you
+1. **Be honest in lessons learned** - Future you will thank present you
 3. **Document deviations** - They're not failures, they're learnings
 4. **Update methodology** - If you found a better way, document it
 5. **Don't skip the checklist** - It catches last-minute issues
@@ -196,7 +178,7 @@ Emit appropriate signals based on your progress:
 
 ## What NOT to Do
 
-- Don't skip final consultation (it's BLOCKING)
+- Don't run `consult` commands yourself (porch handles consultations)
 - Don't skip lessons learned ("nothing to report")
 - Don't merge your own PR (Architect handles integration)
 - Don't leave uncommitted changes

package/skeleton/protocols/{spider → spir}/prompts/specify.md

@@ -1,6 +1,6 @@
 # SPECIFY Phase Prompt
 
-You are executing the **SPECIFY** phase of the SPIDER protocol.
+You are executing the **SPECIFY** phase of the SPIR protocol.
 
 ## Your Goal
 
@@ -13,13 +13,25 @@ Create a comprehensive specification document that thoroughly explores the probl
 - **Current State**: {{current_state}}
 - **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
 
-## CRITICAL: Multi-Agent Consultation is MANDATORY
+## Process
 
-The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
+### 0. Check for Existing Spec (ALWAYS DO THIS FIRST)
 
-## Process
+**Before asking ANY questions**, check if a spec already exists:
+
+```bash
+ls codev/specs/{{project_id}}-*.md
+```
+
+**If a spec file exists:**
+1. READ IT COMPLETELY - the answers to your questions are already there
+2. The spec author has already made the key decisions
+3. DO NOT ask clarifying questions - proceed directly to consultation
+4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch
+
+**If no spec exists:** Proceed to Step 1 below.
 
-### 1. Clarifying Questions (ALWAYS START HERE)
+### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
 
 Before writing anything, ask clarifying questions to understand:
 - What problem is being solved?
@@ -28,7 +40,9 @@ Before writing anything, ask clarifying questions to understand:
 - What's in scope vs out of scope?
 - What does success look like?
 
-If this is your first iteration, ask these questions now and wait for answers.
+If this is your first iteration AND no spec exists, ask these questions now and wait for answers.
+
+**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer.
 
 **On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step.
 
@@ -62,45 +76,9 @@ Define measurable acceptance criteria:
 - Non-functional requirements (performance, security)
 - Test scenarios
 
-### 6. MANDATORY: First Consultation (After Draft)
-
-After completing the initial spec draft:
-
-```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini spec {{project_id}} &
-consult --model codex spec {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Update the spec with incorporated feedback
-- Add a **Consultation Log** section documenting:
-  - Key feedback received
-  - Changes made in response
-  - Any feedback intentionally not incorporated (with reasoning)
-
-### 7. Human Review
+### 6. Finalize
 
-After consultation feedback is incorporated:
-- Present the spec for human review
-- Wait for approval or change requests
-- If changes requested, make them and proceed to Step 8
-
-### 8. MANDATORY: Second Consultation (After Human Feedback)
-
-After incorporating human feedback:
-
-```bash
-# Run consultations again (REQUIRED)
-consult --model gemini spec {{project_id}} &
-consult --model codex spec {{project_id}} &
-wait
-```
-
-- Update Consultation Log with new feedback
-- Incorporate changes
-- Prepare final spec for approval
+After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
 
 ## Output
 
@@ -111,31 +89,27 @@ Create or update the specification file at `codev/specs/{{project_id}}-{{title}}
 - Plan: `codev/plans/{{project_id}}-{{title}}.md`
 - Review: `codev/reviews/{{project_id}}-{{title}}.md`
 
-Include a **Consultation Log** section in the spec documenting all consultation feedback.
-
 ## Signals
 
 Emit appropriate signals based on your progress:
 
-- When waiting for clarifying question answers:
+- When waiting for clarifying question answers, **include your questions in the signal**:
   ```
-  <signal>AWAITING_INPUT</signal>
+  <signal type=AWAITING_INPUT>
+  Please answer these questions:
+  1. What should the primary use case be - internal tooling or customer-facing?
+  2. What are the key constraints we should consider?
+  3. Who are the main stakeholders?
+  </signal>
   ```
 
+  The content inside the signal tag is displayed prominently to the user.
+
 - After completing the initial spec draft:
   ```
   <signal>SPEC_DRAFTED</signal>
   ```
 
-- After incorporating consultation feedback:
-  ```
-  <signal>CONSULTATION_INCORPORATED</signal>
-  ```
-
-- After final spec is ready for human approval:
-  ```
-  <signal>SPEC_READY_FOR_APPROVAL</signal>
-  ```
 
 ## Commit Cadence
 
@@ -152,15 +126,13 @@ git add codev/specs/{{project_id}}-{{title}}.md
 
 ## Important Notes
 
-1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
-2. **Be thorough** - A good spec prevents implementation problems
+1. **Be thorough** - A good spec prevents implementation problems
 3. **Be specific** - Vague specs lead to wrong implementations
 4. **Include examples** - Concrete examples clarify intent
-5. **Document consultations** - Maintain the Consultation Log section
 
 ## What NOT to Do
 
-- Don't skip consultations (they are BLOCKING)
+- Don't run `consult` commands yourself (porch handles consultations)
 - Don't include implementation details (that's for the Plan phase)
 - Don't estimate time (AI makes time estimates meaningless)
 - Don't start coding (you're in Specify, not Implement)

package/skeleton/protocols/spir/protocol.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "spir",
+  "alias": "spider",
+  "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": "Write specification with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "specify.md",
+        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+      },
+      "verify": {
+        "type": "spec-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "spec-approval",
+      "next": "plan"
+    },
+    {
+      "id": "plan",
+      "name": "Plan",
+      "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",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "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": "Implement code with 3-way review per plan phase",
+      "type": "per_plan_phase",
+      "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
+        },
+        "tests": {
+          "command": "npm test -- --exclude='**/e2e/**'",
+          "description": "Unit tests only - e2e tests run in review phase",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "implement",
+        "on_all_phases_complete": "review"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "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",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "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 build phase is complete",
+      "transitions_to": "verify"
+    },
+    "BLOCKED": {
+      "description": "Signal implementation is blocked",
+      "requires": "reason"
+    }
+  },
+  "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": {
+    "mode": "strict",
+    "max_iterations": 7,
+    "verify": {
+      "models": ["gemini", "codex", "claude"],
+      "parallel": true
+    }
+  }
+}

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/{spider → spir}/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/{spider → spir}/templates/review.md

@@ -106,7 +106,7 @@
 
 ## Methodology Feedback
 
-### SP(IDE)R Protocol Effectiveness
+### SPIR Protocol Effectiveness
 - **Specification Phase**: [Was it thorough enough? Too detailed?]
 - **Planning Phase**: [Were estimates accurate? Phases well-sized?]
 - **Implementation Loop**: [Did IDE cycle work well?]

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 run {{project_id}}`
+- 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": "soft",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],