oh-my-claude-sisyphus 3.5.8 → 3.6.1

package/dist/hooks/ultrapilot/decomposer.d.ts

@@ -0,0 +1,141 @@
+/**
+ * AI-Powered Task Decomposition for Ultrapilot
+ *
+ * This module provides intelligent task decomposition using an Architect agent
+ * to analyze tasks and break them into parallel-safe subtasks with proper
+ * file ownership and dependency tracking.
+ */
+/**
+ * Agent type for task execution, determines model complexity
+ */
+export type AgentType = 'executor-low' | 'executor' | 'executor-high';
+/**
+ * Model tier for agent execution
+ */
+export type ModelTier = 'haiku' | 'sonnet' | 'opus';
+/**
+ * A decomposed subtask with file ownership and dependencies
+ */
+export interface DecomposedTask {
+    /** Unique identifier for this subtask */
+    id: string;
+    /** Clear description of what to implement */
+    description: string;
+    /** Files this task will touch (can include globs) */
+    files: string[];
+    /** Task IDs this subtask depends on (must complete first) */
+    blockedBy: string[];
+    /** Agent type based on task complexity */
+    agentType: AgentType;
+    /** Model tier for execution */
+    model: ModelTier;
+}
+/**
+ * Result of task decomposition
+ */
+export interface DecompositionResult {
+    /** Array of parallelizable subtasks */
+    subtasks: DecomposedTask[];
+    /** Files that need sequential handling (config, lock files) */
+    sharedFiles: string[];
+    /** Groups of task IDs that can run in parallel (dependency-ordered) */
+    parallelGroups: string[][];
+}
+/**
+ * Options for decomposition prompt generation
+ */
+export interface DecompositionOptions {
+    /** Maximum number of subtasks to generate */
+    maxSubtasks?: number;
+    /** Preferred model tier for workers */
+    preferredModel?: ModelTier;
+    /** Additional context about project structure */
+    projectContext?: string;
+}
+/**
+ * Default shared file patterns that should be handled by coordinator
+ */
+export declare const DEFAULT_SHARED_FILE_PATTERNS: string[];
+/**
+ * Generate a prompt for the Architect agent to decompose a task
+ *
+ * This prompt instructs the Architect to analyze the task and codebase context,
+ * then produce a structured JSON decomposition with file ownership and dependencies.
+ *
+ * @param task - The task description to decompose
+ * @param codebaseContext - Context about the codebase structure, files, and patterns
+ * @param options - Optional configuration for decomposition
+ * @returns Formatted prompt string for the Architect agent
+ *
+ * @example
+ * ```typescript
+ * const prompt = generateDecompositionPrompt(
+ *   "Build a full-stack todo app with React and Express",
+ *   "Project has src/client and src/server directories..."
+ * );
+ * // Use with Architect agent via Task tool
+ * ```
+ */
+export declare function generateDecompositionPrompt(task: string, codebaseContext: string, options?: DecompositionOptions): string;
+/**
+ * Parse the Architect's response into a structured DecompositionResult
+ *
+ * Handles various response formats including:
+ * - Raw JSON
+ * - JSON wrapped in markdown code fences
+ * - JSON with surrounding explanation text
+ *
+ * @param response - Raw response string from the Architect agent
+ * @returns Parsed and validated DecompositionResult
+ * @throws Error if response cannot be parsed or is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = parseDecompositionResult(architectResponse);
+ * console.log(result.subtasks.length); // Number of parallel tasks
+ * console.log(result.parallelGroups); // Execution order
+ * ```
+ */
+export declare function parseDecompositionResult(response: string): DecompositionResult;
+/**
+ * Generate parallel groups from subtask dependencies
+ *
+ * Creates an ordered array of task ID groups where each group can run
+ * in parallel, and later groups depend on earlier ones completing.
+ *
+ * @param subtasks - Array of decomposed subtasks with blockedBy fields
+ * @returns Array of parallel groups (each group is array of task IDs)
+ */
+export declare function generateParallelGroups(subtasks: DecomposedTask[]): string[][];
+/**
+ * Validate that file ownership doesn't overlap between subtasks
+ *
+ * @param subtasks - Array of decomposed subtasks
+ * @returns Object with isValid flag and any conflicts found
+ */
+export declare function validateFileOwnership(subtasks: DecomposedTask[]): {
+    isValid: boolean;
+    conflicts: Array<{
+        file: string;
+        owners: string[];
+    }>;
+};
+/**
+ * Merge shared files from subtasks into the sharedFiles list
+ *
+ * Identifies files that match shared file patterns and removes them
+ * from subtask ownership, adding them to sharedFiles instead.
+ *
+ * @param result - DecompositionResult to process
+ * @param patterns - Array of glob patterns for shared files
+ * @returns Updated DecompositionResult with shared files extracted
+ */
+export declare function extractSharedFiles(result: DecompositionResult, patterns?: string[]): DecompositionResult;
+/**
+ * Convert DecompositionResult to simple string array for legacy compatibility
+ *
+ * @param result - Full decomposition result
+ * @returns Array of task description strings
+ */
+export declare function toSimpleSubtasks(result: DecompositionResult): string[];
+//# sourceMappingURL=decomposer.d.ts.map

