@cluesmith/codev 1.1.0 → 1.1.1

package/skeleton/protocols/tick/protocol.md

@@ -0,0 +1,277 @@
+# TICK Protocol
+**T**ask **I**dentification, **C**oding, **K**ickout
+
+## Overview
+
+TICK is an **amendment workflow** for existing SPIDER 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. SPIDER is for *creating* new specs.
+
+**Key Insight**: TICKs are not small SPIDERs - they're amendments to existing SPIDERs. This eliminates the "TICK vs SPIDER" decision problem and keeps related work together.
+
+## When to Use TICK
+
+### Use TICK when:
+- Making **amendments to an existing SPIDER 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 SPIDER 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 SPIDER spec exists (create a new SPIDER spec instead)
+- Target spec is not yet `integrated` (complete the SPIDER 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/0002-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/####-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/####-name-tick-001.md`
+   ```
+4. **COMMIT**: `[TICK ####-NNN] Spec: [description]`
+
+### Phase 3: Planning Amendment (Autonomous)
+
+**Agent Actions**:
+1. Update `plans/####-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/####-name-tick-001.md`
+   ```
+4. **COMMIT**: `[TICK ####-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] Impl: [description]`
+
+### Phase 5: Review (User Checkpoint)
+
+**Agent Actions**:
+1. Create review document: `reviews/####-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] 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] 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/####-name.md` | `specs/0002-user-authentication.md` |
+| Plan (modified) | `plans/####-name.md` | `plans/0002-user-authentication.md` |
+| Review (new) | `reviews/####-name-tick-NNN.md` | `reviews/0002-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 0002-001] Spec: Add password reset feature
+[TICK 0002-001] Plan: Add password reset implementation
+[TICK 0002-001] Impl: Add password reset feature
+[TICK 0002-001] Review: Password reset implementation
+[TICK 0002-001] Fixes: Address review feedback
+```
+
+The format `[TICK ####-NNN]` identifies:
+- `####`: Parent spec number (e.g., 0002)
+- `NNN`: TICK amendment number (e.g., 001, 002, 003)
+
+## Key Differences from SPIDER
+
+| Aspect | SPIDER | 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 (0001, 0002) | Uses parent's number (0002-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 SPIDER (create new spec)
+└── YES → Is it integrated?
+    ├── NO → Complete SPIDER cycle first
+    └── YES → Is the change small (<300 LOC)?
+        ├── YES → Use TICK (amend existing spec)
+        └── NO → Use SPIDER (scope too large)
+```
+
+**Mental Model**:
+- SPIDER = 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/0002-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 0002-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 0002-001] Plan: Add password reset implementation`
+4. **Implement** (2 minutes):
+   - Creates password reset endpoint
+   - Implements email service
+   - Tests functionality
+   - Commit: `[TICK 0002-001] Impl: Add password reset feature`
+5. **Review** (1 minute):
+   - Creates `reviews/0002-user-authentication-tick-001.md`
+   - Runs 3-way consultation (Gemini, Codex, Claude)
+   - Commit: `[TICK 0002-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 #### as TICK-NNN"
+4. Update projectlist.md 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 "SPIDER 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 SPIDER 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 SPIDER templates with amendments sections:
+- Spec template: `codev/protocols/spider/templates/spec.md` (includes Amendments section)
+- Plan template: `codev/protocols/spider/templates/plan.md` (includes Amendment History section)
+- Review template: `codev/protocols/tick/templates/review.md` (TICK-specific)

package/skeleton/resources/lessons-learned.md

@@ -0,0 +1,30 @@
+# Lessons Learned
+
+Consolidated wisdom extracted from review documents. Updated during MAINTAIN protocol runs.
+
+---
+
+## Testing
+
+<!-- Add lessons about testing practices -->
+
+## Architecture
+
+<!-- Add lessons about architectural decisions -->
+
+## Process
+
+<!-- Add lessons about development process -->
+
+## Documentation
+
+<!-- Add lessons about documentation practices -->
+
+## Tools
+
+<!-- Add lessons about tooling -->
+
+---
+
+*Last updated: YYYY-MM-DD*
+*Source: codev/reviews/*

package/skeleton/resources/workflow-reference.md

@@ -0,0 +1,229 @@
+# Architect-Builder Workflow Reference
+
+Quick reference for the 7-stage project workflow. For protocol details, see `codev/protocols/spider/protocol.md`.
+
+## Workflow Overview
+
+```
+              CONCEPTION                    PLANNING                     EXECUTION
+┌─────────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                     │
+│  → 1. CONCEIVED                                                                     │
+│         User describes project concept                                              │
+│         Architect adds to projectlist, writes spec                                  │
+│         Architect does 3-way spec review                                            │
+│         ⏸️  HUMAN GATE: Approve spec                                                │
+│                                                                                     │
+│  → 2. SPECIFIED                                                                     │
+│         Human approves spec                                                         │
+│         Architect writes plan                                                       │
+│         Architect does 3-way plan review                                            │
+│         Human reviews and approves plan                                             │
+│                                                                                     │
+│  → 3. PLANNED                                                                       │
+│         Architect commits spec + plan to main                                       │
+├─────────────────────────────────────────────────────────────────────────────────────┤
+│                               IMPLEMENTATION                                        │
+├─────────────────────────────────────────────────────────────────────────────────────┤
+│  → 4. IMPLEMENTING                                                                  │
+│         Architect spawns builder: af spawn -p XXXX                                  │
+│         Builder reads spec and plan                                                 │
+│         For each phase: Implement → Defend → Evaluate                               │
+│         Builder commits after each phase                                            │
+│                                                                                     │
+│  → 5. IMPLEMENTED                                                                   │
+│         Builder writes review doc                                                   │
+│         Builder creates PR, notifies architect                                      │
+├─────────────────────────────────────────────────────────────────────────────────────┤
+│                        HANDOFF / INTEGRATION                                        │
+├─────────────────────────────────────────────────────────────────────────────────────┤
+│  → 6. COMMITTED                                                                     │
+│         Architect does 3-way integration review                                     │
+│         Architect iterates with builder via PR comments                             │
+│         Architect tells builder to merge                                            │
+│         Builder merges PR (NO --delete-branch flag)                                 │
+│         Architect cleans up builder                                                 │
+│                                                                                     │
+│         ⏸️  HUMAN GATE: Validate in production                                      │
+│  → 7. INTEGRATED                                                                    │
+│         Human validates and marks as integrated                                     │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Stage Quick Reference
+
+| Stage | Status | Actor | Key Action | Exit Condition |
+|-------|--------|-------|------------|----------------|
+| 1 | conceived | Architect | Write spec, 3-way review | Human approves spec |
+| 2 | specified | Human + Architect | Write plan, 3-way review | Human approves plan |
+| 3 | planned | Architect | Commit spec + plan | Committed to main |
+| 4 | implementing | Builder | IDE loop per phase | All phases complete |
+| 5 | implemented | Builder | Write review, create PR | PR created |
+| 6 | committed | Architect + Builder | Integration review, merge | PR merged |
+| 7 | integrated | Human | Validate production | Human confirms |
+
+## Human Gates
+
+There are **two points where only a human can advance the workflow**:
+
+1. **conceived → specified**: Human must approve the specification
+2. **committed → integrated**: Human must validate production deployment
+
+AI agents must stop and wait for human action at these gates.
+
+## Common Commands
+
+### Architect Commands
+
+```bash
+# Start the dashboard
+af start
+
+# Spawn a builder for a project
+af spawn -p 0044
+
+# Check all builder statuses
+af status
+
+# Send message to builder
+af send 0044 "Check PR comments and address feedback"
+
+# Open a file for review
+af open codev/specs/0044-name.md
+
+# Clean up after merge
+af cleanup -p 0044
+
+# Stop everything
+af stop
+```
+
+### Builder Commands
+
+```bash
+# Check your own status
+af status
+
+# Send message to architect
+af send architect "Question about the spec..."
+
+# Open a file in the annotation viewer
+af open src/path/to/file.ts
+```
+
+### Consultation Commands
+
+```bash
+# Spec review (during Stage 1)
+consult --model gemini --type spec-review spec 0044
+consult --model codex --type spec-review spec 0044
+
+# Plan review (during Stage 2)
+consult --model gemini --type plan-review plan 0044
+consult --model codex --type plan-review plan 0044
+
+# Implementation review (during Stage 4, after each phase)
+consult --model gemini --type impl-review spec 0044
+consult --model codex --type impl-review spec 0044
+
+# PR ready review (during Stage 5)
+consult --model gemini --type pr-ready pr 88
+consult --model codex --type pr-ready pr 88
+
+# Integration review (during Stage 6)
+consult --model gemini --type integration-review pr 88
+consult --model codex --type integration-review pr 88
+
+# Parallel 3-way reviews (run all three concurrently)
+consult --model gemini --type spec-review spec 0044 &
+consult --model codex --type spec-review spec 0044 &
+consult --model claude --type spec-review spec 0044 &
+wait
+```
+
+## Review Types
+
+| Type | When Used | Focus |
+|------|-----------|-------|
+| `spec-review` | Stage 1 | Requirements clarity, completeness, feasibility |
+| `plan-review` | Stage 2 | Implementation approach, phase breakdown, risk assessment |
+| `impl-review` | Stage 4 | Code quality, test coverage, spec adherence |
+| `pr-ready` | Stage 5 | Final self-check before PR creation |
+| `integration-review` | Stage 6 | System fit, architectural consistency, side effects |
+
+## Builder Lifecycle
+
+```
+spawning → implementing → blocked → implementing → pr-ready → complete
+                ↑______________|
+```
+
+| Status | Meaning |
+|--------|---------|
+| `spawning` | Worktree created, builder starting up |
+| `implementing` | Actively working on the spec |
+| `blocked` | Stuck, needs architect help |
+| `pr-ready` | Implementation complete, ready for review |
+| `complete` | Merged, worktree can be cleaned up |
+
+## Git Workflow
+
+### Branch Naming
+```
+builder/XXXX-spec-name
+```
+
+### Commit Messages
+```
+[Spec XXXX][Implement] Phase description
+[Spec XXXX][Defend] Add tests for phase
+[Spec XXXX][Review] Add lessons learned
+```
+
+### PR Merge (Builder)
+```bash
+# CORRECT - preserves branch for worktree
+gh pr merge N --merge
+
+# WRONG - breaks worktree
+gh pr merge N --merge --delete-branch
+```
+
+### Post-Merge Cleanup (Architect)
+```bash
+git pull                    # Get merged changes
+af cleanup -p XXXX          # Clean up builder worktree
+```
+
+## Troubleshooting
+
+### Builder Reports Blocked
+
+1. Check builder terminal for blocker message
+2. Review any `// REVIEW(@architect):` comments in code
+3. Provide guidance via `af send XXXX "guidance here"`
+4. Builder will resume work after receiving help
+
+### PR Has Conflicts
+
+1. Architect: `git pull` on main
+2. Architect: Resolve conflicts or instruct builder
+3. Builder: Rebase or merge main into branch
+4. Builder: Force push if needed
+
+### Builder Worktree Broken
+
+```bash
+# Check worktree status
+git worktree list
+
+# Force cleanup (only if work is committed/pushed)
+af cleanup -p XXXX --force
+```
+
+## Related Documentation
+
+- Full SPIDER protocol: `codev/protocols/spider/protocol.md`
+- Builder role: `codev/roles/builder.md`
+- Architect role: `codev/roles/architect.md`
+- Consultant role: `codev/roles/consultant.md`

package/{templates → skeleton}/roles/architect.md

@@ -2,6 +2,8 @@
 
 The Architect is the orchestrating agent that manages the overall development process, breaks down work into discrete tasks, spawns Builder agents, and integrates their output.
 
+> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
+
 ## Output Formatting
 
 When referencing files that the user may want to review, format them as clickable URLs using the dashboard's open-file endpoint:

package/{templates → skeleton}/roles/builder.md

@@ -2,6 +2,8 @@
 
 A Builder is a focused implementation agent that works on a single spec in an isolated git worktree. Builders are spawned by the Architect and report their status back.
 
+> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
+
 ## Output Formatting
 
 When referencing files that the user may want to review, format them as clickable URLs using the dashboard's open-file endpoint:

package/skeleton/roles/review-types/impl-review.md

@@ -0,0 +1,56 @@
+# Implementation Review Prompt
+
+## Context
+You are reviewing implementation work at Stage 4 (IMPLEMENTING) of the workflow. A builder has completed a phase (Implement + Defend) and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+
+## Focus Areas
+
+1. **Spec Adherence**
+   - Does the implementation fulfill the spec requirements for this phase?
+   - Are acceptance criteria met?
+   - Are there deviations from the spec that need explanation?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+   - Does it follow project conventions?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+   - Are tests testing the right things (behavior, not implementation)?
+   - Would the tests catch regressions?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - Are there deviations that make sense?
+   - Are there plan items skipped or partially completed?
+
+## 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`: Phase is complete, builder can proceed
+- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but note feedback
+
+## Notes
+
+- This is a phase-level review, not the final PR review
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/roles/review-types/integration-review.md

@@ -0,0 +1,68 @@
+# Integration Review Prompt
+
+## Context
+You are performing an integration review at Stage 6 (COMMITTED) of the workflow. The builder has created a PR and you are evaluating whether this change fits well into the broader system. This is the architect's review, focusing on how the change integrates rather than whether it works.
+
+## Focus Areas
+
+1. **Architectural Fit**
+   - Does this change follow existing patterns in the codebase?
+   - Are there inconsistencies with how similar things are done elsewhere?
+   - Does it introduce new patterns that should be adopted more broadly?
+   - Are dependencies appropriate and minimal?
+
+2. **System Impact**
+   - What other parts of the system might be affected?
+   - Are there potential side effects not addressed?
+   - Does this break any existing functionality?
+   - Are there performance implications?
+
+3. **API/Interface Quality**
+   - Are new interfaces well-designed and consistent?
+   - Will this be easy for other developers to use?
+   - Is it properly documented for consumers?
+   - Does it follow existing conventions?
+
+4. **Maintenance Burden**
+   - Is this code maintainable by others?
+   - Are there any "clever" solutions that should be simplified?
+   - Is the complexity justified?
+   - Will this be easy to debug when issues arise?
+
+5. **Migration/Compatibility**
+   - Are there backward compatibility concerns?
+   - Is migration path clear for existing users?
+   - Are breaking changes properly communicated?
+
+## 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]
+...
+
+INTEGRATION_NOTES:
+- [Note about system integration]
+- [Note about follow-up work needed]
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to merge
+- `REQUEST_CHANGES`: Integration issues that must be addressed
+- `COMMENT`: Suggestions for improvement, can merge but consider feedback
+
+## Notes
+
+- The implementation has already been reviewed - don't re-review code quality
+- Focus on "how does this fit the system" not "does this work"
+- Consider: Will I regret merging this in 6 months?
+- If requesting changes, be specific about what needs to change
+- INTEGRATION_NOTES can include suggestions for follow-up specs