@cluesmith/codev 1.6.1 → 2.0.0-rc.1

package/skeleton/porch/protocols/bugfix.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "./protocol-schema.json",
+  "name": "bugfix",
+  "version": "1.0.0",
+  "description": "BUGFIX: Fast bug fixing from GitHub issues",
+
+  "phases": [
+    {
+      "id": "diagnose",
+      "name": "Diagnose",
+      "prompt": "diagnose.md",
+      "substates": null,
+      "signals": {
+        "ROOT_CAUSE_FOUND": "fix",
+        "NEEDS_MORE_INFO": "diagnose"
+      }
+    },
+    {
+      "id": "fix",
+      "name": "Fix",
+      "prompt": "fix.md",
+      "substates": null,
+      "signals": {
+        "FIX_APPLIED": "test",
+        "FIX_FAILED": "diagnose"
+      }
+    },
+    {
+      "id": "test",
+      "name": "Test",
+      "prompt": "test.md",
+      "substates": null,
+      "signals": {
+        "TESTS_PASS": "pr",
+        "TESTS_FAIL": "fix"
+      },
+      "backpressure": {
+        "tests_pass": {
+          "command": "npm test",
+          "on_fail": "fix"
+        }
+      }
+    },
+    {
+      "id": "pr",
+      "name": "Pull Request",
+      "prompt": "pr.md",
+      "substates": null,
+      "signals": {
+        "PR_CREATED": "complete"
+      }
+    },
+    {
+      "id": "complete",
+      "name": "Complete",
+      "terminal": true
+    }
+  ],
+
+  "gates": [],
+
+  "transitions": {
+    "diagnose": {
+      "default": "fix"
+    },
+    "fix": {
+      "default": "test"
+    },
+    "test": {
+      "on_backpressure_pass": "pr",
+      "on_backpressure_fail": "fix"
+    },
+    "pr": {
+      "default": "complete"
+    }
+  },
+
+  "initial_state": "diagnose",
+
+  "config": {
+    "poll_interval": 5,
+    "max_iterations": 30,
+    "prompts_dir": "prompts"
+  }
+}

package/skeleton/porch/protocols/spider.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "./protocol-schema.json",
+  "name": "spider",
+  "version": "1.0.0",
+  "description": "SPIDER: Specify, Plan, Implement, Defend, Evaluate, Review",
+
+  "phases": [
+    {
+      "id": "specify",
+      "name": "Specify",
+      "prompt": "specify.md",
+      "substates": ["draft", "review"],
+      "initial_substate": "draft",
+      "signals": {
+        "SPEC_READY_FOR_REVIEW": "specify:review"
+      }
+    },
+    {
+      "id": "plan",
+      "name": "Plan",
+      "prompt": "plan.md",
+      "substates": ["draft", "review"],
+      "initial_substate": "draft",
+      "signals": {
+        "PLAN_READY_FOR_REVIEW": "plan:review"
+      }
+    },
+    {
+      "id": "implement",
+      "name": "Implement",
+      "prompt": "implement.md",
+      "substates": null,
+      "signals": {
+        "PHASE_IMPLEMENTED": "defend",
+        "BUILD_FAILED": "implement"
+      }
+    },
+    {
+      "id": "defend",
+      "name": "Defend",
+      "prompt": "defend.md",
+      "substates": null,
+      "signals": {
+        "TESTS_PASSING": "evaluate",
+        "TESTS_FAILED": "defend"
+      },
+      "backpressure": {
+        "tests_pass": {
+          "command": "npm test",
+          "on_fail": "defend"
+        }
+      }
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "prompt": "evaluate.md",
+      "substates": null,
+      "signals": {
+        "EVALUATION_COMPLETE": "review",
+        "CRITERIA_NOT_MET": "implement",
+        "NEXT_PHASE": "implement"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "prompt": "review.md",
+      "substates": null,
+      "signals": {
+        "REVIEW_COMPLETE": "complete"
+      }
+    },
+    {
+      "id": "complete",
+      "name": "Complete",
+      "terminal": true
+    }
+  ],
+
+  "gates": [
+    {
+      "id": "specify_approval",
+      "after_state": "specify:review",
+      "next_state": "plan:draft",
+      "type": "human",
+      "description": "Human approval of specification"
+    },
+    {
+      "id": "plan_approval",
+      "after_state": "plan:review",
+      "next_state": "implement",
+      "type": "human",
+      "description": "Human approval of implementation plan"
+    }
+  ],
+
+  "transitions": {
+    "specify:draft": {
+      "default": "specify:review"
+    },
+    "specify:review": {
+      "on_gate_pass": "plan:draft",
+      "wait_for": "specify_approval"
+    },
+    "plan:draft": {
+      "default": "plan:review"
+    },
+    "plan:review": {
+      "on_gate_pass": "implement",
+      "wait_for": "plan_approval"
+    },
+    "implement": {
+      "default": "defend"
+    },
+    "defend": {
+      "on_backpressure_pass": "evaluate",
+      "on_backpressure_fail": "defend"
+    },
+    "evaluate": {
+      "default": "review"
+    },
+    "review": {
+      "default": "complete"
+    }
+  },
+
+  "initial_state": "specify:draft",
+
+  "config": {
+    "poll_interval": 30,
+    "max_iterations": 100,
+    "prompts_dir": "prompts"
+  }
+}

