@cluesmith/codev 3.0.0-rc.9 → 3.0.1

package/skeleton/protocols/tick/consult-types/plan-review.md

@@ -1,59 +0,0 @@
-# Plan Review Prompt
-
-## Context
-You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
-
-## Focus Areas
-
-1. **Spec Coverage**
-   - Does the plan address all requirements in the spec?
-   - Are there spec requirements not covered by any phase?
-   - Are there phases that go beyond the spec scope?
-
-2. **Phase Breakdown**
-   - Are phases appropriately sized (not too large or too small)?
-   - Is the sequence logical (dependencies respected)?
-   - Can each phase be completed and committed independently?
-
-3. **Technical Approach**
-   - Is the implementation approach sound?
-   - Are the right files/modules being modified?
-   - Are there obvious better approaches being missed?
-
-4. **Testability**
-   - Does each phase have clear test criteria?
-   - Will the Defend step (writing tests) be feasible?
-   - Are edge cases from the spec addressable?
-
-5. **Risk Assessment**
-   - Are there potential blockers not addressed?
-   - Are dependencies on other systems identified?
-   - Is the plan realistic given constraints?
-
-## Verdict Format
-
-After your review, provide your verdict in exactly this format:
-
-```
----
-VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
-SUMMARY: [One-line summary of your assessment]
-CONFIDENCE: [HIGH | MEDIUM | LOW]
----
-KEY_ISSUES:
-- [Issue 1 or "None"]
-- [Issue 2]
-...
-```
-
-**Verdict meanings:**
-- `APPROVE`: Plan is ready for human review
-- `REQUEST_CHANGES`: Significant issues with approach or coverage
-- `COMMENT`: Minor suggestions, plan is workable but could improve
-
-## Notes
-
-- The spec has already been approved - don't re-litigate spec decisions
-- Focus on the quality of the plan as a guide for builders
-- Consider: Would a builder be able to follow this plan successfully?
-- If referencing existing code, verify file paths seem accurate

package/skeleton/protocols/tick/consult-types/pr-review.md

@@ -1,72 +0,0 @@
-# PR Ready Review Prompt
-
-## Context
-You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
-
-## Focus Areas
-
-1. **Completeness**
-   - Are all spec requirements implemented?
-   - Are all plan phases complete?
-   - Is the review document written (`codev/reviews/XXXX-name.md`)?
-   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
-
-2. **Test Status**
-   - Do all tests pass?
-   - Is test coverage adequate for the changes?
-   - Are there any skipped or flaky tests?
-
-3. **Code Cleanliness**
-   - Is there any debug code left in?
-   - Are there any TODO comments that should be resolved?
-   - Are there any `// REVIEW:` comments that weren't addressed?
-   - Is the code properly formatted?
-
-4. **Documentation**
-   - Are inline comments clear where needed?
-   - Is the review document comprehensive?
-   - Are any new APIs documented?
-
-5. **PR Readiness**
-   - Is the branch up to date with main?
-   - Are commits atomic and well-described?
-   - Is the change diff reasonable in size?
-
-## Verdict Format
-
-After your review, provide your verdict in exactly this format:
-
-```
----
-VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
-SUMMARY: [One-line summary of your assessment]
-CONFIDENCE: [HIGH | MEDIUM | LOW]
----
-KEY_ISSUES:
-- [Issue 1 or "None"]
-- [Issue 2]
-...
-
-PR_SUMMARY: |
-  ## Summary
-  [2-3 sentences describing what this PR does]
-
-  ## Key Changes
-  - [Change 1]
-  - [Change 2]
-
-  ## Test Plan
-  - [How to test]
-```
-
-**Verdict meanings:**
-- `APPROVE`: Ready to create PR
-- `REQUEST_CHANGES`: Issues to fix before PR creation
-- `COMMENT`: Minor items, can create PR but note feedback
-
-## Notes
-
-- This is the builder's final self-review before hand-off
-- The PR_SUMMARY in your output can be used as the PR description
-- Focus on "is this ready for someone else to review" not "is this perfect"
-- Any issues found here are cheaper to fix than during integration review

package/skeleton/protocols/tick/consult-types/spec-review.md

