@cluesmith/codev 1.6.2 → 2.0.0-rc.10

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

package/skeleton/protocols/bugfix/protocol.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "bugfix",
+  "version": "1.0.0",
+  "description": "Lightweight protocol for minor bugfixes using GitHub Issues",
+  "phases": [
+    {
+      "id": "investigate",
+      "name": "Investigate",
+      "description": "Understand the bug and its root cause",
+      "type": "once",
+      "steps": [
+        "read_issue",
+        "reproduce_bug",
+        "identify_root_cause",
+        "assess_complexity"
+      ],
+      "transition": {
+        "on_complete": "fix",
+        "on_too_complex": "escalate"
+      }
+    },
+    {
+      "id": "fix",
+      "name": "Fix",
+      "description": "Implement the bug fix",
+      "type": "once",
+      "steps": [
+        "implement_fix",
+        "add_tests",
+        "verify_fix",
+        "commit"
+      ],
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "pr"
+      }
+    },
+    {
+      "id": "pr",
+      "name": "Create PR",
+      "description": "Create pull request for the fix",
+      "type": "once",
+      "steps": [
+        "create_pr",
+        "link_issue",
+        "request_review"
+      ],
+      "consultation": {
+        "on": "review",
+        "models": ["gemini", "codex"],
+        "type": "impl-review",
+        "parallel": true,
+        "max_rounds": 1
+      },
+      "transition": {
+        "on_complete": "review"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Address review feedback",
+      "type": "once",
+      "steps": [
+        "address_feedback",
+        "update_pr"
+      ],
+      "transition": {
+        "on_complete": "merge"
+      }
+    },
+    {
+      "id": "merge",
+      "name": "Merge",
+      "description": "Merge the fix and close the issue",
+      "type": "once",
+      "steps": [
+        "merge_pr",
+        "verify_main",
+        "close_issue"
+      ],
+      "gate": {
+        "name": "merge-approval",
+        "description": "Architect approves merge",
+        "requires": ["review_complete", "tests_pass"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "TOO_COMPLEX": {
+      "description": "Bug is too complex for BUGFIX, escalate to SPIDER",
+      "transitions_to": "escalate"
+    },
+    "BLOCKED": {
+      "description": "Signal fix is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "consultation": {
+      "enabled": true,
+      "models": ["gemini", "codex"],
+      "parallel": true
+    },
+    "checks": {
+      "build": "npm run build",
+      "test": "npm test"
+    }
+  }
+}