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

package/skeleton/protocols/maintain/protocol.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "maintain",
+  "alias": "maint",
+  "version": "2.0.0",
+  "description": "Codebase maintenance - dead code removal, doc sync, hygiene with 3-way review",
+  "input": {
+    "type": "protocol",
+    "required": false,
+    "default_for": ["--protocol maintain"]
+  },
+  "phases": [
+    {
+      "id": "audit",
+      "name": "Audit",
+      "description": "Analyze codebase for dead code, unused dependencies, stale docs",
+      "type": "build_verify",
+      "build": {
+        "prompt": "audit.md",
+        "artifact": "codev/maintain/*.md"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "next": "clean"
+    },
+    {
+      "id": "clean",
+      "name": "Clean",
+      "description": "Remove identified dead code and unused dependencies",
+      "type": "build_verify",
+      "build": {
+        "prompt": "clean.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx}"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 5,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test -- --exclude='**/e2e/**'",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "next": "sync"
+    },
+    {
+      "id": "sync",
+      "name": "Sync Documentation",
+      "description": "Update documentation to match current codebase",
+      "type": "build_verify",
+      "build": {
+        "prompt": "sync.md",
+        "artifact": "codev/resources/*.md"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 5,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify",
+      "description": "Final validation and PR creation",
+      "type": "build_verify",
+      "build": {
+        "prompt": "verify.md",
+        "artifact": "codev/maintain/*.md"
+      },
+      "verify": {
+        "type": "pr-ready",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "gate": "maintain-complete",
+      "next": null
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "verify"
+    },
+    "BLOCKED": {
+      "description": "Signal maintenance is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "max_iterations": 5,
+    "verify": {
+      "models": ["gemini", "codex", "claude"],
+      "parallel": true
+    }
+  }
+}

package/skeleton/protocols/maintain/protocol.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. Unlike SPIDER/TICK (which have sequential phases), MAINTAIN is a **task list** where tasks can run in parallel and some require human review.
+MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. It runs as a **strict porch protocol** with sequential phases and 3-way consultation (Gemini, Codex, Claude) at each phase.
 
 **Core Principle**: Regular maintenance prevents technical debt accumulation.
 
@@ -22,20 +22,26 @@ Any builder can update these files during development, but MAINTAIN ensures they
 
 ## Execution Model
 
-MAINTAIN is executed by a Builder, spawned by the Architect:
+MAINTAIN is orchestrated by porch with 4 sequential phases:
 
 ```
-Architect: "Time for maintenance"
-    ↓
 af spawn --protocol maintain
     ↓
-Builder works through task list
-    ↓
+1. AUDIT: Scan for dead code, unused deps, stale docs
+    ↓ (3-way review)
+2. CLEAN: Remove identified cruft
+    ↓ (3-way review + build/test checks)
+3. SYNC: Update documentation
+    ↓ (3-way review)
+4. VERIFY: Final validation + PR
+    ↓ (3-way review)
 PR with maintenance changes
     ↓
-Architect reviews → Builder merges
+Architect reviews → Merge
 ```
 
+Each phase goes through build-verify cycles with 3-way consultation before proceeding.
+
 ## Prerequisites
 
 Before starting MAINTAIN:
@@ -473,7 +479,7 @@ MAINTAIN is an **operational protocol**, not a feature development protocol:
 | Review | No |
 | 3-Way Consultation | **Yes** (before creating PR) |
 
-**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIDER.
+**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIR.
 
 ---
 

package/skeleton/protocols/protocol-schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "name": {
       "type": "string",
-      "description": "Protocol identifier (e.g., 'spider', 'tick', 'bugfix')"
+      "description": "Protocol identifier (e.g., 'spir', 'tick', 'bugfix')"
     },
     "version": {
       "type": "string",
@@ -27,6 +27,12 @@
       },
       "minItems": 1
     },
+    "input": {
+      "$ref": "#/definitions/protocolInput"
+    },
+    "hooks": {
+      "$ref": "#/definitions/protocolHooks"
+    },
     "signals": {
       "type": "object",
       "description": "Signal definitions for state transitions",
@@ -38,6 +44,11 @@
       "type": "object",
       "description": "Default configuration for the protocol",
       "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["strict", "soft"],
+          "description": "Default orchestration mode for the protocol"
+        },
         "consultation": {
           "$ref": "#/definitions/consultationDefaults"
         },
@@ -232,6 +243,48 @@
           "type": "string"
         }
       }
+    },
+    "protocolInput": {
+      "type": "object",
+      "description": "Protocol input configuration - defines what input types a protocol accepts",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["spec", "github-issue", "task", "protocol", "shell", "worktree"],
+          "description": "Primary input type for this protocol"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether an input of this type is required"
+        },
+        "default_for": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "CLI flags this protocol is the default for (e.g., ['--issue', '-i'])"
+        }
+      }
+    },
+    "protocolHooks": {
+      "type": "object",
+      "description": "Hooks triggered at various points in the spawn lifecycle",
+      "properties": {
+        "pre-spawn": {
+          "type": "object",
+          "description": "Hooks executed before spawning the builder",
+          "properties": {
+            "collision-check": {
+              "type": "boolean",
+              "description": "Check for worktree/PR collisions before spawning"
+            },
+            "comment-on-issue": {
+              "type": "string",
+              "description": "Comment to post on GitHub issue when spawning"
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -0,0 +1,59 @@
+# {{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 protocol document 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
+- Do not deviate from the porch-driven workflow
+
+### 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
+- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval
+{{/if}}
+
+## Protocol
+Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
+Read and internalize the protocol before starting any work.
+
+{{#if spec}}
+## Spec
+Read the specification at: `{{spec.path}}`
+{{/if}}
+
+{{#if plan}}
+## Plan
+Follow the implementation plan at: `{{plan.path}}`
+{{/if}}
+
+{{#if issue}}
+## Issue #{{issue.number}}
+**Title**: {{issue.title}}
+
+**Description**:
+{{issue.body}}
+{{/if}}
+
+{{#if task}}
+## Task
+{{task_text}}
+{{/if}}
+
+## Getting Started
+1. Read the protocol document thoroughly
+2. Review the spec and plan (if available)
+3. Begin implementation following the protocol phases

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

@@ -0,0 +1,208 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the SPIR protocol.
+
+## Your Goal
+
+Write clean, well-structured code AND tests that implement the current plan phase.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}}
+
+## ⚠️ SCOPE RESTRICTION — READ THIS FIRST
+
+**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).**
+
+- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations.
+- **DO NOT** read the full plan file and implement everything you see.
+- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope.
+- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires.
+
+## What Happens After You Finish
+
+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
+
+## 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
+
+Before implementing, verify:
+1. Previous phase (if any) is committed to git
+2. You've read the plan phase you're implementing
+3. You understand the success criteria for this phase
+4. Dependencies from earlier phases are available
+
+## Process
+
+### 1. Review the Plan Phase
+
+Read the current phase in the plan:
+- What is the objective?
+- What files need to be created/modified?
+- What are the success criteria?
+- What dependencies exist?
+
+### 2. Set Up
+
+- Verify you're on the correct branch
+- Check that previous phase is committed: `git log --oneline -5`
+- Ensure build passes before starting: `npm run build` (or equivalent)
+
+### 3. Implement the Code
+
+Write the code following these principles:
+
+**Code Quality Standards**:
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code
+- No debug prints in final code
+- Explicit error handling
+- Follow project style guide
+
+**Implementation Approach**:
+- Work on one file at a time
+- Make small, incremental changes
+- Document complex logic with comments
+
+### 4. Write Tests
+
+**Tests are required.** For each piece of functionality you implement:
+
+- 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)
+
+**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
+npm run build      # Must pass
+npm test           # Must pass
+```
+
+**Important**: Don't assume these commands exist. Check `package.json` first.
+
+Fix any errors before signaling completion.
+
+### 6. Self-Review
+
+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
+- All tests passing
+
+## Signals
+
+When implementation AND tests are complete and passing:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you encounter a blocker:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```
+
+If you need spec/plan clarification:
+
+```
+<signal type=AWAITING_INPUT>
+Your specific questions here
+</signal>
+```
+
+## Important Notes
+
+1. **Follow the plan** - Implement what's specified, not more
+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 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 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 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 `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.
+
+**If a dependency is missing**:
+Signal `BLOCKED` with details about what's missing.
+
+**If build or tests fail and you can't fix it**:
+Signal `BLOCKED` with the error message.

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

@@ -1,6 +1,6 @@
 # PLAN Phase Prompt
 
-You are executing the **PLAN** phase of the SPIDER protocol.
+You are executing the **PLAN** phase of the SPIR protocol.
 
 ## Your Goal
 
@@ -14,10 +14,6 @@ Transform the approved specification into an executable implementation plan with
 - **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
 - **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
 
-## CRITICAL: Multi-Agent Consultation is MANDATORY
-
-The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
-
 ## Prerequisites
 
 Before planning, verify:
@@ -72,51 +68,15 @@ Phase 3: API Endpoints (depends on Phase 2)
 Phase 4: Frontend Integration (depends on Phase 3)
 ```
 
-### 5. MANDATORY: First Consultation (After Draft)
-
-After completing the initial plan draft:
-
-```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini plan {{project_id}} &
-consult --model codex plan {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Update the plan with incorporated feedback
-- Add a **Consultation Log** section documenting:
-  - Key feedback received
-  - Changes made in response
-  - Any feedback intentionally not incorporated (with reasoning)
-
-### 6. Human Review
-
-After consultation feedback is incorporated:
-- Present the plan for human review
-- Wait for approval or change requests
-- If changes requested, make them and proceed to Step 7
-
-### 7. MANDATORY: Second Consultation (After Human Feedback)
-
-After incorporating human feedback:
+### 5. Finalize
 
-```bash
-# Run consultations again (REQUIRED)
-consult --model gemini plan {{project_id}} &
-consult --model codex plan {{project_id}} &
-wait
-```
-
-- Update Consultation Log with new feedback
-- Incorporate changes
-- Prepare final plan for approval
+After completing the plan 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
 
 Create the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
 
-Use the plan template from `codev/protocols/spider/templates/plan.md` if available.
+Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
 ### Plan Structure
 
@@ -148,18 +108,6 @@ Brief summary of what will be implemented.
 - [Risk 1]: [Mitigation]
 - [Risk 2]: [Mitigation]
 
-## Consultation Log
-
-### First Consultation (After Draft)
-- **Gemini Feedback**: [Summary]
-- **Codex Feedback**: [Summary]
-- **Changes Made**: [List]
-- **Not Incorporated**: [List with reasons]
-
-### Second Consultation (After Human Feedback)
-- **Gemini Feedback**: [Summary]
-- **Codex Feedback**: [Summary]
-- **Changes Made**: [List]
 ```
 
 ## Signals
@@ -171,16 +119,6 @@ Emit appropriate signals based on your progress:
   <signal>PLAN_DRAFTED</signal>
   ```
 
-- After incorporating consultation feedback:
-  ```
-  <signal>CONSULTATION_INCORPORATED</signal>
-  ```
-
-- After final plan is ready for human approval:
-  ```
-  <signal>PLAN_READY_FOR_APPROVAL</signal>
-  ```
-
 ## Commit Cadence
 
 Make commits at these milestones:
@@ -196,16 +134,14 @@ git add codev/plans/{{project_id}}-{{title}}.md
 
 ## Important Notes
 
-1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
-2. **No time estimates** - Don't include hours/days/weeks
+1. **No time estimates** - Don't include hours/days/weeks
 3. **Be specific about files** - Exact paths, not "the config file"
 4. **Keep phases small** - 1-3 files per phase is ideal
 5. **Document dependencies clearly** - Prevents blocked work
-6. **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 write code (that's for Implement phase)
 - Don't estimate time (meaningless in AI development)
 - Don't create phases that can't be independently tested