@cluesmith/codev 2.0.0-rc.2 → 2.0.0-rc.4

package/skeleton/protocols/spider/prompts/evaluate.md

@@ -0,0 +1,241 @@
+# EVALUATE Phase Prompt
+
+You are executing the **EVALUATE** phase of the SPIDER protocol.
+
+## Your Goal
+
+Verify the implementation fully satisfies the phase requirements, run mandatory multi-agent consultation, and then commit the completed phase.
+
+## CRITICAL: Multi-Agent Consultation is MANDATORY
+
+**DO NOT COMMIT without consultation approval.** This is a BLOCKING requirement.
+
+The evaluation process is:
+1. Verify implementation and tests
+2. Run multi-agent consultation (GPT-5 Codex + Gemini Pro)
+3. Address any feedback
+4. Get human approval
+5. ONLY THEN commit
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Plan Phase**: {{plan_phase}} (if applicable)
+- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
+- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
+
+## Prerequisites
+
+Before evaluating, verify:
+1. Implementation is complete
+2. Tests are written and passing
+3. Build passes
+4. Lint passes (if configured)
+
+## Process
+
+### 1. Functional Evaluation
+
+Check against the spec's success criteria:
+
+- [ ] All acceptance criteria met?
+- [ ] User scenarios work as expected?
+- [ ] Edge cases handled properly?
+- [ ] Error messages are helpful?
+
+### 2. Non-Functional Evaluation
+
+Assess quality attributes:
+
+- [ ] Performance acceptable?
+- [ ] Security standards maintained?
+- [ ] Code is maintainable?
+- [ ] No unnecessary complexity?
+
+### 3. Spec Compliance Check
+
+Compare implementation to specification:
+
+- [ ] Does exactly what spec says (no more, no less)?
+- [ ] Handles all scenarios mentioned in spec?
+- [ ] Matches the expected behavior described?
+
+### 4. Test Quality Check
+
+Verify test coverage:
+
+- [ ] All new code has tests?
+- [ ] Tests cover happy path AND error cases?
+- [ ] No overmocking (tests use real implementations where possible)?
+- [ ] Tests would catch regressions?
+
+### 5. Deviation Analysis
+
+If implementation differs from plan:
+
+- Document what changed and why
+- Assess impact on other phases
+- Update plan if needed
+
+### 6. MANDATORY: Multi-Agent Consultation
+
+**Before committing, run consultation:**
+
+```bash
+# Run consultations in parallel (REQUIRED)
+consult --model gemini --type impl-review spec {{project_id}} &
+consult --model codex --type impl-review spec {{project_id}} &
+wait
+```
+
+- Review ALL feedback from both models
+- Address any issues raised
+- Document feedback in the phase evaluation notes
+
+**If consultants identify issues:**
+- Return to Implement or Defend as needed
+- Fix the issues
+- Re-run consultation
+- Do NOT commit until consultation passes
+
+### 7. Human Review
+
+After consultation feedback is incorporated:
+- Present evaluation summary for human review
+- Wait for approval to commit
+- If changes requested, address them and re-consult if significant
+
+### 8. Phase Commit (After Approval Only)
+
+**CRITICAL**: Only commit after consultation and human approval.
+
+```bash
+# Stage all changes for this phase - NEVER use git add . or git add -A
+git add <specific-files>
+
+# Commit with proper format
+git commit -m "[Spec {{project_id}}][Phase: {{plan_phase}}] feat: <description>"
+```
+
+Commit message format:
+- `[Spec XXXX][Phase: name] feat:` for new features
+- `[Spec XXXX][Phase: name] fix:` for bug fixes
+- `[Spec XXXX][Phase: name] refactor:` for refactoring
+
+### 9. Update Plan Status
+
+Mark this phase as complete in the plan document.
+
+## Output
+
+- Completed evaluation checklist
+- Phase committed to git
+- Plan updated with phase status
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- After initial evaluation passes (before consultation):
+  ```
+  <signal>EVALUATION_PASSED</signal>
+  ```
+
+- After consultation feedback is incorporated:
+  ```
+  <signal>CONSULTATION_INCORPORATED</signal>
+  ```
+
+- After human approves and commit is complete:
+  ```
+  <signal>EVALUATION_COMPLETE</signal>
+  ```
+
+- If evaluation reveals spec non-compliance:
+  ```
+  <signal>SPEC_VIOLATION:description</signal>
+  ```
+  (Signals return to Implement)
+
+- If tests reveal bugs:
+  ```
+  <signal>IMPLEMENTATION_BUG:description</signal>
+  ```
+  (Signals return to Implement)
+
+- If consultation identifies issues:
+  ```
+  <signal>CONSULTATION_ISSUES:description</signal>
+  ```
+  (Signals return to Implement or Defend)
+
+- If all plan phases are complete:
+  ```
+  <signal>ALL_PHASES_COMPLETE</signal>
+  ```
+  (Signals transition to Review)
+
+## Evaluation Checklist Template
+
+```markdown
+## Phase Evaluation: {{plan_phase}}
+
+### Functional
+- [ ] Acceptance criteria 1: [status]
+- [ ] Acceptance criteria 2: [status]
+- [ ] Edge cases handled: [status]
+
+### Non-Functional
+- [ ] Performance: [acceptable/needs work]
+- [ ] Security: [reviewed/concerns]
+- [ ] Maintainability: [good/needs refactor]
+
+### Tests
+- [ ] Coverage: [X%]
+- [ ] All tests passing: [yes/no]
+- [ ] Overmocking check: [passed/failed]
+
+### Spec Compliance
+- [ ] Matches spec requirements: [yes/no]
+- [ ] Deviations: [none/list them]
+
+### Commit
+- [ ] Changes staged
+- [ ] Commit created: [hash]
+- [ ] Plan updated
+```
+
+## Important Notes
+
+1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
+2. **Be honest** - If something isn't right, fix it before committing
+3. **Don't skip the checklist** - It catches issues before they compound
+4. **Atomic commits** - One commit per phase, not multiple
+5. **Update the plan** - Mark phase status after commit
+6. **Verify the commit** - `git log --oneline -1` should show your commit
+
+## What NOT to Do
+
+- Don't commit without consultation approval (BLOCKING)
+- Don't commit if tests are failing
+- Don't commit if build is broken
+- Don't skip the spec compliance check
+- Don't commit multiple phases together
+- Don't proceed to next phase without committing
+- Don't use `git add .` or `git add -A` (security risk)
+
+## Handling Failures
+
+**If spec compliance fails**:
+Return to Implement, fix the issue, re-run Defend, then Evaluate again.
+
+**If tests fail**:
+Return to Implement to fix bugs, or Defend to fix tests.
+
+**If build fails**:
+Return to Implement to fix build errors.
+
+**If you discover a spec problem**:
+Signal `BLOCKED` and describe the spec issue. The Architect may need to update the spec.

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