@@ -1,55 +0,0 @@
-# Specification Review Prompt
-
-## Context
-You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
-
-## Focus Areas
-
-1. **Completeness**
-   - Are all requirements clearly stated?
-   - Are success criteria defined?
-   - Are edge cases considered?
-   - Is scope well-bounded (not too broad or vague)?
-
-2. **Correctness**
-   - Do requirements make sense technically?
-   - Are there contradictions?
-   - Is the problem statement accurate?
-
-3. **Feasibility**
-   - Can this be implemented with available tools/constraints?
-   - Are there obvious technical blockers?
-   - Is the scope realistic for a single spec?
-
-4. **Clarity**
-   - Would a builder understand what to build?
-   - Are acceptance criteria testable?
-   - Is terminology consistent?
-
-## Verdict Format
-
-After your review, provide your verdict in exactly this format:
-
-```
----
-VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
-SUMMARY: [One-line summary of your assessment]
-CONFIDENCE: [HIGH | MEDIUM | LOW]
----
-KEY_ISSUES:
-- [Issue 1 or "None"]
-- [Issue 2]
-...
-```
-
-**Verdict meanings:**
-- `APPROVE`: Spec is ready for human review
-- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding
-- `COMMENT`: Minor suggestions, can proceed but consider feedback
-
-## Notes
-
-- You are NOT reviewing code - you are reviewing the specification document
-- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review)
-- Be constructive - identify issues AND suggest solutions
-- If the spec references other specs, note if context seems missing

package/skeleton/protocols/tick/protocol.json

@@ -1,151 +0,0 @@
-{
-  "$schema": "../../protocol-schema.json",
-  "name": "tick",
-  "version": "1.1.0",
-  "description": "Amendment workflow for existing SPIR specifications",
-  "input": {
-    "type": "spec",
-    "required": false
-  },
-  "phases": [
-    {
-      "id": "identify",
-      "name": "Identify Target",
-      "description": "Find the existing spec to amend",
-      "type": "once",
-      "steps": [
-        "analyze_requirements",
-        "find_target_spec",
-        "verify_spec_integrated",
-        "determine_tick_number"
-      ],
-      "transition": {
-        "on_complete": "amend_spec"
-      }
-    },
-    {
-      "id": "amend_spec",
-      "name": "Amend Specification",
-      "description": "Update the existing specification",
-      "type": "once",
-      "steps": [
-        "analyze_changes_needed",
-        "update_spec_sections",
-        "add_amendment_entry",
-        "commit_spec_changes"
-      ],
-      "transition": {
-        "on_complete": "amend_plan"
-      }
-    },
-    {
-      "id": "amend_plan",
-      "name": "Amend Plan",
-      "description": "Update the existing plan",
-      "type": "once",
-      "steps": [
-        "update_plan_phases",
-        "add_amendment_history",
-        "commit_plan_changes"
-      ],
-      "transition": {
-        "on_complete": "implement"
-      }
-    },
-    {
-      "id": "implement",
-      "name": "Implement",
-      "description": "Implement the amendment",
-      "type": "once",
-      "steps": [
-        "implement_changes",
-        "self_review",
-        "commit"
-      ],
-      "checks": {
-        "build": {
-          "command": "npm run build",
-          "on_fail": "retry",
-          "max_retries": 2
-        }
-      },
-      "transition": {
-        "on_complete": "defend"
-      }
-    },
-    {
-      "id": "defend",
-      "name": "Defend",
-      "description": "Test the amendment",
-      "type": "once",
-      "steps": [
-        "write_tests",
-        "run_tests",
-        "fix_failures"
-      ],
-      "checks": {
-        "tests": {
-          "command": "npm test",
-          "on_fail": "implement",
-          "max_retries": 1
-        }
-      },
-      "transition": {
-        "on_complete": "evaluate"
-      }
-    },
-    {
-      "id": "evaluate",
-      "name": "Evaluate",
-      "description": "Verify amendment meets requirements",
-      "type": "once",
-      "steps": [
-        "verify_requirements",
-        "check_regressions"
-      ],
-      "transition": {
-        "on_complete": "review"
-      }
-    },
-    {
-      "id": "review",
-      "name": "Review",
-      "description": "Create review document and PR",
-      "type": "once",
-      "steps": [
-        "create_tick_review",
-        "create_pr"
-      ],
-      "consultation": {
-        "on": "review",
-        "models": ["gemini", "codex"],
-        "type": "impl",
-        "parallel": true,
-        "max_rounds": 1
-      },
-      "gate": "pr"
-    }
-  ],
-  "signals": {
-    "PHASE_COMPLETE": {
-      "description": "Signal current phase is complete",
-      "transitions_to": "next_phase"
-    },
-    "BLOCKED": {
-      "description": "Signal implementation is blocked",
-      "requires": "reason"
-    }
-  },
-  "defaults": {
-    "mode": "strict",
-    "consultation": {
-      "enabled": true,
-      "models": ["gemini", "codex"],
-      "parallel": true
-    },
-    "checks": {
-      "build": "npm run build",
-      "test": "npm test"
-    }
-  }
-}

