Ultrapilot Skill
Parallel autopilot that spawns multiple workers with file ownership partitioning for maximum speed.
Overview
Ultrapilot is the parallel evolution of autopilot. It decomposes your task into independent parallelizable subtasks, assigns non-overlapping file sets to each worker, and runs them simultaneously.
Key Capabilities:
Decomposes
task into parallel-safe components
Partitions
files with exclusive ownership (no conflicts)
Spawns
up to 5 parallel workers (Claude Code limit)
Coordinates
progress via TaskOutput
Integrates
changes with sequential handling of shared files
Validates
full system integrity
Speed Multiplier:
Up to 5x faster than sequential autopilot for suitable tasks.
Usage
/oh-my-claudecode:ultrapilot ULTRAPILOT WORKER
${
subtask
.
id
}
Your exclusive file ownership:
${
subtask
.
files
}
Task:
${
subtask
.
description
}
CRITICAL RULES:
1. ONLY modify files in your ownership set
2. If you need to modify a shared file, document the change in your output
3. Do NOT create new files outside your ownership
4. Track all imports from boundary files
Deliver: Code changes + list of boundary dependencies
,
run_in_background
:
true
)
)
;
}
Monitoring:
Poll TaskOutput for each worker
Track completion status
Detect conflicts early
Accumulate boundary dependencies
Max Workers:
5 (Claude Code limit)
Phase 4: Integration
Goal:
Merge all worker changes and handle shared files
Process:
Collect outputs
- Gather all worker deliverables
Detect conflicts
- Check for unexpected overlaps
Handle shared files
- Sequential updates to package.json, etc.
Integrate boundary files
- Merge type definitions, shared utilities
Resolve imports
- Ensure cross-boundary imports are valid
Agent:
Executor (Sonnet) - sequential processing
Conflict Resolution:
If workers unexpectedly touched same file → manual merge
If shared file needs multiple changes → sequential apply
If boundary file changed → validate all dependent workers
Phase 5: Validation
Goal:
Verify integrated system works
Checks (parallel):
Build
-
npm run build
or equivalent
Lint
-
npm run lint
Type check
-
tsc --noEmit
Unit tests
- All tests pass
Integration tests
- Cross-component tests
Agents (parallel):
Build-fixer (Sonnet) - Fix build errors
Architect (Opus) - Functional completeness
Security-reviewer (Opus) - Cross-component vulnerabilities
Retry Policy:
Up to 3 validation rounds. If failures persist, detailed error report to user.
State Management
Session State
Location:
.omc/ultrapilot-state.json
{
"sessionId"
:
"ultrapilot-20260123-1234"
,
"taskDescription"
:
"Build a full-stack todo app"
,
"phase"
:
"execution"
,
"startTime"
:
"2026-01-23T10:30:00Z"
,
"decomposition"
:
{
/ from Phase 1 /
}
,
"workers"
:
{
"worker-1"
:
{
"status"
:
"running"
,
"taskId"
:
"task-abc123"
,
"startTime"
:
"2026-01-23T10:31:00Z"
,
"estimatedDuration"
:
"5m"
}
}
,
"conflicts"
:
[
]
,
"validationAttempts"
:
0
}
File Ownership Map
Location:
.omc/state/ultrapilot-ownership.json
Tracks which worker owns which files (see Phase 2 example above).
Progress Tracking
Location:
.omc/ultrapilot/progress.json
{
"totalWorkers"
:
5
,
"completedWorkers"
:
3
,
"activeWorkers"
:
2
,
"failedWorkers"
:
0
,
"estimatedTimeRemaining"
:
"2m30s"
}
Configuration
Optional settings in
.claude/settings.json
:
{
"omc"
:
{
"ultrapilot"
:
{
"maxWorkers"
:
5
,
"maxValidationRounds"
:
3
,
"conflictPolicy"
:
"coordinator-handles"
,
"fallbackToAutopilot"
:
true
,
"parallelThreshold"
:
2
,
"pauseAfterDecomposition"
:
false
,
"verboseProgress"
:
true
}
}
}
Settings Explained:
maxWorkers
- Max parallel workers (5 is Claude Code limit)
maxValidationRounds
- Validation retry attempts
conflictPolicy
- "coordinator-handles" or "abort-on-conflict"
fallbackToAutopilot
- Auto-switch if task not parallelizable
parallelThreshold
- Min subtasks to use ultrapilot (else fallback)
pauseAfterDecomposition
- Confirm with user before execution
verboseProgress
- Show detailed worker progress
Cancellation
/oh-my-claudecode:cancel
Or say: "stop", "cancel ultrapilot", "abort"
Behavior:
All active workers gracefully terminated
Partial progress saved to state file
Session can be resumed
Resume
If ultrapilot was cancelled or a worker failed:
/oh-my-claudecode:ultrapilot resume
Resume Logic:
Restart failed workers only
Re-use completed worker outputs
Continue from last phase
Examples
Example 1: Full-Stack App
/oh-my-claudecode:ultrapilot Build a todo app with React frontend, Express backend, and PostgreSQL database
Workers:
Frontend (src/client/)
Backend (src/server/)
Database (src/db/)
Tests (tests/)
Docs (docs/)
Shared Files:
package.json, docker-compose.yml, README.md
Duration:
~15 minutes (vs ~75 minutes sequential)
Example 2: Multi-Service Refactor
/oh-my-claudecode:up Refactor all services to use dependency injection
Workers:
Auth service
User service
Payment service
Notification service
Shared Files:
src/types/services.ts, tsconfig.json
Duration:
~8 minutes (vs ~32 minutes sequential)
Example 3: Test Coverage
/oh-my-claudecode:ultrapilot Generate tests for all untested modules
Workers:
API tests
UI component tests
Database tests
Utility tests
Integration tests
Shared Files:
jest.config.js, test-utils.ts
Duration:
~10 minutes (vs ~50 minutes sequential)
Best Practices
Clear module boundaries
- Works best with well-separated code
Minimal shared state
- Reduces integration complexity
Trust the decomposition
- Architect knows what's parallel-safe
Monitor progress
- Check
.omc/ultrapilot/progress.json
Review conflicts early
- Don't wait until integration
File Ownership Strategy
Ownership Types
Exclusive Ownership:
Worker has sole write access
No other worker can touch these files
Worker can create new files in owned directories
Shared Files:
No worker has exclusive access
Handled sequentially in integration phase
Includes: package.json, tsconfig.json, config files, root README
Boundary Files:
Can be read by all workers
Write access determined by usage analysis
Typically: type definitions, shared utilities, interfaces
Ownership Detection Algorithm
For each file in codebase:
If file in shared_patterns (package.json, .config.js):
→ sharedFiles
Else if file imported by 2+ subtask modules:
→ boundaryFiles
→ Assign to most relevant worker OR defer to shared
Else if file in subtask directory:
→ Assign to subtask worker
Else:
→ sharedFiles (safe default)
Shared File Patterns
Automatically classified as shared:
package.json
,
package-lock.json
tsconfig.json
,
.config.js
,
.config.ts
.eslintrc.
,
.prettierrc.
README.md
,
CONTRIBUTING.md
,
LICENSE
Docker files:
Dockerfile
,
docker-compose.yml
CI files:
.github/
,
.gitlab-ci.yml
Conflict Handling
Conflict Types
Unexpected Overlap:
Two workers modified the same file
Resolution:
Coordinator merges with human confirmation
Shared File Contention:
Multiple workers need to update package.json
Resolution:
Sequential application in integration phase
Boundary File Conflict:
Type definition needed by multiple workers
Resolution:
First worker creates, others import
Conflict Policy
coordinator-handles (default):
Coordinator attempts automatic merge
Falls back to user if complex
abort-on-conflict:
Any conflict immediately cancels ultrapilot
User reviews conflict report
Can resume after manual fix
Troubleshooting
Decomposition fails?
Task may be too coupled
Fallback to autopilot triggered automatically
Review
.omc/ultrapilot/decomposition.json
for details
Worker hangs?
Check worker logs in
.omc/logs/ultrapilot-worker-N.log
Cancel and restart that worker
May indicate file ownership issue
Integration conflicts?
Review
.omc/ultrapilot-state.json
conflicts array
Check if shared files were unexpectedly modified
Adjust ownership rules if needed
Validation loops?
Cross-component integration issue
Review boundary imports
May need sequential retry with full context
Too slow?
Check if workers are truly independent
Review decomposition quality
Consider if autopilot would be faster (high interdependency)
Differences from Autopilot
Feature
Autopilot
Ultrapilot
Execution
Sequential
Parallel (up to 5x)
Best For
Single-threaded tasks
Multi-component systems
Complexity
Lower
Higher
Speed
Standard
3-5x faster (suitable tasks)
File Conflicts
N/A
Ownership partitioning
Fallback
N/A
Can fallback to autopilot
Setup
Instant
Decomposition phase (~1-2 min)
Rule of Thumb:
If task has 3+ independent components, use ultrapilot. Otherwise, use autopilot.
Advanced: Custom Decomposition
You can provide a custom decomposition file to skip Phase 1:
Location:
.omc/ultrapilot/custom-decomposition.json
{
"subtasks"
:
[
{
"id"
:
"worker-auth"
,
"description"
:
"Add OAuth2 authentication"
,
"files"
:
[
"src/auth/"
,
"src/middleware/auth.ts"
]
,
"dependencies"
:
[
"src/types/user.ts"
]
}
,
{
"id"
:
"worker-db"
,
"description"
:
"Add user table and migrations"
,
"files"
:
[
"src/db/migrations/*"
,
"src/db/models/user.ts"
]
,
"dependencies"
:
[
]
}
]
,
"sharedFiles"
:
[
"package.json"
,
"src/types/user.ts"
]
}
Then run:
/oh-my-claudecode:ultrapilot --custom-decomposition
STATE CLEANUP ON COMPLETION
IMPORTANT: Delete state files on completion - do NOT just set
active: false
When all workers complete successfully:
Delete ultrapilot state files
rm -f .omc/state/ultrapilot-state.json rm -f .omc/state/ultrapilot-ownership.json Future Enhancements Planned for v4.1: Dynamic worker scaling (start with 2, spawn more if needed) Predictive conflict detection (pre-integration analysis) Worker-to-worker communication (for rare dependencies) Speculative execution (optimistic parallelism) Resume from integration phase (if validation fails) Planned for v4.2: Multi-machine distribution (if Claude Code supports) Real-time progress dashboard Worker performance analytics Auto-tuning of decomposition strategy