@@ -0,0 +1,149 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the SPIDER protocol.
+
+## Your Goal
+
+Write clean, well-structured code that implements the current plan phase.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Plan Phase**: {{plan_phase}} (if applicable)
+- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
+- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
+
+## Consultation Context
+
+**Implementation does NOT require consultation checkpoints** - that happens after Defend.
+
+However, you should be aware:
+- Spec and Plan have already been reviewed by GPT-5 Codex and Gemini Pro
+- After you complete Implement + Defend, your work will be reviewed
+- Implementation must strictly follow the approved spec and plan
+
+## 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
+
+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
+- Test as you go (manual verification is fine here)
+- Document complex logic with comments
+
+### 4. Self-Review
+
+Before signaling completion:
+- Read through all changes
+- Check for obvious bugs
+- Verify code matches the spec requirements
+- Ensure no accidental debug code
+
+### 5. Build Verification
+
+Run build checks using **project-specific commands**:
+
+```bash
+# Check package.json scripts or Makefile for actual commands
+# Common patterns:
+npm run build      # Node.js/TypeScript projects
+npm run typecheck  # TypeScript type checking
+npm run lint       # Linting (ESLint, etc.)
+cargo build        # Rust projects
+go build ./...     # Go projects
+make build         # Projects using Makefiles
+```
+
+**Important**: Don't assume `npm run build` exists. Check `package.json` or equivalent first.
+
+Fix any errors before proceeding.
+
+## Output
+
+- Modified/created source files as specified in the plan phase
+- All build checks passing
+- Code ready for the Defend (testing) phase
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- After implementation is complete and builds pass:
+  ```
+  <signal>PHASE_IMPLEMENTED</signal>
+  ```
+
+- If you encounter a blocker:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```
+
+- If you need spec/plan clarification:
+  ```
+  <signal>NEEDS_CLARIFICATION:specific question</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 must pass** - Don't proceed if build fails
+
+## What NOT to Do
+
+- Don't write tests yet (that's Defend phase)
+- 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 commit yet (that happens after Defend + Evaluate)
+- Don't use `git add .` or `git add -A` when you do commit (security risk)
+
+## Handling Problems
+
+**If the plan is unclear**:
+Signal `NEEDS_CLARIFICATION` 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 fails and you can't fix it**:
+Signal `BLOCKED` with the error message.

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

