1  # Alpha/Delta Protocol — Claude Code Orchestrator
  2  
  3  ## Overview
  4  
  5  A distributed development orchestration system that manages multiple Claude Code instances working in parallel on different aspects of the Alpha/Delta Protocol.
  6  
  7  ```
  8  ┌─────────────────────────────────────────────────────────────────────────────┐
  9  │                              YOUR TERMINAL                                   │
 10  │                                                                              │
 11  │  ┌─────────────────────────────────────────────────────────────────────────┐│
 12  │  │                         ORCHESTRATOR UI                                 ││
 13  │  │                                                                         ││
 14  │  │  Worker Status                                                          ││
 15  │  │  ┌────────────┬───────────┬──────────┬─────────────────┬───────────┐  ││
 16  │  │  │ Worker     │ Role      │ Status   │ Current Task    │ Completed │  ││
 17  │  │  ├────────────┼───────────┼──────────┼─────────────────┼───────────┤  ││
 18  │  │  │ planner    │ planner   │ working  │ Q1 Roadmap...   │ 3         │  ││
 19  │  │  │ exec-alpha │ executor  │ working  │ Validator mod...│ 12        │  ││
 20  │  │  │ exec-delta │ executor  │ idle     │                 │ 8         │  ││
 21  │  │  │ exec-infra │ executor  │ waiting  │ CI Pipeline...  │ 5         │  ││
 22  │  │  │ docs       │ docs      │ working  │ Update API...   │ 15        │  ││
 23  │  │  └────────────┴───────────┴──────────┴─────────────────┴───────────┘  ││
 24  │  │                                                                         ││
 25  │  │  Task Queue: Pending: 7 | In Progress: 3 | Completed: 38 | Failed: 1   ││
 26  │  │                                                                         ││
 27  │  │  ⚠️  Human Input Required:                                              ││
 28  │  │    [exec-infra] Should I use DO Spaces or MinIO for artifact storage?  ││
 29  │  │                                                                         ││
 30  │  └─────────────────────────────────────────────────────────────────────────┘│
 31  │                                                                              │
 32  │  $ orchestrator respond exec-infra "Use DO Spaces, we already have it"      │
 33  │                                                                              │
 34  └─────────────────────────────────────────────────────────────────────────────┘
 35  ```
 36  
 37  ## Architecture
 38  
 39  ### Worker Roles
 40  
 41  | Role | Purpose | Count |
 42  |------|---------|-------|
 43  | **Planner** | Analyzes architecture, creates task specifications (CSPECs) | 1 |
 44  | **Executor (Alpha)** | Implements ALPHA chain features | 1 |
 45  | **Executor (Delta)** | Implements DELTA exchange features | 1 |
 46  | **Executor (Infra)** | Implements CI/CD, tooling, infrastructure | 1 |
 47  | **Documentation** | Keeps all docs synchronized with code | 1 |
 48  
 49  ### Communication Flow
 50  
 51  ```
 52                      ┌─────────────────┐
 53                      │   ORCHESTRATOR  │
 54                      │                 │
 55                      │  • Task Queue   │
 56                      │  • Message Bus  │
 57                      │  • Status UI    │
 58                      └────────┬────────┘
 59                               │
 60           ┌───────────────────┼───────────────────┐
 61           │                   │                   │
 62           ▼                   ▼                   ▼
 63      ┌─────────┐        ┌─────────┐        ┌─────────┐
 64      │ PLANNER │        │EXECUTORS│        │  DOCS   │
 65      │         │        │         │        │         │
 66      │ Creates │───────►│ Execute │───────►│ Update  │
 67      │ CSPECs  │ tasks  │ tasks   │ notify │ docs    │
 68      └─────────┘        └─────────┘        └─────────┘
 69           │                   │                   │
 70           │                   │                   │
 71           ▼                   ▼                   ▼
 72      ┌─────────────────────────────────────────────┐
 73      │              SHARED REPOSITORIES             │
 74      │                                              │
 75      │  alpha-delta-context/   alpha-delta-protocol/│
 76      └─────────────────────────────────────────────┘
 77  ```
 78  
 79  ### Each Worker Has
 80  
 81  1. **Isolated Working Directory**: Own copy of repos to avoid conflicts
 82  2. **Tmux Session**: Persistent, observable, debuggable
 83  3. **Task Inbox**: `tasks/current_task.md`
 84  4. **Output Directory**: `outputs/` for results and questions
 85  5. **Role-Specific System Prompt**: Tailored instructions
 86  
 87  ## Installation
 88  
 89  ### Prerequisites
 90  
 91  ```bash
 92  # Required
 93  - Python 3.10+
 94  - tmux
 95  - git
 96  - Claude Code CLI (claude)
 97  
 98  # Optional (for better UI)
 99  pip install rich
100  ```
101  
102  ### Setup
103  
104  ```bash
105  # Clone the orchestrator
106  git clone <orchestrator-repo> ~/alpha-delta-orchestrator
107  cd ~/alpha-delta-orchestrator
108  
109  # Install dependencies
110  pip install rich anthropic
111  
112  # Set API key
113  export ANTHROPIC_API_KEY="sk-ant-..."
114  
115  # Create workspace structure
116  mkdir -p ~/alpha-delta-workspace
117  cd ~/alpha-delta-workspace
118  
119  # Clone your repositories
120  git clone https://ci.yourdomain.com/alpha-delta/alpha-delta-context.git
121  git clone https://ci.yourdomain.com/alpha-delta/alpha-delta-protocol.git
122  ```
123  
124  ### Configuration
125  
126  Edit `orchestrator.py` or set environment variables:
127  
128  ```bash
129  # Workspace paths
130  export ORCHESTRATOR_WORKSPACE=~/alpha-delta-workspace
131  export ORCHESTRATOR_CONTEXT_REPO=~/alpha-delta-workspace/alpha-delta-context
132  export ORCHESTRATOR_PROTOCOL_REPO=~/alpha-delta-workspace/alpha-delta-protocol
133  
134  # Worker configuration
135  export ORCHESTRATOR_MAX_EXECUTORS=3
136  export ORCHESTRATOR_POLL_INTERVAL=2
137  ```
138  
139  ## Usage
140  
141  ### Starting the Orchestrator
142  
143  ```bash
144  # Full system (all workers)
145  python orchestrator.py start
146  
147  # Without planner (manual task creation only)
148  python orchestrator.py start --no-planner
149  
150  # With specific executor count
151  python orchestrator.py start --executors 2
152  ```
153  
154  ### Monitoring Status
155  
156  ```bash
157  # Real-time status (shown automatically when running)
158  python orchestrator.py status
159  
160  # View specific worker logs
161  python orchestrator.py logs executor-alpha
162  python orchestrator.py logs planner --lines 100
163  ```
164  
165  ### Managing Tasks
166  
167  ```bash
168  # Add task manually
169  python orchestrator.py add-task "Implement validator slashing" \
170    --role executor \
171    --priority high \
172    --description "Implement slashing logic per spec section 4.2.3"
173  
174  # List all tasks
175  python orchestrator.py tasks
176  
177  # List pending tasks only
178  python orchestrator.py tasks --status pending
179  ```
180  
181  ### Responding to Workers
182  
183  When a worker needs human input, you'll see a notification:
184  
185  ```
186  ⚠️  Human Input Required:
187    [executor-infra] Should I use DO Spaces or MinIO for artifact storage?
188  ```
189  
190  Respond with:
191  
192  ```bash
193  python orchestrator.py respond executor-infra "Use DO Spaces, we already have it configured"
194  ```
195  
196  ### Stopping
197  
198  ```bash
199  # Graceful shutdown
200  python orchestrator.py stop
201  
202  # Or Ctrl+C in the running terminal
203  ```
204  
205  ## Worker Deep Dive
206  
207  ### Planner Worker
208  
209  The planner reads architecture documentation and creates tasks:
210  
211  **Input**: Architecture docs, specs, CSPECs in `alpha-delta-context/`
212  
213  **Output**: Task specifications in `outputs/tasks/`:
214  ```markdown
215  # Task: Implement Validator Registration
216  
217  **Component**: alpha-chain
218  **Priority**: High
219  **Depends On**: task_consensus_base
220  
221  ## Description
222  Implement the validator registration system as specified in 
223  Technical Specification 3.0, Section 4.2.
224  
225  ## Acceptance Criteria
226  - [ ] Validators can register with stake
227  - [ ] Registration events are emitted
228  - [ ] Minimum stake requirements enforced
229  
230  ## Implementation Notes
231  - Use the ValidatorRegistry trait from alpha-common
232  - Follow the existing pattern in governance module
233  ```
234  
235  ### Executor Workers
236  
237  Executors implement tasks assigned by the planner or manually:
238  
239  **Workflow**:
240  1. Read `tasks/current_task.md`
241  2. Implement the solution
242  3. Run tests
243  4. Commit to feature branch
244  5. Write result to `outputs/{task_id}_result.md`
245  
246  **If blocked**: Write question to `outputs/{task_id}_question.md`
247  
248  ### Documentation Worker
249  
250  Keeps documentation synchronized:
251  
252  **Monitors**:
253  - Code changes in `alpha-delta-protocol/`
254  - New features completed by executors
255  
256  **Updates**:
257  - Technical Specification
258  - API documentation
259  - README files
260  - Changelog
261  
262  ## Advanced Features
263  
264  ### Accessing Worker Sessions Directly
265  
266  Each worker runs in a tmux session:
267  
268  ```bash
269  # List sessions
270  tmux ls
271  
272  # Attach to a worker
273  tmux attach -t claude-executor-alpha
274  
275  # Detach: Ctrl+B, then D
276  ```
277  
278  ### Custom Worker Prompts
279  
280  Edit the `_get_system_prompt()` method in `orchestrator.py` to customize worker behavior.
281  
282  ### Adding New Worker Roles
283  
284  ```python
285  class WorkerRole(Enum):
286      PLANNER = "planner"
287      EXECUTOR = "executor"
288      DOCUMENTATION = "documentation"
289      SECURITY = "security"  # Add new role
290      TESTING = "testing"    # Add new role
291  ```
292  
293  Then add role-specific prompts in `_get_system_prompt()`.
294  
295  ### Task Dependencies
296  
297  Tasks can specify dependencies:
298  
299  ```python
300  task = Task(
301      id="impl_slashing",
302      title="Implement Slashing",
303      description="...",
304      role=WorkerRole.EXECUTOR,
305      parent_task_id="impl_validator_base"  # Won't start until parent completes
306  )
307  ```
308  
309  ### Parallel Execution Limits
310  
311  Control parallelism:
312  
313  ```python
314  config = OrchestratorConfig(
315      max_executors=3,  # Max concurrent executor workers
316  )
317  ```
318  
319  ## Troubleshooting
320  
321  ### Worker Not Starting
322  
323  ```bash
324  # Check if tmux session exists
325  tmux ls | grep claude-
326  
327  # Check logs
328  cat ~/alpha-delta-workspace/orchestrator-logs/executor-alpha.log
329  
330  # Manually check the session
331  tmux attach -t claude-executor-alpha
332  ```
333  
334  ### API Key Issues
335  
336  ```bash
337  # Verify key is set
338  echo $ANTHROPIC_API_KEY
339  
340  # Test Claude Code directly
341  claude --version
342  claude "Hello, test"
343  ```
344  
345  ### Worker Stuck
346  
347  ```bash
348  # Send interrupt to worker
349  tmux send-keys -t claude-executor-alpha C-c
350  
351  # Or restart specific worker (from orchestrator)
352  # Currently requires full restart - enhancement planned
353  ```
354  
355  ### Task Not Being Picked Up
356  
357  ```bash
358  # Check task queue
359  python orchestrator.py tasks
360  
361  # Check worker status
362  python orchestrator.py status
363  
364  # Verify worker role matches task role
365  ```
366  
367  ## Best Practices
368  
369  ### 1. Start with Planning
370  
371  Let the planner analyze your architecture first:
372  
373  ```bash
374  python orchestrator.py start
375  # Wait for planner to create initial tasks
376  ```
377  
378  ### 2. Review Planner Output
379  
380  Check the generated tasks before executors start:
381  
382  ```bash
383  ls ~/alpha-delta-workspace/workers/planner/outputs/tasks/
384  ```
385  
386  ### 3. Prioritize Critical Path
387  
388  Add high-priority tasks for blockers:
389  
390  ```bash
391  python orchestrator.py add-task "Fix CI pipeline blocker" \
392    --role executor \
393    --priority critical
394  ```
395  
396  ### 4. Keep Context Updated
397  
398  Regularly sync the context repo:
399  
400  ```bash
401  cd ~/alpha-delta-workspace/alpha-delta-context
402  git pull origin main
403  ```
404  
405  ### 5. Monitor Resource Usage
406  
407  With 5 Claude Code instances, monitor API usage:
408  
409  ```bash
410  # Check Anthropic console for usage
411  # Consider rate limiting if needed
412  ```
413  
414  ## Integration with CI
415  
416  The orchestrator can be triggered by CI events:
417  
418  ```yaml
419  # .forgejo/workflows/orchestrator-tasks.yml
420  name: Create Orchestrator Task
421  
422  on:
423    issues:
424      types: [labeled]
425  
426  jobs:
427    create-task:
428      if: github.event.label.name == 'orchestrator'
429      runs-on: ubuntu-latest
430      steps:
431        - name: Create task via API
432          run: |
433            curl -X POST http://orchestrator:8080/tasks \
434              -d '{"title": "${{ github.event.issue.title }}", "description": "${{ github.event.issue.body }}"}'
435  ```
436  
437  ## Roadmap
438  
439  - [ ] Web UI dashboard
440  - [ ] REST API for external integrations
441  - [ ] Task dependency graph visualization
442  - [ ] Automatic conflict resolution between workers
443  - [ ] Cost tracking and budgeting
444  - [ ] Worker performance metrics
445  - [ ] Slack/Discord notifications
446  
447  ---
448  
449  **Version**: 1.0.0  
450  **Author**: Alpha/Delta Team