package/dist/hooks/ultrapilot/decomposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decomposer.d.ts","sourceRoot":"","sources":["../../../src/hooks/ultrapilot/decomposer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,UAAU,GAAG,eAAe,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0CAA0C;IAC1C,SAAS,EAAE,SAAS,CAAC;IACrB,+BAA+B;IAC/B,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uEAAuE;IACvE,cAAc,EAAE,MAAM,EAAE,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,4BAA4B,UA0BxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE,oBAAyB,GACjC,MAAM,CA8GR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAmF9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,EAAE,CAmC7E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACtD,CAuBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,GAAE,MAAM,EAAiC,GAChD,mBAAmB,CAoCrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAEtE"}

package/dist/hooks/ultrapilot/decomposer.js

@@ -0,0 +1,377 @@
+/**
+ * AI-Powered Task Decomposition for Ultrapilot
+ *
+ * This module provides intelligent task decomposition using an Architect agent
+ * to analyze tasks and break them into parallel-safe subtasks with proper
+ * file ownership and dependency tracking.
+ */
+/**
+ * Default shared file patterns that should be handled by coordinator
+ */
+export const DEFAULT_SHARED_FILE_PATTERNS = [
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'tsconfig.json',
+    'tsconfig.*.json',
+    'jest.config.js',
+    'jest.config.ts',
+    'vitest.config.ts',
+    '.eslintrc.*',
+    '.prettierrc.*',
+    '.gitignore',
+    'README.md',
+    'Makefile',
+    'go.mod',
+    'go.sum',
+    'Cargo.toml',
+    'Cargo.lock',
+    'pyproject.toml',
+    'requirements.txt',
+    'setup.py',
+    'Dockerfile',
+    'docker-compose.yml',
+    '.github/**',
+    '.gitlab-ci.yml'
+];
+/**
+ * Generate a prompt for the Architect agent to decompose a task
+ *
+ * This prompt instructs the Architect to analyze the task and codebase context,
+ * then produce a structured JSON decomposition with file ownership and dependencies.
+ *
+ * @param task - The task description to decompose
+ * @param codebaseContext - Context about the codebase structure, files, and patterns
+ * @param options - Optional configuration for decomposition
+ * @returns Formatted prompt string for the Architect agent
+ *
+ * @example
+ * ```typescript
+ * const prompt = generateDecompositionPrompt(
+ *   "Build a full-stack todo app with React and Express",
+ *   "Project has src/client and src/server directories..."
+ * );
+ * // Use with Architect agent via Task tool
+ * ```
+ */
+export function generateDecompositionPrompt(task, codebaseContext, options = {}) {
+    const { maxSubtasks = 5, preferredModel = 'sonnet', projectContext = '' } = options;
+    const additionalContext = projectContext ? `\nPROJECT NOTES:\n${projectContext}\n` : '';
+    return `Analyze this task and decompose it into parallel-safe subtasks for concurrent execution.
+
+TASK: ${task}
+
+CODEBASE CONTEXT:
+${codebaseContext}
+${additionalContext}
+OUTPUT REQUIREMENTS:
+Return a valid JSON object matching this exact schema:
+
+{
+  "subtasks": [
+    {
+      "id": "1",
+      "description": "Clear, actionable description of what to implement",
+      "files": ["src/path/to/file.ts", "src/path/to/other.ts"],
+      "blockedBy": [],
+      "agentType": "executor",
+      "model": "sonnet"
+    }
+  ],
+  "sharedFiles": ["package.json", "tsconfig.json"],
+  "parallelGroups": [["1", "2"], ["3"]]
+}
+
+DECOMPOSITION RULES:
+
+1. FILE OWNERSHIP:
+   - Each subtask should have exclusive ownership of its files
+   - NO file should appear in multiple subtasks' files arrays
+   - Use specific file paths, not directories (unless truly needed)
+   - Mark config/lock files as sharedFiles (handled by coordinator)
+
+2. DEPENDENCIES (blockedBy):
+   - Only add blockedBy if subtask TRULY requires another to complete first
+   - Prefer parallel execution - maximize independent subtasks
+   - Common dependencies: type definitions, shared utilities, API contracts
+
+3. PARALLEL GROUPS:
+   - Group subtasks that can run simultaneously
+   - First group has no dependencies
+   - Later groups depend on earlier ones completing
+   - Example: [["1", "2", "3"], ["4", "5"]] means 1,2,3 run first, then 4,5
+
+4. AGENT/MODEL SELECTION:
+   - executor-low/haiku: Simple changes, single file, straightforward logic
+   - executor/sonnet: Standard implementation, moderate complexity (DEFAULT)
+   - executor-high/opus: Complex refactoring, architectural changes, multi-file coordination
+
+5. SUBTASK GUIDELINES:
+   - Maximum ${maxSubtasks} subtasks
+   - Preferred model tier: ${preferredModel}
+   - Each subtask should be completable in 2-10 minutes
+   - Subtask description should be actionable and specific
+   - Include all files the subtask will CREATE or MODIFY
+
+6. SHARED FILES (coordinator handles):
+   - package.json, lock files
+   - tsconfig.json, config files
+   - Root README.md
+   - Docker/CI configuration
+   - Any file multiple subtasks would need to modify
+
+EXAMPLE OUTPUT:
+
+{
+  "subtasks": [
+    {
+      "id": "1",
+      "description": "Create Express API routes for todo CRUD operations",
+      "files": ["src/server/routes/todos.ts", "src/server/controllers/todoController.ts"],
+      "blockedBy": [],
+      "agentType": "executor",
+      "model": "sonnet"
+    },
+    {
+      "id": "2",
+      "description": "Create React components for todo list UI",
+      "files": ["src/client/components/TodoList.tsx", "src/client/components/TodoItem.tsx"],
+      "blockedBy": [],
+      "agentType": "executor",
+      "model": "sonnet"
+    },
+    {
+      "id": "3",
+      "description": "Create database schema and migrations for todos",
+      "files": ["src/db/migrations/001_create_todos.ts", "src/db/models/Todo.ts"],
+      "blockedBy": [],
+      "agentType": "executor-low",
+      "model": "haiku"
+    },
+    {
+      "id": "4",
+      "description": "Wire up API client in frontend to connect to backend",
+      "files": ["src/client/api/todoApi.ts", "src/client/hooks/useTodos.ts"],
+      "blockedBy": ["1", "2"],
+      "agentType": "executor",
+      "model": "sonnet"
+    }
+  ],
+  "sharedFiles": ["package.json", "tsconfig.json", "src/types/todo.ts"],
+  "parallelGroups": [["1", "2", "3"], ["4"]]
+}
+
+Return ONLY the JSON object, no markdown code fences or additional text.`;
+}
+/**
+ * Parse the Architect's response into a structured DecompositionResult
+ *
+ * Handles various response formats including:
+ * - Raw JSON
+ * - JSON wrapped in markdown code fences
+ * - JSON with surrounding explanation text
+ *
+ * @param response - Raw response string from the Architect agent
+ * @returns Parsed and validated DecompositionResult
+ * @throws Error if response cannot be parsed or is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = parseDecompositionResult(architectResponse);
+ * console.log(result.subtasks.length); // Number of parallel tasks
+ * console.log(result.parallelGroups); // Execution order
+ * ```
+ */
+export function parseDecompositionResult(response) {
+    // Try to extract JSON from response (may be wrapped in markdown or have surrounding text)
+    let jsonStr;
+    // First, try to find JSON in markdown code fences
+    const fencedMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fencedMatch && fencedMatch[1]) {
+        jsonStr = fencedMatch[1].trim();
+    }
+    else {
+        // Try to find raw JSON object
+        const jsonMatch = response.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            throw new Error('Could not parse decomposition result: no JSON object found in response');
+        }
+        jsonStr = jsonMatch[0];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch (e) {
+        throw new Error(`Could not parse decomposition result: invalid JSON - ${e instanceof Error ? e.message : 'unknown error'}`);
+    }
+    // Validate structure
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Could not parse decomposition result: response is not an object');
+    }
+    const result = parsed;
+    // Validate required fields
+    if (!Array.isArray(result.subtasks)) {
+        throw new Error('Could not parse decomposition result: missing or invalid subtasks array');
+    }
+    // Validate each subtask
+    for (const subtask of result.subtasks) {
+        if (!subtask || typeof subtask !== 'object') {
+            throw new Error('Could not parse decomposition result: invalid subtask object');
+        }
+        const st = subtask;
+        if (typeof st.id !== 'string' || !st.id) {
+            throw new Error('Could not parse decomposition result: subtask missing id');
+        }
+        if (typeof st.description !== 'string' || !st.description) {
+            throw new Error('Could not parse decomposition result: subtask missing description');
+        }
+        if (!Array.isArray(st.files)) {
+            throw new Error(`Could not parse decomposition result: subtask ${st.id} missing files array`);
+        }
+        if (!Array.isArray(st.blockedBy)) {
+            // Default to empty array if not provided
+            st.blockedBy = [];
+        }
+        // Validate and default agentType
+        const validAgentTypes = ['executor-low', 'executor', 'executor-high'];
+        if (!st.agentType || !validAgentTypes.includes(st.agentType)) {
+            st.agentType = 'executor';
+        }
+        // Validate and default model
+        const validModels = ['haiku', 'sonnet', 'opus'];
+        if (!st.model || !validModels.includes(st.model)) {
+            st.model = 'sonnet';
+        }
+    }
+    // Validate/default sharedFiles
+    if (!Array.isArray(result.sharedFiles)) {
+        result.sharedFiles = [];
+    }
+    // Validate/default parallelGroups
+    if (!Array.isArray(result.parallelGroups)) {
+        // Generate default parallel groups based on blockedBy
+        result.parallelGroups = generateParallelGroups(result.subtasks);
+    }
+    return result;
+}
+/**
+ * Generate parallel groups from subtask dependencies
+ *
+ * Creates an ordered array of task ID groups where each group can run
+ * in parallel, and later groups depend on earlier ones completing.
+ *
+ * @param subtasks - Array of decomposed subtasks with blockedBy fields
+ * @returns Array of parallel groups (each group is array of task IDs)
+ */
+export function generateParallelGroups(subtasks) {
+    const groups = [];
+    const completed = new Set();
+    const remaining = new Set(subtasks.map((t) => t.id));
+    while (remaining.size > 0) {
+        const currentGroup = [];
+        for (const subtask of subtasks) {
+            if (!remaining.has(subtask.id))
+                continue;
+            // Check if all dependencies are completed
+            const depsCompleted = subtask.blockedBy.every((dep) => completed.has(dep));
+            if (depsCompleted) {
+                currentGroup.push(subtask.id);
+            }
+        }
+        if (currentGroup.length === 0) {
+            // Circular dependency detected - add remaining tasks to break cycle
+            const remainingIds = Array.from(remaining);
+            groups.push(remainingIds);
+            break;
+        }
+        // Mark current group as completed
+        for (const id of currentGroup) {
+            completed.add(id);
+            remaining.delete(id);
+        }
+        groups.push(currentGroup);
+    }
+    return groups;
+}
+/**
+ * Validate that file ownership doesn't overlap between subtasks
+ *
+ * @param subtasks - Array of decomposed subtasks
+ * @returns Object with isValid flag and any conflicts found
+ */
+export function validateFileOwnership(subtasks) {
+    const fileToOwners = new Map();
+    for (const subtask of subtasks) {
+        for (const file of subtask.files) {
+            if (!fileToOwners.has(file)) {
+                fileToOwners.set(file, []);
+            }
+            fileToOwners.get(file).push(subtask.id);
+        }
+    }
+    const conflicts = [];
+    for (const [file, owners] of fileToOwners.entries()) {
+        if (owners.length > 1) {
+            conflicts.push({ file, owners });
+        }
+    }
+    return {
+        isValid: conflicts.length === 0,
+        conflicts
+    };
+}
+/**
+ * Merge shared files from subtasks into the sharedFiles list
+ *
+ * Identifies files that match shared file patterns and removes them
+ * from subtask ownership, adding them to sharedFiles instead.
+ *
+ * @param result - DecompositionResult to process
+ * @param patterns - Array of glob patterns for shared files
+ * @returns Updated DecompositionResult with shared files extracted
+ */
+export function extractSharedFiles(result, patterns = DEFAULT_SHARED_FILE_PATTERNS) {
+    const sharedSet = new Set(result.sharedFiles);
+    // Simple pattern matching (exact match or basic glob)
+    const isSharedFile = (file) => {
+        const fileName = file.split('/').pop() || file;
+        return patterns.some((pattern) => {
+            if (pattern.includes('*')) {
+                // Basic glob: convert to regex
+                const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+                return regex.test(file) || regex.test(fileName);
+            }
+            return file === pattern || fileName === pattern;
+        });
+    };
+    // Process each subtask
+    const updatedSubtasks = result.subtasks.map((subtask) => {
+        const ownedFiles = [];
+        for (const file of subtask.files) {
+            if (isSharedFile(file)) {
+                sharedSet.add(file);
+            }
+            else {
+                ownedFiles.push(file);
+            }
+        }
+        return { ...subtask, files: ownedFiles };
+    });
+    return {
+        subtasks: updatedSubtasks,
+        sharedFiles: Array.from(sharedSet),
+        parallelGroups: result.parallelGroups
+    };
+}
+/**
+ * Convert DecompositionResult to simple string array for legacy compatibility
+ *
+ * @param result - Full decomposition result
+ * @returns Array of task description strings
+ */
+export function toSimpleSubtasks(result) {
+    return result.subtasks.map((t) => t.description);
+}
+//# sourceMappingURL=decomposer.js.map

