Skip to content

Commit b561447

Browse files
ryanmacryanmac
authored
Merge pull request #64 from ryanmac/simplify-readme
Simplify README to focus on developer value
2 parents 6731479 + f852f9f commit b561447

16 files changed

+853
-606
lines changed

‎README.md‎

Lines changed: 42 additions & 606 deletions
Large diffs are not rendered by default.

‎docs/AGENT_WORKFLOW.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Agent Workflow
2+
3+
## AI Agent Quick Start
4+
5+
After setup, Code Conductor creates a `CLAUDE.md` file with AI agent instructions. For Claude Code or other AI coding assistants:
6+
7+
```bash
8+
# The ONLY command AI agents need to know:
9+
./conductor start [role]
10+
```
11+
12+
This single command:
13+
- ✅ Shows your role and capabilities
14+
- ✅ Lists available tasks (creates demo tasks if needed)
15+
- ✅ Claims the best matching task automatically
16+
- ✅ Creates an isolated git worktree
17+
- ✅ Provides all context needed to start
18+
19+
## The Perfect Kickoff Prompt
20+
21+
Start any Claude Code session with this value-focused prompt:
22+
23+
```
24+
Ultrathink: What task will create the most value? Find it, claim it, complete it.
25+
```
26+
27+
This prompt:
28+
- Triggers deep analysis with "ultrathink"
29+
- Focuses on value creation over busy work
30+
- Provides clear action steps: find → claim → complete
31+
- Works with any role or project type
32+
33+
**Pro tip**: Add this to your text expander (e.g., `;ustart`) for instant agent activation.
34+
35+
## Example AI Agent Session
36+
37+
```
38+
> ./conductor start frontend
39+
40+
🤖 Code Conductor Agent: frontend
41+
==================================
42+
📋 Role: frontend
43+
44+
📊 Available Tasks:
45+
#42: Implement dark mode toggle
46+
#43: [INIT] Discover project documentation and create task map
47+
#44: Add responsive navigation menu
48+
49+
🎯 Claiming task...
50+
✅ Claimed task #42
51+
📁 Workspace: worktrees/agent-frontend-42
52+
53+
Next: cd worktrees/agent-frontend-42
54+
```
55+
56+
## AI Agent Workflow
57+
58+
1. **Start work**: `./conductor start dev`
59+
2. **Implement**: Work in the created worktree
60+
3. **Complete**: `./conductor complete`
61+
4. **Repeat**: Automatically moves to next task
62+
63+
## Smart Task Discovery
64+
65+
For existing projects, Code Conductor creates a special discovery task that AI agents can claim to:
66+
- Map all project documentation
67+
- Identify implemented vs missing features
68+
- Generate 10-20 specific development tasks
69+
- Create proper GitHub issues automatically
70+
71+
## Launching an Agent
72+
73+
**Option A: Conductor Desktop App (macOS only)**
74+
```bash
75+
export AGENT_ROLE=dev # or devops, security, etc.
76+
./conductor start
77+
# Follow the printed instructions to open in Conductor app
78+
```
79+
80+
**Option B: Multiple Terminals (All Platforms)**
81+
```bash
82+
./conductor start dev
83+
cd worktrees/agent-dev-[task_id]
84+
# Use tmux or screen for session management on Linux/Windows
85+
# Start your Claude Code session in the worktree
86+
```
87+
88+
## Agent Lifecycle
89+
90+
1. **Initialize**: Load role definition and check dependencies
91+
2. **Claim Task**: Atomically claim an available task
92+
3. **Create Worktree**: Isolated git workspace for conflict-free work
93+
4. **Execute Task**: Follow specifications and success criteria
94+
5. **Report Status**: Update heartbeat and progress
95+
6. **Complete/Idle**: Mark complete or report idle for cleanup
96+
97+
## Universal Bootstrap Prompt
98+
99+
The system provides a single prompt that works for any agent:
100+
101+
```
102+
You are a Claude Code agent in a Code Conductor coordinated project.
103+
ROLE: {role}
104+
PROJECT: {project_name}
105+
106+
1. Read your role definition: .conductor/roles/{role}.md
107+
2. Check available tasks: gh issue list -l 'conductor:task' --assignee '!*'
108+
3. Claim a task: python .conductor/scripts/task-claim.py --role {role}
109+
4. Work in your isolated worktree
110+
5. Commit and push changes when complete
111+
112+
Note: Heartbeats are automatically managed by GitHub Actions.
113+
```

