@cluesmith/codev 2.0.0-rc.8 → 2.0.0

package/skeleton/consult-types/impl-review.md

@@ -1,38 +1,38 @@
 # Implementation Review Prompt
 
 ## Context
-You are reviewing implementation work at Stage 4 (IMPLEMENTING) of the workflow. A builder has completed a phase (Implement + Defend) and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+
+## CRITICAL: Verify Before Flagging
+
+Before requesting changes for missing configuration, incorrect patterns, or framework issues:
+1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
+2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
+3. **Do not assume** your training data reflects the version in use — verify against project files
+4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
 
 ## Focus Areas
 
 1. **Spec Adherence**
    - Does the implementation fulfill the spec requirements for this phase?
    - Are acceptance criteria met?
-   - Are there deviations from the spec that need explanation?
 
 2. **Code Quality**
    - Is the code readable and maintainable?
    - Are there obvious bugs or issues?
    - Are error cases handled appropriately?
-   - Does it follow project conventions?
 
 3. **Test Coverage**
    - Are the tests adequate for this phase?
    - Do tests cover the main paths AND edge cases?
-   - Are tests testing the right things (behavior, not implementation)?
-   - Would the tests catch regressions?
 
 4. **Plan Alignment**
    - Does the implementation follow the plan?
-   - Are there deviations that make sense?
    - Are there plan items skipped or partially completed?
 
 5. **UX Verification** (if spec has UX requirements)
    - Does the actual user experience match what the spec describes?
    - If spec says "async" or "non-blocking", is it actually async?
-   - If spec says "immediate response", does user get one quickly?
-   - Do any flow diagrams in the spec match the actual behavior?
-   - **CRITICAL:** A synchronous implementation that passes tests can completely fail UX requirements
 
 ## Verdict Format
 
@@ -55,6 +55,15 @@ KEY_ISSUES:
 - `REQUEST_CHANGES`: Issues that must be fixed before proceeding
 - `COMMENT`: Minor suggestions, can proceed but note feedback
 
+## Scoping (Multi-Phase Plans)
+
+When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
+- **ONLY review work belonging to the current plan phase**
+- The query will specify which phase you are reviewing
+- Do NOT request changes for functionality scheduled in later phases
+- Do NOT flag missing features that are out of scope for this phase
+- If unsure whether something belongs to this phase, check the plan file
+
 ## Notes
 
 - This is a phase-level review, not the final PR review

package/skeleton/consult-types/integration-review.md

@@ -1,7 +1,7 @@
 # Integration Review Prompt
 
 ## Context
-You are performing an integration review at Stage 6 (COMMITTED) of the workflow. The builder has created a PR and you are evaluating whether this change fits well into the broader system. This is the architect's review, focusing on how the change integrates rather than whether it works.
+You are performing an integration review of a pull request. The builder has created a PR and you are evaluating whether this change fits well into the broader system. This is the architect's review, focusing on how the change integrates rather than whether it works.
 
 ## Focus Areas
 

package/skeleton/consult-types/plan-review.md

@@ -1,7 +1,7 @@
 # Plan Review Prompt
 
 ## Context
-You are reviewing an implementation plan at Stage 2 (SPECIFIED) of the workflow. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
+You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
 
 ## Focus Areas
 

package/skeleton/consult-types/pr-ready.md

@@ -1,7 +1,7 @@
 # PR Ready Review Prompt
 
 ## Context
-You are performing a final self-check at Stage 5 (IMPLEMENTED) of the workflow. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
+You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
 
 ## Focus Areas
 

package/skeleton/consult-types/spec-review.md

@@ -1,7 +1,7 @@
 # Specification Review Prompt
 
 ## Context
-You are reviewing a feature specification at Stage 1 (CONCEIVED) of the workflow. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
+You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
 
 ## Focus Areas
 

package/skeleton/porch/prompts/defend.md

@@ -1,6 +1,6 @@
 # Defend Phase Prompt
 
-You are the **Tester** hat in a Ralph-SPIDER loop.
+You are the **Tester** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/evaluate.md

@@ -1,6 +1,6 @@
 # Evaluate Phase Prompt
 
-You are the **Verifier** hat in a Ralph-SPIDER loop.
+You are the **Verifier** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 
@@ -66,7 +66,7 @@ Create or update evaluation notes in the status file:
 ```markdown
 ## Evaluation Report
 
-**Evaluator**: Ralph-SPIDER Verifier
+**Evaluator**: Ralph-SPIR Verifier
 **Date**: {date}
 **Phase**: {phase-name}
 

package/skeleton/porch/prompts/implement.md

@@ -1,6 +1,6 @@
 # Implement Phase Prompt
 
-You are the **Implementer** hat in a Ralph-SPIDER loop.
+You are the **Implementer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/plan.md

@@ -1,6 +1,6 @@
 # Plan Phase Prompt
 
-You are the **Planner** hat in a Ralph-SPIDER loop.
+You are the **Planner** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/review.md

@@ -1,10 +1,10 @@
 # Review Phase Prompt
 
-You are the **Reviewer** hat in a Ralph-SPIDER loop.
+You are the **Reviewer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 
-Create the final deliverables: PR and review document. This is the capstone of the SPIDER protocol.
+Create the final deliverables: PR and review document. This is the capstone of the SPIR protocol.
 
 ## Input Context
 
@@ -27,7 +27,7 @@ Create `codev/reviews/{project-id}-{name}.md` with:
 - **ID**: {project-id}
 - **Spec**: `codev/specs/{project-id}-{name}.md`
 - **Plan**: `codev/plans/{project-id}-{name}.md`
-- **Protocol**: ralph-spider
+- **Protocol**: ralph-spir
 - **Completed**: {date}
 
 ## Summary
@@ -78,7 +78,7 @@ One paragraph summarizing what was built and why.
 2. Pattern that worked well
 
 ### Process Insights
-1. What worked well in the SPIDER process
+1. What worked well in the SPIR process
 2. What could be improved
 
 ## Recommendations

package/skeleton/porch/prompts/specify.md

@@ -1,6 +1,6 @@
 # Specify Phase Prompt
 
-You are the **Spec Writer** hat in a Ralph-SPIDER loop.
+You are the **Spec Writer** hat in a Ralph-SPIR loop.
 
 ## Your Mission
 

package/skeleton/porch/prompts/understand.md

@@ -30,7 +30,7 @@ TICK is appropriate when:
 - [ ] Requirements are clear
 - [ ] No architectural changes needed
 
-If NOT appropriate, signal: `<signal>NEEDS_SPIDER</signal>`
+If NOT appropriate, signal: `<signal>NEEDS_SPIR</signal>`
 
 ### 3. Document Understanding
 
@@ -58,4 +58,4 @@ When understanding is complete:
 
 - DO NOT start implementing
 - DO NOT create new spec files (amend existing)
-- Keep scope small - if > 300 LOC, recommend SPIDER instead
+- Keep scope small - if > 300 LOC, recommend SPIR instead

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,60 @@
+# {{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 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 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. Create PR with "Fixes #{{issue.number}}" in body
+6. Notify architect via `af send architect "PR #N ready for review (fixes #{{issue.number}})"`
+
+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."
+```
+
+## Notifications
+Always use `af send architect "..."` to notify the architect at key moments:
+- **PR ready**: `af send architect "PR #N ready for review (fixes #{{issue.number}})"`
+- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."`
+- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"`
+{{/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`