oh-my-codex-cli 0.1.0

package/.agent/skills/ultrapilot/SKILL.md

@@ -0,0 +1,647 @@
+---
+name: ultrapilot
+description: Parallel autopilot with file ownership partitioning
+---
+
+# Ultrapilot Skill
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, 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:
+```text
+spawn_agent -> send_input (optional) -> wait -> 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:
+
+```typescript
+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`:
+
+```json
+{
+  "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`
+
+```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:**
+```javascript
+// 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`
+
+```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`
+
+```json
+{
+  "totalWorkers": 5,
+  "completedWorkers": 3,
+  "activeWorkers": 2,
+  "failedWorkers": 0,
+  "estimatedTimeRemaining": "2m30s"
+}
+```
+
+## Configuration
+
+Optional settings in `.codex/settings.json`:
+
+```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`
+
+```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:
+
+```bash
+# 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