@cluesmith/codev 1.1.0

package/templates/DEPENDENCIES.md

@@ -0,0 +1,344 @@
+# Codev Dependencies
+
+This document describes all dependencies required to run Codev and Agent Farm.
+
+## Quick Check
+
+Run the doctor script to verify your installation:
+
+```bash
+./codev/bin/codev-doctor
+```
+
+---
+
+## Core Dependencies (Required)
+
+These are required for Agent Farm to function.
+
+### Node.js
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | 18.0.0 |
+| Purpose | Runtime for Agent Farm server |
+
+**Installation:**
+
+```bash
+# macOS
+brew install node
+
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Verify
+node --version  # Should show v18.x or higher
+```
+
+### tmux
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | 3.0 |
+| Purpose | Terminal multiplexer for managing builder sessions |
+
+**Installation:**
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt install tmux
+
+# Verify
+tmux -V  # Should show tmux 3.x or higher
+```
+
+### ttyd
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | 1.7.0 |
+| Purpose | Web-based terminal for dashboard access |
+
+**Installation:**
+
+```bash
+# macOS
+brew install ttyd
+
+# Ubuntu/Debian (build from source)
+sudo apt install build-essential cmake git libjson-c-dev libwebsockets-dev
+git clone https://github.com/tsl0922/ttyd.git
+cd ttyd && mkdir build && cd build
+cmake .. && make && sudo make install
+
+# Verify
+ttyd --version  # Should show 1.7.x or higher
+```
+
+### git
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | 2.5.0 |
+| Purpose | Version control, worktree support for builders |
+
+**Installation:**
+
+```bash
+# macOS (usually pre-installed with Xcode)
+xcode-select --install
+
+# Ubuntu/Debian
+sudo apt install git
+
+# Verify
+git --version  # Should show 2.5.x or higher
+```
+
+### gh (GitHub CLI)
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | Latest |
+| Purpose | Creating PRs, managing issues, GitHub operations |
+
+**Installation:**
+
+```bash
+# macOS
+brew install gh
+
+# Ubuntu/Debian
+(type -p wget >/dev/null || sudo apt install wget -y) \
+  && sudo mkdir -p -m 755 /etc/apt/keyrings \
+  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+  && sudo apt update \
+  && sudo apt install gh -y
+
+# After installation, authenticate:
+gh auth login
+
+# Verify
+gh auth status  # Should show "Logged in to github.com"
+```
+
+### Python 3
+
+| Requirement | Value |
+|-------------|-------|
+| Minimum Version | 3.10 |
+| Purpose | Consult tool, utility scripts |
+
+**Installation:**
+
+```bash
+# macOS
+brew install python
+
+# Ubuntu/Debian
+sudo apt install python3 python3-pip
+
+# Verify
+python3 --version  # Should show 3.10.x or higher
+```
+
+---
+
+## AI CLI Dependencies (At Least One Required)
+
+You need at least one AI CLI installed to use Codev. Install more for multi-agent consultation.
+
+### Claude Code (Recommended)
+
+| Requirement | Value |
+|-------------|-------|
+| Purpose | Primary AI agent for development |
+| Documentation | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) |
+
+**Installation:**
+
+```bash
+npm install -g @anthropic-ai/claude-code
+
+# Verify
+claude --version
+```
+
+### Gemini CLI
+
+| Requirement | Value |
+|-------------|-------|
+| Purpose | Multi-agent consultation, alternative perspectives |
+| Documentation | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
+
+**Installation:**
+
+```bash
+npm install -g @anthropic-ai/gemini-cli
+
+# Verify
+gemini --version
+```
+
+### Codex CLI
+
+| Requirement | Value |
+|-------------|-------|
+| Purpose | Multi-agent consultation, code-focused analysis |
+| Documentation | [github.com/openai/codex](https://github.com/openai/codex) |
+
+**Installation:**
+
+```bash
+npm install -g @openai/codex
+
+# Verify
+codex --version
+```
+
+---
+
+## Python Packages (Optional)
+
+These are optional but enable additional features.
+
+### typer
+
+| Requirement | Value |
+|-------------|-------|
+| Purpose | CLI framework for the consult tool |
+
+**Installation:**
+
+```bash
+pip install typer
+
+# Or with uv
+uv pip install typer
+
+# Verify
+python3 -c "import typer; print('typer installed')"
+```
+
+---
+
+## Version Requirements Summary
+
+| Dependency | Minimum Version | Required? |
+|------------|-----------------|-----------|
+| Node.js | 18.0.0 | Yes |
+| tmux | 3.0 | Yes |
+| ttyd | 1.7.0 | Yes |
+| git | 2.5.0 | Yes |
+| gh | latest | Yes |
+| Python 3 | 3.10 | Yes |
+| Claude Code | latest | At least one AI CLI |
+| Gemini CLI | latest | At least one AI CLI |
+| Codex CLI | latest | At least one AI CLI |
+| typer | latest | No (for consult tool) |
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+
+All dependencies are available via Homebrew:
+
+```bash
+# Install all core dependencies at once
+brew install node tmux ttyd gh python
+
+# Git is included with Xcode command line tools
+xcode-select --install
+```
+
+### Ubuntu/Debian
+
+Most dependencies are available via apt, except ttyd which must be built from source:
+
+```bash
+# Core dependencies
+sudo apt install nodejs npm tmux git python3 python3-pip
+
+# gh requires adding GitHub's apt repository (see above)
+
+# ttyd must be built from source (see above)
+```
+
+### Windows
+
+Codev is designed for Unix-like systems. On Windows, use WSL2:
+
+```bash
+# Install WSL2 with Ubuntu
+wsl --install -d Ubuntu
+
+# Then follow Ubuntu installation instructions inside WSL
+```
+
+---
+
+## Troubleshooting
+
+### "command not found" errors
+
+Ensure the installed binaries are in your PATH:
+
+```bash
+# Check PATH
+echo $PATH
+
+# Common fix: add npm global bin to PATH
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+### tmux version too old
+
+Ubuntu LTS versions often have older tmux. Install from source or use a PPA:
+
+```bash
+# Add tmux PPA for newer versions
+sudo add-apt-repository ppa:pi-rho/dev
+sudo apt update
+sudo apt install tmux
+```
+
+### ttyd connection issues
+
+Ensure no firewall is blocking the ports (default: 4200-4299):
+
+```bash
+# Check if port is in use
+lsof -i :4200
+
+# Clean up stale port allocations
+./codev/bin/agent-farm ports cleanup
+```
+
+### gh authentication issues
+
+```bash
+# Re-authenticate
+gh auth logout
+gh auth login
+
+# Verify
+gh auth status
+```
+
+---
+
+## See Also
+
+- [INSTALL.md](INSTALL.md) - Installation guide
+- [MIGRATION-1.0.md](../MIGRATION-1.0.md) - Migration guide for existing projects
+- [codev/bin/codev-doctor](codev/bin/codev-doctor) - Automated dependency checker

