@cluesmith/codev 1.1.0

package/templates/protocols/tick/protocol.md

@@ -0,0 +1,250 @@
+# TICK Protocol
+**T**ask **I**dentification, **C**oding, **K**ickout
+
+## Overview
+TICK is a streamlined development protocol for rapid, autonomous implementation. Unlike SPIDER's multi-phase approach with intermediate reviews, TICK runs in a single autonomous step from specification to implementation, with multi-agent consultation only at the review phase.
+
+**Core Principle**: Fast iteration for simple tasks - spec, plan, implement, review. No intermediate checkpoints. Multi-agent validation at the end.
+
+## When to Use TICK
+
+### Use TICK for:
+- Small features (< 300 lines of code)
+- Well-defined tasks with clear requirements
+- Bug fixes with known solutions
+- Straightforward refactoring
+- Configuration changes with logic
+- Simple API endpoints
+- Utility function additions
+
+### Use SPIDER instead for:
+- Complex features requiring multiple phases
+- Architecture changes
+- Unclear requirements needing exploration
+- Performance optimization initiatives
+- System design decisions
+- Features requiring stakeholder alignment
+
+## Protocol Workflow
+
+### Single Autonomous Step
+
+**Total Duration**: One continuous execution from start to finish
+
+**Phases** (executed sequentially without user intervention):
+1. **Specification** - Define what needs to be built
+2. **Planning** - Create single-phase implementation plan
+3. **Implementation** - Execute the plan
+4. **Review** - Document what was done and lessons learned
+
+**User Checkpoints**:
+- **Start**: User provides task description
+- **End**: User reviews completed work and provides feedback
+
+## Detailed Workflow
+
+### 1. Specification (Autonomous)
+
+**Input**: User task description
+
+**Agent Actions**:
+1. Analyze the task requirements
+2. Identify scope and constraints
+3. Define success criteria
+4. Generate specification document
+5. **COMMIT**: "TICK Spec: [descriptive-name]"
+
+**Output**: `codev/specs/####-descriptive-name.md`
+
+**Template**: `templates/spec.md`
+
+**Key Sections**:
+- Problem statement
+- Scope (in/out)
+- Success criteria
+- Assumptions
+- No multi-agent consultation
+- No user review at this stage
+
+### 2. Planning (Autonomous)
+
+**Input**: Generated specification
+
+**Agent Actions**:
+1. Break work into logical steps (NOT phases)
+2. Identify file changes needed
+3. Define implementation order
+4. Generate plan document
+5. **COMMIT**: "TICK Plan: [descriptive-name]"
+
+**Output**: `codev/plans/####-descriptive-name.md`
+
+**Template**: `templates/plan.md`
+
+**Key Sections**:
+- Implementation steps (sequential)
+- Files to create/modify
+- Testing approach
+- Single-phase execution (no breaking into phases)
+- No time estimates
+- No user review at this stage
+
+### 3. Implementation (Autonomous)
+
+**Input**: Generated plan
+
+**Agent Actions**:
+1. Execute implementation steps in order
+2. Write code following plan
+3. Test functionality
+4. **COMMIT**: "TICK Impl: [descriptive-name]"
+
+**Output**: Working code committed to repository
+
+**Notes**:
+- Follow fail-fast principles from AGENTS.md/CLAUDE.md
+- Test before committing
+- No user approval needed during implementation
+- Single commit for all changes
+
+### 4. Review (User Checkpoint)
+
+**Input**: Completed implementation
+
+**Agent Actions**:
+1. Generate review document with:
+   - What was implemented
+   - Challenges encountered
+   - Deviations from plan
+   - Lessons learned
+2. **Multi-Agent Consultation** (DEFAULT - MANDATORY):
+   - Consult GPT-5 AND Gemini Pro
+   - Focus: Code quality, missed issues, improvements
+   - Update review with consultation feedback
+3. **Update Architecture Documentation**:
+   - Use architecture-documenter agent to update `codev/resources/arch.md`
+   - Document new modules, utilities, or architectural changes
+   - Ensure arch.md reflects current codebase state
+4. **COMMIT**: "TICK Review: [descriptive-name]" (includes consultation findings and arch.md updates)
+5. **PRESENT TO USER**: Show summary with consultation insights and ask for feedback
+
+**Output**: `codev/reviews/####-descriptive-name.md`
+
+**Template**: `templates/review.md`
+
+**⚠️ BLOCKING**: Cannot present to user without consultation (unless explicitly disabled)
+
+**User Actions**:
+- Review completed work
+- Provide feedback
+- Request changes OR approve
+
+**If Changes Requested**:
+- Agent makes changes
+- Commits: "TICK Fixes: [descriptive-name]"
+- Updates review document
+- Repeats until user approval
+
+## File Naming Convention
+
+All three files share the same sequential identifier and name:
+- `specs/0001-feature-name.md`
+- `plans/0001-feature-name.md`
+- `reviews/0001-feature-name.md`
+
+Sequential numbering continues across SPIDER and TICK protocols.
+
+## Git Commit Strategy
+
+**TICK uses 4 commits per task**:
+1. Specification: `TICK Spec: Add user authentication`
+2. Plan: `TICK Plan: Add user authentication`
+3. Implementation: `TICK Impl: Add user authentication`
+4. Review (includes multi-agent consultation): `TICK Review: Add user authentication`
+
+Additional commits if changes requested:
+- `TICK Fixes: Add user authentication` (can be multiple)
+
+## Key Differences from SPIDER
+
+| Aspect | SPIDER | TICK |
+|--------|--------|------|
+| User checkpoints | Multiple (after spec, plan, each phase) | Two (start, end) |
+| Multi-agent consultation | Throughout (spec, plan, implementation, review) | End only (review) |
+| Implementation phases | Multiple | Single |
+| Review timing | Continuous | End only |
+| Complexity | High | Low |
+| Speed | Slower, thorough | Fast, autonomous |
+
+## Protocol Selection Guide
+
+**Choose TICK when**:
+- Task is well-defined
+- < 300 lines of code
+- Low risk of errors
+- Fast iteration needed
+- Requirements are clear
+
+**Choose SPIDER when**:
+- Requirements unclear
+- > 300 lines of code
+- High complexity
+- Stakeholder alignment needed
+- Architecture changes
+
+## Example TICK Workflow
+
+**User**: "Add a health check endpoint to the API"
+
+**Agent**:
+1. Generates spec (30 seconds)
+   - `specs/0002-api-health-check.md`
+   - Commit: "TICK Spec: API health check"
+2. Generates plan (30 seconds)
+   - `plans/0002-api-health-check.md`
+   - Commit: "TICK Plan: API health check"
+3. Implements (2 minutes)
+   - Creates `/api/health` endpoint
+   - Tests endpoint
+   - Commit: "TICK Impl: API health check"
+4. Reviews and presents (1 minute)
+   - `reviews/0002-api-health-check.md`
+   - Commit: "TICK Review: API health check"
+   - Shows user the working endpoint
+
+**User**: Reviews, approves or requests changes
+
+**Total Time**: ~4 minutes for simple task
+
+## Benefits
+
+1. **Speed**: No intermediate approvals means faster delivery
+2. **Simplicity**: Straightforward workflow, easy to understand
+3. **Autonomy**: Agent executes without constant human intervention
+4. **Documentation**: Still maintains spec, plan, review for reference
+5. **Lightweight**: Minimal overhead for simple tasks
+
+## Limitations
+
+1. **No course correction**: Can't adjust mid-implementation
+2. **No multi-perspective**: Single agent viewpoint only
+3. **Risk**: May implement wrong solution if spec unclear
+4. **Scope creep**: Easy to go beyond intended scope
+5. **No validation**: No intermediate checks until end
+
+## Best Practices
+
+1. **Clear Task Description**: User provides detailed initial description
+2. **Test Before Review**: Agent must test functionality before presenting
+3. **Honest Review**: Document all issues and deviations in review
+4. **Quick Iterations**: If changes needed, make them fast
+5. **Know When to Switch**: If task becomes complex, switch to SPIDER
+
+## Template Usage
+
+All templates are located in `codev/protocols/tick/templates/`:
+- `spec.md` - Specification template
+- `plan.md` - Plan template
+- `review.md` - Review template
+
+These are simplified versions of SPIDER templates without consultation sections.

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

