@cluesmith/codev 2.0.0-rc.5 → 2.0.0-rc.51

package/skeleton/protocol-schema.json

@@ -0,0 +1,282 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codev.dev/protocol-schema.json",
+  "title": "Codev Protocol Definition",
+  "description": "Schema for porch protocol definitions (SPIDER, TICK, BUGFIX, etc.)",
+  "type": "object",
+  "required": ["name", "phases"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "description": "Protocol name (e.g., 'spider', 'tick', 'bugfix')",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "alias": {
+      "type": "string",
+      "description": "Alternative name for the protocol (e.g., 'spir' for spider)"
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of the protocol",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-z0-9.]+)?$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the protocol"
+    },
+    "phases": {
+      "type": "array",
+      "description": "Ordered list of protocol phases",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/phase" }
+    },
+    "signals": {
+      "type": "object",
+      "description": "Signals that can be emitted during protocol execution",
+      "additionalProperties": { "$ref": "#/$defs/signal" }
+    },
+    "phase_completion": {
+      "type": "object",
+      "description": "Checks run when a plan phase completes",
+      "additionalProperties": {
+        "type": "string",
+        "description": "Shell command to run"
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Default values for phase properties",
+      "properties": {
+        "max_iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 7
+        },
+        "verify": { "$ref": "#/$defs/verifyConfig" }
+      }
+    }
+  },
+  "$defs": {
+    "phase": {
+      "type": "object",
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique phase identifier",
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable phase name"
+        },
+        "description": {
+          "type": "string",
+          "description": "What this phase does"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["once", "build_verify", "per_plan_phase"],
+          "description": "Phase execution type",
+          "default": "build_verify"
+        },
+        "build": { "$ref": "#/$defs/buildConfig" },
+        "verify": { "$ref": "#/$defs/verifyConfig" },
+        "max_iterations": {
+          "type": "integer",
+          "description": "Maximum build-verify iterations before failing",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 7
+        },
+        "on_complete": { "$ref": "#/$defs/onCompleteConfig" },
+        "checks": {
+          "type": "object",
+          "description": "Named checks to run during this phase",
+          "additionalProperties": { "$ref": "#/$defs/check" }
+        },
+        "gate": {
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "Gate name (simple format)",
+              "pattern": "^[a-z][a-z0-9-]*$"
+            },
+            {
+              "$ref": "#/$defs/gateConfig",
+              "description": "Gate with options (extended format)"
+            }
+          ]
+        },
+        "transition": { "$ref": "#/$defs/transitionConfig" },
+        "next": {
+          "oneOf": [
+            { "type": "string", "description": "Next phase id" },
+            { "type": "null", "description": "Terminal phase" }
+          ]
+        }
+      }
+    },
+    "buildConfig": {
+      "type": "object",
+      "description": "Configuration for the build step",
+      "required": ["prompt", "artifact"],
+      "properties": {
+        "prompt": {
+          "type": "string",
+          "description": "Prompt file name (e.g., 'specify.md')"
+        },
+        "artifact": {
+          "type": "string",
+          "description": "Artifact path pattern with ${PROJECT_ID} variable"
+        }
+      }
+    },
+    "verifyConfig": {
+      "type": "object",
+      "description": "Configuration for 3-way verification",
+      "required": ["type", "models"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Review type (maps to consult --type)",
+          "enum": ["spec-review", "plan-review", "impl-review", "pr-ready", "integration-review"]
+        },
+        "models": {
+          "type": "array",
+          "description": "Models to consult",
+          "items": {
+            "type": "string",
+            "enum": ["gemini", "codex", "claude"]
+          },
+          "minItems": 1
+        },
+        "parallel": {
+          "type": "boolean",
+          "description": "Run consultations in parallel",
+          "default": true
+        }
+      }
+    },
+    "onCompleteConfig": {
+      "type": "object",
+      "description": "Actions to perform after successful verification",
+      "properties": {
+        "commit": {
+          "type": "boolean",
+          "description": "Commit artifact to git",
+          "default": false
+        },
+        "push": {
+          "type": "boolean",
+          "description": "Push commit to remote",
+          "default": false
+        }
+      }
+    },
+    "check": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Simple shell command"
+        },
+        {
+          "type": "object",
+          "description": "Check with options",
+          "required": ["command"],
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "Shell command to run"
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description"
+            },
+            "on_fail": {
+              "type": "string",
+              "enum": ["fail", "retry", "warn"],
+              "description": "Action on failure",
+              "default": "fail"
+            },
+            "max_retries": {
+              "type": "integer",
+              "description": "Maximum retry attempts",
+              "minimum": 0,
+              "maximum": 10,
+              "default": 0
+            },
+            "optional": {
+              "type": "boolean",
+              "description": "Don't fail protocol if check fails",
+              "default": false
+            }
+          }
+        }
+      ]
+    },
+    "transitionConfig": {
+      "type": "object",
+      "description": "Transition rules for per_plan_phase types",
+      "properties": {
+        "on_complete": {
+          "type": "string",
+          "description": "Phase to transition to after each plan phase"
+        },
+        "on_all_phases_complete": {
+          "type": "string",
+          "description": "Phase to transition to when all plan phases complete"
+        }
+      }
+    },
+    "signal": {
+      "type": "object",
+      "description": "Signal definition",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "transitions_to": {
+          "type": "string",
+          "description": "State to transition to when signal received"
+        },
+        "requires": {
+          "type": "string",
+          "description": "Required parameter name"
+        }
+      }
+    },
+    "gateConfig": {
+      "type": "object",
+      "description": "Gate with extended configuration",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Gate identifier",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "requires": {
+          "type": "array",
+          "description": "Check names that must pass before gate can be approved",
+          "items": { "type": "string" }
+        },
+        "next": {
+          "oneOf": [
+            { "type": "string", "description": "Next phase after gate approval" },
+            { "type": "null", "description": "Terminal gate" }
+          ]
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+# {{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 BUGFIX 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
+{{/if}}
+
+## Protocol
+Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md`
+
+{{#if issue}}
+## Issue #{{issue.number}}
+**Title**: {{issue.title}}
+
+**Description**:
+{{issue.body}}
+
+## Your Mission
+1. Reproduce the bug
+2. Identify root cause
+3. Implement fix (< 300 LOC)
+4. Add regression test
+5. Run CMAP review (3-way parallel: Gemini, Codex, Claude)
+6. Create PR with "Fixes #{{issue.number}}" in body
+
+If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via:
+```bash
+af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIDER/TICK."
+```
+{{/if}}
+
+## Getting Started
+1. Read the BUGFIX protocol
+2. Review the issue details
+3. Reproduce the bug before fixing

package/skeleton/protocols/bugfix/protocol.json

@@ -1,8 +1,19 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "bugfix",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight protocol for minor bugfixes using GitHub Issues",
+  "input": {
+    "type": "github-issue",
+    "required": false,
+    "default_for": ["--issue", "-i"]
+  },
+  "hooks": {
+    "pre-spawn": {
+      "collision-check": true,
+      "comment-on-issue": "On it! Working on a fix now."
+    }
+  },
   "phases": [
     {
       "id": "investigate",
@@ -105,7 +116,7 @@
       "transitions_to": "next_phase"
     },
     "TOO_COMPLEX": {
-      "description": "Bug is too complex for BUGFIX, escalate to SPIDER",
+      "description": "Bug is too complex for BUGFIX, escalate to SPIR",
       "transitions_to": "escalate"
     },
     "BLOCKED": {
@@ -114,6 +125,7 @@
     }
   },
   "defaults": {
+    "mode": "soft",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],

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

@@ -0,0 +1,47 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing a disciplined experiment.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the EXPERIMENT protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Document your findings thoroughly
+{{/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
+{{/if}}
+
+## Protocol
+Follow the EXPERIMENT protocol: `codev/protocols/experiment/protocol.md`
+
+## EXPERIMENT Overview
+The EXPERIMENT protocol ensures disciplined experimentation:
+
+1. **Hypothesis Phase**: Define what you're testing and success criteria
+2. **Design Phase**: Plan the experiment approach
+3. **Execute Phase**: Run the experiment and gather data
+4. **Analyze Phase**: Evaluate results and draw conclusions
+
+{{#if task}}
+## Experiment Focus
+{{task_text}}
+{{/if}}
+
+## Key Principles
+- Start with a clear, falsifiable hypothesis
+- Define success/failure criteria upfront
+- Keep scope minimal for quick iteration
+- Document findings regardless of outcome
+- Separate experiment artifacts from production code
+
+## Getting Started
+1. Read the EXPERIMENT protocol document
+2. Define your hypothesis clearly
+3. Follow the phases in order

package/skeleton/protocols/experiment/protocol.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "experiment",
+  "version": "1.0.0",
+  "description": "Disciplined experimentation with hypothesis testing",
+  "input": {
+    "type": "none",
+    "required": false,
+    "default_for": []
+  },
+  "hooks": {
+    "pre-spawn": {}
+  },
+  "phases": [
+    {
+      "id": "hypothesis",
+      "name": "Hypothesis",
+      "description": "Define the hypothesis and success criteria",
+      "type": "once",
+      "steps": [
+        "define_hypothesis",
+        "define_success_criteria",
+        "define_scope",
+        "create_experiment_doc"
+      ],
+      "transition": {
+        "on_complete": "design"
+      }
+    },
+    {
+      "id": "design",
+      "name": "Design",
+      "description": "Design the experiment approach",
+      "type": "once",
+      "steps": [
+        "choose_approach",
+        "identify_dependencies",
+        "plan_implementation",
+        "define_measurements"
+      ],
+      "transition": {
+        "on_complete": "execute"
+      }
+    },
+    {
+      "id": "execute",
+      "name": "Execute",
+      "description": "Run the experiment",
+      "type": "once",
+      "steps": [
+        "implement_prototype",
+        "gather_data",
+        "document_findings"
+      ],
+      "transition": {
+        "on_complete": "analyze"
+      }
+    },
+    {
+      "id": "analyze",
+      "name": "Analyze",
+      "description": "Analyze results and draw conclusions",
+      "type": "once",
+      "steps": [
+        "analyze_data",
+        "evaluate_hypothesis",
+        "document_conclusions",
+        "recommend_next_steps"
+      ],
+      "gate": {
+        "name": "experiment-complete",
+        "description": "Experiment complete",
+        "requires": ["conclusions_documented"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal experiment is blocked",
+      "requires": "reason"
+    },
+    "HYPOTHESIS_REJECTED": {
+      "description": "Signal hypothesis was disproven",
+      "transitions_to": "analyze"
+    }
+  },
+  "defaults": {
+    "mode": "soft",
+    "consultation": {
+      "enabled": false,
+      "models": [],
+      "parallel": false
+    },
+    "checks": {}
+  }
+}

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

@@ -0,0 +1,41 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing the MAINTAIN protocol to clean up and synchronize the codebase.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the MAINTAIN protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Work through each phase methodically
+{{/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
+{{/if}}
+
+## Protocol
+Follow the MAINTAIN protocol: `codev/protocols/maintain/protocol.md`
+
+## MAINTAIN Overview
+The MAINTAIN protocol handles codebase hygiene:
+
+1. **Audit Phase**: Scan for dead code, unused dependencies, stale docs
+2. **Clean Phase**: Remove identified cruft, verify build
+3. **Sync Phase**: Update documentation (arch.md, lessons-learned.md, CLAUDE.md)
+4. **Verify Phase**: Run full test suite, confirm health
+
+## Key Rules
+- Use soft deletion (move to `codev/maintain/.trash/`)
+- Always verify build passes after removals
+- Update documentation to match current architecture
+- Don't remove anything actively used
+
+## Getting Started
+1. Read the MAINTAIN protocol document
+2. Start with the Audit phase
+3. Document all changes made

package/skeleton/protocols/maintain/prompts/audit.md

@@ -0,0 +1,111 @@
+# AUDIT Phase Prompt
+
+You are executing the **AUDIT** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Analyze the codebase to identify dead code, unused dependencies, and stale documentation.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Determine Base Commit
+
+Find the last maintenance run:
+```bash
+ls codev/maintain/
+```
+
+If previous runs exist, note the base commit to focus on changes since then.
+
+### 2. Scan for Dead Code
+
+Run static analysis tools:
+
+```bash
+# TypeScript/JavaScript
+npx ts-prune 2>/dev/null || echo "ts-prune not available"
+npx depcheck 2>/dev/null || echo "depcheck not available"
+
+# Check for unused exports
+grep -r "export " --include="*.ts" --include="*.tsx" | head -50
+```
+
+### 3. Scan for Unused Dependencies
+
+Check package.json for unused dependencies:
+```bash
+cat package.json | grep -A100 '"dependencies"' | head -50
+```
+
+Cross-reference with actual imports in the codebase.
+
+### 4. Scan for Stale Documentation
+
+Check for references to deleted files/functions:
+```bash
+# Recent changes
+git log --oneline -20
+
+# Check if arch.md references exist
+grep -E "src/|packages/" codev/resources/arch.md | head -20
+```
+
+### 5. Create Audit Report
+
+Create a maintenance run file: `codev/maintain/NNNN.md`
+
+Document:
+- Dead code identified (with file paths)
+- Unused dependencies
+- Stale documentation references
+- Recommended actions
+
+Use the template structure:
+```markdown
+# Maintenance Run NNNN
+
+**Date**: YYYY-MM-DD
+**Base Commit**: <commit-hash>
+
+## Dead Code Identified
+
+| File | Item | Reason |
+|------|------|--------|
+| path/to/file.ts | unusedFunction() | Not imported anywhere |
+
+## Unused Dependencies
+
+| Package | Reason |
+|---------|--------|
+| some-pkg | Not imported |
+
+## Stale Documentation
+
+| Document | Issue |
+|----------|-------|
+| arch.md | References deleted module |
+
+## Recommended Actions
+
+1. Remove X
+2. Update Y
+3. ...
+```
+
+## Signals
+
+When audit report is complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```