@cluesmith/codev 2.0.11 → 2.0.13

package/skeleton/protocols/aspir/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/aspir/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/aspir/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/aspir/consult-types/spec-review.md

@@ -0,0 +1,55 @@
+# Specification Review Prompt
+
+## Context
+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
+
+1. **Completeness**
+   - Are all requirements clearly stated?
+   - Are success criteria defined?
+   - Are edge cases considered?
+   - Is scope well-bounded (not too broad or vague)?
+
+2. **Correctness**
+   - Do requirements make sense technically?
+   - Are there contradictions?
+   - Is the problem statement accurate?
+
+3. **Feasibility**
+   - Can this be implemented with available tools/constraints?
+   - Are there obvious technical blockers?
+   - Is the scope realistic for a single spec?
+
+4. **Clarity**
+   - Would a builder understand what to build?
+   - Are acceptance criteria testable?
+   - Is terminology consistent?
+
+## 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`: Spec is ready for human review
+- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but consider feedback
+
+## Notes
+
+- You are NOT reviewing code - you are reviewing the specification document
+- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review)
+- Be constructive - identify issues AND suggest solutions
+- If the spec references other specs, note if context seems missing

package/skeleton/protocols/aspir/prompts/implement.md

@@ -0,0 +1,215 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the SPIR protocol.
+
+## Your Goal
+
+Write clean, well-structured code AND tests that implement the current plan phase.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}}
+
+## ⚠️ SCOPE RESTRICTION — READ THIS FIRST
+
+**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).**
+
+- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations.
+- **DO NOT** read the full plan file and implement everything you see.
+- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope.
+- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires.
+
+## What Happens After You Finish
+
+When you signal `PHASE_COMPLETE`, porch will:
+1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation
+2. Check that tests exist and pass
+3. If reviewers request changes, you'll be respawned with their feedback
+4. Once approved, porch commits and moves to the next plan phase
+
+## Spec Compliance (CRITICAL)
+
+**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
+
+### Trust Hierarchy
+
+```
+SPEC (source of truth)
+  ↓
+PLAN (implementation guide derived from spec)
+  ↓
+EXISTING CODE (NOT TRUSTED - must be validated against spec)
+```
+
+**Never trust existing code over the spec.** Previous implementations may have drifted.
+
+### Pre-Implementation Sanity Check (PISC)
+
+**Before writing ANY code:**
+
+1. ✅ "Have I read the spec in the last 30 minutes?"
+2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?"
+3. ✅ "Does my approach match the spec's Technical Implementation section?"
+4. ✅ "If the spec has code examples, am I following them?"
+5. ✅ "Does the existing code I'm building on actually match the spec?"
+
+**If ANY answer is "no" or "unsure" → STOP and re-read the spec.**
+
+### Avoiding "Fixing Mode"
+
+A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to:
+- Cargo-culting patterns that may be wrong
+- Building on broken foundations
+- Implementing something different from the spec
+
+**When you catch yourself "fixing" code:**
+1. STOP
+2. Ask: "What does the spec say about this?"
+3. Re-read the spec's Traps to Avoid section
+4. Verify existing code matches the spec before building on it
+
+## Prerequisites
+
+Before implementing, verify:
+1. Previous phase (if any) is committed to git
+2. You've read the plan phase you're implementing
+3. You understand the success criteria for this phase
+4. Dependencies from earlier phases are available
+
+## Process
+
+### 1. Review the Plan Phase
+
+Read the current phase in the plan:
+- What is the objective?
+- What files need to be created/modified?
+- What are the success criteria?
+- What dependencies exist?
+
+### 2. Set Up
+
+- Verify you're on the correct branch
+- Check that previous phase is committed: `git log --oneline -5`
+- Ensure build passes before starting: `npm run build` (or equivalent)
+
+### 3. Implement the Code
+
+Write the code following these principles:
+
+**Code Quality Standards**:
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code
+- No debug prints in final code
+- Explicit error handling
+- Follow project style guide
+
+**Implementation Approach**:
+- Work on one file at a time
+- Make small, incremental changes
+- Document complex logic with comments
+
+### 4. Write Tests
+
+**Tests are required.** For each piece of functionality you implement:
+
+- Write unit tests for core logic
+- Write integration tests if the phase involves multiple components
+- Test error cases and edge conditions
+- Ensure tests are deterministic (no flaky tests)
+
+**Test file locations** (follow project conventions):
+- `tests/` or `__tests__/` directories
+- `*.test.ts` or `*.spec.ts` naming
+
+### 5. Verify Everything Works
+
+Run both build and tests:
+
+```bash
+npm run build      # Must pass
+npm test           # Must pass
+```
+
+**Important**: Don't assume these commands exist. Check `package.json` first.
+
+Fix any errors before signaling completion.
+
+### 6. Self-Review
+
+Before signaling completion:
+- Read through all code changes
+- Read through all test changes
+- Verify code matches the spec requirements
+- Ensure no accidental debug code
+- Check test coverage is adequate
+
+## Output
+
+When complete, you should have:
+- Modified/created source files as specified in the plan phase
+- Tests covering the new functionality
+- All build checks passing
+- All tests passing
+
+## Signals
+
+When implementation AND tests are complete and passing:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you encounter a blocker:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```
+
+If you need spec/plan clarification:
+
+```
+<signal type=AWAITING_INPUT>
+Your specific questions here
+</signal>
+```
+
+## Important Notes
+
+1. **Follow the plan** - Implement what's specified, not more
+2. **Don't over-engineer** - Simplest solution that works
+3. **Don't skip error handling** - But don't go overboard either
+4. **Keep changes focused** - Only touch files in this phase
+5. **Build AND tests must pass** - Don't signal complete until both pass
+6. **Write tests** - Every implementation phase needs tests
+
+## What NOT to Do
+
+- Don't modify files outside this phase's scope
+- Don't add features not in the spec
+- Don't leave TODO comments for later (fix now or note as blocker)
+- Don't skip writing tests
+- Don't use `git add .` or `git add -A` when you commit (security risk)
+
+## Handling Problems
+
+**If the plan is unclear**:
+Signal `AWAITING_INPUT` with your specific question.
+
+**If you discover the spec is wrong**:
+Signal `BLOCKED` and explain the issue. The Architect may need to update the spec.
+
+**If a dependency is missing**:
+Signal `BLOCKED` with details about what's missing.
+
+**If build or tests fail and you can't fix it**:
+Signal `BLOCKED` with the error message.
+
+**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use workarounds to avoid the failure
+3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`)
+4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up
+5. Commit the skip and continue with your work

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