package/dist/hooks/ultrapilot/decomposer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decomposer.js","sourceRoot":"","sources":["../../../src/hooks/ultrapilot/decomposer.ts"],"names":[],"mappings":"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"}

package/dist/hooks/ultrapilot/index.d.ts

@@ -6,6 +6,8 @@
  * while managing file ownership to avoid conflicts.
  */
 import type { UltrapilotConfig, UltrapilotState, WorkerState, IntegrationResult } from './types.js';
+export { generateDecompositionPrompt, parseDecompositionResult, generateParallelGroups, validateFileOwnership, extractSharedFiles, toSimpleSubtasks, DEFAULT_SHARED_FILE_PATTERNS } from './decomposer.js';
+export type { DecomposedTask, DecompositionResult, DecompositionOptions, AgentType, ModelTier } from './decomposer.js';
 /**
  * Start ultrapilot coordinator
  *
@@ -21,6 +23,35 @@ export declare function startUltrapilot(cwd: string, task: string, config?: Part
  * Decompose a task into parallelizable subtasks
  *
  * Uses heuristics to identify independent work units that can be executed in parallel.
+ * For more intelligent decomposition with file ownership and dependencies, use the
+ * AI-powered decomposition functions:
+ *
+ * @example AI-powered decomposition (recommended for complex tasks):
+ * ```typescript
+ * import {
+ *   generateDecompositionPrompt,
+ *   parseDecompositionResult,
+ *   toSimpleSubtasks
+ * } from './decomposer.js';
+ *
+ * // Generate prompt for Architect agent
+ * const prompt = generateDecompositionPrompt(task, codebaseContext);
+ *
+ * // Call Architect agent (via Task tool in orchestrator)
+ * const response = await Task({
+ *   subagent_type: 'oh-my-claudecode:architect',
+ *   model: 'opus',
+ *   prompt
+ * });
+ *
+ * // Parse structured result with file ownership
+ * const result = parseDecompositionResult(response);
+ *
+ * // Use result.subtasks for full DecomposedTask objects with:
+ * // - id, description, files, blockedBy, agentType, model
+ * // Or convert to simple strings for legacy compatibility:
+ * const subtasks = toSimpleSubtasks(result);
+ * ```
  *
  * @param task - Task description
  * @param config - Configuration options

package/dist/hooks/ultrapilot/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/ultrapilot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAiBpB;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,eAAe,CAAC,CAU1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAgCnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,WAAW,EAAE,CAAC,CA2BxB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAgBD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+C9E;AAsFD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CA0BT;AAGD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/ultrapilot/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAwBpB,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,4BAA4B,EAC7B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,SAAS,EACT,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,OAAO,CAAC,WAAW,EAAE,CAAC,CA2BxB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAgBD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+C9E;AAsFD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CA0BT;AAGD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC"}

package/dist/hooks/ultrapilot/index.js

@@ -7,6 +7,14 @@
  */
 import { DEFAULT_CONFIG } from './types.js';
 import { readUltrapilotState, writeUltrapilotState, initUltrapilot, addWorker, getCompletedWorkers, getRunningWorkers, getFailedWorkers, recordConflict } from './state.js';
