ryanmac · ryanmac · Jul 25, 2025 · Jul 25, 2025 · Jul 25, 2025
diff --git 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
@@ -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,12 +328,19 @@ 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 ""
 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}"
 
@@ -352,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 - <<EOF
 import yaml
-try:
-    with open('.conductor/config.yaml', 'r') as f:
-        config = yaml.safe_load(f)
-        roles = config.get('roles', {}).get('specialized', [])
-        print(' '.join(roles))
-except:
-    print('code-reviewer')
-" 2>/dev/null)
-
-    echo -e "🎯 Configured specialized roles: ${GREEN}$CONFIGURED_ROLES${NC}"
-    echo ""
 
-    # 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
+# Define all available roles
+all_roles = ["code-reviewer", "frontend", "mobile", "devops", "security", "ml-engineer", "ui-designer", "data"]
 
-    # 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" <<EOF
-import sys, json, yaml
+# Read current config
 with open('.conductor/config.yaml', 'r') as f:
     config = yaml.safe_load(f)
-current_roles = config.get('roles', {}).get('specialized', [])
-new_roles = json.loads(sys.argv[1])
-combined_roles = list(set(current_roles + new_roles))
-config['roles']['specialized'] = combined_roles
+
+# Update roles to include all available roles
+config['roles']['specialized'] = all_roles
+
+# Write updated config
 with open('.conductor/config.yaml', 'w') as f:
     yaml.dump(config, f, default_flow_style=False)
-print(f'✅ Roles added: {", ".join(new_roles)}')
+
+print(f'✅ All {len(all_roles)} roles configured: {", ".join(all_roles)}')
 EOF
-                if [ $? -ne 0 ]; then
-                    echo -e "${YELLOW}⚠️ Could not update roles automatically.${NC}"
-                fi
-            else
-                echo -e "${YELLOW}⚠️ No valid selections made.${NC}"
-            fi
-        else
-            echo -e "${GREEN}✅ Keeping current role configuration.${NC}"
-        fi
+
+    if [ $? -ne 0 ]; then
+        echo -e "${YELLOW}⚠️ Could not configure roles automatically. Continuing anyway...${NC}"
+    else
+        echo -e "${GREEN}✅ All agent roles are now available for use!${NC}"
     fi
+    echo ""
 else
     echo -e "${GREEN}✅ Existing role configuration preserved.${NC}"
 fi
@@ -583,7 +534,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 +612,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)"
@@ -696,8 +647,10 @@ elif [ "$ENV_CHOICE" != "1" ]; then
         echo "  ✅ Auto-detected technology stack"
     fi
     echo "  ✅ AI code-reviewer for all PRs"
-    echo "  ✅ Specialized roles: ${CONFIGURED_ROLES}"
+    echo "  ✅ All specialized roles configured (frontend, backend, devops, security, etc.)"
     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}"
@@ -723,9 +676,10 @@ else
         echo "  ✅ Auto-detected technology stack"
     fi
     echo "  ✅ AI code-reviewer for all PRs"
-    echo "  ✅ Specialized roles: ${CONFIGURED_ROLES}"
+    echo "  ✅ All specialized roles configured (frontend, backend, devops, security, etc.)"
     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
@@ -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.
diff --git 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