@@ -0,0 +1,150 @@
+# PLAN Phase Prompt
+
+You are executing the **PLAN** phase of the SPIR protocol.
+
+## Your Goal
+
+Transform the approved specification into an executable implementation plan with clear phases.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
+
+## Prerequisites
+
+Before planning, verify:
+1. The specification exists and has been approved
+2. You've read and understood the entire spec
+3. Success criteria are clear and measurable
+
+## Process
+
+### 1. Analyze the Specification
+
+Read the spec thoroughly. Identify:
+- All functional requirements
+- Non-functional requirements
+- Dependencies and constraints
+- Success criteria to validate against
+
+### 2. Identify Implementation Phases
+
+Break the work into logical phases. Each phase should be:
+- **Self-contained** - A complete unit of functionality
+- **Independently testable** - Can be verified on its own
+- **Valuable** - Delivers observable progress
+- **Committable** - Can be a single atomic commit
+
+Good phase examples:
+- "Database Schema" - Creates all tables/migrations
+- "Core API Endpoints" - Implements main REST routes
+- "Authentication Flow" - Handles login/logout/session
+
+Bad phase examples:
+- "Setup" - Too vague
+- "Part 1" - Not descriptive
+- "Everything" - Not broken down
+
+### 3. Define Each Phase
+
+For each phase, document:
+- **Objective** - Single clear goal
+- **Files to modify/create** - Specific paths
+- **Dependencies** - Which phases must complete first
+- **Success criteria** - How to know it's done
+- **Test approach** - What tests will verify it
+
+### 4. Order Phases by Dependencies
+
+Arrange phases so dependencies are satisfied:
+```
+Phase 1: Database Schema (no dependencies)
+Phase 2: Data Models (depends on Phase 1)
+Phase 3: API Endpoints (depends on Phase 2)
+Phase 4: Frontend Integration (depends on Phase 3)
+```
+
+### 5. Finalize
+
+After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
+
+## Output
+
+Create the plan file at `codev/plans/{{artifact_name}}.md`.
+
+Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
+
+### Plan Structure
+
+```markdown
+# Implementation Plan: {{title}}
+
+## Overview
+Brief summary of what will be implemented.
+
+## Phases
+
+### Phase 1: [Name]
+- **Objective**: [Single clear goal]
+- **Files**: [List of files to create/modify]
+- **Dependencies**: None
+- **Success Criteria**: [How to verify completion]
+- **Tests**: [What tests will be written]
+
+### Phase 2: [Name]
+- **Objective**: [Single clear goal]
+- **Files**: [List of files]
+- **Dependencies**: Phase 1
+- **Success Criteria**: [Verification method]
+- **Tests**: [Test approach]
+
+[Continue for all phases...]
+
+## Risk Assessment
+- [Risk 1]: [Mitigation]
+- [Risk 2]: [Mitigation]
+
+```
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- After completing the plan draft:
+  ```
+  <signal>PLAN_DRAFTED</signal>
+  ```
+
+## Commit Cadence
+
+Make commits at these milestones:
+1. `[Spec {{project_id}}] Initial implementation plan`
+2. `[Spec {{project_id}}] Plan with multi-agent review`
+3. `[Spec {{project_id}}] Plan with user feedback`
+4. `[Spec {{project_id}}] Final approved plan`
+
+**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
+```bash
+git add codev/plans/{{artifact_name}}.md
+```
+
+## Important Notes
+
+1. **No time estimates** - Don't include hours/days/weeks
+3. **Be specific about files** - Exact paths, not "the config file"
+4. **Keep phases small** - 1-3 files per phase is ideal
+5. **Document dependencies clearly** - Prevents blocked work
+
+## What NOT to Do
+
+- Don't run `consult` commands yourself (porch handles consultations)
+- Don't write code (that's for Implement phase)
+- Don't estimate time (meaningless in AI development)
+- Don't create phases that can't be independently tested
+- Don't skip dependency analysis
+- Don't make phases too large (if >5 files, split it)
+- Don't use `git add .` or `git add -A` (security risk)