From 149dc91f21351aeb374a55684d37ed1878f1a9e4 Mon Sep 17 00:00:00 2001 From: ryanmac Date: Thu, 24 Jul 2025 22:52:10 -0500 Subject: [PATCH 1/2] fix: Clarify token requirements and Python dependency scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on user feedback, this commit addresses confusion about: 1. GitHub Token Requirements: - Emphasize that NO CONDUCTOR_GITHUB_TOKEN setup is needed - Workflows use GitHub's built-in authentication - Add clear messaging throughout installation process 2. Python Dependency Clarification: - Python is only needed for conductor scripts, NOT for CI/CD - Code Conductor does NOT add Python test/lint workflows - Language-agnostic workflows only 3. Documentation Improvements: - Add comprehensive FAQ addressing common concerns - Update installer with clearer messaging - Enhance README to highlight no-token setup This ensures users understand that Code Conductor: - Uses GitHub's built-in auth (no manual tokens) - Doesn't impose language-specific CI/CD - Only requires Python for orchestration scripts πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 9 ++++- conductor-init.sh | 21 +++++++++-- docs/FAQ.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 4 files changed, 115 insertions(+), 4 deletions(-) create mode 100644 docs/FAQ.md diff --git a/README.md b/README.md index 220fed4..de6c6cb 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,13 @@ One command. 60 seconds. Done. bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh) ``` -The installer auto-detects your stack (React, Python, Go, etc.) and configures everything. No GitHub tokens. No complex setup. +The installer auto-detects your stack (React, Python, Go, etc.) and configures everything. **No GitHub tokens needed. No complex setup.** + +✨ **What you get:** +- βœ… GitHub Actions workflows that use built-in authentication +- βœ… No manual token creation or repository secrets required +- βœ… AI code reviews work automatically on all PRs +- βœ… Language-agnostic setup (no Python CI/CD added to non-Python projects) **Or let Claude Code install it for you:** ``` @@ -65,6 +71,7 @@ gh issue create --label "conductor:task" --title "Add dark mode toggle" - [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 +- [FAQ](docs/FAQ.md) - Common questions about tokens, Python, and workflows - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions πŸš€ **[Power User Prompts](CLAUDE_CODE_PROMPT.md)** - Game-changing automation with Claude Code diff --git a/conductor-init.sh b/conductor-init.sh index 8f6c13c..9dd225a 100644 --- a/conductor-init.sh +++ b/conductor-init.sh @@ -17,6 +17,9 @@ echo "==========================================" echo "This script will install Code Conductor into your current Git repository." echo "It will download necessary files and run the setup automatically." echo "" +echo -e "${GREEN}✨ No GitHub Token Setup Required!${NC}" +echo "Code Conductor uses GitHub's built-in authentication - no manual token needed." +echo "" # Step 1: Prerequisite Checks echo -e "${YELLOW}πŸ” Checking prerequisites...${NC}" @@ -36,6 +39,8 @@ fi # Check for Python 3.9-3.12 if ! command -v python3 >/dev/null 2>&1 || ! python3 -c "import sys; exit(0 if sys.version_info >= (3,9) and sys.version_info < (3,13) else 1)"; then echo -e "${RED}❌ Error: Python 3.9-3.12 is required. Please install Python 3.9, 3.10, 3.11, or 3.12.${NC}" + echo -e "${YELLOW}Note: Python is only needed for conductor scripts, NOT for your project's CI/CD.${NC}" + echo -e "${YELLOW}Code Conductor does NOT add Python-specific workflows to non-Python projects.${NC}" exit 1 fi @@ -323,6 +328,13 @@ if [ "$IS_UPGRADE" = false ]; then echo -e "${GREEN}βœ… Setup complete.${NC}" echo "" + + # Emphasize no token requirement + echo -e "${GREEN}πŸ” GitHub Integration Status:${NC}" + echo " βœ… Workflows configured to use GitHub's built-in token" + echo " βœ… No CONDUCTOR_GITHUB_TOKEN setup required" + echo " βœ… AI code reviews will work automatically on PRs" + echo "" else echo -e "${GREEN}βœ… Skipping setup - existing configuration preserved.${NC}" echo "" @@ -583,7 +595,7 @@ case "$ENV_CHOICE" in echo " β€’ Conductor will handle task claiming and worktree setup automatically" echo " β€’ Use the built-in terminal for git operations" echo " β€’ AI code reviews happen automatically on PRs" - echo " β€’ No GitHub token setup neededβ€”uses built-in authentication" + echo -e " β€’ ${GREEN}No GitHub token setup neededβ€”uses built-in authentication${NC}" echo "" echo "πŸ“š Learn more: https://conductor.build" ;; @@ -661,7 +673,7 @@ if [ "$IS_UPGRADE" = true ]; then echo " β€’ Role definitions (.conductor/roles/)" echo " β€’ GitHub workflows (.github/workflows/)" echo " β€’ Setup and configuration tools" - echo " β€’ Token configuration (no manual setup needed)" + echo -e " β€’ ${GREEN}Token configuration (uses GitHub's built-in auth)${NC}" echo "" echo "βœ… What was preserved:" echo " β€’ Your project configuration (.conductor/config.yaml)" @@ -698,6 +710,8 @@ elif [ "$ENV_CHOICE" != "1" ]; then echo " βœ… AI code-reviewer for all PRs" echo " βœ… Specialized roles: ${CONFIGURED_ROLES}" echo " βœ… Demo tasks ready to claim" + echo -e " ${GREEN}βœ… No GitHub token setup required${NC}" + echo -e " ${GREEN}βœ… No Python CI/CD workflows added${NC}" echo "" echo -e "${YELLOW}Quick Start Commands:${NC}" echo -e " πŸ“‹ View tasks: ${GREEN}./conductor tasks${NC}" @@ -725,7 +739,8 @@ else echo " βœ… AI code-reviewer for all PRs" echo " βœ… Specialized roles: ${CONFIGURED_ROLES}" echo " βœ… Demo tasks ready in Conductor" - echo " βœ… No GitHub token setup required" + echo -e " ${GREEN}βœ… No GitHub token setup required${NC}" + echo -e " ${GREEN}βœ… No Python CI/CD workflows added${NC}" echo "" echo "πŸ“š Documentation: https://github.com/ryanmac/code-conductor" echo "πŸ› Report issues: https://github.com/ryanmac/code-conductor/issues" diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..b614c86 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,88 @@ +# Frequently Asked Questions + +## Do I need to set up a CONDUCTOR_GITHUB_TOKEN? + +**No!** Code Conductor uses GitHub's built-in authentication (`${{ github.token }}`) for all workflows. This token is automatically available in GitHub Actions with no setup required. + +You only need a Personal Access Token (PAT) if you want: +- Higher API rate limits (5,000/hour vs 1,000/hour) +- Cross-repository access +- Ability to trigger other workflows + +For detailed token information, see [.conductor/GITHUB_TOKEN_SETUP.md](.conductor/GITHUB_TOKEN_SETUP.md). + +## Why does Code Conductor require Python? + +Python is required **only for the conductor orchestration scripts**, not for your project's CI/CD. Here's what this means: + +- βœ… **Required**: Python 3.9-3.12 to run conductor commands +- ❌ **NOT added**: Python test runners (pytest) +- ❌ **NOT added**: Python linters (flake8, black) +- ❌ **NOT added**: Python security scanners (safety) +- ❌ **NOT added**: Any Python-specific CI/CD workflows + +Your project's existing CI/CD remains unchanged. Code Conductor only adds three language-agnostic GitHub workflows for task orchestration. + +## Does Code Conductor add Python CI/CD to my JavaScript/TypeScript/Go project? + +**No!** Code Conductor is language-agnostic. It detects your project's technology stack and configures roles accordingly, but it does NOT add language-specific CI/CD workflows. + +The only workflows added are: +1. `conductor.yml` - Task orchestration and health checks +2. `conductor-cleanup.yml` - Stale worktree cleanup +3. `pr-review.yml` - AI code reviews (if enabled) + +These workflows only run conductor scripts and do not test, lint, or build your code. + +## What if I see Python test failures in my CI? + +If you're seeing Python test failures like: +``` +============================= test session starts ============================== +collected 0 items +============================ no tests ran in 0.02s ============================= +Error: Process completed with exit code 5. +``` + +This is NOT from Code Conductor. Check if: +1. You accidentally copied CI workflows from the Code Conductor repository itself +2. You have existing Python CI workflows in your project +3. Another tool added Python-specific workflows + +Code Conductor's template workflows do not include any Python testing commands. + +## Can I use Code Conductor without installing Python? + +Currently, Python is required because the conductor scripts are written in Python. We chose Python for: +- Maximum compatibility across all platforms +- Easy installation via standard package managers +- Reliable YAML and JSON processing +- Strong GitHub API support + +Future versions may offer alternative implementations, but Python remains the most universal choice. + +## Do I need to manage Python dependencies for my non-Python project? + +No, the Python dependencies are isolated to Code Conductor's functionality: +- `pyyaml` - For configuration file handling +- Standard library modules only + +These are only used by conductor scripts and do not affect your project's dependencies. + +## How do I know which workflows were added by Code Conductor? + +Code Conductor only adds workflows from its templates: +- `.github/workflows/conductor.yml` +- `.github/workflows/conductor-cleanup.yml` +- `.github/workflows/pr-review.yml` (if code-reviewer role is enabled) + +Any other workflows (especially those running pytest, flake8, etc.) are from other sources. + +## Can I remove the Python dependency from Code Conductor? + +The conductor scripts require Python to run. However, you can: +1. Run agents from the Conductor app (macOS) which handles Python internally +2. Use containerized environments where Python is pre-installed +3. Install Python in your CI environment only (not locally) + +The Python requirement is minimal and doesn't affect your project's runtime or deployment. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 1bda549..6b19b09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ Welcome to the comprehensive Code Conductor documentation. This directory contai - [**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 +- [**FAQ**](FAQ.md) - Frequently asked questions and clarifications ### Core Concepts - [**Architecture**](ARCHITECTURE.md) - System design and components From c2cee47ba80fbca225631f9bbe93eebf56675df6 Mon Sep 17 00:00:00 2001 From: ryanmac Date: Thu, 24 Jul 2025 22:56:58 -0500 Subject: [PATCH 2/2] feat: Auto-configure all roles during installation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simplifies the installation process by automatically configuring all available roles instead of prompting users to select which ones they want. This change: - Removes the interactive role selection prompt - Automatically adds all 8 specialized roles during setup - Updates output messages to reflect automatic configuration - Reduces installation friction and complexity Users can simply ignore roles they don't need. Having all roles available doesn't impose any overhead and ensures maximum flexibility. πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- conductor-init.sh | 115 +++++++++++----------------------------------- 1 file changed, 27 insertions(+), 88 deletions(-) diff --git a/conductor-init.sh b/conductor-init.sh index 9dd225a..faa28a8 100644 --- a/conductor-init.sh +++ b/conductor-init.sh @@ -340,7 +340,7 @@ else echo "" fi -# Step 5: Interactive Role Configuration (improved: numbered menu) - skip for upgrades +# Step 5: Auto-configure All Roles - skip for upgrades if [ "$IS_UPGRADE" = false ]; then echo -e "${YELLOW}🎭 Configuring agent roles...${NC}" @@ -364,100 +364,39 @@ except: echo -e "πŸ“Š Detected technology stacks: ${GREEN}$DETECTED_STACKS${NC}" fi - # Get configured roles - CONFIGURED_ROLES=$(python3 -c " + # Define all available roles + ALL_ROLES=("code-reviewer" "frontend" "mobile" "devops" "security" "ml-engineer" "ui-designer" "data") + + # Automatically configure all roles + echo -e "${YELLOW}πŸ“ Configuring all available roles...${NC}" + + # Update config.yaml with all roles + python3 - </dev/null) - echo -e "🎯 Configured specialized roles: ${GREEN}$CONFIGURED_ROLES${NC}" - echo "" +# Define all available roles +all_roles = ["code-reviewer", "frontend", "mobile", "devops", "security", "ml-engineer", "ui-designer", "data"] - # Parse current roles and filter suggestions - ALL_ROLES=("code-reviewer" "frontend" "mobile" "devops" "security" "ml-engineer" "ui-designer" "data") - ROLE_DESCRIPTIONS=( - "AI-powered PR reviews" - "React, Vue, Angular development" - "React Native, Flutter development" - "CI/CD, deployments, infrastructure" - "Security audits, vulnerability scanning" - "Machine learning tasks" - "Design systems, UI/UX" - "Data pipelines, analytics" - ) - - # Get array of current roles - IFS=' ' read -ra CURRENT_ROLES_ARRAY <<< "$CONFIGURED_ROLES" - - # Build suggested roles (exclude already configured) - SUGGESTED_ROLES=() - SUGGESTED_INDICES=() - for i in "${!ALL_ROLES[@]}"; do - role="${ALL_ROLES[$i]}" - if [[ ! " ${CURRENT_ROLES_ARRAY[@]} " =~ " ${role} " ]]; then - SUGGESTED_ROLES+=("$role") - SUGGESTED_INDICES+=("$i") - fi - done - - # Ask if user wants to adjust roles - if [ ${#SUGGESTED_ROLES[@]} -eq 0 ]; then - echo -e "${GREEN}βœ… All available roles are already configured.${NC}" - else - echo "Available roles to add:" - for i in "${!SUGGESTED_ROLES[@]}"; do - idx=${SUGGESTED_INDICES[$i]} - echo " $((i+1))) ${SUGGESTED_ROLES[$i]} - ${ROLE_DESCRIPTIONS[$idx]}" - done - echo "" - read -p "Select roles to add (comma-separated numbers, or Enter to skip): " -r ROLE_SELECTION - - if [ -n "$ROLE_SELECTION" ]; then - # Parse selected numbers and build role list - SELECTED_ROLES=() - IFS=',' read -ra SELECTIONS <<< "$ROLE_SELECTION" - for num in "${SELECTIONS[@]}"; do - num=$(echo $num | tr -d ' ') # Trim spaces - if [[ $num =~ ^[0-9]+$ ]] && [ "$num" -ge 1 ] && [ "$num" -le "${#SUGGESTED_ROLES[@]}" ]; then - SELECTED_ROLES+=("${SUGGESTED_ROLES[$((num-1))]}") - fi - done - - if [ ${#SELECTED_ROLES[@]} -gt 0 ]; then - # Update config.yaml with selected roles (robust JSON passing) - if ! command -v jq >/dev/null 2>&1; then - echo -e "${RED}❌ jq is required for robust role selection. Please install jq and try again.${NC}" - exit 1 - fi - ROLES_TO_ADD_JSON=$(printf '%s\n' "${SELECTED_ROLES[@]}" | jq -R . | jq -s .) - python3 - "$ROLES_TO_ADD_JSON" <