‎docs/AI_CODE_REVIEW.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# AI Code Review - Smart, Opt-In Quality Gates
2+
3+
Request AI code reviews when you need them - no more review spam for trivial changes:
4+
5+
- 🎯 **Opt-in reviews** - Add `needs-review` label or comment `/conductor review` to request
6+
- 🔒 **Security scanning** - Agents check for hardcoded secrets, SQL injection risks, unsafe operations
7+
- 🐛 **Bug detection** - Comprehensive analysis for null references, race conditions, logic errors
8+
- 💡 **Smart filtering** - Automatically skips docs-only changes, tiny PRs, and bot updates
9+
- 🧪 **Test coverage** - Suggests missing tests and edge cases
10+
11+
## How It Works
12+
13+
1. **Request a review** - Add `needs-review` label or comment `/conductor review` on your PR
14+
2. **Smart filtering** - System checks if review is needed (skips trivial changes)
15+
3. **Task creation** - Review task appears as GitHub Issue (only if needed)
16+
4. **Agent review** - AI agents claim and complete thorough code review
17+
5. **PR feedback** - Detailed review posted as PR comment
18+
19+
## Automatic Skip Conditions
20+
- PRs with less than 10 lines changed
21+
- Documentation-only changes
22+
- Dependabot and bot PRs
23+
- PRs labeled with `skip-review`
24+
- Draft PRs
25+
26+
## Triggering Reviews
27+
```bash
28+
# Option 1: Add label
29+
gh pr edit 123 --add-label needs-review
30+
31+
# Option 2: Comment on PR
32+
@conductor review # or /conductor review
33+
34+
# Option 3: Manual workflow
35+
gh workflow run pr-review-tasks.yml -f pr_number=123
36+
```

‎docs/ARCHITECTURE.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Architecture
2+
3+
## How It Works
4+
5+
1. **Setup Phase**: Use the universal installer to configure your project. The setup script detects your project type and configures roles.
6+
2. **Task Creation**: Create tasks via GitHub Issues with the `conductor:task` label
7+
3. **Agent Initialization**: Agents use the universal bootstrap to claim work
8+
4. **Isolated Development**: Each agent works in a git worktree to prevent conflicts
9+
5. **Automated Coordination**: GitHub Actions manage health, cleanup, and task flow
10+
11+
## Hybrid Role Model
12+
13+
The system uses a hybrid approach optimized for efficiency:
14+
15+
- **Default Role**: `dev` - A generalist that can handle any task without specific requirements
16+
- **Specialized Roles**: Optional roles like `devops`, `security` for complex domains
17+
18+
This reduces the complexity of managing many agent types while maintaining quality for specialized work.
19+
20+
## File Structure
21+
22+
```
23+
.conductor/
24+
├── config.yaml # Project configuration with auto-detected stack
25+
├── roles/ # Role definitions
26+
│ ├── dev.md # Default generalist
27+
│ ├── code-reviewer.md # AI-powered PR reviewer
28+
│ ├── frontend.md # UI/UX specialist
29+
│ ├── mobile.md # Mobile app developer
30+
│ ├── devops.md # CI/CD specialist
31+
│ ├── security.md # Security specialist
32+
│ ├── ml-engineer.md # ML/AI specialist
33+
│ └── data.md # Data engineer
34+
├── scripts/ # Automation scripts
35+
│ ├── conductor # Universal AI agent command
36+
│ ├── task-claim.py # Atomic task assignment
37+
│ ├── create-review-task.py # Creates review tasks from PRs
38+
│ └── health-check.py # System monitoring
39+
└── examples/ # Stack-specific task templates
40+
├── nextjs-webapp/
41+
├── python-webapp/
42+
├── mobile-app/
43+
└── ...
44+
```
45+
46+
## Core Components
47+
48+
1. **Setup System** (`setup.py`)
49+
- Interactive/auto configuration wizard
50+
- Detects technology stack automatically
51+
- Configures agent roles based on project type
52+
- Creates GitHub workflows for automation
53+
54+
2. **Task Management** (GitHub Issues)
55+
- GitHub Issues with `conductor:task` label serve as tasks
56+
- Issues have unique numbers, descriptions, success criteria
57+
- GitHub's atomic operations prevent race conditions
58+
- Native integration with GitHub Projects and Actions
59+
60+
3. **Agent Roles** (`.conductor/roles/`)
61+
- `dev.md` - Default generalist role for most tasks
62+
- Specialized roles: `devops`, `security`, `frontend`, `mobile`, `ml-engineer`, `data`
63+
- `code-reviewer` - AI-powered PR reviews (always included)
64+
- Hybrid model: prefer `dev` role unless task requires specialization
65+
66+
4. **Agent Coordination** (`.conductor/scripts/`)
67+
- `conductor` - Universal agent command (primary interface)
68+
- `task-claim.py` - Task assignment via GitHub Issue assignment
69+
- `health-check.py` - Monitor agent heartbeats
70+
- `cleanup-stale.py` - Remove abandoned work
71+
- Git worktrees provide isolation between agents
72+
73+
5. **GitHub Integration**
74+
- Issues become tasks via `conductor:task` label
75+
- Actions run health checks every 15 minutes
76+
- AI code reviews on all PRs
77+
- Status dashboard via `conductor:status` issue
78+
79+
## Key Design Patterns
80+
81+
1. **Atomic Operations**: GitHub's issue assignment API ensures atomic task claiming
82+
2. **Worktree Isolation**: Each agent works in separate git worktree (`worktrees/agent-{role}-{task_id}`)
83+
3. **Heartbeat System**: Agents update timestamps; stale work auto-cleaned after timeout
84+
4. **File Conflict Prevention**: Worktree isolation ensures agents work on separate branches
85+
5. **Self-Healing**: GitHub Actions monitor health, clean stale work, process issues

