ultrapilot

name	ultrapilot
description	Parallel autopilot with file ownership partitioning
version	0.1.0
source	fork
checksum	6250c29229a38c28e8e436881b98a7940375e399ee7cd1a1837bf6176e04e7db
updated_at	"2026-02-11T01:29:16.000Z"
intent	execution
layer	orchestration

Ultrapilot Skill

Native Subagent Protocol (Codex)

Codex supports native subagents. Delegate with spawn_agent, coordinate with send_input, collect via wait_agent, and clean up with close_agent.

Execution preference:

1. Use native subagents first for independent workstreams (parallel when possible).
2. Merge results in main thread and run final verification.
3. Fallback only when delegation is blocked: use the [ANALYST]/[ARCHITECT]/[EXECUTOR]/[REVIEWER] structure in a single response.

Minimal orchestration pattern:

spawn_agent -> send_input (optional) -> wait_agent -> close_agent

Codex invocation: use $ultrapilot ... or ultrapilot: ...

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:

1. Decomposes task into parallel-safe components
2. Partitions files with exclusive ownership (no conflicts)
3. Spawns up to 5 parallel workers (Codex limit)
4. Coordinates progress via TaskOutput
5. Integrates changes with sequential handling of shared files
6. Validates full system integrity

Speed Multiplier: Up to 5x faster than sequential autopilot for suitable tasks.

Usage

$ultrapilot <your task>
$up "Build a full-stack todo app"
$ultrapilot Refactor the entire backend

Magic Keywords

These phrases auto-activate ultrapilot:

• "ultrapilot", "ultra pilot"
• "parallel build", "parallel autopilot"
• "swarm build", "swarm mode"
• "fast parallel", "ultra fast"

When to Use

Ultrapilot Excels At:

• Multi-component systems (frontend + backend + database)
• Independent feature additions across different modules
• Large refactorings with clear module boundaries
• Parallel test file generation
• Multi-service architectures

Autopilot Better For:

• Single-threaded sequential tasks
• Heavy interdependencies between components
• Tasks requiring constant integration checks
• Small focused features in a single module

Architecture

User Input: "Build a full-stack todo app"
           |
           v
  [ULTRAPILOT COORDINATOR]
           |
   Decomposition + File Partitioning
           |
   +-------+-------+-------+-------+
   |       |       |       |       |
   v       v       v       v       v
[W-1]   [W-2]   [W-3]   [W-4]   [W-5]
backend frontend database api-docs tests
(src/  (src/   (src/    (docs/)  (tests/)
 api/)  ui/)    db/)
   |       |       |       |       |
   +---+---+---+---+---+---+---+---+
       |
       v
  [INTEGRATION PHASE]
  (shared files: package.json, tsconfig.json, etc.)
       |
       v
  [VALIDATION PHASE]
  (full system test)

Phases

Phase 0: Task Analysis

Goal: Determine if task is parallelizable

Checks:

• Can task be split into 2+ independent subtasks?
• Are file boundaries clear?
• Are dependencies minimal?

Output: Go/No-Go decision (falls back to autopilot if unsuitable)

Phase 1: Decomposition

Goal: Break task into parallel-safe subtasks

Agent: Architect (Opus)

Method: AI-Powered Task Decomposition

Ultrapilot uses the decomposer module to generate intelligent task breakdowns:

import {
  generateDecompositionPrompt,
  parseDecompositionResult,
  validateFileOwnership,
  extractSharedFiles
} from 'src/hooks/ultrapilot/decomposer';

// 1. Generate prompt for Architect
const prompt = generateDecompositionPrompt(task, codebaseContext, {
  maxSubtasks: 5,
  preferredModel: 'sonnet'
});

// 2. Run ARCHITECT phase with opus and capture structured output
// [ARCHITECT | opus] <prompt>
const response = "<architect_response>";

// 3. Parse structured result
const result = parseDecompositionResult(response);

// 4. Validate no file conflicts
const { isValid, conflicts } = validateFileOwnership(result.subtasks);

// 5. Extract shared files from subtasks
const finalResult = extractSharedFiles(result);

Process:

1. Analyze task requirements via Architect agent
2. Identify independent components with file boundaries
3. Assign agent type (executor-low/executor/executor-high) per complexity
4. Map dependencies between subtasks (blockedBy)
5. Generate parallel execution groups
6. Identify shared files (handled by coordinator)

Output: Structured DecompositionResult:

