@cluesmith/codev 2.0.6 → 2.0.7

package/skeleton/protocols/protocol-schema.json

@@ -149,7 +149,7 @@
         },
         "type": {
           "type": "string",
-          "description": "Review type (spec-review, plan-review, impl-review, pr-ready)"
+          "description": "Review type (spec, plan, impl, pr, phase, integration)"
         },
         "parallel": {
           "type": "boolean",

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

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+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?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - 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?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `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
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/protocols/spir/consult-types/phase-review.md

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+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?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - 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?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `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
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/protocols/spir/consult-types/pr-review.md

@@ -0,0 +1,72 @@
+# PR Ready Review Prompt
+
+## Context
+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
+
+1. **Completeness**
+   - Are all spec requirements implemented?
+   - Are all plan phases complete?
+   - Is the review document written (`codev/reviews/XXXX-name.md`)?
+   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
+
+2. **Test Status**
+   - Do all tests pass?
+   - Is test coverage adequate for the changes?
+   - Are there any skipped or flaky tests?
+
+3. **Code Cleanliness**
+   - Is there any debug code left in?
+   - Are there any TODO comments that should be resolved?
+   - Are there any `// REVIEW:` comments that weren't addressed?
+   - Is the code properly formatted?
+
+4. **Documentation**
+   - Are inline comments clear where needed?
+   - Is the review document comprehensive?
+   - Are any new APIs documented?
+
+5. **PR Readiness**
+   - Is the branch up to date with main?
+   - Are commits atomic and well-described?
+   - Is the change diff reasonable in size?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+
+PR_SUMMARY: |
+  ## Summary
+  [2-3 sentences describing what this PR does]
+
+  ## Key Changes
+  - [Change 1]
+  - [Change 2]
+
+  ## Test Plan
+  - [How to test]
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to create PR
+- `REQUEST_CHANGES`: Issues to fix before PR creation
+- `COMMENT`: Minor items, can create PR but note feedback
+
+## Notes
+
+- This is the builder's final self-review before hand-off
+- The PR_SUMMARY in your output can be used as the PR description
+- Focus on "is this ready for someone else to review" not "is this perfect"
+- Any issues found here are cheaper to fix than during integration review

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

@@ -11,8 +11,8 @@ Transform the approved specification into an executable implementation plan with
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
-- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
 
 ## Prerequisites
 
@@ -74,7 +74,7 @@ After completing the plan draft, signal completion. Porch will run 3-way consult
 
 ## Output
 
-Create the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
+Create the plan file at `codev/plans/{{artifact_name}}.md`.
 
 Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
@@ -129,7 +129,7 @@ Make commits at these milestones:
 
 **CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
 ```bash
-git add codev/plans/{{project_id}}-{{title}}.md
+git add codev/plans/{{artifact_name}}.md
 ```
 
 ## Important Notes

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

@@ -11,9 +11,9 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
-- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
-- **Review File**: `codev/reviews/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
+- **Review File**: `codev/reviews/{{artifact_name}}.md`
 
 ## Prerequisites
 
@@ -57,7 +57,7 @@ Compare final implementation to original specification:
 
 ### 3. Create Review Document
 
-Create `codev/reviews/{{project_id}}-{{title}}.md`:
+Create `codev/reviews/{{artifact_name}}.md`:
 
 ```markdown
 # Review: {{title}}
@@ -118,7 +118,7 @@ Before PR:
 
 **IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that
 porch consultation reviews the actual PR, and the architect can review a real PR
-when the pr-ready gate fires.
+when the pr gate fires.
 
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
@@ -135,10 +135,10 @@ gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 - Manual testing completed for [Y]
 
 ## Spec
-Link: codev/specs/{{project_id}}-{{title}}.md
+Link: codev/specs/{{artifact_name}}.md
 
 ## Review
-Link: codev/reviews/{{project_id}}-{{title}}.md
+Link: codev/reviews/{{artifact_name}}.md
 EOF
 )"
 ```
@@ -151,7 +151,7 @@ changes, you'll be respawned with their feedback.
 
 ## Output
 
-- Review document at `codev/reviews/{{project_id}}-{{title}}.md`
+- Review document at `codev/reviews/{{artifact_name}}.md`
 - Updated documentation (if needed)
 - Pull request created and ready for review
 

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

@@ -11,7 +11,7 @@ Create a comprehensive specification document that thoroughly explores the probl
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
 
 ## Process
 
@@ -82,12 +82,12 @@ After completing the spec draft, signal completion. Porch will run 3-way consult
 
 ## Output
 
-Create or update the specification file at `codev/specs/{{project_id}}-{{title}}.md`.
+Create or update the specification file at `codev/specs/{{artifact_name}}.md`.
 
 **IMPORTANT**: Keep spec/plan/review filenames in sync:
-- Spec: `codev/specs/{{project_id}}-{{title}}.md`
-- Plan: `codev/plans/{{project_id}}-{{title}}.md`
-- Review: `codev/reviews/{{project_id}}-{{title}}.md`
+- Spec: `codev/specs/{{artifact_name}}.md`
+- Plan: `codev/plans/{{artifact_name}}.md`
+- Review: `codev/reviews/{{artifact_name}}.md`
 
 ## Signals
 
@@ -121,7 +121,7 @@ Make commits at these milestones:
 
 **CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
 ```bash