package/skeleton/protocols/tick/protocol.md

@@ -1,277 +0,0 @@
-# TICK Protocol
-**T**ask **I**dentification, **C**oding, **K**ickout
-
-## Overview
-
-TICK is an **amendment workflow** for existing SPIR specifications. Rather than creating new standalone specs, TICK modifies existing spec and plan documents in-place, tracking changes in an "Amendments" section.
-
-**Core Principle**: TICK is for *refining* existing specs. SPIR is for *creating* new specs.
-
-**Key Insight**: TICKs are not small SPIRs - they're amendments to existing SPIRs. This eliminates the "TICK vs SPIR" decision problem and keeps related work together.
-
-## When to Use TICK
-
-### Use TICK when:
-- Making **amendments to an existing SPIR spec** that is already `integrated`
-- Small scope (< 300 lines of new/changed code)
-- Requirements are clear and well-defined
-- No fundamental architecture changes
-- Examples:
-  - Adding a feature to an existing system (e.g., "add password reset to user auth")
-  - Bug fixes that extend existing functionality
-  - Configuration changes with logic
-  - Utility function additions to existing modules
-  - Refactoring within an existing feature
-
-### Use SPIR instead when:
-- Creating a **new feature from scratch** (no existing spec to amend)
-- Major architecture changes (scope too large for amendment)
-- Unclear requirements needing exploration
-- > 300 lines of code
-- Multiple stakeholders need alignment
-
-### Cannot Use TICK when:
-- No relevant SPIR spec exists (create a new SPIR spec instead)
-- Target spec is not yet `integrated` (complete the SPIR cycle first)
-
-## Amendment Workflow
-
-### Phase 1: Identify Target Spec
-
-**Input**: User describes the amendment needed
-
-**Agent Actions**:
-1. Analyze the amendment requirements
-2. Search for the relevant existing spec to amend
-3. Verify the spec exists and is `integrated`
-4. Load current spec and plan documents
-5. Determine next TICK number (count existing TICK entries + 1)
-
-**Example**:
-```
-User: "Use TICK to add password reset to the auth system"
-Agent finds: specs/2-user-authentication.md (status: integrated)
-Agent determines: Next TICK is TICK-001 (first amendment)
-```
-
-### Phase 2: Specification Amendment (Autonomous)
-
-**Agent Actions**:
-1. Analyze what needs to change in the spec
-2. Update relevant sections of `specs/NNN-name.md`:
-   - Problem Statement (if scope expands)
-   - Success Criteria (if new criteria added)
-   - Solution Approaches (if design changes)
-   - Any other section that needs updating
-3. Add entry to "Amendments" section at bottom:
-   ```markdown
-   ### TICK-001: [Title] (YYYY-MM-DD)
-
-   **Summary**: [One-line description]
-
-   **Problem Addressed**:
-   [Why this amendment was needed]
-
-   **Spec Changes**:
-   - [Section]: [What changed]
-
-   **Plan Changes**:
-   - [Phase/steps]: [What was added/modified]
-
-   **Review**: See `reviews/NNN-name-tick-001.md`
-   ```
-4. **COMMIT**: `[TICK NNN-NNN] Spec: [description]`
-
-### Phase 3: Planning Amendment (Autonomous)
-
-**Agent Actions**:
-1. Update `plans/NNN-name.md` with new implementation steps
-2. Add/modify phases as needed
-3. Add entry to "Amendment History" section at bottom:
-   ```markdown
-   ### TICK-001: [Title] (YYYY-MM-DD)
-
-   **Changes**:
-   - [Phase added]: [Description]
-   - [Implementation steps]: [What was updated]
-
-   **Review**: See `reviews/NNN-name-tick-001.md`
-   ```
-4. **COMMIT**: `[TICK NNN-NNN] Plan: [description]`
-
-### Phase 4: Implementation (Autonomous)
-
-**Agent Actions**:
-1. Execute implementation steps from the plan
-2. Write code following fail-fast principles
-3. Test functionality
-4. **COMMIT**: `[TICK NNN-NNN] Impl: [description]`
-
-### Phase 5: Review (User Checkpoint)
-
-**Agent Actions**:
-1. Create review document: `reviews/NNN-name-tick-NNN.md`
-   - What was amended and why
-   - Changes made to spec and plan
-   - Implementation challenges
-   - Lessons learned
-2. **Multi-Agent Consultation** (MANDATORY):
-   - Consult GPT-5 AND Gemini Pro
-   - Focus: Code quality, missed issues, improvements
-   - Update review with consultation feedback
-3. **Update Architecture Documentation** (if applicable)
-4. **COMMIT**: `[TICK NNN-NNN] Review: [description]`
-5. **PRESENT TO USER**: Show summary with consultation insights
-
-**User Actions**:
-- Review completed work
-- Provide feedback
-- Request changes OR approve
-
-**If Changes Requested**:
-- Agent makes changes
-- Commits: `[TICK NNN-NNN] Fixes: [description]`
-- Updates review document
-- Repeats until user approval
-
-## File Naming Convention
-
-TICK amendments modify existing files and create new review files:
-
-| File Type | Pattern | Example |
-|-----------|---------|---------|
-| Spec (modified) | `specs/NNN-name.md` | `specs/2-user-authentication.md` |
-| Plan (modified) | `plans/NNN-name.md` | `plans/2-user-authentication.md` |
-| Review (new) | `reviews/NNN-name-tick-NNN.md` | `reviews/2-user-authentication-tick-001.md` |
-
-**Note**: Spec and plan files are modified in-place. Only the review file is new.
-
-## Git Commit Strategy
-
-**TICK commits reference the parent spec and TICK number**:
-
-```
-[TICK 2-001] Spec: Add password reset feature
-[TICK 2-001] Plan: Add password reset implementation
-[TICK 2-001] Impl: Add password reset feature
-[TICK 2-001] Review: Password reset implementation
-[TICK 2-001] Fixes: Address review feedback
-```
-
-The format `[TICK <parent>-<tick>]` identifies:
-- `<parent>`: Parent spec number (e.g., 2)
-- `<tick>`: TICK amendment number (e.g., 001, 002, 003)
-
-## Key Differences from SPIR
-
-| Aspect | SPIR | TICK |
-|--------|--------|------|
-| Purpose | Create new features | Amend existing features |
-| File creation | Creates new spec/plan/review | Modifies spec/plan, creates review |
-| Sequential numbering | Gets new number (1, 2) | Uses parent's number (2-001) |
-| Scope | Any size | < 300 lines typically |
-| Prerequisites | None | Existing integrated spec required |
-| User checkpoints | Multiple (spec, plan, phases) | Two (start, end) |
-| Multi-agent consultation | Throughout | End only (review) |
-
-## Protocol Selection Guide
-
-```
-Is there an existing spec to amend?
-├── NO → Use SPIR (create new spec)
-└── YES → Is it integrated?
-    ├── NO → Complete SPIR cycle first
-    └── YES → Is the change small (<300 LOC)?
-        ├── YES → Use TICK (amend existing spec)
-        └── NO → Use SPIR (scope too large)
-```
-
-**Mental Model**:
-- SPIR = Create new feature from scratch
-- TICK = Refine/extend existing feature
-
-## Example TICK Workflow
-
-**User**: "Add password reset to the user authentication system"
-
-**Agent**:
-1. **Identify**: Finds `specs/2-user-authentication.md` (integrated)
-2. **Amend Spec** (30 seconds):
-   - Updates Success Criteria with password reset requirements
-   - Adds TICK-001 entry to Amendments section
-   - Commit: `[TICK 2-001] Spec: Add password reset feature`
-3. **Amend Plan** (30 seconds):
-   - Adds Phase 4: Password Reset Email Service
-   - Adds TICK-001 entry to Amendment History
-   - Commit: `[TICK 2-001] Plan: Add password reset implementation`
-4. **Implement** (2 minutes):
-   - Creates password reset endpoint
-   - Implements email service
-   - Tests functionality
-   - Commit: `[TICK 2-001] Impl: Add password reset feature`
-5. **Review** (1 minute):
-   - Creates `reviews/2-user-authentication-tick-001.md`
-   - Runs 3-way consultation (Gemini, Codex, Claude)
-   - Commit: `[TICK 2-001] Review: Password reset implementation`
-   - Shows user the completed work
-
-**Total Time**: ~4 minutes for simple amendment
-
-## Multiple TICKs per Spec
-
-A single spec can have multiple TICK amendments over its lifetime:
-
-```markdown
-## Amendments
-
-### TICK-003: Add MFA support (2025-03-15)
-...
-
-### TICK-002: Add session timeout (2025-02-01)
-...
-
-### TICK-001: Add password reset (2025-01-15)
-...
-```
-
-TICKs are listed in reverse chronological order (newest first). Each TICK builds on the previous state of the spec.
-
-## Migration from Standalone TICK
-
-Existing standalone TICK projects (created before this protocol change) are grandfathered in. No migration required.
-
-**Optional Migration** (if desired):
-1. Identify the "parent spec" the TICK logically extends
-2. Move TICK content into an amendment entry in the parent spec
-3. Archive the standalone files with a note: "Migrated to spec NNN as TICK-NNN"
-4. Update the GitHub Issue to reflect the change
-
-## Benefits
-
-1. **Single source of truth**: Spec file shows complete feature evolution
-2. **Clear history**: Amendments section documents all changes chronologically
-3. **Reduced fragmentation**: Related work stays together
-4. **Simpler mental model**: "New vs amendment" is clearer than "SPIR vs TICK"
-5. **Preserved context**: Looking at a spec shows all refinements
-
-## Limitations
-
-1. **Requires existing spec**: Cannot use TICK for greenfield work
-2. **Spec can grow large**: Many TICKs add content (consider: >5 TICKs suggests need for new spec)
-3. **Merge conflicts**: Multiple TICKs on same spec may conflict
-4. **No course correction**: Can't adjust mid-implementation
-
-## Best Practices
-
-1. **Verify spec is integrated**: Never TICK a spec that isn't complete
-2. **Keep TICKs small**: If scope grows, consider new SPIR spec
-3. **Clear summaries**: Amendment entries should be self-explanatory
-4. **Test before review**: Always test functionality before presenting
-5. **Honest documentation**: Document all deviations in review
-
-## Templates
-
-TICK uses the standard SPIR templates with amendments sections:
-- Spec template: `codev/protocols/spir/templates/spec.md` (includes Amendments section)
-- Plan template: `codev/protocols/spir/templates/plan.md` (includes Amendment History section)
-- Review template: `codev/protocols/tick/templates/review.md` (TICK-specific)