{
  "subtasks": [
    {
      "id": "1",
      "description": "Backend API routes",
      "files": ["src/api/routes.ts", "src/api/handlers.ts"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "2",
      "description": "Frontend components",
      "files": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "3",
      "description": "Wire frontend to backend",
      "files": ["src/client/api.ts"],
      "blockedBy": ["1", "2"],
      "agentType": "executor-low",
      "model": "haiku"
    }
  ],
  "sharedFiles": [
    "package.json",
    "tsconfig.json",
    "README.md"
  ],
  "parallelGroups": [["1", "2"], ["3"]]
}

Decomposition Types:

Type	Description	Use Case
DecomposedTask	Full task with id, files, blockedBy, agentType, model	Intelligent worker spawning
DecompositionResult	Complete result with subtasks, sharedFiles, parallelGroups	Full decomposition output
toSimpleSubtasks()	Convert to string[] for legacy compatibility	Simple task lists

Phase 2: File Ownership Partitioning

Goal: Assign exclusive file sets to workers

Rules:

1. Exclusive ownership - No file in multiple worker sets
2. Shared files deferred - Handled sequentially in integration
3. Boundary files tracked - Files that import across boundaries

Data Structure: .omc/state/ultrapilot-ownership.json

{
  "sessionId": "ultrapilot-20260123-1234",
  "workers": {
    "worker-1": {
      "ownedFiles": ["src/api/routes.ts", "src/api/handlers.ts"],
      "ownedGlobs": ["src/api/**"],
      "boundaryImports": ["src/types.ts"]
    },
    "worker-2": {
      "ownedFiles": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "ownedGlobs": ["src/ui/**"],
      "boundaryImports": ["src/types.ts"]
    }
  },
  "sharedFiles": ["package.json", "tsconfig.json", "src/types.ts"],
  "conflictPolicy": "coordinator-handles"
}

Phase 3: Parallel Execution

Goal: Run all workers simultaneously

Spawn Workers:

// Pseudocode
workers = [];
for (subtask in decomposition.subtasks) {
  workers.push(
    runWorker({
      role: "EXECUTOR",
      model: "sonnet",
      prompt: `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`,
      runInBackground: true
    })
  );
}

Monitoring:

• Poll TaskOutput for each worker
• Track completion status
• Detect conflicts early
• Accumulate boundary dependencies

Max Workers: 5 (Codex limit)

Phase 4: Integration

Goal: Merge all worker changes and handle shared files

Process:

1. Collect outputs - Gather all worker deliverables
2. Detect conflicts - Check for unexpected overlaps
3. Handle shared files - Sequential updates to package.json, etc.
4. Integrate boundary files - Merge type definitions, shared utilities
5. 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):

1. Build - npm run build or equivalent
2. Lint - npm run lint
3. Type check - tsc --noEmit
4. Unit tests - All tests pass
5. 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 .codex/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 Codex 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

$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:

$ultrapilot resume

Resume Logic:

• Restart failed workers only
• Re-use completed worker outputs
• Continue from last phase

Examples

Example 1: Full-Stack App

$ultrapilot Build a todo app with React frontend, Express backend, and PostgreSQL database

Workers:

1. Frontend (src/client/)
2. Backend (src/server/)
3. Database (src/db/)
4. Tests (tests/)
5. Docs (docs/)

Shared Files: package.json, docker-compose.yml, README.md

Duration: ~15 minutes (vs ~75 minutes sequential)

Example 2: Multi-Service Refactor

$up Refactor all services to use dependency injection

Workers:

1. Auth service
2. User service
3. Payment service
4. Notification service

Shared Files: src/types/services.ts, tsconfig.json

Duration: ~8 minutes (vs ~32 minutes sequential)

Example 3: Test Coverage

$ultrapilot Generate tests for all untested modules

Workers:

1. API tests
2. UI component tests
3. Database tests
4. Utility tests
5. Integration tests

Shared Files: jest.config.js, test-utils.ts

Duration: ~10 minutes (vs ~50 minutes sequential)

Best Practices

1. Clear module boundaries - Works best with well-separated code
2. Minimal shared state - Reduces integration complexity
3. Trust the decomposition - Architect knows what's parallel-safe
4. Monitor progress - Check .omc/ultrapilot/progress.json
5. 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:

$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 Codex supports)
• Real-time progress dashboard
• Worker performance analytics
• Auto-tuning of decomposition strategy