@cluesmith/codev 1.1.0 → 1.1.1

package/templates/protocols/spider-solo/protocol.md

@@ -1,619 +0,0 @@
-# SPIDER-SOLO Protocol
-
-## Prerequisites
-
-**No External Dependencies Required**:
-- SPIDER-SOLO is a single-agent variant that doesn't require Zen MCP
-- All review and validation is done through self-review
-- Ideal when multi-agent infrastructure is not available
-
-## Protocol Configuration
-
-### Self-Review Only (NO MULTI-AGENT CONSULTATION)
-
-**DEFAULT BEHAVIOR:**
-SPIDER-SOLO uses self-review and human approval only.
-
-**KEY DIFFERENCE FROM SPIDER:**
-- No multi-agent consultation at any checkpoint
-- All review is done through careful self-examination
-- Emphasis on thorough self-validation before presenting to user
-
-**REVIEW APPROACH:**
-- Self-review at each checkpoint where SPIDER would consult agents
-- Use critical thinking to identify gaps and issues
-- Document self-review findings transparently
-- Rely on human feedback for validation
-
-## Overview
-SPIDER-SOLO is a single-agent variant of the SPIDER protocol that emphasizes specification-driven development with iterative implementation and continuous self-review. It maintains the same structured approach but without multi-agent collaboration.
-
-**Core Principle**: Each feature is tracked through exactly THREE documents - a specification, a plan, and a review with lessons learned - all sharing the same filename and sequential identifier.
-
-## When to Use SPIDER-SOLO
-
-### Use SPIDER-SOLO for:
-- New feature development (when Zen MCP is not available)
-- Architecture changes (single-agent review)
-- Complex refactoring (self-validated)
-- System design decisions (human-approved)
-- API design and implementation
-- Performance optimization initiatives
-
-### Skip SPIDER-SOLO for:
-- Simple bug fixes (< 10 lines)
-- Documentation updates
-- Configuration changes
-- Dependency updates
-- Emergency hotfixes (but do a lightweight retrospective after)
-
-## Protocol Phases
-
-### S - Specify (Design Exploration with Self-Review)
-
-**Purpose**: Thoroughly explore the problem space and solution options before committing to an approach.
-
-**Workflow Overview**:
-1. User provides a prompt describing what they want built
-2. Agent generates initial specification document
-3. **COMMIT**: "Initial specification draft"
-4. Self-review the specification critically
-5. Agent updates spec based on self-review
-6. **COMMIT**: "Specification after self-review"
-7. Human reviews and provides comments for changes
-8. Agent makes changes and lists what was modified
-9. **COMMIT**: "Specification with user feedback"
-10. Final self-review of updated document
-11. Final updates based on self-review
-12. **COMMIT**: "Final approved specification"
-13. Iterate steps 7-12 until user approves and says to proceed to planning
-
-**Important**: Keep documentation minimal - use only THREE core files with the same name:
-- `specs/####-descriptive-name.md` - The specification
-- `plans/####-descriptive-name.md` - The implementation plan
-- `reviews/####-descriptive-name.md` - Review and lessons learned (created during Review phase)
-
-**Process**:
-1. **Clarifying Questions** (ALWAYS START HERE)
-   - Ask the user/stakeholder questions to understand the problem
-   - Probe for hidden requirements and constraints
-   - Understand the business context and goals
-   - Identify what's in scope and out of scope
-   - Continue asking until the problem is crystal clear
-
-2. **Problem Analysis**
-   - Clearly articulate the problem being solved
-   - Identify stakeholders and their needs
-   - Document current state and desired state
-   - List assumptions and constraints
-
-3. **Solution Exploration**
-   - Generate multiple solution approaches (as many as appropriate)
-   - For each approach, document:
-     - Technical design
-     - Trade-offs (pros/cons)
-     - Estimated complexity
-     - Risk assessment
-
-4. **Open Questions**
-   - List all uncertainties that need resolution
-   - Categorize as:
-     - Critical (blocks progress)
-     - Important (affects design)
-     - Nice-to-know (optimization)
-
-5. **Success Criteria**
-   - Define measurable acceptance criteria
-   - Include performance requirements
-   - Specify quality metrics
-   - Document test scenarios
-
-6. **Self-Review Process**
-   - **First Self-Review** (after initial draft):
-     - Critically examine problem clarity and solution completeness
-     - Look for missing requirements or edge cases
-     - Document self-identified improvements
-     - Update specification based on self-review
-   - **Second Self-Review** (after human comments):
-     - Validate changes align with feedback
-     - Ensure specification is comprehensive
-     - Final specification refinement
-
-   **Note**: Self-review only - no multi-agent consultation in SOLO variant
-
-**⚠️ IMPORTANT**: Thorough self-review is critical before proceeding
-
-**Output**: Single specification document in `codev/specs/####-descriptive-name.md`
-- All self-review findings incorporated directly into this document
-- Include a "Self-Review Notes" section summarizing identified improvements
-- Version control captures evolution through commits
-**Template**: `templates/spec.md`
-**Review Required**: Yes - Human approval AFTER self-review
-
-### P - Plan (Structured Decomposition)
-
-**Purpose**: Transform the approved specification into an executable roadmap with clear phases.
-
-**⚠️ CRITICAL: No Time Estimates in the AI Age**
-- **NEVER include time estimates** (hours, days, weeks, story points)
-- AI-driven development makes traditional time estimates meaningless
-- Delivery speed depends on iteration cycles, not calendar time
-- Focus on logical dependencies and phase ordering instead
-- Measure progress by completed phases, not elapsed time
-- The only valid metrics are: "done" or "not done"
-
-**Workflow Overview**:
-1. Agent creates initial plan document
-2. **COMMIT**: "Initial plan draft"
-3. Self-review the plan thoroughly
-4. Agent updates plan with self-review findings
-5. **COMMIT**: "Plan after self-review"
-6. User reviews and requests modifications
-7. Agent updates plan based on user feedback
-8. **COMMIT**: "Plan with user feedback"
-9. Final self-review of updated plan
-10. Final updates based on self-review
-11. **COMMIT**: "Final approved plan"
-12. Iterate steps 6-11 until agreement is reached
-
-**Phase Design Goals**:
-Each phase should be:
-- A separate piece of work that can be checked in as a unit
-- A complete set of functionality
-- Self-contained and independently valuable
-
-**Process**:
-1. **Phase Definition**
-   - Break work into logical phases
-   - Each phase must:
-     - Have a clear, single objective
-     - Be independently testable
-     - Deliver observable value
-     - Be a complete unit that can be committed
-     - End with evaluation discussion and single commit
-   - Note dependencies inline, for example:
-     ```markdown
-     Phase 2: API Endpoints
-     - Depends on: Phase 1 (Database Schema)
-     - Objective: Create /users and /todos endpoints
-     - Evaluation: Test coverage, API design review, performance check
-     - Commit: Will create single commit after user approval
-     ```
-
-2. **Success Metrics**
-   - Define "done" for each phase
-   - Include test coverage requirements
-   - Specify performance benchmarks
-   - Document acceptance tests
-
-3. **Self-Review Process**
-   - **First Self-Review** (after plan creation):
-     - Assess feasibility and phase breakdown
-     - Verify completeness of planned approach
-     - Update plan based on self-identified gaps
-   - **Second Self-Review** (after human review):
-     - Validate adjustments align with feedback
-     - Confirm approach is sound
-     - Final plan refinement
-
-   **Note**: Self-review only - no multi-agent consultation in SOLO variant
-
-**⚠️ IMPORTANT**: Comprehensive self-review required before proceeding
-
-**Output**: Single plan document in `codev/plans/####-descriptive-name.md`
-- Same filename as specification, different directory
-- All self-review findings incorporated directly
-- Include phase status tracking within this document
-- **DO NOT include time estimates** - Focus on deliverables and dependencies, not hours/days
-- Version control captures evolution through commits
-**Template**: `templates/plan.md`
-**Review Required**: Yes - Technical lead approval AFTER self-review
-
-### (IDE) - Implementation Loop
-
-Execute for each phase in the plan. This is a strict cycle that must be completed in order.
-
-**⚠️ MANDATORY**: The I-D-E cycle MUST be completed for EACH PHASE, not just at the end of all phases. Skipping D (Defend) or E (Evaluate) for any phase is a PROTOCOL VIOLATION.
-
-**CRITICAL PRECONDITION**: Before starting any phase, verify the previous phase was committed to git. No phase can begin without the prior phase's commit.
-
-**Phase Completion Process**:
-1. **Implement** - Build the code for this phase
-2. **Defend** - Write comprehensive tests that guard functionality
-3. **Evaluate** - Assess and discuss with user
-4. **Commit** - Single atomic commit for the phase (MANDATORY before next phase)
-5. **Proceed** - Move to next phase only after commit
-
-**Handling Failures**:
-- If **Defend** phase reveals gaps → return to **Implement** to fix
-- If **Evaluation** reveals unmet criteria → return to **Implement**
-- If user requests changes → return to **Implement**
-- If fundamental plan flaws found → mark phase as `blocked` and revise plan
-
-**Commit Requirements**:
-- Each phase MUST end with a git commit before proceeding
-- Commit message format: `[Spec ####][Phase: name] type: Description`
-- No work on the next phase until current phase is committed
-- If changes are needed after commit, create a new commit with fixes
-
-#### I - Implement (Build with Discipline)
-
-**Purpose**: Transform the plan into working code with high quality standards.
-
-**Precondition**: Previous phase must be committed (verify with `git log`)
-
-**Requirements**:
-1. **Pre-Implementation**
-   - Verify previous phase is committed to git
-   - Review the phase plan and success criteria
-   - Set up the development environment
-   - Create feature branch following naming convention
-   - Document any plan deviations immediately
-
-2. **During Implementation**
-   - Write self-documenting code
-   - Follow project style guide strictly
-   - Implement incrementally with frequent commits
-   - Each commit must:
-     - Be atomic (single logical change)
-     - Include descriptive message
-     - Reference the phase
-     - Pass basic syntax checks
-
-3. **Code Quality Standards**
-   - No commented-out code
-   - No debug prints in final code
-   - Handle all error cases explicitly
-   - Include necessary logging
-   - Follow security best practices
-
-4. **Documentation Requirements**
-   - Update API documentation
-   - Add inline comments for complex logic
-   - Update README if needed
-   - Document configuration changes
-
-**Evidence Required**:
-- Link to commits
-- Code review approval (if applicable)
-- No linting errors
-- CI pipeline pass link (build/test/lint)
-
-**Self-Review Process**:
-- Critically review code quality, patterns, security, best practices
-- Look for potential improvements and issues
-- Update code based on self-identified concerns before proceeding
-
-#### D - Defend (Write Comprehensive Tests)
-
-**Purpose**: Create comprehensive automated tests that safeguard intended behavior and prevent regressions.
-
-**CRITICAL**: Tests must be written IMMEDIATELY after implementation, NOT retroactively at the end of all phases. This is MANDATORY.
-
-**Requirements**:
-1. **Defensive Test Creation**
-   - Write unit tests for all new functions
-   - Create integration tests for feature flows
-   - Develop edge case coverage
-   - Build error condition tests
-   - Establish performance benchmarks
-
-2. **Test Validation** (ALL MANDATORY)
-   - All new tests must pass
-   - All existing tests must pass
-   - No reduction in overall coverage
-   - Performance benchmarks met
-   - Security scans pass
-   - **Avoid Overmocking**:
-     - Test behavior, not implementation details
-     - Prefer integration tests over unit tests with heavy mocking
-     - Only mock external dependencies (APIs, databases, file systems)
-     - Never mock the system under test itself
-     - Use real implementations for internal module boundaries
-
-3. **Test Suite Documentation**
-   - Document test scenarios
-   - Explain complex test setups
-   - Note any flaky tests
-   - Record performance baselines
-
-**Evidence Required**:
-- Test execution logs
-- Coverage report (show no reduction)
-- Performance test results (if applicable per spec)
-- Security scan results (if configured)
-- CI test run link with artifacts
-
-**Self-Review Process**:
-- Review test coverage completeness and edge cases
-- Assess defensive patterns and test strategy
-- Write additional tests based on self-identified gaps
-- Document review findings for evaluation discussion
-
-#### E - Evaluate (Assess Objectively)
-
-**Purpose**: Verify the implementation fully satisfies the phase requirements and maintains system quality. This is where the critical discussion happens before committing the phase.
-
-**Requirements**:
-1. **Functional Evaluation**
-   - All acceptance criteria met
-   - User scenarios work as expected
-   - Edge cases handled properly
-   - Error messages are helpful
-
-2. **Non-Functional Evaluation**
-   - Performance requirements satisfied
-   - Security standards maintained
-   - Code maintainability assessed
-   - Technical debt documented
-
-3. **Deviation Analysis**
-   - Document any changes from plan
-   - Explain reasoning for changes
-   - Assess impact on other phases
-   - Update future phases if needed
-   - **Overmocking Check** (MANDATORY):
-     - Verify tests focus on behavior, not implementation
-     - Ensure at least one integration test per critical path
-     - Check that internal module boundaries use real implementations
-     - Confirm mocks are only used for external dependencies
-     - Tests should survive refactoring that preserves behavior
-
-4. **Final Self-Review Before User Evaluation**
-   - Perform thorough self-assessment of the phase
-   - Identify and fix any remaining issues
-   - **CRITICAL**: Ensure high confidence in the implementation
-   - Only proceed to user evaluation after thorough self-validation
-   - If any doubts remain, address them FIRST
-
-5. **Evaluation Discussion with User**
-   - Present to user: "Phase X complete. Here's what was built: [summary]"
-   - Share test results and coverage metrics
-   - Share self-review findings and confidence level
-   - Ask: "Any changes needed before I commit this phase?"
-   - Incorporate user feedback if requested
-   - Get explicit approval to proceed
-
-6. **Phase Commit** (MANDATORY - NO EXCEPTIONS)
-   - Create single atomic commit for the entire phase
-   - Commit message: `[Spec ####][Phase: name] type: Description`
-   - Update the plan document marking this phase as complete
-   - Push all changes to version control
-   - Document any deviations or decisions in the plan
-   - **CRITICAL**: Next phase CANNOT begin until this commit is complete
-   - Verify commit with `git log` before proceeding
-
-7. **Final Verification**
-   - Confirm all self-review findings were addressed
-   - Verify all tests pass
-   - Check that documentation is updated
-   - Ensure no outstanding concerns from user
-
-**Evidence Required**:
-- Evaluation checklist completed
-- Test results and coverage report
-- Self-review notes and findings
-- User approval from evaluation discussion
-- Updated plan document with:
-  - Phase marked complete
-  - Evaluation discussion summary
-  - Any deviations noted
-- Git commit for this phase
-- Final CI run link after all fixes
-
-## 📋 PHASE COMPLETION CHECKLIST (MANDATORY BEFORE NEXT PHASE)
-
-**⚠️ STOP: DO NOT PROCEED TO NEXT PHASE UNTIL ALL ITEMS ARE ✅**
-
-### Before Starting ANY Phase:
-- [ ] Previous phase is committed to git (verify with `git log`)
-- [ ] Plan document shows previous phase as `completed`
-- [ ] No outstanding issues from previous phase
-
-### After Implement Phase:
-- [ ] All code for this phase is complete
-- [ ] Code follows project style guide
-- [ ] No commented-out code or debug prints
-- [ ] Error handling is implemented
-- [ ] Documentation is updated (if needed)
-- [ ] Self-review completed (critical examination)
-- [ ] Self-identified issues have been fixed
-
-### After Defend Phase:
-- [ ] Unit tests written for all new functions
-- [ ] Integration tests written for critical paths
-- [ ] Edge cases have test coverage
-- [ ] All new tests are passing
-- [ ] All existing tests still pass
-- [ ] No reduction in code coverage
-- [ ] Overmocking check completed (tests focus on behavior)
-- [ ] Self-review of test coverage completed
-- [ ] Test gaps identified and addressed
-
-### After Evaluate Phase:
-- [ ] All acceptance criteria from spec are met
-- [ ] Performance requirements satisfied
-- [ ] Security standards maintained
-- [ ] Thorough self-assessment completed
-- [ ] High confidence in implementation achieved
-- [ ] User evaluation discussion completed
-- [ ] User has given explicit approval to proceed
-- [ ] Plan document updated with phase status
-- [ ] Phase commit created with proper message format
-- [ ] Commit pushed to version control
-- [ ] Commit verified with `git log`
-
-### ❌ PHASE BLOCKERS (Fix Before Proceeding):
-- Any failing tests
-- Unresolved self-review concerns
-- Missing user approval
-- Uncommitted changes
-- Incomplete documentation
-- Coverage reduction
-- Low confidence in implementation
-
-**REMINDER**: Each phase is atomic. You cannot start the next phase until the current phase is fully complete, tested, evaluated, and committed.
-
-### R - Review/Refine/Revise (Continuous Improvement)
-
-**Purpose**: Ensure overall coherence, capture learnings, and improve the methodology.
-
-**Precondition**: All implementation phases must be committed (verify with `git log --oneline | grep "\[Phase"`)
-
-**Process**:
-1. **Comprehensive Review**
-   - Verify all phases have been committed to git
-   - Compare final implementation to original specification
-   - Assess overall architecture impact
-   - Review code quality across all changes
-   - Validate documentation completeness
-
-2. **Refinement Actions**
-   - Refactor code for clarity if needed
-   - Optimize performance bottlenecks
-   - Improve test coverage gaps
-   - Enhance documentation
-
-3. **Revision Requirements** (MANDATORY)
-   - Update README.md with any new features or changes
-   - Update AGENTS.md and CLAUDE.md with protocol improvements from lessons learned
-   - Update specification and plan documents with final status
-   - Revise architectural diagrams if needed
-   - Update API documentation
-   - Modify deployment guides as necessary
-   - **CRITICAL**: Update this protocol document based on lessons learned
-
-4. **Systematic Issue Review** (MANDATORY)
-   - Review entire project for systematic issues:
-     - Repeated problems across phases
-     - Process bottlenecks or inefficiencies
-     - Missing documentation patterns
-     - Technical debt accumulation
-     - Testing gaps or quality issues
-   - Document systematic findings in lessons learned
-   - Create action items for addressing systematic issues
-
-5. **Lessons Learned** (MANDATORY)
-   - What went well?
-   - What was challenging?
-   - What would you do differently?
-   - What methodology improvements are needed?
-   - What systematic issues were identified?
-
-6. **Methodology Evolution**
-   - Propose process improvements based on lessons
-   - Update protocol documents with improvements
-   - Update templates if needed
-   - Share learnings with team
-   - Document in `codev/reviews/`
-   - **Important**: This protocol should evolve based on each project's learnings
-
-**Output**:
-- Single review document in `codev/reviews/####-descriptive-name.md`
-- Same filename as spec/plan, captures review and learnings from this feature
-- Methodology improvement proposals (update protocol if needed)
-
-**Review Required**: Yes - Team retrospective recommended
-
-## File Naming Conventions
-
-### Specifications and Plans
-Format: `####-descriptive-name.md`
-- Use sequential numbering (0001, 0002, etc.)
-- Same filename in both `specs/` and `plans/` directories
-- Example: `0001-user-authentication.md`
-
-## Status Tracking
-
-Status is tracked at the **phase level** within plan documents, not at the document level.
-
-Each phase in a plan should have a status:
-- `pending`: Not started
-- `in-progress`: Currently being worked on
-- `completed`: Phase finished and tested
-- `blocked`: Cannot proceed due to external factors
-
-## Git Integration
-
-### Commit Message Format
-
-For specification/plan documents:
-```
-[Spec ####] <stage>: <description>
-```
-
-Examples:
-```
-[Spec 0001] Initial specification draft
-[Spec 0001] Specification after self-review
-[Spec 0001] Specification with user feedback
-[Spec 0001] Final approved specification
-```
-
-For implementation:
-```
-[Spec ####][Phase: <phase-name>] <type>: <description>
-
-<optional detailed description>
-```
-
-Example:
-```
-[Spec 0001][Phase: user-auth] feat: Add password hashing service
-
-Implements bcrypt-based password hashing with configurable rounds
-```
-
-### Branch Naming
-```
-spider/####-<spec-name>/<phase-name>
-```
-
-Example:
-```
-spider/0001-user-authentication/database-schema
-```
-
-
-## Best Practices
-
-### During Specification
-- Use clear, unambiguous language
-- Include concrete examples
-- Define measurable success criteria
-- Link to relevant references
-
-### During Planning
-- Keep phases small and focused
-- Ensure each phase delivers value
-- Note phase dependencies inline (no formal dependency mapping needed)
-- Include rollback strategies
-
-### During Implementation
-- Follow the plan but document deviations
-- Maintain test coverage
-- Keep commits atomic and well-described
-- Update documentation as you go
-
-### During Review
-- Check against original specification
-- Document lessons learned
-- Propose methodology improvements
-- Update estimates for future work
-
-## Templates
-
-Templates for each phase are available in the `templates/` directory:
-- `spec.md` - Specification template
-- `plan.md` - Planning template (includes phase status tracking)
-- `review.md` - Review and lessons learned template
-
-**Remember**: Only create THREE documents per feature - spec, plan, and review with the same filename in different directories.
-
-## Protocol Evolution
-
-This protocol can be customized per project:
-1. Fork the protocol directory
-2. Modify templates and processes
-3. Document changes in `protocol-changes.md`
-4. Share improvements back to the community