package/skeleton/porch/protocols/tick.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "./protocol-schema.json",
+  "name": "tick",
+  "version": "1.0.0",
+  "description": "TICK: Fast autonomous implementation for amendments",
+
+  "phases": [
+    {
+      "id": "understand",
+      "name": "Understand",
+      "prompt": "understand.md",
+      "substates": null,
+      "signals": {
+        "UNDERSTOOD": "implement"
+      }
+    },
+    {
+      "id": "implement",
+      "name": "Implement",
+      "prompt": "implement.md",
+      "substates": null,
+      "signals": {
+        "IMPLEMENTED": "verify",
+        "BUILD_FAILED": "implement"
+      }
+    },
+    {
+      "id": "verify",
+      "name": "Verify",
+      "prompt": "verify.md",
+      "substates": null,
+      "signals": {
+        "VERIFIED": "complete",
+        "VERIFICATION_FAILED": "implement"
+      },
+      "backpressure": {
+        "tests_pass": {
+          "command": "npm test",
+          "on_fail": "implement"
+        },
+        "build_pass": {
+          "command": "npm run build",
+          "on_fail": "implement"
+        }
+      }
+    },
+    {
+      "id": "complete",
+      "name": "Complete",
+      "terminal": true
+    }
+  ],
+
+  "gates": [],
+
+  "transitions": {
+    "understand": {
+      "default": "implement"
+    },
+    "implement": {
+      "default": "verify"
+    },
+    "verify": {
+      "on_backpressure_pass": "complete",
+      "on_backpressure_fail": "implement"
+    }
+  },
+
+  "initial_state": "understand",
+
+  "config": {
+    "poll_interval": 5,
+    "max_iterations": 50,
+    "prompts_dir": "prompts"
+  }
+}