‎docs/BEST_PRACTICES.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Best Practices
2+
3+
1. **Task Design**: Make tasks self-contained with clear specs
4+
2. **Duplicate Prevention**: Check existing issues before creating new ones - use `./conductor check-dup "title"`
5+
3. **Role Selection**: Start with dev-only, add specializations as needed
6+
4. **Regular Cleanup**: Let automation handle stale work
7+
5. **Monitor Health**: Check status issue regularly
8+
6. **Incremental Adoption**: Start small, expand as comfortable
9+
10+
See also: [Duplicate Prevention Guide](DUPLICATE_PREVENTION.md) for detailed strategies
11+
12+
## Task Format
13+
14+
Tasks are created as GitHub Issues with complete specifications:
15+
16+
**Issue Title**: Implement authentication
17+
18+
**Issue Body**:
19+
```markdown
20+
## Description
21+
Implement user authentication system for the application.
22+
23+
## Specifications
24+
See: docs/auth-spec.md
25+
26+
## Best Practices
27+
- Use JWT tokens
28+
- Implement refresh tokens
29+
30+
## Success Criteria
31+
- Tests: 100% coverage
32+
- Security: Pass security scan
33+
```
34+
35+
**Labels**:
36+
- `conductor:task` (required)
37+
- `effort:medium`
38+
- `priority:medium`
39+
- `skill:backend` (optional, for specialized tasks)

‎docs/CONFIGURATION.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Configuration Guide
2+
3+
## Project Configuration
4+
5+
The main configuration file is `.conductor/config.yaml`, created during setup.
6+
7+
### Configuration Structure
8+
9+
```yaml
10+
# .conductor/config.yaml
11+
project_name: string
12+
documentation:
13+
main: string (path to main docs)
14+
additional: [array of paths]
15+
technology_stack:
16+
languages: [detected languages]
17+
frameworks: [detected frameworks]
18+
tools: [detected build tools]
19+
roles:
20+
default: "dev"
21+
specialized: [list of specialized roles]
22+
github_integration:
23+
enabled: boolean
24+
issue_to_task: boolean
25+
pr_reviews: boolean
26+
worktree_retention_days: number (default 7)
27+
```
28+
29+
## Setup Options
30+
31+
Run `python setup.py` to configure:
32+
33+
- Project name and documentation location
34+
- Technology stack detection
35+
- Role selection (hybrid model)
36+
- Task management approach
37+
- GitHub integration settings
38+
39+
## Role Definitions
40+
41+
Each role has a Markdown file in `.conductor/roles/` defining:
42+
43+
- Responsibilities
44+
- Task selection criteria
45+
- Required skills
46+
- Success metrics
47+
48+
## Environment Variables
49+
50+
- `AGENT_ROLE` - Set the default agent role
51+
- `CONDUCTOR_DEBUG` - Enable debug logging
52+
- `WORKTREE_BASE` - Override default worktree location

‎docs/DEVELOPMENT.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Development Setup
2+
3+
## Prerequisites
4+
- Python 3.9-3.12
5+
- Git
6+
- GitHub CLI (optional, for issue integration)
7+
8+
## Local Development
9+
```bash
10+
# Clone and setup
11+
git clone https://github.com/ryanmac/code-conductor.git
12+
cd code-conductor
13+
14+
# Install with Poetry (recommended)
15+
poetry install
16+
17+
# Or with pip
18+
python3 -m venv .venv
19+
source .venv/bin/activate
20+
pip install -r requirements.txt
21+
22+
# Run tests
23+
poetry run pytest tests/ -v
24+
# or
25+
python -m pytest tests/ -v
26+
27+
# Run linting
28+
poetry run flake8 .conductor/scripts/ setup.py
29+
poetry run black --check .conductor/scripts/ setup.py
30+
```
31+
32+
## CI/CD
33+
The project uses GitHub Actions for continuous integration:
34+
- **Linting**: flake8 and black formatting checks
35+
- **Testing**: pytest on multiple Python versions (3.9, 3.10, 3.11, 3.12)
36+
- **Security**: safety vulnerability scanning
37+
- **Platforms**: Ubuntu and macOS
38+
39+
## Contributing
40+
41+
This is a template repository. To contribute:
42+
43+
1. Fork and improve
44+
2. Test with your project type
45+
3. Submit PRs with examples
46+
4. Share your adaptations
47+
48+
### Development Guidelines
49+
- Follow PEP 8 style guidelines
50+
- Add tests for new functionality
51+
- Update documentation for changes
52+
- Ensure CI passes before submitting PRs

0 commit comments

Comments
 (0)