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

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]

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

@@ -1,89 +0,0 @@
-# TICK Review: [Title]
-
-## Metadata
-- **ID**: ####-[short-name]
-- **Protocol**: TICK
-- **Date**: [YYYY-MM-DD]
-- **Specification**: [Link to spec file]
-- **Plan**: [Link to plan file]
-- **Status**: [completed/needs-fixes]
-
-## Implementation Summary
-[Brief description of what was implemented]
-
-## Success Criteria Status
-- [ ] [Criterion 1 from spec]
-- [ ] [Criterion 2 from spec]
-- [ ] [Criterion 3 from spec]
-- [ ] Tests passed
-- [ ] No breaking changes
-
-## Files Changed
-
-### Created
-- `path/to/file1.ts` - [purpose]
-- `path/to/file2.ts` - [purpose]
-
-### Modified
-- `path/to/existing1.ts` - [changes made]
-- `path/to/existing2.ts` - [changes made]
-
-## Deviations from Plan
-[None if plan was followed exactly, otherwise list what changed and why]
-
-## Testing Results
-
-### Manual Tests
-1. [Scenario 1] - ✅/❌
-2. [Scenario 2] - ✅/❌
-3. [Scenario 3] - ✅/❌
-
-### Automated Tests (if applicable)
-- [Test result summary]
-
-## Challenges Encountered
-1. [Challenge 1]
-   - **Solution**: [How resolved]
-2. [Challenge 2]
-   - **Solution**: [How resolved]
-
-## Lessons Learned
-
-### What Went Well
-- [Success point 1]
-- [Success point 2]
-
-### What Could Improve
-- [Improvement area 1]
-- [Improvement area 2]
-
-## Consultation Feedback
-
-[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."]
-
-### [Phase] Phase (Round N)
-
-#### Gemini
-- **Concern**: [Summary of concern]
-  - **Addressed**: [What was changed]
-
-#### Codex
-- **Concern**: [Summary of concern]
-  - **Rebutted**: [Why current approach is correct]
-
-#### Claude
-- No concerns raised (APPROVE)
-
-## TICK Protocol Feedback
-- **Autonomous execution**: [Worked well / Issues encountered]
-- **Single-phase approach**: [Appropriate / Should have used SPIR]
-- **Speed vs quality trade-off**: [Balanced / Too fast / Too slow]
-- **End-only consultation**: [Caught issues / Missed opportunities]
-
-## Follow-Up Actions
-- [ ] [Any remaining work]
-- [ ] [Technical debt created]
-- [ ] [Future enhancements]
-
-## Conclusion
-[Brief summary of outcome and whether TICK was appropriate for this task]

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

@@ -1,61 +0,0 @@
-# TICK Specification: [Title]
-
-## Metadata
-- **ID**: ####-[short-name]
-- **Protocol**: TICK
-- **Created**: [YYYY-MM-DD]
-- **Status**: autonomous
-
-## Task Description
-[What needs to be built? Be specific and concise.]
-
-## Scope
-
-### In Scope
-- [Feature/change 1]
-- [Feature/change 2]
-- [Feature/change 3]
-
-### Out of Scope
-- [What we're NOT doing]
-- [Future considerations]
-
-## Success Criteria
-- [ ] [Specific, testable criterion 1]
-- [ ] [Specific, testable criterion 2]
-- [ ] [Specific, testable criterion 3]
-- [ ] Tests pass
-- [ ] No breaking changes
-
-## Constraints
-- [Technical limitation 1]
-- [Technical limitation 2]
-- [Time/scope constraints]
-
-## Assumptions
-- [Assumption 1]
-- [Assumption 2]
-- [Dependencies]
-
-## Implementation Approach
-[Brief description of how this will be implemented - single approach only]
-
-### Key Changes
-- [File/component 1: what will change]
-- [File/component 2: what will change]
-- [File/component 3: what will change]
-
-## Risks
-| Risk | Mitigation |
-|------|------------|
-| [Risk 1] | [How to handle] |
-| [Risk 2] | [How to handle] |
-
-## Testing Approach
-### Test Scenarios
-1. [Happy path scenario]
-2. [Edge case scenario]
-3. [Error scenario]
-
-## Notes
-[Any additional context]