# orchestrator

> Top-level coordination of the autonomous system. Manages session transitions, feature selection, and overall progress tracking. Use as the main entry point for autonomous runs.

- Author: Nova
- Repository: One-Up-Dev/autonomous-apex-ralph
- Version: 20260127171406
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/One-Up-Dev/autonomous-apex-ralph
- Web: https://mule.run/skillshub/@@One-Up-Dev/autonomous-apex-ralph~orchestrator:20260127171406

---

---
name: orchestrator
description: Top-level coordination of the autonomous system. Manages session transitions, feature selection, and overall progress tracking. Use as the main entry point for autonomous runs.
---

# Orchestrator Skill

Coordinates the entire autonomous development process.

## Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR                               │
│                                                                 │
│  Session 1: INITIALIZER                                         │
│  ├── Read app_spec.txt                                         │
│  ├── Generate feature_list.json                                │
│  ├── Create GitHub Issues                                      │
│  └── Create init.sh                                            │
│                     ↓                                           │
│  Session 2+: CODING LOOP                                        │
│  ├── Get bearings (read progress, features)                    │
│  ├── Select next feature (priority order)                      │
│  ├── APEX workflow (Analyze → Plan → Execute → eXamine)        │
│  ├── Ralph loop (retry up to 3x, then deep-research)           │
│  └── Commit and update progress                                │
│                     ↓                                           │
│  Repeat until all features pass or session ends                │
└─────────────────────────────────────────────────────────────────┘
```

## Session Types

### Session 1: Initialization

Use `prompts/initializer_prompt.md`

**Goal:** Set up everything for coding sessions

**Outputs:**
- `feature_list.json` - All features to implement
- GitHub Issues - One per feature
- `init.sh` - Server startup script
- `claude-progress.txt` - Progress tracking

### Session 2+: Coding

Use `prompts/coding_prompt.md`

**Goal:** Implement features using APEX + Ralph

**Loop:**
1. Read progress file
2. Select next unclaimed issue
3. Run APEX workflow
4. Ralph handles success/failure
5. Update progress
6. Repeat

## Feature Selection

Priority order (from `config.yaml`):

```yaml
feature_priority:
  - ui          # Layout and components first
  - functional  # Core functionality
  - style       # CSS and polish
  - persistence # Save/load
  - integration # External APIs last
```

Within category, select by:
1. `depends_on` satisfied (all dependencies pass)
2. Lower `complexity_score` first
3. Order in `feature_list.json`

## Progress Tracking

### feature_list.json

```json
[
  {
    "category": "ui",
    "description": "...",
    "passes": false,      // ← Updated on completion
    "inProgress": false   // ← Set when claimed
  }
]
```

### claude-progress.txt

Human-readable progress notes updated each session:

```markdown
# Session N

## Completed
- Feature X (Issue #1) ✅
- Feature Y (Issue #2) ✅

## Current
- Feature Z (Issue #3) - in progress

## Retries
- Feature W: 2 retries (type error)

## Statistics
- Passing: 15/42
- Remaining: 27
- Time: ~45 min
```

### GitHub Issues

Real-time status via labels:
- `status:in-progress` - Currently working
- `status:blocked` - Dependencies missing
- `needs-investigation` - Failed after retries

## Session Transitions

### Before Context Fills

1. Commit all work
2. Update `claude-progress.txt`
3. Sync GitHub issue status
4. Leave app in working state

### Next Session Starts

1. Run "Get Your Bearings" (Step 1 in coding_prompt)
2. Verify app works (test passing features)
3. Resume from last incomplete feature

## Error Handling

| Situation | Action |
|-----------|--------|
| Feature fails 3x | Deep Research |
| Feature fails 6x | Mark `needs-investigation`, skip |
| Dependencies missing | Mark `status:blocked`, skip |
| App broken | Fix before new features |
| Context filling | Clean commit, update progress |

## Configuration

From `config/config.yaml`:

```yaml
orchestrator:
  session_type: "auto"  # auto-detect based on feature_list.json
  max_features_per_session: 10
  commit_frequency: 3  # features per commit
  
  on_context_warning:
    commit: true
    update_progress: true
    sync_issues: true
```

## Integration Points

| Skill | When Used |
|-------|-----------|
| github-issues | Issue management |
| apex | Feature implementation |
| ralph | Retry handling |
| deep-research | Escalation |

## Scripts

### run_session.sh

```bash
#!/bin/bash
# Run a coding session

SESSION=${1:-"coding"}

if [ "$SESSION" = "init" ]; then
    echo "Running initialization session..."
    cat prompts/initializer_prompt.md
else
    echo "Running coding session..."
    cat prompts/coding_prompt.md
fi
```

### check_progress.sh

```bash
#!/bin/bash
# Check overall progress

TOTAL=$(cat feature_list.json | jq length)
PASSING=$(cat feature_list.json | jq '[.[] | select(.passes == true)] | length')
REMAINING=$((TOTAL - PASSING))

echo "📊 Progress: $PASSING/$TOTAL ($REMAINING remaining)"
```

## Best Practices

1. **One feature at a time** - Complete before starting next
2. **Frequent commits** - Every 1-3 features
3. **Track everything** - Comments, progress file
4. **Clean handoffs** - Next session should understand state
5. **Fail fast** - Don't waste time on blocked features