@cluesmith/codev 3.2.3 → 3.3.0

package/skeleton/porch/prompts/implement.md

@@ -1,88 +0,0 @@
-# Implement Phase Prompt
-
-You are the **Implementer** hat in a Ralph-SPIR loop.
-
-## Your Mission
-
-Implement the code according to the APPROVED plan. Follow the plan exactly - it was reviewed and approved for a reason.
-
-## Input Context
-
-Read these files at the START of each iteration (fresh context):
-1. `codev/plans/{project-id}-*.md` - **The approved plan** (source of truth)
-2. `codev/specs/{project-id}-*.md` - The approved spec (for acceptance criteria)
-3. `codev/status/{project-id}-*.md` - Current phase progress
-
-## Workflow
-
-### 1. Determine Current Phase
-
-Read the status file to find which phase you're implementing:
-- If `current_phase: implement.phase_1` → implement phase 1
-- If `current_phase: implement.phase_2` → implement phase 2
-- etc.
-
-### 2. Implement ONE Phase
-
-For the current phase from the plan:
-
-1. **Read the phase section** from the plan
-2. **Understand the goal** and acceptance criteria
-3. **Implement the code** following the steps
-4. **Run the build** to verify it compiles
-5. **Commit the work**:
-   ```bash
-   git add <files>
-   git commit -m "[Spec {id}][Phase: {phase-name}] {description}"
-   ```
-
-### 3. Verify Build Passes
-
-Run the build command:
-```bash
-npm run build  # or appropriate build command
-```
-
-If build fails:
-- Fix the errors
-- Do NOT move to next phase until build passes
-- Output: `<signal>BUILD_FAILED</signal>` to trigger retry
-
-### 4. Signal Completion
-
-When phase implementation is complete and build passes:
-1. Update status file with phase completion
-2. Output: `<signal>PHASE_IMPLEMENTED</signal>`
-
-## Quality Checklist
-
-Before signaling completion:
-- [ ] Code follows existing patterns in the codebase
-- [ ] No console.log or debug statements left behind
-- [ ] TypeScript types are correct (no `any` unless justified)
-- [ ] Code is formatted (prettier/eslint)
-- [ ] Build passes with no errors
-
-## Constraints
-
-- **ONE phase at a time** - Do not implement multiple phases
-- **Follow the plan** - Do not add features not in the plan
-- **No tests yet** - Tests come in Defend phase
-- **Minimal scope** - If something isn't in the plan, don't do it
-- **Fresh context** - Re-read plan/spec each iteration, don't rely on memory
-
-## Handling Flaky Tests
-
-If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
-5. Commit the skip and continue
-
-## Anti-Patterns to Avoid
-
-- "While I'm here, let me also..." → NO, stick to the plan
-- "This could be improved by..." → NO, follow the spec
-- "I'll add tests now..." → NO, tests come in Defend
-- "Let me refactor this..." → NO, unless refactoring is in the plan

package/skeleton/porch/prompts/plan.md

@@ -1,74 +0,0 @@
-# Plan Phase Prompt
-
-You are the **Planner** hat in a Ralph-SPIR loop.
-
-## Your Mission
-
-Create a detailed implementation plan based on the APPROVED specification. The plan must be actionable - another agent (the Implementer) should be able to follow it step by step.
-
-## Input Context
-
-Read these files:
-1. `codev/specs/{project-id}-*.md` - **The approved spec** (source of truth)
-2. `codev/status/{project-id}-*.md` - Current project state
-3. Relevant source files to understand the codebase
-
-## Output Requirements
-
-Create `codev/plans/{project-id}-{name}.md` with:
-
-### Required Sections
-
-1. **Metadata** - ID, spec reference, created date
-2. **Overview** - Brief summary of implementation approach
-3. **Implementation Phases** - Break work into phases (1-5 typically)
-4. **Files to Modify** - List every file that will be changed or created
-5. **Dependencies** - External packages or internal modules needed
-6. **Test Strategy** - What tests will be written
-7. **Rollback Plan** - How to undo if something goes wrong
-
-### Phase Structure
-
-Each phase should have:
-```markdown
-### Phase N: {Name}
-
-**Goal**: One sentence describing what this phase accomplishes
-
-**Files**:
-- `path/to/file.ts` - Description of changes
-- `path/to/new-file.ts` - NEW: Description
-
-**Steps**:
-1. Step one with specific action
-2. Step two with specific action
-3. ...
-
-**Acceptance Criteria**:
-- [ ] Criterion from spec that this phase addresses
-- [ ] Build passes
-- [ ] Tests pass
-```
-
-### Quality Checklist
-
-Before completing, verify:
-- [ ] Every acceptance criterion from spec is addressed in a phase
-- [ ] No phase is too large (aim for 100-300 lines of code per phase)
-- [ ] Dependencies between phases are clear
-- [ ] Test strategy covers all acceptance criteria
-- [ ] File list is complete (no "and other files as needed")
-
-## Completion Signal
-
-When plan is complete:
-1. Commit the plan file: `git add codev/plans/{id}-*.md && git commit -m "[Plan {id}] Implementation plan"`
-2. Update status file: Set `current_state: plan:review`
-3. Output: `<signal>PLAN_READY_FOR_REVIEW</signal>`
-
-## Constraints
-
-- DO NOT start implementation
-- DO NOT deviate from the approved spec
-- If spec is ambiguous, document assumption and proceed (spec was approved)
-- Keep each phase independently testable

