@cluesmith/codev 2.0.0-rc.1 → 2.0.0-rc.11

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

@@ -0,0 +1,217 @@
+# REVIEW Phase Prompt
+
+You are executing the **REVIEW** phase of the SPIDER protocol.
+
+## Your Goal
+
+Perform a comprehensive review, document lessons learned, run final consultation, and prepare for PR submission.
+
+## CRITICAL: Final Consultation Before PR
+
+The SPIDER protocol **requires** a final consultation with GPT-5 Codex AND Gemini Pro before submitting the PR. This ensures the complete implementation is reviewed.
+
+## 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`
+- **Review File**: `codev/reviews/{{project_id}}-{{title}}.md`
+
+## Prerequisites
+
+Before review, verify:
+1. All implementation phases are committed
+2. All tests are passing
+3. Build is passing
+4. Spec compliance verified for all phases
+
+Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"`
+
+## Process
+
+### 1. Comprehensive Review
+
+Review the entire implementation:
+
+**Code Quality**:
+- Is the code readable and maintainable?
+- Are there any code smells?
+- Is error handling consistent?
+- Are there any security concerns?
+
+**Architecture**:
+- Does the implementation fit well with existing code?
+- Are there any architectural concerns?
+- Is the design scalable if needed?
+
+**Documentation**:
+- Is code adequately commented where needed?
+- Are public APIs documented?
+- Is README updated if needed?
+
+### 2. Spec Comparison
+
+Compare final implementation to original specification:
+
+- What was delivered vs what was specified?
+- Any deviations? Document why.
+- All success criteria met?
+
+### 3. Create Review Document
+
+Create `codev/reviews/{{project_id}}-{{title}}.md`:
+
+```markdown
+# Review: {{title}}
+
+## Summary
+Brief description of what was implemented.
+
+## Spec Compliance
+- [x] Requirement 1: Implemented as specified
+- [x] Requirement 2: Implemented with deviation (see below)
+- [x] Requirement 3: Implemented as specified
+
+## Deviations from Plan
+- **Phase X**: [What changed and why]
+
+## Lessons Learned
+
+### What Went Well
+- [Positive observation 1]
+- [Positive observation 2]
+
+### Challenges Encountered
+- [Challenge 1]: [How it was resolved]
+- [Challenge 2]: [How it was resolved]
+
+### What Would Be Done Differently
+- [Insight 1]
+- [Insight 2]
+
+### Methodology Improvements
+- [Suggested improvement to SPIDER protocol]
+- [Suggested improvement to tooling]
+
+## Technical Debt
+- [Any shortcuts taken that should be addressed later]
+
+## Follow-up Items
+- [Any items identified for future work]
+```
+
+### 4. Update Documentation
+
+If needed, update:
+- README.md (new features, changed behavior)
+- API documentation
+- Architecture documentation (`codev/resources/arch.md`)
+
+### 5. Final Verification
+
+Before PR:
+- [ ] All tests pass (use project-specific test command)
+- [ ] Build passes (use project-specific build command)
+- [ ] Lint passes (if configured)
+- [ ] No uncommitted changes: `git status`
+- [ ] Review document complete
+
+### 6. MANDATORY: Final Consultation (PR-Ready Review)
+
+**Before creating the PR, run final consultation:**
+
+```bash
+# Run consultations in parallel (REQUIRED)
+consult --model gemini --type pr-ready spec {{project_id}} &
+consult --model codex --type pr-ready spec {{project_id}} &
+wait
+```
+
+- Review ALL feedback from both models
+- Address any final issues identified
+- This is the last chance to catch problems before PR
+
+### 7. Create Pull Request
+
+Prepare PR with:
+
+**Title**: `[Spec {{project_id}}] {{title}}`
+
+**Body**:
+```markdown
+## Summary
+[Brief description of the implementation]
+
+## Changes
+- [Change 1]
+- [Change 2]
+
+## Testing
+- All unit tests passing
+- Integration tests added for [X]
+- Manual testing completed for [Y]
+
+## Spec
+Link: codev/specs/{{project_id}}-{{title}}.md
+
+## Review
+Link: codev/reviews/{{project_id}}-{{title}}.md
+```
+
+## Output
+
+- Review document at `codev/reviews/{{project_id}}-{{title}}.md`
+- Updated documentation (if needed)
+- Pull request ready for submission
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- After review document is complete:
+  ```
+  <signal>REVIEW_COMPLETE</signal>
+  ```
+
+- After PR is created:
+  ```
+  <signal>PR_CREATED</signal>
+  ```
+
+- When ready for Architect review:
+  ```
+  <signal>PR_READY</signal>
+  ```
+
+## Important Notes
+
+1. **Final consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews before PR
+2. **Be honest in lessons learned** - Future you will thank present you
+3. **Document deviations** - They're not failures, they're learnings
+4. **Update methodology** - If you found a better way, document it
+5. **Don't skip the checklist** - It catches last-minute issues
+6. **Clean PR description** - Makes review easier
+
+## What NOT to Do
+
+- Don't skip final consultation (it's BLOCKING)
+- Don't skip lessons learned ("nothing to report")
+- Don't merge your own PR (Architect handles integration)
+- Don't leave uncommitted changes
+- Don't forget to update documentation
+- Don't rush this phase - it's valuable for learning
+- Don't use `git add .` or `git add -A` (security risk)
+
+## Review Prompts for Reflection
+
+Ask yourself:
+- What surprised me during implementation?
+- Where did I spend the most time? Was it avoidable?
+- What would have helped me go faster?
+- Did the spec adequately describe what was needed?
+- Did the plan phases make sense in hindsight?
+- What tests caught issues? What tests were unnecessary?
+
+Capture these reflections in the lessons learned section.

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