-git add codev/specs/{{project_id}}-{{title}}.md
+git add codev/specs/{{artifact_name}}.md
 ```
 
 ## Important Notes

package/skeleton/protocols/spir/protocol.json

@@ -17,10 +17,10 @@
       "type": "build_verify",
       "build": {
         "prompt": "specify.md",
-        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+        "artifact": "codev/specs/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "spec-review",
+        "type": "spec",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -39,10 +39,10 @@
       "type": "build_verify",
       "build": {
         "prompt": "plan.md",
-        "artifact": "codev/plans/${PROJECT_ID}-*.md"
+        "artifact": "codev/plans/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "plan-review",
+        "type": "plan",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -52,9 +52,9 @@
         "push": true
       },
       "checks": {
-        "plan_exists": "test -f codev/plans/${PROJECT_ID}-*.md",
-        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_ID}-*.md",
-        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_ID}-*.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
+        "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md",
+        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
       },
       "gate": "plan-approval",
       "next": "implement"
@@ -69,7 +69,7 @@
         "artifact": "src/**/*.{ts,tsx,js,jsx}"
       },
       "verify": {
-        "type": "impl-review",
+        "type": "impl",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -103,10 +103,10 @@
       "type": "build_verify",
       "build": {
         "prompt": "review.md",
-        "artifact": "codev/reviews/${PROJECT_ID}-*.md"
+        "artifact": "codev/reviews/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "pr-ready",
+        "type": "pr",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -126,7 +126,7 @@
           "optional": true
         }
       },
-      "gate": "pr-ready",
+      "gate": "pr",
       "next": null
     }
   ],

package/skeleton/protocols/spir/templates/review.md

@@ -33,7 +33,7 @@ All times [timezone], [date range].
 | — | **GATE: [gate-name]** (human approval required) |
 | HH:MM | Implementation begins |
 | HH:MM | Phase N complete after N iterations |
-| HH:MM | **GATE: pr-ready** |
+| HH:MM | **GATE: pr** |
 
 ### Autonomous Operation
 
@@ -43,7 +43,7 @@ All times [timezone], [date range].
 | Human gate wait | ~Nh Nm | Idle — waiting for approval |
 | Implementation → PR | ~Nh Nm | N phases, N consultation rounds |
 
-**Total wall clock** (first commit to pr-ready): **Xh Ym**
+**Total wall clock** (first commit to pr): **Xh Ym**
 **Total autonomous work time** (excluding gate waits): **~Xh Ym**
 **Context window resets**: [N] (resumed automatically / required manual restart)
 

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

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+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?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - 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?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `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
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

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

@@ -0,0 +1,59 @@
+# Plan Review Prompt
+
+## Context
+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
+
+1. **Spec Coverage**
+   - Does the plan address all requirements in the spec?
+   - Are there spec requirements not covered by any phase?
+   - Are there phases that go beyond the spec scope?
+
+2. **Phase Breakdown**
+   - Are phases appropriately sized (not too large or too small)?
+   - Is the sequence logical (dependencies respected)?
+   - Can each phase be completed and committed independently?
+
+3. **Technical Approach**
+   - Is the implementation approach sound?
+   - Are the right files/modules being modified?
+   - Are there obvious better approaches being missed?
+
+4. **Testability**
+   - Does each phase have clear test criteria?
+   - Will the Defend step (writing tests) be feasible?
+   - Are edge cases from the spec addressable?
+
+5. **Risk Assessment**
+   - Are there potential blockers not addressed?
+   - Are dependencies on other systems identified?
+   - Is the plan realistic given constraints?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Plan is ready for human review
+- `REQUEST_CHANGES`: Significant issues with approach or coverage
+- `COMMENT`: Minor suggestions, plan is workable but could improve
+
+## Notes
+
+- The spec has already been approved - don't re-litigate spec decisions
+- Focus on the quality of the plan as a guide for builders
+- Consider: Would a builder be able to follow this plan successfully?
+- If referencing existing code, verify file paths seem accurate

package/skeleton/protocols/tick/consult-types/pr-review.md

@@ -0,0 +1,72 @@
+# PR Ready Review Prompt
+
+## Context
+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
+
+1. **Completeness**
+   - Are all spec requirements implemented?
+   - Are all plan phases complete?
+   - Is the review document written (`codev/reviews/XXXX-name.md`)?
+   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
+
+2. **Test Status**
+   - Do all tests pass?
+   - Is test coverage adequate for the changes?
+   - Are there any skipped or flaky tests?
+
+3. **Code Cleanliness**
+   - Is there any debug code left in?
+   - Are there any TODO comments that should be resolved?
+   - Are there any `// REVIEW:` comments that weren't addressed?
+   - Is the code properly formatted?
+
+4. **Documentation**
+   - Are inline comments clear where needed?
+   - Is the review document comprehensive?
+   - Are any new APIs documented?
+
+5. **PR Readiness**
+   - Is the branch up to date with main?
+   - Are commits atomic and well-described?
+   - Is the change diff reasonable in size?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+
+PR_SUMMARY: |
+  ## Summary
+  [2-3 sentences describing what this PR does]
+
+  ## Key Changes
+  - [Change 1]
+  - [Change 2]
+
+  ## Test Plan
+  - [How to test]
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to create PR
+- `REQUEST_CHANGES`: Issues to fix before PR creation
+- `COMMENT`: Minor items, can create PR but note feedback
+
+## Notes
+
+- This is the builder's final self-review before hand-off
+- The PR_SUMMARY in your output can be used as the PR description
+- Focus on "is this ready for someone else to review" not "is this perfect"
+- Any issues found here are cheaper to fix than during integration review