diff --git a/README.md b/README.md index 5499cd5..220fed4 100644 --- a/README.md +++ b/README.md @@ -1,645 +1,81 @@ # ๐ŸŽผ Code Conductor -> โš ๏ธ **Repository Renamed** -> This project was previously named **Conductor's Score** (`Code-Conductor`). -> It has been renamed to **Code Conductor** (`code-conductor`) as of July 23, 2025. -> GitHub redirects all URLs, but please update any bookmarks or references. - image -**Transform your development workflow in 60 seconds.** From tweet discovery to AI agents shipping codeโ€”the GitHub-native coordination system that changes how you build. - -> *"Stop juggling tasks. Start orchestrating agents."* - -## ๐Ÿš€ **Why Developers Are Switching to Agentic Development** - -- โšก **Focus on architecture, let agents handle implementation** - Spend time on what matters most -- ๐ŸŽฏ **Zero config for 90% of projects** - Auto-detects your stack and configures optimal roles -- ๐Ÿ”’ **Smart AI code reviews** - Opt-in reviews when you need them, not spam on every PR -- ๐Ÿค– **Smart agent roles** - Generalist "dev" handles most tasks, specialists for complex work -- ๐Ÿ“Š **Native GitHub integration** - Issues become tasks, Actions monitor health -- ๐Ÿ”„ **Self-healing coordination** - Automatic cleanup, heartbeat monitoring, stale work recovery - -*"From weekend side project to shipping product in weeks, not months."* - -## ๐Ÿš€ **NEW: Let Claude Code Do Everything For You** - -**Skip the manual setup.** Paste this into Claude Code and watch the magic happen: - -``` -I need to move faster. Install Code Conductor into this project so we can run multiple Claude Code agents at once. - -Execute: bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) -``` - -Claude Code will handle everythingโ€”installation, configuration, even creating your first task roadmap. **No GitHub token setup required!** The system uses GitHub's built-in authentication automatically. **[See more power prompts โ†’](CLAUDE_CODE_PROMPT.md)** - -## ๐ŸŽฏ **90% Stack Coverage - Your Tech is Supported** +**Orchestrate multiple AI coding agents. Ship 10x faster.** -Code Conductor automatically detects and configures for the most popular technology stacks: +## The Problem -### **Frontend & Full-Stack** (40% of projects) -- **React/Next.js** - Auto-configures frontend & UI roles -- **Vue/Nuxt** - Component-based development ready -- **Angular** - Enterprise app support -- **Svelte/SvelteKit** - Modern reactive apps +You're using Claude Code to ship features, but you're still working sequentially. One task at a time. One PR at a time. Meanwhile, your backlog keeps growing. -### **Backend & APIs** (35% of projects) -- **Node.js** (Express, NestJS) - Microservices ready -- **Python** (Django, Flask, FastAPI) - Web & ML support -- **Go** (Gin, Echo, Fiber) - High-performance services -- **Java/Kotlin** (Spring) - Enterprise backends -- **PHP** (Laravel, Symfony) - Rapid development -- **.NET Core** (ASP.NET) - Microsoft stack +## The Solution -### **Mobile & Desktop** (15% of projects) -- **React Native** - Cross-platform mobile -- **Flutter** - Native performance -- **Tauri** - Lightweight desktop apps -- **Electron** - Web-powered desktop +Code Conductor lets you run multiple AI agents in parallelโ€”each working on different features simultaneously. No conflicts. No coordination overhead. Just pure, parallelized productivity. -### **Specialized Roles Auto-Configured** -Based on your stack, we automatically add: -- ๐Ÿค– **code-reviewer** - AI agent role for reviewing pull requests -- ๐ŸŽจ **frontend** - UI/UX implementation -- ๐Ÿ“ฑ **mobile** - Platform-specific features -- ๐Ÿ”ง **devops** - CI/CD & infrastructure -- ๐Ÿ”’ **security** - Vulnerability scanning -- ๐Ÿงฎ **ml-engineer** - ML model deployment -- ๐Ÿ“Š **data** - ETL & analytics +**Transform your workflow:** +- ๐Ÿš€ **Hours, not weeks** - Multiple agents tackle your backlog in parallel +- ๐Ÿ”’ **Zero merge conflicts** - Each agent works in isolated git worktrees +- ๐Ÿค– **Works with Claude Code** - Your favorite AI assistant, multiplied +- ๐ŸŽฏ **Self-managing** - Agents claim tasks, implement, and ship autonomously -## โšก **60-Second Setup** +## Quick Start -**One command. Instant AI coordination.** - -**Prerequisites for all options:** Git, Python 3.9-3.12, curl (for one-liner), and tar. Run from the root of an existing Git repository. **If using pyenv, ensure your active Python version (e.g., via `pyenv shell 3.12.x`) has Poetry installed if you prefer it; otherwise, the script falls back to pip.** - -### **Option 1: Universal One-Liner (Recommended - No Cloning Required)** -Run this in your existing project's root directory to download and install Code Conductor directly: +One command. 60 seconds. Done. ```bash bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) ``` -- This method avoids cloning the full Code Conductor repo and is ideal for integrating into existing projects without repository pollution. -- The script will prompt before overwriting any existing installation. -- **Security best practice:** Review the script at the raw URL before running. -- **Pyenv users:** If Poetry install fails, switch to the Python version that has Poetry installed (e.g., `pyenv shell 3.10.13`) and re-run. - -One-line Install -Happy orchestrating - - -### Option 2: Poetry (For Cloned Repo) -```bash -# Clone the repository -git clone https://github.com/ryanmac/code-conductor.git -cd code-conductor - -# Install with Poetry (auto-creates virtual environment) -poetry install -poetry run python setup.py -``` - -### Option 3: Pip + Virtual Environment (For Cloned Repo) -```bash -# Clone the repository -git clone https://github.com/ryanmac/code-conductor.git -cd code-conductor - -# Create virtual environment -python3 -m venv .venv -source .venv/bin/activate # On Windows: .venv\Scripts\activate - -# Install dependencies -pip install -r requirements.txt - -# Run setup -python setup.py -``` - -### Option 4: One-Command Install Script (For Cloned Repo) -```bash -# From the repository directory: -./install.sh - -# Or with custom setup options: -./install.sh --auto -``` - -**That's it.** No GitHub token setup requiredโ€”the system uses GitHub Actions' built-in authentication. Now create a GitHub Issue with `conductor:task` label, launch an agent via [Conductor.build](https://conductor.build) (macOS only as of 2024-07-22) or terminal workflow (all platforms), and watch it work. - -## ๐Ÿ”„ **Upgrading Code Conductor** - -**Keep your Code Conductor installation up-to-date with the latest features!** - -### **Automatic Upgrade Detection** - -Simply run the same installation command in your project: - -```bash -bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) -``` - -The installer will: -- โœ… Detect your existing installation and version -- โœ… Prompt to upgrade, reinstall, or cancel -- โœ… Preserve your configurations and customizations -- โœ… Update only core scripts and workflows -- โœ… Show what's new after upgrading - -### **What Gets Updated** -- `.conductor/scripts/` - Core conductor commands -- `.conductor/roles/` - Latest role definitions -- `.github/workflows/` - Updated GitHub Actions -- `setup.py`, `requirements.txt` - Dependency updates - -### **What Gets Preserved** -- `.conductor/config.yaml` - Your project configuration -- `CLAUDE.md` - Your custom AI instructions -- All existing tasks and work in progress -- Git worktrees and agent states - -### **Using Claude Code for Upgrades** - -Want to upgrade in seconds? Copy this power prompt into Claude Code: +The installer auto-detects your stack (React, Python, Go, etc.) and configures everything. No GitHub tokens. No complex setup. +**Or let Claude Code install it for you:** ``` -We need the latest Code Conductor features. Upgrade our installation to unlock enhanced task management and duplicate prevention. - -Run: bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) -Choose option 1 (Upgrade) and verify with ./conductor status -``` - -**๐Ÿš€ See [CLAUDE_CODE_PROMPT.md](CLAUDE_CODE_PROMPT.md) for game-changing automation prompts** that transform your project into an agentic development powerhouse. - -## ๐Ÿค– **AI Agent Quick Start** - -**NEW: AI-first experience with automatic onboarding!** - -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 - -## How It Works - -1. **Setup Phase**: Use the universal installer (Option 1) or other setup methods 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 - -## Architecture - -### 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/ - โ””โ”€โ”€ ... -``` - -## Configuration - -### Project Setup - -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 - -### 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 +I need to move faster. Install Code Conductor into this project so we can run multiple Claude Code agents at once. -## Success Criteria -- Tests: 100% coverage -- Security: Pass security scan +Execute: bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) ``` -**Labels**: -- `conductor:task` (required) -- `effort:medium` -- `priority:medium` -- `skill:backend` (optional, for specialized tasks) - -## ๐Ÿค– 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 +## See It In Action -### 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 -``` +# Create a task (GitHub Issue) +gh issue create --label "conductor:task" --title "Add dark mode toggle" -## Agent Workflow +# Launch an agent +./conductor start frontend -### Launching an Agent +# Watch it work +# โœ“ Claims task #42 +# โœ“ Creates isolated worktree +# โœ“ Implements feature +# โœ“ Opens pull request +# โœ“ Moves to next task -**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 +# Launch more agents to parallelize +./conductor start backend ./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 -``` - -๐Ÿ“š **[See complete usage guide โ†’](docs/USAGE.md)** - -### 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. -``` - -## GitHub Integration - -### Issues as Tasks - -Create issues with the `conductor:task` label to automatically convert them to tasks. - -### Automated Workflows - -- **Health Monitoring**: Every 15 minutes -- **Stale Cleanup**: Removes abandoned work -- **Task Scheduling**: Processes dependencies -- **Status Reports**: Updates dashboard issue - -## Monitoring - -### System Health - -```bash -# Check local status -python .conductor/scripts/health-check.py - -# View GitHub dashboard -# Check issue with 'conductor:status' label -``` - -### Metrics Tracked - -- Active agents and their tasks -- Available task queue depth -- Completion rate and velocity -- System health indicators - -## Examples - -### ๐ŸŒŸ **Works with Your Stack** - -
-React Web App - Modern full-stack development - -```yaml -project_name: harmony-webapp -roles: - default: dev - specialized: [devops, ui-designer] -build_validation: - - npm test -- --coverage - - npm run lint - - npm run build -``` -
- -
-Chrome Extension + NextJS - Browser extension with web dashboard - -```yaml -project_name: symphony-extension -roles: - default: dev - specialized: [devops] -protected_files: - - packages/extension/manifest.json -``` -
- -
-Python Microservices - Scalable backend architecture - -```yaml -project_name: api-platform -roles: - default: dev - specialized: [devops, security] -quality_checks: - - pytest --cov=services - - bandit -r services/ -``` -
- -
-Tauri Desktop App - Cross-platform Rust + JS application - -```yaml -project_name: desktop-app -roles: - default: dev - specialized: [devops, security, rust-dev] -matrix_builds: [ubuntu, macos, windows] -``` -
- -**Don't see your stack?** [Contribute an example](CONTRIBUTING.md) and help other developers! - -## Troubleshooting - -### Common Issues - -**No tasks available** -- Check GitHub issues: gh issue list -l 'conductor:task' -- Verify no file conflicts blocking tasks -- Create new tasks: gh issue create --label 'conductor:task' - -**Agent can't claim tasks** -- Run `python .conductor/scripts/dependency-check.py` -- Ensure GitHub CLI is authenticated: `gh auth status` -- Check git repository is clean: `git status` -- Note: No GitHub token setup requiredโ€”workflows use built-in authentication - -**File conflicts** -- System prevents these automatically -- If occurs, check worktree isolation -- Run cleanup: `python .conductor/scripts/cleanup-stale.py` - -### Debug Commands - -```bash -# Check dependencies -python .conductor/scripts/dependency-check.py - -# View system state -gh issue list -l 'conductor:task' --json state,assignees,title - -# Force cleanup -python .conductor/scripts/cleanup-stale.py --timeout 0 - -# Validate configuration -python .conductor/scripts/validate-config.py ``` -## Storage Footprint - -**Disk Usage**: Each agent creates a Git worktree (~50-200MB depending on project size) -- **Cleanup**: Run `gtclean` weekly to remove abandoned worktrees -- **Monitor**: Use `gtw` to list active worktrees -- **Automatic**: Stale worktrees (>7 days inactive) are auto-archived via GitHub Actions - -**Pro tip**: Large projects should set `worktree_retention_days: 3` in config.yaml - -## 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](docs/DUPLICATE_PREVENTION.md) for detailed strategies - -## 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 - -## License +**The secret:** Each agent works in its own git worktreeโ€”like having multiple copies of your repo. Agent A refactors authentication while Agent B adds dark mode. Zero conflicts. -MIT - See LICENSE file +## Learn More -## Support +๐Ÿ“š **[Full Documentation โ†’](docs/)** +- [Installation Guide](docs/INSTALLATION.md) - All setup options +- [Stack Support](docs/STACK_SUPPORT.md) - Works with React, Vue, Python, Go, and more +- [Architecture](docs/ARCHITECTURE.md) - How it all works under the hood +- [AI Code Review](docs/AI_CODE_REVIEW.md) - Smart, opt-in PR reviews +- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions -- ๐Ÿ› [Issue Tracker](https://github.com/ryanmac/code-conductor/issues) -- ๐Ÿ’ฌ [Discussions](https://github.com/ryanmac/code-conductor/discussions) +๐Ÿš€ **[Power User Prompts](CLAUDE_CODE_PROMPT.md)** - Game-changing automation with Claude Code -## ๐Ÿ’ฌ **Join the Community** +## Community - ๐Ÿ› **Found a bug?** [Report it](https://github.com/ryanmac/code-conductor/issues) - ๐Ÿ’ก **Have an idea?** [Start a discussion](https://github.com/ryanmac/code-conductor/discussions) -- ๐Ÿ› ๏ธ **Want to contribute?** [See our guide](CONTRIBUTING.md) +- ๐Ÿ› ๏ธ **Want to contribute?** [See our guide](.github/CONTRIBUTING.md) - ๐• **Share your success** Mention [@ryanmac](https://x.com/ryanmac) with #CodeConductor -**Built for [Conductor.build](https://conductor.build) and [Warp](https://www.warp.dev/) users who refuse to juggle tasks manually.** +--- -*Transform your development workflow. One command. Infinite possibilities.* ๐ŸŽผ +**Stop juggling tasks. Start shipping features.** ๐ŸŽผ diff --git a/docs/AGENT_WORKFLOW.md b/docs/AGENT_WORKFLOW.md new file mode 100644 index 0000000..230db23 --- /dev/null +++ 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. +``` \ No newline at end of file diff --git a/docs/AI_CODE_REVIEW.md b/docs/AI_CODE_REVIEW.md new file mode 100644 index 0000000..15e361d --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..2f7bd15 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md new file mode 100644 index 0000000..51392ab --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..a72a972 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..b6910e8 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md new file mode 100644 index 0000000..56278b6 --- /dev/null +++ b/docs/EXAMPLES.md @@ -0,0 +1,49 @@ +# Examples - Works with Your Stack + +## React Web App - Modern full-stack development + +```yaml +project_name: harmony-webapp +roles: + default: dev + specialized: [devops, ui-designer] +build_validation: + - npm test -- --coverage + - npm run lint + - npm run build +``` + +## Chrome Extension + NextJS - Browser extension with web dashboard + +```yaml +project_name: symphony-extension +roles: + default: dev + specialized: [devops] +protected_files: + - packages/extension/manifest.json +``` + +## Python Microservices - Scalable backend architecture + +```yaml +project_name: api-platform +roles: + default: dev + specialized: [devops, security] +quality_checks: + - pytest --cov=services + - bandit -r services/ +``` + +## Tauri Desktop App - Cross-platform Rust + JS application + +```yaml +project_name: desktop-app +roles: + default: dev + specialized: [devops, security, rust-dev] +matrix_builds: [ubuntu, macos, windows] +``` + +**Don't see your stack?** [Contribute an example](../CONTRIBUTING.md) and help other developers! \ No newline at end of file diff --git a/docs/GITHUB_INTEGRATION.md b/docs/GITHUB_INTEGRATION.md new file mode 100644 index 0000000..8bb05bb --- /dev/null +++ b/docs/GITHUB_INTEGRATION.md @@ -0,0 +1,59 @@ +# GitHub Integration + +## Issues as Tasks + +Create issues with the `conductor:task` label to automatically convert them to tasks. + +## 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) + +## Automated Workflows + +- **Health Monitoring**: Every 15 minutes +- **Stale Cleanup**: Removes abandoned work +- **Task Scheduling**: Processes dependencies +- **Status Reports**: Updates dashboard issue + +## GitHub Authentication + +Code Conductor uses GitHub's built-in authentication for all operations. No manual token setup is required for most users! + +### Default Setup (Recommended) +The workflows generated by Code Conductor automatically use GitHub Actions' built-in `${{ github.token }}`, which provides: +- โœ… Read/write access to issues, pull requests, and code +- โœ… Ability to create and manage labels +- โœ… No setup required - works out of the box! + +### Advanced Setup (Optional) +Only create a Personal Access Token if you need: +- Higher API rate limits (5,000/hour instead of 1,000/hour) +- Cross-repository access +- Ability to trigger other workflows + +For detailed setup instructions and troubleshooting, see [.conductor/GITHUB_TOKEN_SETUP.md](../.conductor/GITHUB_TOKEN_SETUP.md). \ No newline at end of file diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..daa10bd --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,66 @@ +# Installation Guide + +## Prerequisites +All installation methods require: +- Git +- Python 3.9-3.12 +- curl (for one-liner) +- tar + +Run from the root of an existing Git repository. **If using pyenv, ensure your active Python version (e.g., via `pyenv shell 3.12.x`) has Poetry installed if you prefer it; otherwise, the script falls back to pip.** + +## Option 1: Universal One-Liner (Recommended - No Cloning Required) +Run this in your existing project's root directory to download and install Code Conductor directly: + +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) +``` + +- This method avoids cloning the full Code Conductor repo and is ideal for integrating into existing projects without repository pollution. +- The script will prompt before overwriting any existing installation. +- **Security best practice:** Review the script at the raw URL before running. +- **Pyenv users:** If Poetry install fails, switch to the Python version that has Poetry installed (e.g., `pyenv shell 3.10.13`) and re-run. + +One-line Install +Happy orchestrating + +## Option 2: Poetry (For Cloned Repo) +```bash +# Clone the repository +git clone https://github.com/ryanmac/code-conductor.git +cd code-conductor + +# Install with Poetry (auto-creates virtual environment) +poetry install +poetry run python setup.py +``` + +## Option 3: Pip + Virtual Environment (For Cloned Repo) +```bash +# Clone the repository +git clone https://github.com/ryanmac/code-conductor.git +cd code-conductor + +# Create virtual environment +python3 -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt + +# Run setup +python setup.py +``` + +## Option 4: One-Command Install Script (For Cloned Repo) +```bash +# From the repository directory: +./install.sh + +# Or with custom setup options: +./install.sh --auto +``` + +## After Installation + +No GitHub token setup requiredโ€”the system uses GitHub Actions' built-in authentication. Now create a GitHub Issue with `conductor:task` label, launch an agent via [Conductor.build](https://conductor.build) (macOS only as of 2024-07-22) or terminal workflow (all platforms), and watch it work. \ No newline at end of file diff --git a/docs/MONITORING.md b/docs/MONITORING.md new file mode 100644 index 0000000..13814cd --- /dev/null +++ b/docs/MONITORING.md @@ -0,0 +1,49 @@ +# Monitoring + +## System Health + +```bash +# Check local status +python .conductor/scripts/health-check.py + +# View GitHub dashboard +# Check issue with 'conductor:status' label +``` + +## Metrics Tracked + +- Active agents and their tasks +- Available task queue depth +- Completion rate and velocity +- System health indicators + +## Health Monitoring + +GitHub Actions run health checks every 15 minutes to: +- Monitor agent heartbeats +- Clean up stale worktrees +- Update status dashboard +- Process new tasks + +## Status Dashboard + +The system automatically maintains a GitHub Issue with the `conductor:status` label that shows: +- Currently active agents +- Tasks in progress +- Recent completions +- System health status + +## Debugging + +Use these commands to diagnose issues: + +```bash +# View all conductor tasks +gh issue list -l 'conductor:task' --json state,assignees,title + +# Check agent worktrees +ls -la worktrees/ + +# View recent activity +gh issue list -l 'conductor:task' --state all --limit 20 +``` \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1bda549 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Code Conductor Documentation + +Welcome to the comprehensive Code Conductor documentation. This directory contains detailed guides and references for all aspects of the system. + +## ๐Ÿ“š Documentation Index + +### Getting Started +- [**Installation Guide**](INSTALLATION.md) - All installation methods and options +- [**Usage Guide**](USAGE.md) - How to use Code Conductor effectively +- [**Stack Support**](STACK_SUPPORT.md) - Supported technologies and frameworks + +### Core Concepts +- [**Architecture**](ARCHITECTURE.md) - System design and components +- [**Best Practices**](BEST_PRACTICES.md) - Recommended workflows and patterns +- [**Duplicate Prevention**](DUPLICATE_PREVENTION.md) - Strategies to avoid duplicate work + +### Features +- [**AI Code Review**](AI_CODE_REVIEW.md) - Smart pull request reviews +- [**Examples**](EXAMPLES.md) - Configuration examples for different stacks + +### Operations +- [**Upgrading**](UPGRADING.md) - How to update Code Conductor +- [**Troubleshooting**](TROUBLESHOOTING.md) - Common issues and solutions +- [**Development**](DEVELOPMENT.md) - Contributing to Code Conductor + +### Advanced Topics +- [**GitHub Integration**](GITHUB_INTEGRATION.md) - Deep dive into GitHub features +- [**Configuration**](CONFIGURATION.md) - Detailed configuration options +- [**Agent Workflow**](AGENT_WORKFLOW.md) - How agents operate +- [**Monitoring**](MONITORING.md) - System health and metrics +- [**Storage**](STORAGE.md) - Managing disk usage + +## Quick Links + +- ๐Ÿš€ [Power User Prompts](../CLAUDE_CODE_PROMPT.md) - Advanced Claude Code automation +- ๐Ÿ› ๏ธ [Contributing Guide](../CONTRIBUTING.md) - Help improve Code Conductor +- ๐Ÿ’ฌ [GitHub Discussions](https://github.com/ryanmac/code-conductor/discussions) - Community support \ No newline at end of file diff --git a/docs/STACK_SUPPORT.md b/docs/STACK_SUPPORT.md new file mode 100644 index 0000000..e22704e --- /dev/null +++ b/docs/STACK_SUPPORT.md @@ -0,0 +1,37 @@ +# ๐ŸŽฏ Stack Support & Coverage + +Code Conductor automatically detects and configures for the most popular technology stacks, covering 90% of modern projects. + +## Frontend & Full-Stack (40% of projects) +- **React/Next.js** - Auto-configures frontend & UI roles +- **Vue/Nuxt** - Component-based development ready +- **Angular** - Enterprise app support +- **Svelte/SvelteKit** - Modern reactive apps + +## Backend & APIs (35% of projects) +- **Node.js** (Express, NestJS) - Microservices ready +- **Python** (Django, Flask, FastAPI) - Web & ML support +- **Go** (Gin, Echo, Fiber) - High-performance services +- **Java/Kotlin** (Spring) - Enterprise backends +- **PHP** (Laravel, Symfony) - Rapid development +- **.NET Core** (ASP.NET) - Microsoft stack + +## Mobile & Desktop (15% of projects) +- **React Native** - Cross-platform mobile +- **Flutter** - Native performance +- **Tauri** - Lightweight desktop apps +- **Electron** - Web-powered desktop + +## Specialized Roles Auto-Configured +Based on your stack, we automatically add: +- ๐Ÿค– **code-reviewer** - AI agent role for reviewing pull requests +- ๐ŸŽจ **frontend** - UI/UX implementation +- ๐Ÿ“ฑ **mobile** - Platform-specific features +- ๐Ÿ”ง **devops** - CI/CD & infrastructure +- ๐Ÿ”’ **security** - Vulnerability scanning +- ๐Ÿงฎ **ml-engineer** - ML model deployment +- ๐Ÿ“Š **data** - ETL & analytics + +## Don't See Your Stack? + +[Contribute an example](../CONTRIBUTING.md) and help other developers! \ No newline at end of file diff --git a/docs/STORAGE.md b/docs/STORAGE.md new file mode 100644 index 0000000..c5abbe4 --- /dev/null +++ b/docs/STORAGE.md @@ -0,0 +1,50 @@ +# Storage Management + +## Disk Usage + +Each agent creates a Git worktree, which uses disk space: +- Small projects: ~50MB per worktree +- Medium projects: ~100-150MB per worktree +- Large projects: ~200MB+ per worktree + +## Automatic Cleanup + +Stale worktrees are automatically cleaned up: +- Default retention: 7 days +- Configurable via `worktree_retention_days` in config.yaml +- GitHub Actions run cleanup every 15 minutes + +## Manual Cleanup + +```bash +# List all worktrees +git worktree list + +# Remove specific worktree +git worktree remove worktrees/agent-dev-42 + +# Remove all stale worktrees +python .conductor/scripts/cleanup-stale.py --timeout 0 + +# Alias for quick cleanup (if configured) +gtclean +``` + +## Best Practices + +1. **Large Projects**: Set `worktree_retention_days: 3` in config.yaml +2. **Regular Cleanup**: Run `gtclean` weekly +3. **Monitor Usage**: Use `du -sh worktrees/` to check disk usage +4. **CI/CD Servers**: Set aggressive cleanup (1-2 days retention) + +## Storage Optimization + +For projects with limited disk space: + +```yaml +# .conductor/config.yaml +worktree_retention_days: 2 +max_concurrent_agents: 3 +``` + +This limits the number of worktrees and reduces retention time. \ No newline at end of file diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..15f9019 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,44 @@ +# Troubleshooting + +## Common Issues + +### No tasks available +- Check GitHub issues: `gh issue list -l 'conductor:task'` +- Verify no file conflicts blocking tasks +- Create new tasks: `gh issue create --label 'conductor:task'` + +### Agent can't claim tasks +- Run `python .conductor/scripts/dependency-check.py` +- Ensure GitHub CLI is authenticated: `gh auth status` +- Check git repository is clean: `git status` +- Note: No GitHub token setup requiredโ€”workflows use built-in authentication + +### File conflicts +- System prevents these automatically +- If occurs, check worktree isolation +- Run cleanup: `python .conductor/scripts/cleanup-stale.py` + +## Debug Commands + +```bash +# Check dependencies +python .conductor/scripts/dependency-check.py + +# View system state +gh issue list -l 'conductor:task' --json state,assignees,title + +# Force cleanup +python .conductor/scripts/cleanup-stale.py --timeout 0 + +# Validate configuration +python .conductor/scripts/validate-config.py +``` + +## Storage Footprint + +**Disk Usage**: Each agent creates a Git worktree (~50-200MB depending on project size) +- **Cleanup**: Run `gtclean` weekly to remove abandoned worktrees +- **Monitor**: Use `gtw` to list active worktrees +- **Automatic**: Stale worktrees (>7 days inactive) are auto-archived via GitHub Actions + +**Pro tip**: Large projects should set `worktree_retention_days: 3` in config.yaml \ No newline at end of file diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md new file mode 100644 index 0000000..0671b8a --- /dev/null +++ b/docs/UPGRADING.md @@ -0,0 +1,43 @@ +# Upgrading Code Conductor + +Keep your Code Conductor installation up-to-date with the latest features! + +## Automatic Upgrade Detection + +Simply run the same installation command in your project: + +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) +``` + +The installer will: +- โœ… Detect your existing installation and version +- โœ… Prompt to upgrade, reinstall, or cancel +- โœ… Preserve your configurations and customizations +- โœ… Update only core scripts and workflows +- โœ… Show what's new after upgrading + +## What Gets Updated +- `.conductor/scripts/` - Core conductor commands +- `.conductor/roles/` - Latest role definitions +- `.github/workflows/` - Updated GitHub Actions +- `setup.py`, `requirements.txt` - Dependency updates + +## What Gets Preserved +- `.conductor/config.yaml` - Your project configuration +- `CLAUDE.md` - Your custom AI instructions +- All existing tasks and work in progress +- Git worktrees and agent states + +## Using Claude Code for Upgrades + +Want to upgrade in seconds? Copy this power prompt into Claude Code: + +``` +We need the latest Code Conductor features. Upgrade our installation to unlock enhanced task management and duplicate prevention. + +Run: bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) +Choose option 1 (Upgrade) and verify with ./conductor status +``` + +**๐Ÿš€ See [CLAUDE_CODE_PROMPT.md](../CLAUDE_CODE_PROMPT.md) for game-changing automation prompts** that transform your project into an agentic development powerhouse. \ No newline at end of file