Skip to content

Commit c3be135

Browse files
authored
Merge pull request #68 from ryanmac/fix/language-agnostic-setup-and-docs
2 parents 4ed1c81 + c2cee47 commit c3be135

File tree

4 files changed

+142
-92
lines changed

4 files changed

+142
-92
lines changed

README.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,13 @@ One command. 60 seconds. Done.
2626
bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh)
2727
```
2828

29-
The installer auto-detects your stack (React, Python, Go, etc.) and configures everything. No GitHub tokens. No complex setup.
29+
The installer auto-detects your stack (React, Python, Go, etc.) and configures everything. **No GitHub tokens needed. No complex setup.**
30+
31+
**What you get:**
32+
- ✅ GitHub Actions workflows that use built-in authentication
33+
- ✅ No manual token creation or repository secrets required
34+
- ✅ AI code reviews work automatically on all PRs
35+
- ✅ Language-agnostic setup (no Python CI/CD added to non-Python projects)
3036

3137
**Or let Claude Code install it for you:**
3238
```
@@ -65,6 +71,7 @@ gh issue create --label "conductor:task" --title "Add dark mode toggle"
6571
- [Stack Support](docs/STACK_SUPPORT.md) - Works with React, Vue, Python, Go, and more
6672
- [Architecture](docs/ARCHITECTURE.md) - How it all works under the hood
6773
- [AI Code Review](docs/AI_CODE_REVIEW.md) - Smart, opt-in PR reviews
74+
- [FAQ](docs/FAQ.md) - Common questions about tokens, Python, and workflows
6875
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
6976

7077
🚀 **[Power User Prompts](CLAUDE_CODE_PROMPT.md)** - Game-changing automation with Claude Code

conductor-init.sh

Lines changed: 45 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ echo "=========================================="
1717
echo "This script will install Code Conductor into your current Git repository."
1818
echo "It will download necessary files and run the setup automatically."
1919
echo ""
20+
echo -e "${GREEN}✨ No GitHub Token Setup Required!${NC}"
21+
echo "Code Conductor uses GitHub's built-in authentication - no manual token needed."
22+
echo ""
2023

2124
# Step 1: Prerequisite Checks
2225
echo -e "${YELLOW}🔍 Checking prerequisites...${NC}"
@@ -36,6 +39,8 @@ fi
3639
# Check for Python 3.9-3.12
3740
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
3841
echo -e "${RED}❌ Error: Python 3.9-3.12 is required. Please install Python 3.9, 3.10, 3.11, or 3.12.${NC}"
42+
echo -e "${YELLOW}Note: Python is only needed for conductor scripts, NOT for your project's CI/CD.${NC}"
43+
echo -e "${YELLOW}Code Conductor does NOT add Python-specific workflows to non-Python projects.${NC}"
3944
exit 1
4045
fi
4146

@@ -323,12 +328,19 @@ if [ "$IS_UPGRADE" = false ]; then
323328

324329
echo -e "${GREEN}✅ Setup complete.${NC}"
325330
echo ""
331+
332+
# Emphasize no token requirement
333+
echo -e "${GREEN}🔐 GitHub Integration Status:${NC}"
334+
echo " ✅ Workflows configured to use GitHub's built-in token"
335+
echo " ✅ No CONDUCTOR_GITHUB_TOKEN setup required"
336+
echo " ✅ AI code reviews will work automatically on PRs"
337+
echo ""
326338
else
327339
echo -e "${GREEN}✅ Skipping setup - existing configuration preserved.${NC}"
328340
echo ""
329341
fi
330342

331-
# Step 5: Interactive Role Configuration (improved: numbered menu) - skip for upgrades
343+
# Step 5: Auto-configure All Roles - skip for upgrades
332344
if [ "$IS_UPGRADE" = false ]; then
333345
echo -e "${YELLOW}🎭 Configuring agent roles...${NC}"
334346

@@ -352,100 +364,39 @@ except:
352364
echo -e "📊 Detected technology stacks: ${GREEN}$DETECTED_STACKS${NC}"
353365
fi
354366