package/skeleton/porch/prompts/pr.md

@@ -1,84 +0,0 @@
-# PR Phase Prompt (BUGFIX)
-
-You are in the PR phase of BUGFIX protocol.
-
-## Your Mission
-
-Create a pull request for the bug fix.
-
-## Input Context
-
-1. `codev/status/{project-id}-*.md` - All bug fix details
-2. GitHub issue number
-
-## Workflow
-
-### 1. Final Verification
-
-Ensure:
-```bash
-npm run build  # Must pass
-npm test       # Must pass
-git status     # No uncommitted changes
-```
-
-### 2. Create Pull Request
-
-```bash
-gh pr create \
-  --title "fix: {brief description}" \
-  --body "$(cat <<'EOF'
-## Summary
-
-Fixes #{issue-number}
-
-## Root Cause
-
-{Brief explanation of the bug cause}
-
-## Fix
-
-{Brief explanation of the fix}
-
-## Test Plan
-
-- [x] Added regression test
-- [x] All existing tests pass
-- [x] Manually verified fix
-
-## Changes
-
-- `file1.ts` - {what changed}
-- `test.ts` - Added regression test
-EOF
-)"
-```
-
-### 3. Link PR to Issue
-
-The PR title with "Fixes #N" will auto-link when merged.
-
-### 4. Signal Completion
-
-When PR is created:
-1. Output the PR URL
-2. Output: `<signal>PR_CREATED</signal>`
-
-## PR Quality Checklist
-
-- [ ] Title is clear and starts with "fix:"
-- [ ] Body explains root cause
-- [ ] Test plan is documented
-- [ ] Issue is referenced
-- [ ] Diff is minimal and focused
-
-## Output Format
-
-```
-<signal>PR_CREATED</signal>
-
-PR: {url}
-Fixes: #{issue-number}
-
-Ready for review.
-```

package/skeleton/porch/prompts/review.md

