@cluesmith/codev 2.0.0-rc.7 → 2.0.0-rc.71

package/skeleton/protocols/spir/protocol.json

@@ -0,0 +1,156 @@
+{
+  "$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": {
+        "pr_exists": {
+          "command": "gh pr list --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'",
+          "description": "PR must be created before signaling completion"
+        },
+        "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/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]