@@ -0,0 +1,214 @@
+# PLAN Phase Prompt
+
+You are executing the **PLAN** phase of the SPIDER 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/{{project_id}}-{{title}}.md`
+- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
+
+## CRITICAL: Multi-Agent Consultation is MANDATORY
+
+The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
+
+## 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. MANDATORY: First Consultation (After Draft)
+
+After completing the initial plan draft:
+
+```bash
+# Run consultations in parallel (REQUIRED)
+consult --model gemini plan {{project_id}} &
+consult --model codex plan {{project_id}} &
+wait
+```
+
+- Review ALL feedback from both models
+- Update the plan with incorporated feedback
+- Add a **Consultation Log** section documenting:
+  - Key feedback received
+  - Changes made in response
+  - Any feedback intentionally not incorporated (with reasoning)
+
+### 6. Human Review
+
+After consultation feedback is incorporated:
+- Present the plan for human review
+- Wait for approval or change requests
+- If changes requested, make them and proceed to Step 7
+
+### 7. MANDATORY: Second Consultation (After Human Feedback)
+
+After incorporating human feedback:
+
+```bash
+# Run consultations again (REQUIRED)
+consult --model gemini plan {{project_id}} &
+consult --model codex plan {{project_id}} &
+wait
+```
+
+- Update Consultation Log with new feedback
+- Incorporate changes
+- Prepare final plan for approval
+
+## Output
+
+Create the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
+
+Use the plan template from `codev/protocols/spider/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]
+
+## Consultation Log
+
+### First Consultation (After Draft)
+- **Gemini Feedback**: [Summary]
+- **Codex Feedback**: [Summary]
+- **Changes Made**: [List]
+- **Not Incorporated**: [List with reasons]
+
+### Second Consultation (After Human Feedback)
+- **Gemini Feedback**: [Summary]
+- **Codex Feedback**: [Summary]
+- **Changes Made**: [List]
+```
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- After completing the plan draft:
+  ```
+  <signal>PLAN_DRAFTED</signal>
+  ```
+
+- After incorporating consultation feedback:
+  ```
+  <signal>CONSULTATION_INCORPORATED</signal>
+  ```
+
+- After final plan is ready for human approval:
+  ```
+  <signal>PLAN_READY_FOR_APPROVAL</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/{{project_id}}-{{title}}.md
+```
+
+## Important Notes
+
+1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
+2. **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
+6. **Document consultations** - Maintain the Consultation Log section
+
+## What NOT to Do
+
+- Don't skip consultations (they are BLOCKING)
+- 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)