ultrapilot

merozemory

•

1933 months ago

Source Raw

Parallel autopilot with file ownership partitioning for Android projects

Quick Install

npxskills add merozemory/oh-my-droid--skill ultrapilot

Instructions

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 (Factory Droid 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

/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. Call Architect agent
const response = await Task({
  subagent_type: 'oh-my-droid:architect',
  model: 'opus',
  prompt
});

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

Analyze task requirements via Architect agent
Identify independent components with file boundaries
Assign agent type (executor-low/executor/executor-high) per complexity
Map dependencies between subtasks (blockedBy)
Generate parallel execution groups
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:

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

Data Structure: .omd/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(
    Task(
      subagent_type: "oh-my-droid:executor",
      model: "claude-sonnet-4-5-20250929",
      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`,
      run_in_background: true
    )
  );
}

Monitoring:

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

Max Workers: 5 (Factory Droid 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: .omd/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: .omd/state/ultrapilot-ownership.json

Tracks which worker owns which files (see Phase 2 example above).

Progress Tracking

Location: .omd/ultrapilot/progress.json

{
  "totalWorkers": 5,
  "completedWorkers": 3,
  "activeWorkers": 2,
  "failedWorkers": 0,
  "estimatedTimeRemaining": "2m30s"
}

Configuration

Optional settings in .factory/settings.json:

{
  "omd": {
    "ultrapilot": {
      "maxWorkers": 5,
      "maxValidationRounds": 3,
      "conflictPolicy": "coordinator-handles",
      "fallbackToAutopilot": true,
      "parallelThreshold": 2,
      "pauseAfterDecomposition": false,
      "verboseProgress": true
    }
  }
}

Settings Explained:

maxWorkers - Max parallel workers (5 is Factory Droid 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:

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

/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

/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 .omd/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

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 .omd/ultrapilot/decomposition.json for details

Worker hangs?

Check worker logs in .omd/logs/ultrapilot-worker-N.log
Cancel and restart that worker
May indicate file ownership issue

Integration conflicts?

Review .omd/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: .omd/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 .omd/state/ultrapilot-state.json
rm -f .omd/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 Factory Droid supports)
Real-time progress dashboard
Worker performance analytics
Auto-tuning of decomposition strategy

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885

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 (Factory Droid 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

/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. Call Architect agent
const response = await Task({
  subagent_type: 'oh-my-droid:architect',
  model: 'opus',
  prompt
});

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

Analyze task requirements via Architect agent
Identify independent components with file boundaries
Assign agent type (executor-low/executor/executor-high) per complexity
Map dependencies between subtasks (blockedBy)
Generate parallel execution groups
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:

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

Data Structure: .omd/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(
    Task(
      subagent_type: "oh-my-droid:executor",
      model: "claude-sonnet-4-5-20250929",
      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`,
      run_in_background: true
    )
  );
}

Monitoring:

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

Max Workers: 5 (Factory Droid 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: .omd/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: .omd/state/ultrapilot-ownership.json

Tracks which worker owns which files (see Phase 2 example above).

Progress Tracking

Location: .omd/ultrapilot/progress.json

{
  "totalWorkers": 5,
  "completedWorkers": 3,
  "activeWorkers": 2,
  "failedWorkers": 0,
  "estimatedTimeRemaining": "2m30s"
}

Configuration

Optional settings in .factory/settings.json:

{
  "omd": {
    "ultrapilot": {
      "maxWorkers": 5,
      "maxValidationRounds": 3,
      "conflictPolicy": "coordinator-handles",
      "fallbackToAutopilot": true,
      "parallelThreshold": 2,
      "pauseAfterDecomposition": false,
      "verboseProgress": true
    }
  }
}

Settings Explained:

maxWorkers - Max parallel workers (5 is Factory Droid 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:

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

/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

/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 .omd/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

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 .omd/ultrapilot/decomposition.json for details

Worker hangs?

Check worker logs in .omd/logs/ultrapilot-worker-N.log
Cancel and restart that worker
May indicate file ownership issue

Integration conflicts?

Review .omd/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: .omd/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 .omd/state/ultrapilot-state.json
rm -f .omd/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 Factory Droid supports)
Real-time progress dashboard
Worker performance analytics
Auto-tuning of decomposition strategy