ryanmac · ryanmac · Jul 25, 2025 · Jul 25, 2025 · Jul 25, 2025
diff --git a/README.md b/README.md
diff --git a/docs/AGENT_WORKFLOW.md b/docs/AGENT_WORKFLOW.md
@@ -0,0 +1,113 @@
+# Agent Workflow
+
+## AI Agent Quick Start
+
+After setup, Code Conductor creates a `CLAUDE.md` file with AI agent instructions. For Claude Code or other AI coding assistants:
+
+```bash
+# The ONLY command AI agents need to know:
+./conductor start [role]
+```
+
+This single command:
+- ✅ Shows your role and capabilities
+- ✅ Lists available tasks (creates demo tasks if needed)
+- ✅ Claims the best matching task automatically
+- ✅ Creates an isolated git worktree
+- ✅ Provides all context needed to start
+
+## The Perfect Kickoff Prompt
+
+Start any Claude Code session with this value-focused prompt:
+
+```
+Ultrathink: What task will create the most value? Find it, claim it, complete it.
+```
+
+This prompt:
+- Triggers deep analysis with "ultrathink"
+- Focuses on value creation over busy work
+- Provides clear action steps: find → claim → complete
+- Works with any role or project type
+
+**Pro tip**: Add this to your text expander (e.g., `;ustart`) for instant agent activation.
+
+## Example AI Agent Session
+
+```
+> ./conductor start frontend
+
+🤖 Code Conductor Agent: frontend
+==================================
+📋 Role: frontend
+
+📊 Available Tasks:
+  #42: Implement dark mode toggle
+  #43: [INIT] Discover project documentation and create task map
+  #44: Add responsive navigation menu
+
+🎯 Claiming task...
+✅ Claimed task #42
+📁 Workspace: worktrees/agent-frontend-42
+
+Next: cd worktrees/agent-frontend-42
+```
+
+## AI Agent Workflow
+
+1. **Start work**: `./conductor start dev`
+2. **Implement**: Work in the created worktree
+3. **Complete**: `./conductor complete`
+4. **Repeat**: Automatically moves to next task
+
+## Smart Task Discovery
+
+For existing projects, Code Conductor creates a special discovery task that AI agents can claim to:
+- Map all project documentation
+- Identify implemented vs missing features
+- Generate 10-20 specific development tasks
+- Create proper GitHub issues automatically
+
+## Launching an Agent
+
+**Option A: Conductor Desktop App (macOS only)**
+```bash
+export AGENT_ROLE=dev  # or devops, security, etc.
+./conductor start
+# Follow the printed instructions to open in Conductor app
+```
+
+**Option B: Multiple Terminals (All Platforms)**
+```bash
+./conductor start dev
+cd worktrees/agent-dev-[task_id]
+# Use tmux or screen for session management on Linux/Windows
+# Start your Claude Code session in the worktree
+```
+
+## Agent Lifecycle
+
+1. **Initialize**: Load role definition and check dependencies
+2. **Claim Task**: Atomically claim an available task
+3. **Create Worktree**: Isolated git workspace for conflict-free work
+4. **Execute Task**: Follow specifications and success criteria
+5. **Report Status**: Update heartbeat and progress
+6. **Complete/Idle**: Mark complete or report idle for cleanup
+
+## Universal Bootstrap Prompt
+
+The system provides a single prompt that works for any agent:
+
+```
+You are a Claude Code agent in a Code Conductor coordinated project.
+ROLE: {role}
+PROJECT: {project_name}
+
+1. Read your role definition: .conductor/roles/{role}.md
+2. Check available tasks: gh issue list -l 'conductor:task' --assignee '!*'
+3. Claim a task: python .conductor/scripts/task-claim.py --role {role}
+4. Work in your isolated worktree
+5. Commit and push changes when complete
+
+Note: Heartbeats are automatically managed by GitHub Actions.
+```
diff --git a/docs/AI_CODE_REVIEW.md b/docs/AI_CODE_REVIEW.md
@@ -0,0 +1,36 @@
+# AI Code Review - Smart, Opt-In Quality Gates
+
+Request AI code reviews when you need them - no more review spam for trivial changes:
+
+- 🎯 **Opt-in reviews** - Add `needs-review` label or comment `/conductor review` to request
+- 🔒 **Security scanning** - Agents check for hardcoded secrets, SQL injection risks, unsafe operations
+- 🐛 **Bug detection** - Comprehensive analysis for null references, race conditions, logic errors
+- 💡 **Smart filtering** - Automatically skips docs-only changes, tiny PRs, and bot updates
+- 🧪 **Test coverage** - Suggests missing tests and edge cases
+
+## How It Works
+
+1. **Request a review** - Add `needs-review` label or comment `/conductor review` on your PR
+2. **Smart filtering** - System checks if review is needed (skips trivial changes)
+3. **Task creation** - Review task appears as GitHub Issue (only if needed)
+4. **Agent review** - AI agents claim and complete thorough code review
+5. **PR feedback** - Detailed review posted as PR comment
+
+## Automatic Skip Conditions
+- PRs with less than 10 lines changed
+- Documentation-only changes
+- Dependabot and bot PRs
+- PRs labeled with `skip-review`
+- Draft PRs
+
+## Triggering Reviews
+```bash
+# Option 1: Add label
+gh pr edit 123 --add-label needs-review
+
+# Option 2: Comment on PR
+@conductor review  # or /conductor review
+
+# Option 3: Manual workflow
+gh workflow run pr-review-tasks.yml -f pr_number=123
+```
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -0,0 +1,85 @@
+# Architecture
+
+## How It Works
+
+1. **Setup Phase**: Use the universal installer to configure your project. The setup script detects your project type and configures roles.
+2. **Task Creation**: Create tasks via GitHub Issues with the `conductor:task` label
+3. **Agent Initialization**: Agents use the universal bootstrap to claim work
+4. **Isolated Development**: Each agent works in a git worktree to prevent conflicts
+5. **Automated Coordination**: GitHub Actions manage health, cleanup, and task flow
+
+## Hybrid Role Model
+
+The system uses a hybrid approach optimized for efficiency:
+
+- **Default Role**: `dev` - A generalist that can handle any task without specific requirements
+- **Specialized Roles**: Optional roles like `devops`, `security` for complex domains
+
+This reduces the complexity of managing many agent types while maintaining quality for specialized work.
+
+## File Structure
+
+```
+.conductor/
+├── config.yaml           # Project configuration with auto-detected stack
+├── roles/               # Role definitions
+│   ├── dev.md          # Default generalist
+│   ├── code-reviewer.md # AI-powered PR reviewer
+│   ├── frontend.md     # UI/UX specialist
+│   ├── mobile.md       # Mobile app developer
+│   ├── devops.md       # CI/CD specialist
+│   ├── security.md     # Security specialist
+│   ├── ml-engineer.md  # ML/AI specialist
+│   └── data.md         # Data engineer
+├── scripts/            # Automation scripts
+│   ├── conductor       # Universal AI agent command
+│   ├── task-claim.py   # Atomic task assignment
+│   ├── create-review-task.py # Creates review tasks from PRs
+│   └── health-check.py # System monitoring
+└── examples/           # Stack-specific task templates
+    ├── nextjs-webapp/
+    ├── python-webapp/
+    ├── mobile-app/
+    └── ...
+```
+
+## Core Components
+
+1. **Setup System** (`setup.py`)
+   - Interactive/auto configuration wizard
+   - Detects technology stack automatically
+   - Configures agent roles based on project type
+   - Creates GitHub workflows for automation
+
+2. **Task Management** (GitHub Issues)
+   - GitHub Issues with `conductor:task` label serve as tasks
+   - Issues have unique numbers, descriptions, success criteria
+   - GitHub's atomic operations prevent race conditions
+   - Native integration with GitHub Projects and Actions
+
+3. **Agent Roles** (`.conductor/roles/`)
+   - `dev.md` - Default generalist role for most tasks
+   - Specialized roles: `devops`, `security`, `frontend`, `mobile`, `ml-engineer`, `data`
+   - `code-reviewer` - AI-powered PR reviews (always included)
+   - Hybrid model: prefer `dev` role unless task requires specialization
+
+4. **Agent Coordination** (`.conductor/scripts/`)
+   - `conductor` - Universal agent command (primary interface)
+   - `task-claim.py` - Task assignment via GitHub Issue assignment
+   - `health-check.py` - Monitor agent heartbeats
+   - `cleanup-stale.py` - Remove abandoned work
+   - Git worktrees provide isolation between agents
+
+5. **GitHub Integration**
+   - Issues become tasks via `conductor:task` label
+   - Actions run health checks every 15 minutes
+   - AI code reviews on all PRs
+   - Status dashboard via `conductor:status` issue
+
+## Key Design Patterns
+
+1. **Atomic Operations**: GitHub's issue assignment API ensures atomic task claiming
+2. **Worktree Isolation**: Each agent works in separate git worktree (`worktrees/agent-{role}-{task_id}`)
+3. **Heartbeat System**: Agents update timestamps; stale work auto-cleaned after timeout
+4. **File Conflict Prevention**: Worktree isolation ensures agents work on separate branches
+5. **Self-Healing**: GitHub Actions monitor health, clean stale work, process issues
diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md
@@ -0,0 +1,39 @@
+# Best Practices
+
+1. **Task Design**: Make tasks self-contained with clear specs
+2. **Duplicate Prevention**: Check existing issues before creating new ones - use `./conductor check-dup "title"`
+3. **Role Selection**: Start with dev-only, add specializations as needed
+4. **Regular Cleanup**: Let automation handle stale work
+5. **Monitor Health**: Check status issue regularly
+6. **Incremental Adoption**: Start small, expand as comfortable
+
+See also: [Duplicate Prevention Guide](DUPLICATE_PREVENTION.md) for detailed strategies
+
+## Task Format
+
+Tasks are created as GitHub Issues with complete specifications:
+
+**Issue Title**: Implement authentication
+
+**Issue Body**:
+```markdown
+## Description
+Implement user authentication system for the application.
+
+## Specifications
+See: docs/auth-spec.md
+
+## Best Practices
+- Use JWT tokens
+- Implement refresh tokens
+
+## Success Criteria
+- Tests: 100% coverage
+- Security: Pass security scan
+```
+
+**Labels**:
+- `conductor:task` (required)
+- `effort:medium`
+- `priority:medium`
+- `skill:backend` (optional, for specialized tasks)
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -0,0 +1,52 @@
+# Configuration Guide
+
+## Project Configuration
+
+The main configuration file is `.conductor/config.yaml`, created during setup.
+
+### Configuration Structure
+
+```yaml
+# .conductor/config.yaml
+project_name: string
+documentation: 
+  main: string (path to main docs)
+  additional: [array of paths]
+technology_stack:
+  languages: [detected languages]
+  frameworks: [detected frameworks]
+  tools: [detected build tools]
+roles:
+  default: "dev"
+  specialized: [list of specialized roles]
+github_integration:
+  enabled: boolean
+  issue_to_task: boolean
+  pr_reviews: boolean
+worktree_retention_days: number (default 7)
+```
+
+## Setup Options
+
+Run `python setup.py` to configure:
+
+- Project name and documentation location
+- Technology stack detection
+- Role selection (hybrid model)
+- Task management approach
+- GitHub integration settings
+
+## Role Definitions
+
+Each role has a Markdown file in `.conductor/roles/` defining:
+
+- Responsibilities
+- Task selection criteria
+- Required skills
+- Success metrics
+
+## Environment Variables
+
+- `AGENT_ROLE` - Set the default agent role
+- `CONDUCTOR_DEBUG` - Enable debug logging
+- `WORKTREE_BASE` - Override default worktree location
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -0,0 +1,52 @@
+# Development Setup
+
+## Prerequisites
+- Python 3.9-3.12
+- Git
+- GitHub CLI (optional, for issue integration)
+
+## Local Development
+```bash
+# Clone and setup
+git clone https://github.com/ryanmac/code-conductor.git
+cd code-conductor
+
+# Install with Poetry (recommended)
+poetry install
+
+# Or with pip
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# Run tests
+poetry run pytest tests/ -v
+# or
+python -m pytest tests/ -v
+
+# Run linting
+poetry run flake8 .conductor/scripts/ setup.py
+poetry run black --check .conductor/scripts/ setup.py
+```
+
+## CI/CD
+The project uses GitHub Actions for continuous integration:
+- **Linting**: flake8 and black formatting checks
+- **Testing**: pytest on multiple Python versions (3.9, 3.10, 3.11, 3.12)
+- **Security**: safety vulnerability scanning
+- **Platforms**: Ubuntu and macOS
+
+## Contributing
+
+This is a template repository. To contribute:
+
+1. Fork and improve
+2. Test with your project type
+3. Submit PRs with examples
+4. Share your adaptations
+
+### Development Guidelines
+- Follow PEP 8 style guidelines
+- Add tests for new functionality
+- Update documentation for changes
+- Ensure CI passes before submitting PRs