355-
# Get configured roles
356-
CONFIGURED_ROLES=$(python3 -c "
367+
# Define all available roles
368+
ALL_ROLES=("code-reviewer" "frontend" "mobile" "devops" "security" "ml-engineer" "ui-designer" "data")
369+
370+
# Automatically configure all roles
371+
echo -e "${YELLOW}📝 Configuring all available roles...${NC}"
372+
373+
# Update config.yaml with all roles
374+
python3 - <<EOF
357375
import yaml
358-
try:
359-
with open('.conductor/config.yaml', 'r') as f:
360-
config = yaml.safe_load(f)
361-
roles = config.get('roles', {}).get('specialized', [])
362-
print(' '.join(roles))
363-
except:
364-
print('code-reviewer')
365-
" 2>/dev/null)
366-
367-
echo -e "🎯 Configured specialized roles: ${GREEN}$CONFIGURED_ROLES${NC}"
368-
echo ""
369376
370-
# Parse current roles and filter suggestions
371-
ALL_ROLES=("code-reviewer" "frontend" "mobile" "devops" "security" "ml-engineer" "ui-designer" "data")
372-
ROLE_DESCRIPTIONS=(
373-
"AI-powered PR reviews"
374-
"React, Vue, Angular development"
375-
"React Native, Flutter development"
376-
"CI/CD, deployments, infrastructure"
377-
"Security audits, vulnerability scanning"
378-
"Machine learning tasks"
379-
"Design systems, UI/UX"
380-
"Data pipelines, analytics"
381-
)
382-
383-
# Get array of current roles
384-
IFS=' ' read -ra CURRENT_ROLES_ARRAY <<< "$CONFIGURED_ROLES"
385-
386-
# Build suggested roles (exclude already configured)
387-
SUGGESTED_ROLES=()
388-
SUGGESTED_INDICES=()
389-
for i in "${!ALL_ROLES[@]}"; do
390-
role="${ALL_ROLES[$i]}"
391-
if [[ ! " ${CURRENT_ROLES_ARRAY[@]} " =~ " ${role} " ]]; then
392-
SUGGESTED_ROLES+=("$role")
393-
SUGGESTED_INDICES+=("$i")
394-
fi
395-
done
377+
# Define all available roles
378+
all_roles = ["code-reviewer", "frontend", "mobile", "devops", "security", "ml-engineer", "ui-designer", "data"]
396379
397-
# Ask if user wants to adjust roles
398-
if [ ${#SUGGESTED_ROLES[@]} -eq 0 ]; then
399-
echo -e "${GREEN}✅ All available roles are already configured.${NC}"
400-
else
401-
echo "Available roles to add:"
402-
for i in "${!SUGGESTED_ROLES[@]}"; do
403-
idx=${SUGGESTED_INDICES[$i]}
404-
echo " $((i+1))) ${SUGGESTED_ROLES[$i]} - ${ROLE_DESCRIPTIONS[$idx]}"
405-
done
406-
echo ""
407-
read -p "Select roles to add (comma-separated numbers, or Enter to skip): " -r ROLE_SELECTION
408-
409-
if [ -n "$ROLE_SELECTION" ]; then
410-
# Parse selected numbers and build role list
411-
SELECTED_ROLES=()
412-
IFS=',' read -ra SELECTIONS <<< "$ROLE_SELECTION"
413-
for num in "${SELECTIONS[@]}"; do
414-
num=$(echo $num | tr -d ' ') # Trim spaces
415-
if [[ $num =~ ^[0-9]+$ ]] && [ "$num" -ge 1 ] && [ "$num" -le "${#SUGGESTED_ROLES[@]}" ]; then
416-
SELECTED_ROLES+=("${SUGGESTED_ROLES[$((num-1))]}")
417-
fi
418-
done
419-
420-
if [ ${#SELECTED_ROLES[@]} -gt 0 ]; then
421-
# Update config.yaml with selected roles (robust JSON passing)
422-
if ! command -v jq >/dev/null 2>&1; then
423-
echo -e "${RED}❌ jq is required for robust role selection. Please install jq and try again.${NC}"
424-
exit 1
425-
fi
426-
ROLES_TO_ADD_JSON=$(printf '%s\n' "${SELECTED_ROLES[@]}" | jq -R . | jq -s .)
427-
python3 - "$ROLES_TO_ADD_JSON" <<EOF
428-
import sys, json, yaml
380+
# Read current config
429381
with open('.conductor/config.yaml', 'r') as f:
430382
config = yaml.safe_load(f)
431-
current_roles = config.get('roles', {}).get('specialized', [])
432-
new_roles = json.loads(sys.argv[1])
433-
combined_roles = list(set(current_roles + new_roles))
434-
config['roles']['specialized'] = combined_roles
383+
384+
# Update roles to include all available roles
385+
config['roles']['specialized'] = all_roles
386+
387+
# Write updated config
435388
with open('.conductor/config.yaml', 'w') as f:
436389
yaml.dump(config, f, default_flow_style=False)
437-
print(f'✅ Roles added: {", ".join(new_roles)}')
390+
391+
print(f'✅ All {len(all_roles)} roles configured: {", ".join(all_roles)}')
438392
EOF
439-
if [ $? -ne 0 ]; then
440-
echo -e "${YELLOW}⚠️ Could not update roles automatically.${NC}"
441-
fi
442-
else
443-
echo -e "${YELLOW}⚠️ No valid selections made.${NC}"
444-
fi
445-
else
446-
echo -e "${GREEN}✅ Keeping current role configuration.${NC}"
447-
fi
393+
394+
if [ $? -ne 0 ]; then
395+
echo -e "${YELLOW}⚠️ Could not configure roles automatically. Continuing anyway...${NC}"
396+
else
397+
echo -e "${GREEN}✅ All agent roles are now available for use!${NC}"
448398
fi
399+
echo ""
449400
else
450401
echo -e "${GREEN}✅ Existing role configuration preserved.${NC}"
451402
fi
@@ -583,7 +534,7 @@ case "$ENV_CHOICE" in
583534
echo " • Conductor will handle task claiming and worktree setup automatically"
584535
echo " • Use the built-in terminal for git operations"
585536
echo " • AI code reviews happen automatically on PRs"
586-
echo " • No GitHub token setup needed—uses built-in authentication"
537+
echo -e "${GREEN}No GitHub token setup needed—uses built-in authentication${NC}"
587538
echo ""
588539
echo "📚 Learn more: https://conductor.build"
589540
;;
@@ -661,7 +612,7 @@ if [ "$IS_UPGRADE" = true ]; then
661612
echo " • Role definitions (.conductor/roles/)"
662613
echo " • GitHub workflows (.github/workflows/)"
663614
echo " • Setup and configuration tools"
664-
echo " • Token configuration (no manual setup needed)"
615+
echo -e "${GREEN}Token configuration (uses GitHub's built-in auth)${NC}"
665616
echo ""
666617
echo "✅ What was preserved:"
667618
echo " • Your project configuration (.conductor/config.yaml)"
@@ -696,8 +647,10 @@ elif [ "$ENV_CHOICE" != "1" ]; then
696647
echo " ✅ Auto-detected technology stack"
697648
fi
698649
echo " ✅ AI code-reviewer for all PRs"
699-
echo "Specialized roles: ${CONFIGURED_ROLES}"
650+
echo "All specialized roles configured (frontend, backend, devops, security, etc.)"
700651
echo " ✅ Demo tasks ready to claim"
652+
echo -e " ${GREEN}✅ No GitHub token setup required${NC}"
653+
echo -e " ${GREEN}✅ No Python CI/CD workflows added${NC}"
701654
echo ""
702655
echo -e "${YELLOW}Quick Start Commands:${NC}"
703656
echo -e " 📋 View tasks: ${GREEN}./conductor tasks${NC}"
@@ -723,9 +676,10 @@ else
723676
echo " ✅ Auto-detected technology stack"
724677
fi
725678
echo " ✅ AI code-reviewer for all PRs"
726-
echo "Specialized roles: ${CONFIGURED_ROLES}"
679+
echo "All specialized roles configured (frontend, backend, devops, security, etc.)"
727680
echo " ✅ Demo tasks ready in Conductor"
728-
echo " ✅ No GitHub token setup required"
681+
echo -e " ${GREEN}✅ No GitHub token setup required${NC}"
682+
echo -e " ${GREEN}✅ No Python CI/CD workflows added${NC}"
729683
echo ""
730684
echo "📚 Documentation: https://github.com/ryanmac/code-conductor"
731685
echo "🐛 Report issues: https://github.com/ryanmac/code-conductor/issues"

docs/FAQ.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Frequently Asked Questions
2+
3+
## Do I need to set up a CONDUCTOR_GITHUB_TOKEN?
4+
5+
**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.
6+
7+
You only need a Personal Access Token (PAT) if you want:
8+
- Higher API rate limits (5,000/hour vs 1,000/hour)
9+
- Cross-repository access
10+
- Ability to trigger other workflows
11+
12+
For detailed token information, see [.conductor/GITHUB_TOKEN_SETUP.md](.conductor/GITHUB_TOKEN_SETUP.md).
13+
14+
## Why does Code Conductor require Python?
15+
16+
Python is required **only for the conductor orchestration scripts**, not for your project's CI/CD. Here's what this means:
17+
18+
-**Required**: Python 3.9-3.12 to run conductor commands
19+
-**NOT added**: Python test runners (pytest)
20+
-**NOT added**: Python linters (flake8, black)
21+
-**NOT added**: Python security scanners (safety)
22+
-**NOT added**: Any Python-specific CI/CD workflows
23+
24+
Your project's existing CI/CD remains unchanged. Code Conductor only adds three language-agnostic GitHub workflows for task orchestration.
25+
26+
## Does Code Conductor add Python CI/CD to my JavaScript/TypeScript/Go project?
27+
28+
**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.
29+
30+
The only workflows added are:
31+
1. `conductor.yml` - Task orchestration and health checks
32+
2. `conductor-cleanup.yml` - Stale worktree cleanup
33+
3. `pr-review.yml` - AI code reviews (if enabled)
34+
35+
These workflows only run conductor scripts and do not test, lint, or build your code.
36+
37+
## What if I see Python test failures in my CI?
38+
39+
If you're seeing Python test failures like:
40+
```
41+
============================= test session starts ==============================
42+
collected 0 items
43+
============================ no tests ran in 0.02s =============================
44+
Error: Process completed with exit code 5.
45+
```
46+
47+
This is NOT from Code Conductor. Check if:
48+
1. You accidentally copied CI workflows from the Code Conductor repository itself
49+
2. You have existing Python CI workflows in your project
50+
3. Another tool added Python-specific workflows
51+
52+
Code Conductor's template workflows do not include any Python testing commands.
53+
54+
## Can I use Code Conductor without installing Python?
55+
56+
Currently, Python is required because the conductor scripts are written in Python. We chose Python for:
57+
- Maximum compatibility across all platforms
58+
- Easy installation via standard package managers
59+
- Reliable YAML and JSON processing
60+
- Strong GitHub API support
61+
62+
Future versions may offer alternative implementations, but Python remains the most universal choice.
63+
64+
## Do I need to manage Python dependencies for my non-Python project?
65+
66+
No, the Python dependencies are isolated to Code Conductor's functionality:
67+
- `pyyaml` - For configuration file handling
68+
- Standard library modules only
69+
70+
These are only used by conductor scripts and do not affect your project's dependencies.
71+
72+
## How do I know which workflows were added by Code Conductor?
73+
74+
Code Conductor only adds workflows from its templates:
75+
- `.github/workflows/conductor.yml`
76+
- `.github/workflows/conductor-cleanup.yml`
77+
- `.github/workflows/pr-review.yml` (if code-reviewer role is enabled)
78+
79+
Any other workflows (especially those running pytest, flake8, etc.) are from other sources.
80+
81+
## Can I remove the Python dependency from Code Conductor?
82+
83+
The conductor scripts require Python to run. However, you can:
84+
1. Run agents from the Conductor app (macOS) which handles Python internally
85+
2. Use containerized environments where Python is pre-installed
86+
3. Install Python in your CI environment only (not locally)
87+
88+
The Python requirement is minimal and doesn't affect your project's runtime or deployment.

docs/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Welcome to the comprehensive Code Conductor documentation. This directory contai
88
- [**Installation Guide**](INSTALLATION.md) - All installation methods and options
99
- [**Usage Guide**](USAGE.md) - How to use Code Conductor effectively
1010
- [**Stack Support**](STACK_SUPPORT.md) - Supported technologies and frameworks
11+
- [**FAQ**](FAQ.md) - Frequently asked questions and clarifications
1112

1213
### Core Concepts
1314
- [**Architecture**](ARCHITECTURE.md) - System design and components

0 commit comments

Comments
 (0)