package/skeleton/protocols/tick/templates/plan.md

@@ -1,67 +0,0 @@
-# TICK Plan: [Title]
-
-## Metadata
-- **ID**: ####-[short-name]
-- **Protocol**: TICK
-- **Specification**: [Link to spec file]
-- **Created**: [YYYY-MM-DD]
-- **Status**: autonomous
-
-## Implementation Approach
-[Brief description of chosen approach from specification]
-
-## Implementation Steps
-
-### Step 1: [Action]
-**Files**: [list files to create/modify]
-**Changes**: [what to do]
-
-### Step 2: [Action]
-**Files**: [list files to create/modify]
-**Changes**: [what to do]
-
-### Step 3: [Action]
-**Files**: [list files to create/modify]
-**Changes**: [what to do]
-
-[Add more steps as needed - keep sequential]
-
-## Files to Create/Modify
-
-### New Files
-- `path/to/file1.ts` - [purpose]
-- `path/to/file2.ts` - [purpose]
-
-### Modified Files
-- `path/to/existing1.ts` - [what changes]
-- `path/to/existing2.ts` - [what changes]
-
-## Testing Strategy
-
-### Manual Testing
-1. [Test scenario 1]
-2. [Test scenario 2]
-3. [Test scenario 3]
-
-### Automated Tests (if applicable)
-- [Test file 1: what to test]
-- [Test file 2: what to test]
-
-## Success Criteria
-- [ ] All steps completed
-- [ ] Manual tests pass
-- [ ] No breaking changes
-- [ ] Code committed
-
-## Risks
-| Risk | If Occurs |
-|------|-----------|
-| [Risk 1] | [Fallback plan] |
-| [Risk 2] | [Fallback plan] |
-
-## Dependencies
-- [Dependency 1]
-- [Dependency 2]
-
-## Notes
-[Any implementation notes or considerations]