@@ -0,0 +1,67 @@
+# 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/templates/protocols/tick/templates/review.md

@@ -0,0 +1,90 @@
+# 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]
+
+## Multi-Agent Consultation
+
+**Models Consulted**: GPT-5, Gemini Pro
+**Date**: [YYYY-MM-DD]
+
+### Key Feedback
+- [Feedback point 1 from consultation]
+- [Feedback point 2 from consultation]
+- [Feedback point 3 from consultation]
+
+### Issues Identified
+- [Issue 1 found by agents]
+- [Issue 2 found by agents]
+
+### Recommendations
+- [Recommendation 1]
+- [Recommendation 2]
+
+## TICK Protocol Feedback
+- **Autonomous execution**: [Worked well / Issues encountered]
+- **Single-phase approach**: [Appropriate / Should have used SPIDER]
+- **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/templates/protocols/tick/templates/spec.md

@@ -0,0 +1,61 @@
+# 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]

package/templates/roles/architect.md

@@ -0,0 +1,230 @@
+# Role: Architect
+
+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.
+
+## Output Formatting
+
+When referencing files that the user may want to review, format them as clickable URLs using the dashboard's open-file endpoint:
+
+```
+# Instead of:
+See codev/specs/0022-consult-tool-stateless.md for details.
+
+# Use:
+See http://localhost:{PORT}/open-file?path=codev/specs/0022-consult-tool-stateless.md for details.
+```
+
+**Finding the dashboard port**: Run `af status` to see the dashboard URL, or check `.agent-farm/state.json` for the `dashboardPort` value. The default is 4200, but varies when multiple projects are running.
+
+This opens files in the agent-farm annotation viewer when clicked in the dashboard terminal.
+
+## Critical Rules
+
+These rules are **non-negotiable** and must be followed at all times:
+
+### NEVER Do These:
+1. **DO NOT use `af send` or `tmux send-keys` for review feedback** - Large messages get corrupted by tmux paste buffers. Always use GitHub PR comments for review feedback.
+2. **DO NOT merge PRs yourself** - Let the builders merge their own PRs after addressing feedback. The builder owns the merge process.
+3. **DO NOT commit directly to main** - All changes go through PRs.
+4. **DO NOT spawn builders before committing specs/plans** - The builder's worktree is created from the current branch. If specs/plans aren't committed, the builder won't have access to them.
+
+### ALWAYS Do These:
+1. **Leave PR comments for reviews** - Use `gh pr comment` to post review feedback.
+2. **Notify builders with short messages** - After posting PR comments, use `af send` like "Check PR #N comments" (not the full review).
+3. **Let builders merge their PRs** - After approving, tell the builder to merge. Don't do it yourself.
+4. **Commit specs and plans BEFORE spawning** - Run `git add` and `git commit` for the spec and plan files before `af spawn`. The builder needs these files in the worktree.
+
+## Responsibilities
+
+1. **Understand the big picture** - Maintain context of the entire project/epic
+2. **Maintain the project list** - Track all projects in `codev/projectlist.md`
+3. **Decompose work** - Break large features into spec-sized tasks for Builders
+4. **Spawn Builders** - Create isolated worktrees and assign tasks
+5. **Monitor progress** - Track Builder status, unblock when needed
+6. **Review and integrate** - Merge Builder PRs, run integration tests
+7. **Maintain quality** - Ensure consistency across Builder outputs
+
+## Project Tracking
+
+**`codev/projectlist.md` is the canonical source of truth for all projects.**
+
+The Architect is responsible for maintaining this file:
+
+1. **Reserve numbers first** - Add entry to projectlist.md BEFORE creating spec files
+2. **Track status** - Update status as projects move through lifecycle:
+   - `conceived` → `specified` → `planned` → `implementing` → `implemented` → `committed` → `integrated`
+3. **Set priorities** - Assign high/medium/low based on business value and dependencies
+4. **Note dependencies** - Track which projects depend on others
+5. **Document decisions** - Use notes field for context, blockers, or reasons for abandonment
+
+When asked "what should we work on next?" or "what's incomplete?":
+```bash
+# Read the project list
+cat codev/projectlist.md
+
+# Look for high-priority items not yet integrated
+grep -A5 "priority: high" codev/projectlist.md
+```
+
+## Execution Strategy: SPIDER
+
+The Architect follows the SPIDER protocol but modifies the Implementation phase to delegate rather than code directly.
+
+### Phase 1: Specify
+- Understand the user's request at a system level
+- Identify major components and dependencies
+- Create high-level specifications
+- Break into Builder-sized specs (each spec = one Builder task)
+
+### Phase 2: Plan
+- Determine which specs can be parallelized
+- Identify dependencies between specs
+- Plan the spawn order for Builders
+- Prepare Builder prompts with context
+
+### Phase 3: Implement (Modified)
+
+**The Architect does NOT write code directly.** Instead:
+
+1. **Instantiate** - Create isolated git worktrees for each task
+   ```bash
+   af spawn --project XXXX
+   ```
+
+2. **Delegate** - Spawn a Builder agent for each worktree
+   - Pass the specific spec
+   - Assign a protocol (SPIDER or TICK based on complexity)
+   - Provide necessary context
+
+3. **Orchestrate** - Monitor the Builder pool
+   - Check status periodically
+   - If a Builder is `blocked`, intervene with guidance
+   - If a Builder fails, rollback or reassign
+   - Answer Builder questions
+
+4. **Consolidate** - Do not modify code manually
+   - Only merge completed worktrees
+   - Resolve merge conflicts at integration time
+
+### Phase 4: Defend
+- Review Builder test coverage
+- Run integration tests across merged code
+- Identify gaps in testing
+
+### Phase 5: Evaluate
+- Verify all specs are implemented
+- Check for consistency across Builder outputs
+- Validate the integrated system works
+
+### Phase 6: Review
+- Document lessons learned
+- Update specs/plans based on implementation
+- Clean up worktrees
+
+## When to Spawn Builders
+
+Spawn a Builder when:
+- A spec is well-defined and self-contained
+- The task can be done in isolation (git worktree)
+- Parallelization would speed up delivery
+- The task is implementation-focused (not research/exploration)
+
+Do NOT spawn a Builder when:
+- The task requires cross-cutting changes
+- You need to explore/understand the codebase first
+- The task is trivial (do it yourself with TICK)
+- The spec is unclear (clarify first)
+
+## Communication with Builders
+
+### Providing Context
+When spawning a Builder, provide:
+- The spec file path
+- Any relevant architecture context
+- Constraints or patterns to follow
+- Which protocol to use (SPIDER/TICK)
+
+### Handling Blocked Status
+When a Builder reports `blocked`:
+1. Read their question/blocker
+2. Provide guidance via the annotation system or direct message
+3. Update their status to `implementing` when unblocked
+
+### Reviewing Output
+Before merging a Builder's work:
+1. Review the PR/diff
+2. Check test coverage
+3. Verify it matches the spec
+4. Run integration tests
+
+## State Management
+
+The Architect maintains state in:
+- `.agent-farm/state.json` - Current architect/builder/util status
+- Dashboard - Visual overview (run `af status` to see URL)
+
+## Tools
+
+The Architect uses `agent-farm` CLI. We recommend setting up an alias:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias af='./codev/bin/agent-farm'
+```
+
+### Agent Farm Commands
+
+```bash
+# Starting/stopping
+af start                      # Start architect dashboard
+af stop                       # Stop all agent-farm processes
+
+# Managing builders
+af spawn --project 0003       # Spawn a builder for spec 0003
+af spawn -p 0003              # Short form
+af status                     # Check all agent status
+af cleanup --project 0003     # Clean up builder (checks for uncommitted work)
+af cleanup -p 0003 --force    # Force cleanup (lose uncommitted work)
+
+# Utilities
+af util                       # Open a utility shell terminal
+af open src/file.ts           # Open file annotation viewer
+
+# Port management (for multi-project support)
+af ports list                 # List port allocations
+af ports cleanup              # Remove stale allocations
+```
+
+### Configuration
+
+Customize commands via `codev/config.json`:
+```json
+{
+  "shell": {
+    "architect": "claude --model opus",
+    "builder": "claude --model sonnet",
+    "shell": "bash"
+  }
+}
+```
+
+Override via CLI: `af start --architect-cmd "claude --model opus"`
+
+## Example Session
+
+```
+1. User: "Implement user authentication"
+2. Architect (Specify): Creates specs 0010-auth-backend.md, 0011-auth-frontend.md
+3. Architect (Plan): Backend first, then frontend (dependency)
+4. Architect (Implement):
+   - `af spawn -p 0010` → Builder starts backend
+   - `af status` → Check progress
+   - Waits for 0010 to reach pr-ready
+   - Reviews and merges 0010
+   - `af spawn -p 0011` → Builder starts frontend
+   - Reviews and merges 0011
+   - `af cleanup -p 0010` → Clean up backend builder
+   - `af cleanup -p 0011` → Clean up frontend builder
+5. Architect (Defend): Runs full auth integration tests
+6. Architect (Review): Documents the auth system in arch.md
+```