@cluesmith/codev 1.6.1 → 2.0.0-rc.1

package/skeleton/porch/prompts/fix.md

@@ -0,0 +1,59 @@
+# Fix Phase Prompt (BUGFIX)
+
+You are in the Fix phase of BUGFIX protocol.
+
+## Your Mission
+
+Apply the fix for the diagnosed bug. Keep changes minimal and focused.
+
+## Input Context
+
+1. `codev/status/{project-id}-*.md` - Diagnosis results
+2. GitHub issue for context
+
+## Workflow
+
+### 1. Review Diagnosis
+
+From status file, confirm:
+- Root cause is identified
+- Affected files are listed
+- Proposed fix is documented
+
+### 2. Implement Fix
+
+Apply the minimal fix:
+1. Change ONLY what's necessary
+2. Follow existing code patterns
+3. Add comments explaining non-obvious changes
+
+### 3. Verify Fix Compiles
+
+```bash
+npm run build
+```
+
+If build fails:
+- Fix build errors
+- Output: `<signal>FIX_FAILED</signal>` if can't resolve
+
+### 4. Commit Fix
+
+```bash
+git add <files>
+git commit -m "fix: {brief description}
+
+Fixes #{issue-number}"
+```
+
+### 5. Signal Completion
+
+When fix is applied and builds:
+- Output: `<signal>FIX_APPLIED</signal>`
+
+## Constraints
+
+- **Minimal changes only** - fix the bug, nothing else
+- DO NOT refactor surrounding code
+- DO NOT add unrelated improvements
+- Keep the diff small and focused

package/skeleton/porch/prompts/implement.md

@@ -0,0 +1,79 @@
+# Implement Phase Prompt
+
+You are the **Implementer** hat in a Ralph-SPIDER 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
+
+## 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

@@ -0,0 +1,74 @@
+# Plan Phase Prompt
+
+You are the **Planner** hat in a Ralph-SPIDER 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

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

@@ -0,0 +1,179 @@
+# Review Phase Prompt
+
+You are the **Reviewer** hat in a Ralph-SPIDER loop.
+
+## Your Mission
+
+Create the final deliverables: PR and review document. This is the capstone of the SPIDER 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-spider
+- **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 SPIDER process
+2. What could be improved
+
+## Recommendations
+
+- Recommendation for future work
+- Follow-up items (if any)
+```
+
+### 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

@@ -0,0 +1,53 @@
+# Specify Phase Prompt
+
+You are the **Spec Writer** hat in a Ralph-SPIDER 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. `codev/projectlist.md` - Project entry with initial description
+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

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

package/skeleton/porch/prompts/understand.md

@@ -0,0 +1,61 @@
+# Understand Phase Prompt (TICK)
+
+You are working in a TICK protocol - fast autonomous implementation for amendments.
+
+## Your Mission
+
+Understand the existing spec and what amendment is being requested. TICK is for small changes to existing, integrated features.
+
+## Input Context
+
+Read these files:
+1. `codev/specs/{project-id}-*.md` - The existing spec (being amended)
+2. `codev/plans/{project-id}-*.md` - The existing plan
+3. `codev/status/{project-id}-*.md` - Current state and amendment description
+
+## Workflow
+
+### 1. Identify the Amendment
+
+From the status file, understand:
+- What change is being requested?
+- What's the scope? (Should be < 300 LOC)
+- What existing code will be affected?
+
+### 2. Verify TICK is Appropriate
+
+TICK is appropriate when:
+- [ ] Feature already has an integrated spec
+- [ ] Change is small (< 300 LOC)
+- [ ] Requirements are clear
+- [ ] No architectural changes needed
+
+If NOT appropriate, signal: `<signal>NEEDS_SPIDER</signal>`
+
+### 3. Document Understanding
+
+Update status file with:
+```markdown
+## Amendment Understanding
+
+**Existing Spec**: {spec-id}
+**Amendment Request**: {description}
+**Scope**: {estimated LOC}
+**Files to Change**:
+- file1.ts
+- file2.ts
+
+**Approach**: {brief description of how to implement}
+```
+
+### 4. Signal Completion
+
+When understanding is complete:
+1. Update status file
+2. Output: `<signal>UNDERSTOOD</signal>`
+
+## Constraints
+
+- DO NOT start implementing
+- DO NOT create new spec files (amend existing)
+- Keep scope small - if > 300 LOC, recommend SPIDER instead

package/skeleton/porch/prompts/verify.md

@@ -0,0 +1,58 @@
+# Verify Phase Prompt (TICK)
+
+You are in the Verify phase of TICK protocol.
+
+## Your Mission
+
+Verify that the amendment implementation is complete and correct. Run tests and build to ensure nothing is broken.
+
+## Input Context
+
+Read these files:
+1. `codev/specs/{project-id}-*.md` - Spec with amendment
+2. `codev/status/{project-id}-*.md` - Implementation notes
+
+## Workflow
+
+### 1. Run Build
+
+```bash
+npm run build
+```
+
+If build fails:
+- Output: `<signal>VERIFICATION_FAILED</signal>`
+- Include error details in output
+
+### 2. Run Tests
+
+```bash
+npm test
+```
+
+If tests fail:
+- Output: `<signal>VERIFICATION_FAILED</signal>`
+- Include which tests failed
+
+### 3. Quick Manual Check
+
+Verify:
+- [ ] Amendment matches the request
+- [ ] No unintended side effects
+- [ ] Code follows project conventions
+
+### 4. Signal Completion
+
+When all checks pass:
+1. Update status file with verification results
+2. Output: `<signal>VERIFIED</signal>`
+
+## Backpressure
+
+Both build AND tests must pass before VERIFIED can be signaled. This is non-negotiable.
+
+## Constraints
+
+- DO NOT add new features
+- DO NOT refactor unrelated code
+- Keep verification focused on the amendment