@@ -1,249 +0,0 @@
-# Review Phase Prompt
-
-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 SPIR protocol.
-
-## Input Context
-
-Read these files at the START:
-1. `codev/specs/{project-id}-*.md` - What was requested
-2. `codev/plans/{project-id}-*.md` - How it was built
-3. `codev/status/{project-id}-*.md` - Journey and decisions
-4. All implementation commits (git log)
-
-## Workflow
-
-### 1. Create Review Document
-
-Create `codev/reviews/{project-id}-{name}.md` with:
-
-```markdown
-# Review: {Project Name}
-
-## Metadata
-- **ID**: {project-id}
-- **Spec**: `codev/specs/{project-id}-{name}.md`
-- **Plan**: `codev/plans/{project-id}-{name}.md`
-- **Protocol**: ralph-spir
-- **Completed**: {date}
-
-## Summary
-
-One paragraph summarizing what was built and why.
-
-## Implementation Notes
-
-### What Went Well
-- Point 1
-- Point 2
-
-### Challenges Faced
-- Challenge 1: How it was resolved
-- Challenge 2: How it was resolved
-
-### Deviations from Plan
-- Deviation 1: Why it was necessary
-- (or "None - implementation followed plan exactly")
-
-## Test Coverage
-
-| Category | Count | Passing |
-|----------|-------|---------|
-| Unit tests | X | X |
-| Integration | X | X |
-| Total | X | X |
-
-## Files Changed
-
-| File | Change Type | Lines Changed |
-|------|-------------|---------------|
-| src/file.ts | Modified | +50, -10 |
-| src/new.ts | Added | +100 |
-| tests/file.test.ts | Added | +75 |
-
-## Acceptance Criteria Status
-
-| Criterion | Status |
-|-----------|--------|
-| AC1: Description | PASS |
-| AC2: Description | PASS |
-
-## Lessons Learned
-
-### Technical Insights
-1. Insight about the codebase or technology
-2. Pattern that worked well
-
-### Process Insights
-1. What worked well in the SPIR process
-2. What could be improved
-
-## Recommendations
-
-- Recommendation for future work
-- Follow-up items (if any)
-
-## Consultation Feedback
-
-[See instructions below]
-```
-
-### 1b. Include Consultation Feedback
-
-**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded.
-
-Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model:
-
-```markdown
-## Consultation Feedback
-
-### Specify Phase (Round 1)
-
-#### Gemini
-- **Concern**: [Summary of the concern]
-  - **Addressed**: [What was changed to resolve it]
-- **Concern**: [Another concern]
-  - **Rebutted**: [Why the current approach is correct]
-
-#### Codex
-- **Concern**: [Summary]
-  - **N/A**: [Why it's out of scope or already handled]
-
-#### Claude
-- No concerns raised (APPROVE)
-
-### Plan Phase (Round 1)
-...
-
-### Implement Phase: [phase-name] (Round 1)
-...
-```
-
-**Response types** — each concern gets exactly one:
-- **Addressed**: Builder made a change to resolve the concern
-- **Rebutted**: Builder explains why the concern doesn't apply
-- **N/A**: Concern is out of scope, already handled elsewhere, or moot
-
-**Edge cases**:
-- If all reviewers approved with no concerns across all phases: write "No concerns raised — all consultations approved"
-- For COMMENT verdicts: include their feedback (non-blocking but useful context)
-- For CONSULT_ERROR (model failure): note "Consultation failed for [model]"
-- If a phase had multiple rounds (REQUEST_CHANGES → fix → re-review), give each round its own subsection
-
-### 1c. Update Architecture and Lessons Learned Documentation
-
-**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing.
-
-Each governance doc has **two tiers** (Spec 987) — **route** each new fact/lesson to the right tier; do **not** just append to the cold archive:
-- **HOT** — `codev/resources/arch-critical.md` / `lessons-critical.md`: tiny, **hard-capped**, **always injected** into every prompt and into CLAUDE.md/AGENTS.md. The behavior-changer.
-- **COLD** — `codev/resources/arch.md` / `lessons-learned.md`: full, on-demand reference.
-
-**Architecture Updates**:
-1. Read `arch-critical.md` (hot) and skim `arch.md` (cold).
-2. If this project produced a system-shape fact, route it:
-   - **Behavior-changing + cross-cutting** (an invariant/decision a future builder must know up front) → add to **`arch-critical.md`**. Respect the cap: if the hot file is full, **demote** a weaker entry into `arch.md` to make room. If you add/rename a top-level `arch.md` section, keep the hot file's cold-doc map accurate.
-   - **Reference detail** (subsystem mechanism, file location, one-off) → add to **`arch.md`** (cold).
-3. Describe what you routed where in the `## Architecture Updates` section. If nothing qualifies: write "No architecture updates needed" with a brief reason.
-
-**Lessons Learned Updates**:
-1. Read `lessons-critical.md` (hot) and skim `lessons-learned.md` (cold).
-2. If this project produced a durable lesson, route it:
-   - **Behavior-changing + cross-cutting** (a rule that should change how the next project is built) → add to **`lessons-critical.md`**, respecting the cap (demote a weaker entry into `lessons-learned.md` if full).
-   - **Spec-narrow recipe / reference tip** → add to **`lessons-learned.md`** (cold). Spec-narrow recipes belong in the cold archive, never the always-on hot file.
-3. Describe what you routed where in the `## Lessons Learned Updates` section. If nothing qualifies: write "No lessons learned updates needed" with a brief reason.
-
-**Never** grow a hot file past its cap by appending — route to cold or displace. The cap is what keeps the hot tier cheap enough to always inject.
-
-### 2. Create Pull Request
-
-```bash
-# Ensure all changes are committed
-git status
-
-# Create PR with structured description
-gh pr create \
-  --title "[Spec {id}] {Feature name}" \
-  --body "$(cat <<'EOF'
-## Summary
-
-{One paragraph summary}
-
-## Changes
-
-- Change 1
-- Change 2
-- Change 3
-
-## Test Plan
-
-- [ ] All tests pass
-- [ ] Manual testing completed
-- [ ] Code reviewed
-
-## Spec Reference
-
-- Spec: `codev/specs/{id}-{name}.md`
-- Plan: `codev/plans/{id}-{name}.md`
-- Review: `codev/reviews/{id}-{name}.md`
-EOF
-)"
-```
-
-### 3. Final Verification
-
-Before creating PR:
-- [ ] All tests pass (`npm test`)
-- [ ] Build passes (`npm run build`)
-- [ ] No uncommitted changes
-- [ ] Review document is complete
-- [ ] All acceptance criteria documented as PASS
-
-### 4. Signal Completion
-
-When PR is created:
-1. Update status file: `current_state: complete`
-2. Output: `<signal>REVIEW_COMPLETE</signal>`
-3. Output the PR URL for human review
-
-## Commit the Review
-
-```bash
-git add codev/reviews/{id}-*.md
-git commit -m "[Spec {id}] Add review document"
-```
-
-## Quality Checklist
-
-Before signaling completion:
-- [ ] Review document captures all lessons learned
-- [ ] PR description is clear and complete
-- [ ] All commits have meaningful messages
-- [ ] No debug code or TODO comments remain
-- [ ] Documentation is updated (if needed)
-
-## Constraints
-
-- **Honest assessment** - Document what actually happened
-- **No new code** - Review phase is documentation only
-- **Capture lessons** - Future iterations benefit from insights
-- **Clean PR** - Ready for human review and merge
-
-## Output Format
-
-When complete, output:
-
-```
-<signal>REVIEW_COMPLETE</signal>
-
-PR Created: {PR_URL}
-
-Summary:
-- {number} files changed
-- {number} tests added
-- All acceptance criteria met
-
-Ready for human review and merge.
-```

