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

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 (SPIR, TICK, BUGFIX, etc.)",
+  "type": "object",
+  "required": ["name", "phases"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "description": "Protocol name (e.g., 'spir', 'tick', 'bugfix')",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "alias": {
+      "type": "string",
+      "description": "Alternative name for the protocol (e.g., 'spider' for spir)"
+    },
+    "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,54 @@
+# {{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
+
+### 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 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 SPIR/TICK."
+```
+{{/if}}
+
+## Getting Started
+1. Read the BUGFIX protocol
+2. Review the issue details
+3. Reproduce the bug before fixing

package/skeleton/protocols/bugfix/prompts/fix.md

@@ -0,0 +1,77 @@
+# FIX Phase Prompt
+
+You are executing the **FIX** phase of the BUGFIX protocol.
+
+## Your Goal
+
+Implement the bug fix and add a regression test. Keep it minimal and focused.
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Implement the Fix
+
+Apply the minimum change needed to resolve the bug:
+- Fix the root cause identified in the INVESTIGATE phase
+- Do NOT refactor surrounding code
+- Do NOT add features beyond what's needed
+- Do NOT fix other bugs you happen to notice (file separate issues)
+
+**Code Quality**:
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code or debug prints
+- Follow existing project conventions
+
+### 2. Add a Regression Test
+
+**A regression test is MANDATORY.** Every bugfix MUST include a test unless you provide explicit justification for why a test is impossible (e.g., pure CSS-only change with no testable behavior). If you skip the test, you MUST explain why in your commit message and PR description.
+
+Write a test that:
+- Fails without the fix (demonstrates the bug)
+- Passes with the fix (demonstrates the fix works)
+- Covers the specific scenario from the issue
+- Is deterministic (not flaky)
+
+Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.).
+
+### 3. Verify the Fix
+
+Run build and tests:
+
+```bash
+npm run build      # Must pass
+npm test           # Must pass
+```
+
+Fix any failures before proceeding. If build/test commands don't exist, check `package.json`.
+
+### 4. Commit
+
+Stage and commit your changes:
+- Use explicit file paths (never `git add -A` or `git add .`)
+- Commit message: `Fix #{{issue.number}}: <brief description>`
+
+## Signals
+
+When fix and tests are complete and passing:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you encounter a blocker:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```
+
+## Important Notes
+
+1. **Minimal changes only** — Fix the bug, nothing else
+2. **Regression test is MANDATORY** — No fix without a test. If truly untestable, justify in writing.
+3. **Build AND tests must pass** — Don't signal complete until both pass
+4. **Stay under 300 LOC** — If the fix grows beyond this, signal `TOO_COMPLEX`

package/skeleton/protocols/bugfix/prompts/investigate.md

@@ -0,0 +1,77 @@
+# INVESTIGATE Phase Prompt
+
+You are executing the **INVESTIGATE** phase of the BUGFIX protocol.
+
+## Your Goal
+
+Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC).
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Read the Issue
+
+Read the full issue description. Identify:
+- What is the expected behavior?
+- What is the actual behavior?
+- Are there reproduction steps?
+- Are there error messages or screenshots?
+
+### 2. Reproduce the Bug
+
+Before fixing anything, confirm the bug exists:
+- Follow the reproduction steps from the issue
+- If no steps are given, infer them from the description
+- Document the exact reproduction steps you used
+- If you **cannot** reproduce, signal `BLOCKED` with details
+
+### 3. Identify Root Cause
+
+Trace the bug to its source:
+- Read the relevant code paths
+- Use grep/search to find related code
+- Identify the exact file(s) and line(s) causing the issue
+- Understand **why** the bug occurs, not just **where**
+
+### 4. Assess Complexity
+
+Determine if this is BUGFIX-appropriate:
+- **< 300 LOC change**: Proceed with BUGFIX
+- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate
+
+Consider:
+- How many files need to change?
+- Does it require new abstractions or refactoring?
+- Are there cascading effects?
+
+## Output
+
+By the end of this phase, you should know:
+1. The exact root cause
+2. Which files need to change
+3. The approximate size of the fix
+4. Whether it's BUGFIX-appropriate
+
+## Signals
+
+When investigation is complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If the bug is too complex for BUGFIX:
+
+```
+<signal>TOO_COMPLEX</signal>
+```
+
+If you're blocked (can't reproduce, missing context, etc.):
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -0,0 +1,61 @@
+# PR Phase Prompt
+
+You are executing the **PR** phase of the BUGFIX protocol.
+
+## Your Goal
+
+Create a pull request, run CMAP review, and address feedback.
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Create the Pull Request
+
+Create a PR that links to the issue:
+
+```bash
+gh pr create --title "Fix #{{issue.number}}: <brief description>" --body "$(cat <<'EOF'
+## Summary
+
+<1-2 sentence description of the bug and fix>
+
+Fixes #{{issue.number}}
+
+## Root Cause
+
+<Brief explanation of why the bug occurred>
+
+## Fix
+
+<Brief explanation of what was changed>
+
+## Test Plan
+
+- [ ] Regression test added
+- [ ] Build passes
+- [ ] All tests pass
+EOF
+)"
+```
+
+### 2. Signal Completion
+
+After the PR is created, signal completion. Porch will run consultation automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
+
+## Signals
+
+When PR is created and reviews are complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you're blocked:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```

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",
@@ -32,6 +43,11 @@
         "commit"
       ],
       "checks": {
+        "regression_test": {
+          "description": "A regression test MUST be added unless explicitly justified. No fix without a test.",
+          "required": true,
+          "skip_requires_justification": true
+        },
         "build": {
           "command": "npm run build",
           "on_fail": "retry",
@@ -105,7 +121,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 +130,7 @@
     }
   },
   "defaults": {
+    "mode": "soft",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],

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

@@ -0,0 +1,52 @@
+# {{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
+
+### 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 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