@@ -0,0 +1,174 @@
+# SPECIFY Phase Prompt
+
+You are executing the **SPECIFY** phase of the SPIDER protocol.
+
+## Your Goal
+
+Create a comprehensive specification document that thoroughly explores the problem space and proposed solution.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Spec File**: `codev/specs/{{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.
+
+## Process
+
+### 1. Clarifying Questions (ALWAYS START HERE)
+
+Before writing anything, ask clarifying questions to understand:
+- What problem is being solved?
+- Who are the stakeholders?
+- What are the constraints?
+- What's in scope vs out of scope?
+- What does success look like?
+
+If this is your first iteration, ask these questions now and wait for answers.
+
+**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step.
+
+### 2. Problem Analysis
+
+Once you have answers, document:
+- The problem being solved (clearly articulated)
+- Current state vs desired state
+- Stakeholders and their needs
+- Assumptions and constraints
+
+### 3. Solution Exploration
+
+Generate multiple solution approaches. For each:
+- Technical design overview
+- Trade-offs (pros/cons)
+- Complexity assessment
+- Risk assessment
+
+### 4. Open Questions
+
+List uncertainties categorized as:
+- **Critical** - blocks progress
+- **Important** - affects design
+- **Nice-to-know** - optimization
+
+### 5. Success Criteria
+
+Define measurable acceptance criteria:
+- Functional requirements (MUST, SHOULD, COULD)
+- Non-functional requirements (performance, security)
+- Test scenarios
+
+### 6. MANDATORY: First Consultation (After Draft)
+
+After completing the initial spec draft:
+
+```bash
+# Run consultations in parallel (REQUIRED)
+consult --model gemini spec {{project_id}} &
+consult --model codex spec {{project_id}} &
+wait
+```
+
+- Review ALL feedback from both models
+- Update the spec with incorporated feedback
+- Add a **Consultation Log** section documenting:
+  - Key feedback received
+  - Changes made in response
+  - Any feedback intentionally not incorporated (with reasoning)
+
+### 7. Human Review
+
+After consultation feedback is incorporated:
+- Present the spec for human review
+- Wait for approval or change requests
+- If changes requested, make them and proceed to Step 8
+
+### 8. MANDATORY: Second Consultation (After Human Feedback)
+
+After incorporating human feedback:
+
+```bash
+# Run consultations again (REQUIRED)
+consult --model gemini spec {{project_id}} &
+consult --model codex spec {{project_id}} &
+wait
+```
+
+- Update Consultation Log with new feedback
+- Incorporate changes
+- Prepare final spec for approval
+
+## Output
+
+Create or update the specification file at `codev/specs/{{project_id}}-{{title}}.md`.
+
+**IMPORTANT**: Keep spec/plan/review filenames in sync:
+- Spec: `codev/specs/{{project_id}}-{{title}}.md`
+- Plan: `codev/plans/{{project_id}}-{{title}}.md`
+- Review: `codev/reviews/{{project_id}}-{{title}}.md`
+
+Include a **Consultation Log** section in the spec documenting all consultation feedback.
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- When waiting for clarifying question answers, **include your questions in the signal**:
+  ```
+  <signal type=AWAITING_INPUT>
+  Please answer these questions:
+  1. What should the primary use case be - internal tooling or customer-facing?
+  2. What are the key constraints we should consider?
+  3. Who are the main stakeholders?
+  </signal>
+  ```
+
+  The content inside the signal tag is displayed prominently to the user.
+
+- After completing the initial spec draft:
+  ```
+  <signal>SPEC_DRAFTED</signal>
+  ```
+
+- After incorporating consultation feedback:
+  ```
+  <signal>CONSULTATION_INCORPORATED</signal>
+  ```
+
+- After final spec is ready for human approval:
+  ```
+  <signal>SPEC_READY_FOR_APPROVAL</signal>
+  ```
+
+## Commit Cadence
+
+Make commits at these milestones:
+1. `[Spec {{project_id}}] Initial specification draft`
+2. `[Spec {{project_id}}] Specification with multi-agent review`
+3. `[Spec {{project_id}}] Specification with user feedback`
+4. `[Spec {{project_id}}] Final approved specification`
+
+**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
+```bash
+git add codev/specs/{{project_id}}-{{title}}.md
+```
+
+## Important Notes
+
+1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
+2. **Be thorough** - A good spec prevents implementation problems
+3. **Be specific** - Vague specs lead to wrong implementations
+4. **Include examples** - Concrete examples clarify intent
+5. **Document consultations** - Maintain the Consultation Log section
+
+## What NOT to Do
+
+- Don't skip consultations (they are BLOCKING)
+- Don't include implementation details (that's for the Plan phase)
+- Don't estimate time (AI makes time estimates meaningless)
+- Don't start coding (you're in Specify, not Implement)
+- Don't use `git add .` or `git add -A` (security risk)

package/skeleton/protocols/spider/protocol.json

@@ -1,147 +1,90 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "spider",
-  "version": "1.0.0",
-  "description": "Specification-driven development with multi-agent consultation",
+  "alias": "spir",
+  "version": "2.1.0",
+  "description": "SPIR: Specify → Plan → Implement → Review with build-verify cycles",
   "phases": [
     {
       "id": "specify",
       "name": "Specify",
-      "description": "Collaborative design exploration and specification",
-      "type": "once",
-      "steps": [
-        "clarifying_questions",
-        "problem_analysis",
-        "solution_exploration",
-        "open_questions",
-        "success_criteria",
-        "spec_draft",
-        "consultation_1",
-        "human_review",
-        "consultation_2",
-        "spec_final"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Write specification with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "specify.md",
+        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "spec-review",
-        "parallel": true,
-        "max_rounds": 3
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "spec-approval",
-        "description": "Human approves specification before planning",
-        "requires": ["spec_final", "consultation_2"],
-        "next": "plan"
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "spec-approval",
+      "next": "plan"
     },
     {
       "id": "plan",
       "name": "Plan",
-      "description": "Implementation planning with phased breakdown",
-      "type": "once",
-      "steps": [
-        "analyze_spec",
-        "identify_phases",
-        "define_steps",
-        "plan_draft",
-        "consultation",
-        "human_review",
-        "plan_final"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Write implementation plan with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "plan.md",
+        "artifact": "codev/plans/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "plan-review",
-        "parallel": true,
-        "max_rounds": 2
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "plan-approval",
-        "description": "Human approves plan before implementation",
-        "requires": ["plan_final", "consultation"],
-        "next": "implement"
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "plan_exists": "test -f codev/plans/${PROJECT_ID}-*.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_ID}-*.md",
+        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_ID}-*.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
+      },
+      "gate": "plan-approval",
+      "next": "implement"
     },
     {
       "id": "implement",
       "name": "Implement",
-      "description": "Code implementation following the plan",
+      "description": "Implement code with 3-way review per plan phase",
       "type": "per_plan_phase",
-      "steps": [
-        "read_phase",
-        "implement_code",
-        "self_review",
-        "commit"
-      ],
+      "build": {
+        "prompt": "implement.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx}"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
       "checks": {
         "build": {
           "command": "npm run build",
           "on_fail": "retry",
           "max_retries": 2
         },
-        "typecheck": {
-          "command": "npm run typecheck",
-          "on_fail": "retry",
-          "max_retries": 2
-        }
-      },
-      "transition": {
-        "on_complete": "defend",
-        "on_fail": "implement"
-      }
-    },
-    {
-      "id": "defend",
-      "name": "Defend",
-      "description": "Testing and verification",
-      "type": "per_plan_phase",
-      "steps": [
-        "write_tests",
-        "run_tests",
-        "fix_failures",
-        "commit"
-      ],
-      "checks": {
         "tests": {
           "command": "npm test",
-          "on_fail": "implement",
-          "max_retries": 1
-        },
-        "lint": {
-          "command": "npm run lint",
           "on_fail": "retry",
-          "max_retries": 1
+          "max_retries": 2
         }
       },
-      "consultation": {
-        "on": "complete",
-        "models": ["gemini", "codex", "claude"],
-        "type": "impl-review",
-        "parallel": true,
-        "max_rounds": 2
-      },
-      "transition": {
-        "on_complete": "evaluate",
-        "on_fail": "implement"
-      }
-    },
-    {
-      "id": "evaluate",
-      "name": "Evaluate",
-      "description": "Verify implementation against spec",
-      "type": "per_plan_phase",
-      "steps": [
-        "check_spec_compliance",
-        "check_success_criteria",
-        "document_deviations"
-      ],
-      "gate": {
-        "name": "phase-complete",
-        "description": "Plan phase implementation is verified",
-        "requires": ["all_checks_pass", "spec_compliance"],
-        "next": "implement"
-      },
       "transition": {
         "on_complete": "implement",
         "on_all_phases_complete": "review"
@@ -150,55 +93,46 @@
     {
       "id": "review",
       "name": "Review",
-      "description": "Final review and lessons learned",
-      "type": "once",
-      "steps": [
-        "create_review_document",
-        "document_lessons",
-        "final_consultation",
-        "create_pr"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex", "claude"],
+      "description": "Final review and PR with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "review.md",
+        "artifact": "codev/reviews/${PROJECT_ID}-*.md"
+      },
+      "verify": {
         "type": "pr-ready",
-        "parallel": true,
-        "max_rounds": 1
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
       },
-      "gate": {
-        "name": "pr-ready",
-        "description": "Implementation ready for PR",
-        "requires": ["review_complete", "all_tests_pass", "consultation"],
-        "next": null
-      }
+      "max_iterations": 7,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "pr-ready",
+      "next": null
     }
   ],
   "signals": {
     "PHASE_COMPLETE": {
-      "description": "Signal current phase is complete",
-      "transitions_to": "next_phase"
+      "description": "Signal current build phase is complete",
+      "transitions_to": "verify"
     },
     "BLOCKED": {
       "description": "Signal implementation is blocked",
       "requires": "reason"
-    },
-    "REVISION_NEEDED": {
-      "description": "Signal changes requested",
-      "transitions_to": "current_phase"
-    },
-    "APPROVED": {
-      "description": "Signal gate approval received"
     }
   },
+  "phase_completion": {
+    "build_succeeds": "npm run build 2>&1",
+    "tests_pass": "npm test 2>&1",
+    "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'"
+  },
   "defaults": {
-    "consultation": {
-      "enabled": true,
+    "max_iterations": 7,
+    "verify": {
       "models": ["gemini", "codex", "claude"],
       "parallel": true
-    },
-    "checks": {
-      "build": "npm run build",
-      "test": "npm test"
     }
   }
 }