@cluesmith/codev 1.1.0 → 1.2.0

package/templates/protocols/tick/protocol.md

@@ -1,250 +0,0 @@
-# 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/roles/architect.md

@@ -1,230 +0,0 @@
-# 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
-```