+// AI-powered decomposition utilities
+// TODO: Use these with the Architect agent for intelligent task decomposition
+// Example integration:
+//   const prompt = generateDecompositionPrompt(task, codebaseContext);
+//   const response = await Task({ subagent_type: 'architect', prompt });
+//   const result = parseDecompositionResult(response);
+//   const subtasks = toSimpleSubtasks(result);
+export { generateDecompositionPrompt, parseDecompositionResult, generateParallelGroups, validateFileOwnership, extractSharedFiles, toSimpleSubtasks, DEFAULT_SHARED_FILE_PATTERNS } from './decomposer.js';
 /**
  * Start ultrapilot coordinator
  *
@@ -23,20 +31,53 @@ export async function startUltrapilot(cwd, task, config) {
     const subtasks = await decomposeTask(task, mergedConfig);
     // Initialize state
     const state = initUltrapilot(cwd, task, subtasks, undefined, mergedConfig);
+    if (!state) {
+        throw new Error('Failed to initialize ultrapilot: another mode is active');
+    }
     return state;
 }
 /**
  * Decompose a task into parallelizable subtasks
  *
  * Uses heuristics to identify independent work units that can be executed in parallel.
+ * For more intelligent decomposition with file ownership and dependencies, use the
+ * AI-powered decomposition functions:
+ *
+ * @example AI-powered decomposition (recommended for complex tasks):
+ * ```typescript
+ * import {
+ *   generateDecompositionPrompt,
+ *   parseDecompositionResult,
+ *   toSimpleSubtasks
+ * } from './decomposer.js';
+ *
+ * // Generate prompt for Architect agent
+ * const prompt = generateDecompositionPrompt(task, codebaseContext);
+ *
+ * // Call Architect agent (via Task tool in orchestrator)
+ * const response = await Task({
+ *   subagent_type: 'oh-my-claudecode:architect',
+ *   model: 'opus',
+ *   prompt
+ * });
+ *
+ * // Parse structured result with file ownership
+ * const result = parseDecompositionResult(response);
+ *
+ * // Use result.subtasks for full DecomposedTask objects with:
+ * // - id, description, files, blockedBy, agentType, model
+ * // Or convert to simple strings for legacy compatibility:
+ * const subtasks = toSimpleSubtasks(result);
+ * ```
  *
  * @param task - Task description
  * @param config - Configuration options
  * @returns Array of subtask descriptions
  */
 export async function decomposeTask(task, config) {
-    // For now, implement basic heuristics for task decomposition
-    // In future, this could use an AI agent to analyze the task
+    // Heuristic-based decomposition for simple cases
+    // For complex tasks, use generateDecompositionPrompt() with Architect agent
+    // to get structured DecompositionResult with file ownership and dependencies
     const subtasks = [];
     // Look for explicit lists (numbered or bulleted)
     const listItemPattern = /^[\s]*(?:\d+\.|[-*+])\s+(.+)$/gm;