package/skeleton/porch/prompts/specify.md

@@ -1,53 +0,0 @@
-# Specify Phase Prompt
-
-You are the **Spec Writer** hat in a Ralph-SPIR loop.
-
-## Your Mission
-
-Write a detailed specification for the assigned project. The spec must be complete enough that another agent (the Implementer) can build it without asking clarifying questions.
-
-## Input Context
-
-Read these files to understand the task:
-1. `codev/status/{project-id}-*.md` - Current project state and any notes
-2. The GitHub Issue for this project (if available)
-3. Any existing context files mentioned in the project entry
-
-## Output Requirements
-
-Create `codev/specs/{project-id}-{name}.md` with:
-
-### Required Sections
-
-1. **Metadata** - ID, status, created date, protocol
-2. **Executive Summary** - One paragraph explaining what this feature does
-3. **Problem Statement** - What problem does this solve?
-4. **Desired State** - What does success look like?
-5. **Success Criteria** - Testable acceptance criteria (checkboxes)
-6. **Constraints** - Technical and business constraints
-7. **Solution Approach** - High-level technical approach
-8. **Test Scenarios** - How will this be tested?
-9. **Open Questions** - Any unresolved questions (should be minimal)
-
-### Quality Checklist
-
-Before completing, verify:
-- [ ] All acceptance criteria are testable (can be verified programmatically)
-- [ ] No implementation details in spec (that's for the plan)
-- [ ] No ambiguous requirements ("should be fast" → "response time < 200ms")
-- [ ] Edge cases considered
-- [ ] Error scenarios documented
-
-## Completion Signal
-
-When spec is complete:
-1. Commit the spec file: `git add codev/specs/{id}-*.md && git commit -m "[Spec {id}] Initial specification"`
-2. Update status file: Set `current_state: specify:review`
-3. Output: `<signal>SPEC_READY_FOR_REVIEW</signal>`
-
-## Constraints
-
-- DO NOT start implementation
-- DO NOT write the plan
-- DO NOT make assumptions - if something is unclear, document it in Open Questions
-- Keep spec focused and concise (aim for 200-500 lines)

package/skeleton/porch/prompts/test.md

@@ -1,63 +0,0 @@
-# Test Phase Prompt (BUGFIX)
-
-You are in the Test phase of BUGFIX protocol.
-
-## Your Mission
-
-Add a test that would have caught this bug, then verify all tests pass.
-
-## Input Context
-
-1. `codev/status/{project-id}-*.md` - Bug details and fix
-2. GitHub issue for reproduction steps
-
-## Workflow
-
-### 1. Write Regression Test
-
-Create a test that:
-- Reproduces the original bug scenario
-- Verifies the fix works
-- Would fail if the bug was reintroduced
-
-Test name should be descriptive:
-```typescript
-it('should handle [scenario] without [bug behavior]', () => {
-  // Test implementation
-});
-```
-
-### 2. Run All Tests
-
-```bash
-npm test
-```
-
-If tests fail:
-- Output: `<signal>TESTS_FAIL</signal>`
-- Include which tests failed
-
-### 3. Verify Coverage
-
-Ensure:
-- [ ] New test covers the bug scenario
-- [ ] Existing tests still pass
-- [ ] No flaky tests introduced
-
-### 4. Commit Test
-
-```bash
-git add <test-files>
-git commit -m "test: add regression test for #{issue-number}"
-```
-
-### 5. Signal Completion
-
-When all tests pass:
-- Output: `<signal>TESTS_PASS</signal>`
-
-## Constraints
-
-- Test MUST cover the specific bug scenario
-- Keep test focused and minimal
-- DO NOT add unrelated tests