package/skeleton/protocols/bugfix/protocol.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "bugfix",
+  "version": "1.0.0",
+  "description": "Lightweight protocol for minor bugfixes using GitHub Issues",
+  "phases": [
+    {
+      "id": "investigate",
+      "name": "Investigate",
+      "description": "Understand the bug and its root cause",
+      "type": "once",
+      "steps": [
+        "read_issue",
+        "reproduce_bug",
+        "identify_root_cause",
+        "assess_complexity"
+      ],
+      "transition": {
+        "on_complete": "fix",
+        "on_too_complex": "escalate"
+      }
+    },
+    {
+      "id": "fix",
+      "name": "Fix",
+      "description": "Implement the bug fix",
+      "type": "once",
+      "steps": [
+        "implement_fix",
+        "add_tests",
+        "verify_fix",
+        "commit"
+      ],
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "pr"
+      }
+    },
+    {
+      "id": "pr",
+      "name": "Create PR",
+      "description": "Create pull request for the fix",
+      "type": "once",
+      "steps": [
+        "create_pr",
+        "link_issue",
+        "request_review"
+      ],
+      "consultation": {
+        "on": "review",
+        "models": ["gemini", "codex"],
+        "type": "impl-review",
+        "parallel": true,
+        "max_rounds": 1
+      },
+      "transition": {
+        "on_complete": "review"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Address review feedback",
+      "type": "once",
+      "steps": [
+        "address_feedback",
+        "update_pr"
+      ],
+      "transition": {
+        "on_complete": "merge"
+      }
+    },
+    {
+      "id": "merge",
+      "name": "Merge",
+      "description": "Merge the fix and close the issue",
+      "type": "once",
+      "steps": [
+        "merge_pr",
+        "verify_main",
+        "close_issue"
+      ],
+      "gate": {
+        "name": "merge-approval",
+        "description": "Architect approves merge",
+        "requires": ["review_complete", "tests_pass"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "TOO_COMPLEX": {
+      "description": "Bug is too complex for BUGFIX, escalate to SPIDER",
+      "transitions_to": "escalate"
+    },
+    "BLOCKED": {
+      "description": "Signal fix is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "consultation": {
+      "enabled": true,
+      "models": ["gemini", "codex"],
+      "parallel": true
+    },
+    "checks": {
+      "build": "npm run build",
+      "test": "npm test"
+    }
+  }
+}

package/skeleton/protocols/protocol-schema.json

@@ -0,0 +1,237 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codev.dev/protocol-schema.json",
+  "title": "Protocol Definition",
+  "description": "Schema for porch protocol definitions",
+  "type": "object",
+  "required": ["name", "version", "description", "phases"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Protocol identifier (e.g., 'spider', 'tick', 'bugfix')"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the protocol"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the protocol"
+    },
+    "phases": {
+      "type": "array",
+      "description": "Ordered list of protocol phases",
+      "items": {
+        "$ref": "#/definitions/phase"
+      },
+      "minItems": 1
+    },
+    "signals": {
+      "type": "object",
+      "description": "Signal definitions for state transitions",
+      "additionalProperties": {
+        "$ref": "#/definitions/signal"
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Default configuration for the protocol",
+      "properties": {
+        "consultation": {
+          "$ref": "#/definitions/consultationDefaults"
+        },
+        "checks": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "phase": {
+      "type": "object",
+      "required": ["id", "name", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique phase identifier"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable phase name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Phase description"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["once", "per_plan_phase"],
+          "description": "Whether phase runs once or per plan phase"
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Ordered list of steps within the phase"
+        },
+        "checks": {
+          "type": "object",
+          "description": "Build/test checks for this phase",
+          "additionalProperties": {
+            "$ref": "#/definitions/check"
+          }
+        },
+        "consultation": {
+          "$ref": "#/definitions/consultation"
+        },
+        "gate": {
+          "$ref": "#/definitions/gate"
+        },
+        "transition": {
+          "$ref": "#/definitions/transition"
+        }
+      }
+    },
+    "check": {
+      "type": "object",
+      "required": ["command"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Command to run"
+        },
+        "on_fail": {
+          "type": "string",
+          "description": "Action on failure: 'retry' or phase name to return to"
+        },
+        "max_retries": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum retry attempts"
+        },
+        "retry_delay": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delay between retries in seconds"
+        }
+      }
+    },
+    "consultation": {
+      "type": "object",
+      "properties": {
+        "on": {
+          "type": "string",
+          "enum": ["review", "complete"],
+          "description": "When to trigger consultation"
+        },
+        "models": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "AI models to consult"
+        },
+        "type": {
+          "type": "string",
+          "description": "Review type (spec-review, plan-review, impl-review, pr-ready)"
+        },
+        "parallel": {
+          "type": "boolean",
+          "description": "Run consultations in parallel"
+        },
+        "max_rounds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum revision rounds"
+        },
+        "next": {
+          "type": "string",
+          "description": "Phase to proceed to after consultation"
+        }
+      }
+    },
+    "consultationDefaults": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether consultation is enabled by default"
+        },
+        "models": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "parallel": {
+          "type": "boolean"
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Gate identifier"
+        },
+        "description": {
+          "type": "string",
+          "description": "What this gate checks"
+        },
+        "requires": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Items that must be complete to pass"
+        },
+        "next": {
+          "type": ["string", "null"],
+          "description": "Next phase after gate (null for terminal)"
+        }
+      }
+    },
+    "transition": {
+      "type": "object",
+      "properties": {
+        "on_complete": {
+          "type": "string",
+          "description": "Phase to transition to on completion"
+        },
+        "on_fail": {
+          "type": "string",
+          "description": "Phase to return to on failure"
+        },
+        "on_too_complex": {
+          "type": "string",
+          "description": "Action when task is too complex"
+        },
+        "on_all_phases_complete": {
+          "type": "string",
+          "description": "Phase to transition to when all plan phases are done"
+        }
+      }
+    },
+    "signal": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "transitions_to": {
+          "type": "string"
+        },
+        "requires": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}