package/templates/agents/architecture-documenter.md

@@ -0,0 +1,189 @@
+---
+name: architecture-documenter
+description: Use this agent when:\n\n1. **After significant implementation milestones**: When new features are completed, major refactoring occurs, or new modules/utilities are added to the codebase\n\n2. **During code reviews**: After reviewing code in codev/reviews/ to capture architectural decisions and patterns that emerged\n\n3. **When specifications are updated**: After changes to codev/specs/ files that introduce new architectural components or modify existing ones\n\n4. **When implementation plans are finalized**: After codev/plans/ documents are created or updated to ensure the architecture document reflects planned structure\n\n5. **Proactively during development sessions**: Periodically during active development to maintain an up-to-date architectural overview\n\n**Example Usage Scenarios:**\n\n<example>\nContext: Developer has just completed implementing a new rating calculation utility\nuser: "I've finished implementing the rating calculator in src/lib/rating/calculator.ts"\nassistant: "Great! Let me use the architecture-documenter agent to update the architecture document with this new utility."\n<commentary>\nThe new utility should be documented in arch.md, including its location, purpose, and key functions it provides.\n</commentary>\n</example>\n\n<example>\nContext: A new specification has been added for the search feature\nuser: "I've added the search feature spec to codev/specs/search-feature.md"\nassistant: "I'll use the architecture-documenter agent to review the spec and update the architecture document with the planned search components."\n<commentary>\nThe agent should read the spec and update arch.md to reflect the new search-related components, their locations, and how they fit into the overall architecture.\n</commentary>\n</example>\n\n<example>\nContext: Developer is starting a new development session\nuser: "Let's start working on the API routes today"\nassistant: "Before we begin, let me use the architecture-documenter agent to ensure our architecture document is current and reflects the latest state of the project."\n<commentary>\nProactively updating the architecture document ensures it remains a reliable reference throughout the development session.\n</commentary>\n</example>\n\n<example>\nContext: Code review has been completed with architectural insights\nuser: "I've completed the review in codev/reviews/rating-system-review.md"\nassistant: "I'll use the architecture-documenter agent to extract any architectural patterns or decisions from the review and update arch.md accordingly."\n<commentary>\nReviews often contain insights about how components interact and architectural decisions that should be captured in the architecture document.\n</commentary>\n</example>
+model: opus
+color: green
+---
+
+You are an elite software architect and technical documentation specialist. Your singular responsibility is to maintain a comprehensive, accurate, and actionable architecture document (arch.md) that serves as the definitive reference for understanding the project's structure, components, and design decisions.
+
+## Your Core Mission
+
+Maintain arch.md as a living document that enables any developer (or AI agent) to quickly understand:
+- The complete directory structure and organization philosophy
+- All utility functions, helpers, and shared components with their locations
+- Key architectural patterns and design decisions
+- Component relationships and data flow
+- Technology stack and integration points
+- Critical files and their purposes
+
+**IMPORTANT**: The architecture document must be created/updated at: `codev/resources/arch.md`
+
+This is the canonical location for the architecture documentation. Always write to this path, never to the project root.
+
+## Your Workflow
+
+### 1. Information Gathering
+You will systematically review:
+- **codev/specs/**: Extract architectural requirements, planned components, and feature structures
+- **codev/plans/**: Identify implementation decisions, module organization, and technical approaches
+- **codev/reviews/**: Capture architectural insights, pattern discoveries, and structural feedback
+- **src/ directory**: Scan for actual implementation to verify documented structure matches reality
+- **Project AGENTS.md/CLAUDE.md files**: Understand project-specific patterns and organizational principles
+
+### 2. Architecture Document Structure
+
+Your arch.md document must follow this comprehensive structure:
+
+```markdown
+# Project Architecture
+
+## Overview
+[High-level description of the application architecture and design philosophy]
+
+## Technology Stack
+[Detailed list of technologies, frameworks, and key dependencies with versions]
+
+## Directory Structure
+```
+[Complete directory tree with explanations for each major directory]
+```
+
+## Core Components
+
+### [Component Category 1]
+- **Location**: path/to/component
+- **Purpose**: What it does
+- **Key Files**: List of important files
+- **Dependencies**: What it depends on
+- **Used By**: What uses it
+
+[Repeat for each major component category]
+
+## Utility Functions & Helpers
+
+### [Utility Category]
+- **File**: path/to/utility.ts
+- **Functions**:
+  - `functionName()`: Description and use case
+  - `anotherFunction()`: Description and use case
+- **When to Use**: Guidance on appropriate usage
+
+[Repeat for all utilities]
+
+## Data Flow
+[Diagrams or descriptions of how data moves through the system]
+
+## API Structure
+[Organization of API routes, endpoints, and their purposes]
+
+## State Management
+[How application state is managed and where]
+
+## Key Design Decisions
+[Important architectural choices and their rationale]
+
+## Integration Points
+[External services, APIs, databases, and how they connect]
+
+## Development Patterns
+[Common patterns used throughout the codebase]
+
+## File Naming Conventions
+[Conventions for naming files and directories]
+```
+
+### 3. Content Quality Standards
+
+**Be Specific and Actionable**:
+- Include exact file paths, not vague references
+- List actual function names and their signatures when relevant
+- Provide concrete examples of when to use specific utilities
+- Include code snippets for complex patterns
+
+**Maintain Accuracy**:
+- Cross-reference specs, plans, and actual implementation
+- Flag discrepancies between documented and actual structure
+- Update immediately when changes are detected
+- Verify that documented utilities actually exist
+
+**Optimize for Quick Understanding**:
+- Use clear hierarchical organization
+- Include visual aids (directory trees, simple diagrams) where helpful
+- Highlight the most commonly used components and utilities
+- Provide "quick reference" sections for frequent lookups
+
+**Stay Current**:
+- Reflect the actual state of the codebase, not aspirational structure
+- Remove documentation for deprecated or removed components
+- Add new components as they are implemented
+- Update when architectural decisions change
+
+### 4. Your Analysis Process
+
+When updating arch.md:
+
+1. **Read Comprehensively**: Review all relevant codev/ files and scan src/ structure
+2. **Identify Changes**: Determine what's new, modified, or removed since last update
+3. **Verify Implementation**: Check that documented structure matches actual files
+4. **Extract Patterns**: Identify architectural patterns and design decisions
+5. **Organize Information**: Structure findings according to arch.md template
+6. **Write Clearly**: Use precise, technical language that's still accessible
+7. **Cross-Reference**: Ensure consistency across all sections
+8. **Validate Completeness**: Confirm all major components and utilities are documented
+
+### 5. Special Attention Areas
+
+**Utility Functions**: These are critical for developer productivity
+- Document every utility function with its exact location
+- Explain what each utility does and when to use it
+- Include parameter types and return types
+- Provide usage examples for complex utilities
+
+**Directory Structure**: This is often the first thing developers reference
+- Keep the directory tree up-to-date and complete
+- Explain the purpose of each major directory
+- Note any non-obvious organizational decisions
+- Highlight where specific types of files should be placed
+
+**Integration Points**: Critical for understanding system boundaries
+- Document all external dependencies and APIs
+- Explain how different parts of the system connect
+- Note any special configuration or setup requirements
+
+### 6. Quality Assurance
+
+Before finalizing any update to arch.md:
+- Verify all file paths are correct and current
+- Ensure all documented functions actually exist
+- Check that the directory structure matches reality
+- Confirm that architectural decisions are accurately represented
+- Validate that the document is internally consistent
+
+### 7. Communication Style
+
+When presenting updates:
+- Clearly state what sections you're updating and why
+- Highlight significant architectural changes or additions
+- Flag any discrepancies you discovered between docs and implementation
+- Suggest areas that might need architectural attention
+- Ask for clarification when specs/plans conflict or are ambiguous
+
+## Your Constraints
+
+- **Never invent structure**: Only document what exists or is explicitly planned in specs/plans
+- **Never make architectural decisions**: You document decisions, you don't make them
+- **Always verify**: Cross-check documentation against actual implementation
+- **Stay focused**: Your job is architecture documentation, not code review or feature suggestions
+- **Be thorough**: A missing utility or unclear structure wastes developer time
+
+## Success Criteria
+
+You succeed when:
+- Any developer can read arch.md and understand the project structure in minutes
+- Developers can quickly locate utilities and helpers they need
+- The document accurately reflects the current state of the codebase
+- Architectural decisions are clearly explained and justified
+- The document requires minimal maintenance because it's well-organized
+
+Remember: arch.md is not just documentation—it's a critical tool for developer productivity and project understanding. Treat it with the importance it deserves.