@iloom/cli 0.9.1 → 0.10.0

package/dist/plan-U7ZQWLFY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/plan.ts"],"sourcesContent":["import { logger, createStderrLogger } from '../utils/logger.js'\nimport { withLogger } from '../utils/logger-context.js'\nimport chalk from 'chalk'\nimport { detectClaudeCli, launchClaude } from '../utils/claude.js'\nimport { PromptTemplateManager, type TemplateVariables } from '../lib/PromptTemplateManager.js'\nimport { generateIssueManagementMcpConfig } from '../utils/mcp.js'\nimport { SettingsManager, PlanCommandSettingsSchema } from '../lib/SettingsManager.js'\nimport { IssueTrackerFactory } from '../lib/IssueTrackerFactory.js'\nimport { matchIssueIdentifier } from '../utils/IdentifierParser.js'\nimport { IssueManagementProviderFactory } from '../mcp/IssueManagementProviderFactory.js'\nimport { needsFirstRunSetup, launchFirstRunSetup } from '../utils/first-run-setup.js'\nimport type { IssueProvider, ChildIssueResult, DependenciesResult } from '../mcp/types.js'\nimport { promptConfirmation, isInteractiveEnvironment } from '../utils/prompt.js'\nimport { TelemetryService } from '../lib/TelemetryService.js'\n\n// Define provider arrays for validation and dynamic flag generation\nconst PLANNER_PROVIDERS = ['claude', 'gemini', 'codex'] as const\nconst REVIEWER_PROVIDERS = ['claude', 'gemini', 'codex', 'none'] as const\n\ntype PlannerProvider = (typeof PLANNER_PROVIDERS)[number]\ntype ReviewerProvider = (typeof REVIEWER_PROVIDERS)[number]\n\n/**\n * Format child issues as a markdown list for inclusion in the prompt\n */\nfunction formatChildIssues(children: ChildIssueResult[], issuePrefix: string): string {\n\tif (children.length === 0) return 'None'\n\treturn children\n\t\t.map(child => `- ${issuePrefix}${child.id}: ${child.title} (${child.state})`)\n\t\t.join('\\n')\n}\n\n/**\n * Format dependencies as a markdown list for inclusion in the prompt\n */\nfunction formatDependencies(dependencies: DependenciesResult, issuePrefix: string): string {\n\tconst lines: string[] = []\n\n\tif (dependencies.blockedBy.length > 0) {\n\t\tlines.push('**Blocked by:**')\n\t\tfor (const dep of dependencies.blockedBy) {\n\t\t\tlines.push(`- ${issuePrefix}${dep.id}: ${dep.title} (${dep.state})`)\n\t\t}\n\t}\n\n\tif (dependencies.blocking.length > 0) {\n\t\tif (lines.length > 0) lines.push('')\n\t\tlines.push('**Blocking:**')\n\t\tfor (const dep of dependencies.blocking) {\n\t\t\tlines.push(`- ${issuePrefix}${dep.id}: ${dep.title} (${dep.state})`)\n\t\t}\n\t}\n\n\treturn lines.length > 0 ? lines.join('\\n') : 'None'\n}\n\n/**\n * Launch interactive planning session with Architect persona\n * Implements the `il plan` command requested in issue #471\n *\n * The Architect persona helps users:\n * - Break epics down into child issues following \"1 issue = 1 loom = 1 PR\" pattern\n * - Think through implementation approaches\n * - Create issues at the end of the planning session using MCP tools\n */\nexport class PlanCommand {\n\tprivate readonly templateManager: PromptTemplateManager\n\n\tconstructor(templateManager?: PromptTemplateManager) {\n\t\tthis.templateManager = templateManager ?? new PromptTemplateManager()\n\t}\n\n\t/**\n\t * Main entry point for the plan command\n\t * @param prompt - Optional initial planning prompt or topic\n\t * @param model - Optional model to use (defaults to 'opus')\n\t * @param yolo - Optional flag to enable autonomous mode (skip permission prompts)\n\t * @param planner - Optional planner provider (defaults to 'claude')\n\t * @param reviewer - Optional reviewer provider (defaults to 'none')\n\t * @param printOptions - Print mode options for headless/CI execution\n\t */\n\tpublic async execute(\n\t\tprompt?: string,\n\t\tmodel?: string,\n\t\tyolo?: boolean,\n\t\tplanner?: string,\n\t\treviewer?: string,\n\t\tprintOptions?: {\n\t\t\tprint?: boolean\n\t\t\toutputFormat?: 'json' | 'stream-json' | 'text'\n\t\t\tverbose?: boolean\n\t\t\tjson?: boolean\n\t\t\tjsonStream?: boolean\n\t\t}\n\t): Promise<void> {\n\t\t// Wrap execution in stderr logger for JSON modes to keep stdout clean\n\t\tconst isJsonMode = (printOptions?.json ?? false) || (printOptions?.jsonStream ?? false)\n\t\tif (isJsonMode) {\n\t\t\tconst jsonLogger = createStderrLogger()\n\t\t\treturn withLogger(jsonLogger, () => this.executeInternal(prompt, model, yolo, planner, reviewer, printOptions))\n\t\t}\n\n\t\treturn this.executeInternal(prompt, model, yolo, planner, reviewer, printOptions)\n\t}\n\n\t/**\n\t * Internal execution method (separated for withLogger wrapping)\n\t */\n\tprivate async executeInternal(\n\t\tprompt?: string,\n\t\tmodel?: string,\n\t\tyolo?: boolean,\n\t\tplanner?: string,\n\t\treviewer?: string,\n\t\tprintOptions?: {\n\t\t\tprint?: boolean\n\t\t\toutputFormat?: 'json' | 'stream-json' | 'text'\n\t\t\tverbose?: boolean\n\t\t\tjson?: boolean\n\t\t\tjsonStream?: boolean\n\t\t}\n\t): Promise<void> {\n\t\t// Validate and normalize planner CLI argument\n\t\tlet normalizedPlanner: PlannerProvider | undefined\n\t\tif (planner) {\n\t\t\tconst normalized = planner.toLowerCase()\n\t\t\tconst result = PlanCommandSettingsSchema.shape.planner.safeParse(normalized)\n\t\t\tif (!result.success) {\n\t\t\t\tthrow new Error(`Invalid planner: \"${planner}\". Allowed values: ${PLANNER_PROVIDERS.join(', ')}`)\n\t\t\t}\n\t\t\tnormalizedPlanner = normalized as PlannerProvider\n\t\t}\n\n\t\t// Validate and normalize reviewer CLI argument\n\t\tlet normalizedReviewer: ReviewerProvider | undefined\n\t\tif (reviewer) {\n\t\t\tconst normalized = reviewer.toLowerCase()\n\t\t\tconst result = PlanCommandSettingsSchema.shape.reviewer.safeParse(normalized)\n\t\t\tif (!result.success) {\n\t\t\t\tthrow new Error(`Invalid reviewer: \"${reviewer}\". Allowed values: ${REVIEWER_PROVIDERS.join(', ')}`)\n\t\t\t}\n\t\t\tnormalizedReviewer = normalized as ReviewerProvider\n\t\t}\n\n\t\tlogger.debug('PlanCommand.execute() starting', {\n\t\t\tcwd: process.cwd(),\n\t\t\thasPrompt: !!prompt,\n\t\t\tyolo,\n\t\t\tplanner: normalizedPlanner ?? planner,\n\t\t\treviewer: normalizedReviewer ?? reviewer,\n\t\t})\n\n\t\t// Check for first-run setup (same check as StartCommand)\n\t\tif (process.env.FORCE_FIRST_TIME_SETUP === \"true\" || await needsFirstRunSetup()) {\n\t\t\tawait launchFirstRunSetup()\n\t\t}\n\n\t\tlogger.info(chalk.bold('Starting interactive planning session...'))\n\n\t\t// Check if Claude CLI is available\n\t\tlogger.debug('Checking Claude CLI availability')\n\t\tconst claudeAvailable = await detectClaudeCli()\n\t\tlogger.debug('Claude CLI availability check result', { claudeAvailable })\n\n\t\tif (!claudeAvailable) {\n\t\t\tlogger.error(\n\t\t\t\t\"Claude Code not detected. Please install it: npm install -g @anthropic-ai/claude-code\"\n\t\t\t)\n\t\t\tthrow new Error('Claude Code CLI is required for planning sessions')\n\t\t}\n\n\t\t// Load settings to detect configured issue provider and model\n\t\tconst settingsManager = new SettingsManager()\n\t\tconst settings = await settingsManager.loadSettings()\n\n\t\t// Detect if prompt is an issue number for decomposition mode\n\t\t// Uses shared matchIssueIdentifier() utility to identify issue identifiers:\n\t\t// - Numeric pattern: #123 or 123 (GitHub format)\n\t\t// - Project key pattern: ENG-123, PROJ-456 (requires at least 2 letters before dash)\n\t\tconst identifierMatch = prompt ? matchIssueIdentifier(prompt) : { isIssueIdentifier: false }\n\t\tconst looksLikeIssueIdentifier = identifierMatch.isIssueIdentifier\n\t\tlet decompositionContext: {\n\t\t\tidentifier: string\n\t\t\ttitle: string\n\t\t\tbody: string\n\t\t\tchildren?: ChildIssueResult[]\n\t\t\tdependencies?: DependenciesResult\n\t\t} | null = null\n\n\t\tconst provider = settings ? IssueTrackerFactory.getProviderName(settings) : 'github'\n\t\tconst issuePrefix = provider === 'github' ? '#' : ''\n\n\t\tif (prompt && looksLikeIssueIdentifier) {\n\t\t\t// Validate and fetch issue using issueTracker.detectInputType() pattern from StartCommand\n\t\t\tconst issueTracker = IssueTrackerFactory.create(settings)\n\n\t\t\tlogger.debug('Detected potential issue identifier, validating via issueTracker', { identifier: prompt })\n\n\t\t\t// Use detectInputType to validate the identifier exists (same pattern as StartCommand)\n\t\t\tconst detection = await issueTracker.detectInputType(prompt)\n\n\t\t\tif (detection.type === 'issue' && detection.identifier) {\n\t\t\t\t// Valid issue found - fetch full details for decomposition context\n\t\t\t\tconst issue = await issueTracker.fetchIssue(detection.identifier)\n\t\t\t\tdecompositionContext = {\n\t\t\t\t\tidentifier: String(issue.number),\n\t\t\t\t\ttitle: issue.title,\n\t\t\t\t\tbody: issue.body\n\t\t\t\t}\n\t\t\t\tlogger.info(chalk.dim(`Preparing to create a detailed plan for issue #${decompositionContext.identifier}: ${decompositionContext.title}`))\n\n\t\t\t\t// Fetch existing children and dependencies using MCP provider\n\t\t\t\t// This allows users to resume planning where they left off\n\t\t\t\ttry {\n\t\t\t\t\tconst mcpProvider = IssueManagementProviderFactory.create(provider as IssueProvider, settings ?? undefined)\n\n\t\t\t\t\t// Fetch child issues\n\t\t\t\t\tlogger.debug('Fetching child issues for decomposition context', { identifier: decompositionContext.identifier })\n\t\t\t\t\tconst children = await mcpProvider.getChildIssues({ number: decompositionContext.identifier })\n\t\t\t\t\tif (children.length > 0) {\n\t\t\t\t\t\tdecompositionContext.children = children\n\t\t\t\t\t\tlogger.debug('Found existing child issues', { count: children.length })\n\t\t\t\t\t}\n\n\t\t\t\t\t// Fetch dependencies (both directions)\n\t\t\t\t\tlogger.debug('Fetching dependencies for decomposition context', { identifier: decompositionContext.identifier })\n\t\t\t\t\tconst dependencies = await mcpProvider.getDependencies({\n\t\t\t\t\t\tnumber: decompositionContext.identifier,\n\t\t\t\t\t\tdirection: 'both'\n\t\t\t\t\t})\n\t\t\t\t\tif (dependencies.blocking.length > 0 || dependencies.blockedBy.length > 0) {\n\t\t\t\t\t\tdecompositionContext.dependencies = dependencies\n\t\t\t\t\t\tlogger.debug('Found existing dependencies', {\n\t\t\t\t\t\t\tblocking: dependencies.blocking.length,\n\t\t\t\t\t\t\tblockedBy: dependencies.blockedBy.length\n\t\t\t\t\t\t})\n\t\t\t\t\t}\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// Log but don't fail - children/dependencies are optional context\n\t\t\t\t\tlogger.debug('Failed to fetch children/dependencies, continuing without them', {\n\t\t\t\t\t\terror: error instanceof Error ? error.message : 'Unknown error'\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Input matched issue pattern but issue not found - treat as regular prompt\n\t\t\t\tlogger.debug('Input matched issue pattern but issue not found, treating as planning topic', {\n\t\t\t\t\tidentifier: prompt,\n\t\t\t\t\tdetectionType: detection.type\n\t\t\t\t})\n\t\t\t}\n\t\t}\n\n\t\t// Use CLI model if provided, otherwise use settings (plan.model), defaults to opus\n\t\tconst effectiveModel = model ?? settingsManager.getPlanModel(settings ?? undefined)\n\n\t\t// Get effective planner/reviewer (CLI > settings > default)\n\t\tconst effectivePlanner = normalizedPlanner ?? settingsManager.getPlanPlanner(settings ?? undefined)\n\t\tconst effectiveReviewer = normalizedReviewer ?? settingsManager.getPlanReviewer(settings ?? undefined)\n\n\t\tlogger.debug('Detected issue provider, model, planner, and reviewer', {\n\t\t\tprovider,\n\t\t\teffectiveModel,\n\t\t\teffectivePlanner,\n\t\t\teffectiveReviewer,\n\t\t})\n\n\t\t// Generate MCP config for issue management tools\n\t\t// This will throw if no git remote is configured - offer to run 'il init' as fallback\n\t\tlogger.debug('Generating MCP config for issue management')\n\t\tlet mcpConfig: Record<string, unknown>[]\n\t\ttry {\n\t\t\tmcpConfig = await generateIssueManagementMcpConfig(undefined, undefined, provider, settings ?? undefined)\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : 'Unknown error'\n\n\t\t\t// Check if running in interactive mode - offer to run init\n\t\t\tif (isInteractiveEnvironment()) {\n\t\t\t\tconst shouldRunInit = await promptConfirmation(\n\t\t\t\t\t\"No git repository or remote found. Would you like to run 'il init' to set up?\",\n\t\t\t\t\ttrue\n\t\t\t\t)\n\t\t\t\tif (shouldRunInit) {\n\t\t\t\t\t// Dynamically import and run InitCommand\n\t\t\t\t\tlogger.info(chalk.bold('Launching iloom init...'))\n\t\t\t\t\tconst { InitCommand } = await import('./init.js')\n\t\t\t\t\tconst initCommand = new InitCommand()\n\t\t\t\t\tawait initCommand.execute(\n\t\t\t\t\t\t'Help the user set up a GitHub repository or Linear project for this project so they can use issue management features. When complete tell the user they can exit to continue the planning session.'\n\t\t\t\t\t)\n\n\t\t\t\t\t// Retry MCP config generation after init\n\t\t\t\t\tlogger.info(chalk.bold('Retrying planning session setup...'))\n\t\t\t\t\ttry {\n\t\t\t\t\t\tmcpConfig = await generateIssueManagementMcpConfig(undefined, undefined, provider, settings ?? undefined)\n\t\t\t\t\t} catch (retryError) {\n\t\t\t\t\t\tconst retryMessage = retryError instanceof Error ? retryError.message : 'Unknown error'\n\t\t\t\t\t\tlogger.error(`Failed to generate MCP config: ${retryMessage}`)\n\t\t\t\t\t\tif (provider === 'github') {\n\t\t\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t\t\t'GitHub issue management requires a git repository with a GitHub remote configured.'\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`Cannot start planning session after init: ${retryMessage}. Ensure you are in a git repository with a GitHub remote configured.`\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t\t\t'Linear issue management requires LINEAR_API_TOKEN to be configured.'\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`Cannot start planning session after init: ${retryMessage}. Ensure LINEAR_API_TOKEN is configured in settings or environment.`\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\t// User declined init prompt - show provider-specific error messages\n\t\t\t\t\tlogger.error(`Failed to generate MCP config: ${message}`)\n\t\t\t\t\tif (provider === 'github') {\n\t\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t\t'GitHub issue management requires a git repository with a GitHub remote configured.'\n\t\t\t\t\t\t)\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`Cannot start planning session: ${message}. Ensure you are in a git repository with a GitHub remote configured.`\n\t\t\t\t\t\t)\n\t\t\t\t\t} else {\n\t\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t\t'Linear issue management requires LINEAR_API_TOKEN to be configured.'\n\t\t\t\t\t\t)\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`Cannot start planning session: ${message}. Ensure LINEAR_API_TOKEN is configured in settings or environment.`\n\t\t\t\t\t\t)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Non-interactive mode - show provider-specific error messages\n\t\t\t\tlogger.error(`Failed to generate MCP config: ${message}`)\n\t\t\t\tif (provider === 'github') {\n\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t'GitHub issue management requires a git repository with a GitHub remote configured.'\n\t\t\t\t\t)\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Cannot start planning session: ${message}. Ensure you are in a git repository with a GitHub remote configured.`\n\t\t\t\t\t)\n\t\t\t\t} else {\n\t\t\t\t\tlogger.error(\n\t\t\t\t\t\t'Linear issue management requires LINEAR_API_TOKEN to be configured.'\n\t\t\t\t\t)\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Cannot start planning session: ${message}. Ensure LINEAR_API_TOKEN is configured in settings or environment.`\n\t\t\t\t\t)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tlogger.debug('MCP config generated', {\n\t\t\tserverCount: mcpConfig.length,\n\t\t})\n\n\t\t// Detect VS Code mode\n\t\tconst isVscodeMode = process.env.ILOOM_VSCODE === '1'\n\t\tlogger.debug('VS Code mode detection', { isVscodeMode })\n\n\t\t// Compute template variables for multi-AI provider support\n\t\t// Generate USE_*_PLANNER and USE_*_REVIEWER flags dynamically\n\t\tconst providerFlags = PLANNER_PROVIDERS.reduce((acc, p) => ({\n\t\t\t...acc,\n\t\t\t[`USE_${p.toUpperCase()}_PLANNER`]: effectivePlanner === p,\n\t\t}), {} as Record<string, boolean>)\n\n\t\t// Add reviewer flags (excluding 'none')\n\t\t;(['claude', 'gemini', 'codex'] as const).forEach(p => {\n\t\t\tproviderFlags[`USE_${p.toUpperCase()}_REVIEWER`] = effectiveReviewer === p\n\t\t})\n\n\t\t// Load plan prompt template with mode-specific variables\n\t\tlogger.debug('Loading plan prompt template')\n\t\tconst templateVariables: TemplateVariables = {\n\t\t\tIS_VSCODE_MODE: isVscodeMode,\n\t\t\tEXISTING_ISSUE_MODE: !!decompositionContext,\n\t\t\tFRESH_PLANNING_MODE: !decompositionContext,\n\t\t\tPARENT_ISSUE_NUMBER: decompositionContext?.identifier,\n\t\t\tPARENT_ISSUE_TITLE: decompositionContext?.title,\n\t\t\tPARENT_ISSUE_BODY: decompositionContext?.body,\n\t\t\tPARENT_ISSUE_CHILDREN: decompositionContext?.children\n\t\t\t\t? formatChildIssues(decompositionContext.children, issuePrefix)\n\t\t\t\t: undefined,\n\t\t\tPARENT_ISSUE_DEPENDENCIES: decompositionContext?.dependencies\n\t\t\t\t? formatDependencies(decompositionContext.dependencies, issuePrefix)\n\t\t\t\t: undefined,\n\t\t\tPLANNER: effectivePlanner,\n\t\t\tREVIEWER: effectiveReviewer,\n\t\t\tHAS_REVIEWER: effectiveReviewer !== 'none',\n\t\t\t...providerFlags,\n\t\t}\n\t\tconst architectPrompt = await this.templateManager.getPrompt('plan', templateVariables)\n\t\tlogger.debug('Plan prompt loaded', {\n\t\t\tpromptLength: architectPrompt.length,\n\t\t\tmode: decompositionContext ? 'decomposition' : 'fresh',\n\t\t})\n\n\t\t// Define allowed tools for the Architect persona\n\t\tconst allowedTools = [\n\t\t\t// Issue management tools\n\t\t\t'mcp__issue_management__create_issue',\n\t\t\t'mcp__issue_management__create_child_issue',\n\t\t\t'mcp__issue_management__get_issue',\n\t\t\t'mcp__issue_management__get_child_issues',\n\t\t\t'mcp__issue_management__get_comment',\n\t\t\t'mcp__issue_management__create_comment',\n\t\t\t// Dependency management tools\n\t\t\t'mcp__issue_management__create_dependency',\n\t\t\t'mcp__issue_management__get_dependencies',\n\t\t\t'mcp__issue_management__remove_dependency',\n\t\t\t// Codebase exploration tools (read-only)\n\t\t\t'Read',\n\t\t\t'Glob',\n\t\t\t'Grep',\n\t\t\t'Task',\n\t\t\t// Web research tools\n\t\t\t'WebFetch',\n\t\t\t'WebSearch',\n\t\t\t// Git commands for understanding repo state\n\t\t\t'Bash(git status:*)',\n\t\t\t'Bash(git log:*)',\n\t\t\t'Bash(git branch:*)',\n\t\t\t'Bash(git remote:*)',\n\t\t\t'Bash(git diff:*)',\n\t\t\t'Bash(git show:*)',\n\t\t]\n\n\t\t// Determine if we're in print/headless mode\n\t\tconst isHeadless = printOptions?.print ?? false\n\n\t\t// Build Claude options\n\t\tconst claudeOptions: Parameters<typeof launchClaude>[1] = {\n\t\t\tmodel: effectiveModel,\n\t\t\theadless: isHeadless,\n\t\t\tappendSystemPrompt: architectPrompt,\n\t\t\tmcpConfig,\n\t\t\taddDir: process.cwd(),\n\t\t\tallowedTools,\n\t\t}\n\n\t\t// Add output format and verbose options if provided (print mode only)\n\t\tif (printOptions?.outputFormat !== undefined) {\n\t\t\tclaudeOptions.outputFormat = printOptions.outputFormat\n\t\t}\n\t\tif (printOptions?.verbose !== undefined) {\n\t\t\tclaudeOptions.verbose = printOptions.verbose\n\t\t}\n\n\t\t// Add JSON mode if specified (requires print mode)\n\t\tif (printOptions?.json) {\n\t\t\tclaudeOptions.jsonMode = 'json'\n\t\t\tclaudeOptions.outputFormat = 'stream-json' // Force stream-json for parsing\n\t\t} else if (printOptions?.jsonStream) {\n\t\t\tclaudeOptions.jsonMode = 'stream'\n\t\t\tclaudeOptions.outputFormat = 'stream-json' // Force stream-json for streaming\n\t\t}\n\n\t\t// Force yolo mode when print mode is enabled (headless execution requires autonomous mode)\n\t\tconst effectiveYolo = (yolo ?? false) || isHeadless\n\n\t\t// Handle --yolo mode\n\t\tif (effectiveYolo) {\n\t\t\t// Only require prompt for explicit --yolo flag, not for print mode auto-yolo\n\t\t\tif (yolo && !prompt) {\n\t\t\t\tthrow new Error('--yolo requires a prompt or issue identifier (e.g., il plan --yolo \"add gitlab support\" or il plan --yolo 42)')\n\t\t\t}\n\t\t\tlogger.warn(\n\t\t\t\t'YOLO mode enabled - Claude will skip permission prompts and proceed autonomously. This could destroy important data or make irreversible changes. Proceeding means you accept this risk.'\n\t\t\t)\n\t\t}\n\n\t\tlogger.debug('Launching Claude with options', {\n\t\t\toptionKeys: Object.keys(claudeOptions),\n\t\t\theadless: claudeOptions.headless,\n\t\t\thasSystemPrompt: !!claudeOptions.appendSystemPrompt,\n\t\t\taddDir: claudeOptions.addDir,\n\t\t\tyolo,\n\t\t\tprint: isHeadless,\n\t\t})\n\n\t\t// Launch Claude in interactive mode\n\t\t// Construct initial message based on mode\n\t\tlet initialMessage: string\n\t\tif (decompositionContext) {\n\t\t\t// Issue decomposition mode - provide context about what to decompose\n\t\t\tinitialMessage = `Break down issue #${decompositionContext.identifier} into child issues.`\n\t\t} else if (prompt) {\n\t\t\t// Fresh planning with user-provided topic\n\t\t\tinitialMessage = prompt\n\t\t} else {\n\t\t\t// Interactive mode - no topic provided\n\t\t\tinitialMessage = 'Help me plan a feature or decompose work into issues.'\n\t\t}\n\n\t\t// Apply yolo mode wrapper if enabled (includes print mode)\n\t\tif (effectiveYolo) {\n\t\t\tinitialMessage = `[AUTONOMOUS MODE]\nProceed through the flow without requiring user interaction. Make and document your assumptions and proceed to create the epic and child issues and dependencies if necessary. This guidance supersedes all previous guidance.\n\n[TOPIC]\n${initialMessage}`\n\t\t}\n\n\t\tconst claudeResult = await launchClaude(initialMessage, {\n\t\t\t...claudeOptions,\n\t\t\t...(effectiveYolo && { permissionMode: 'bypassPermissions' as const }),\n\t\t})\n\n\t\t// Track epic.planned telemetry for decomposition sessions\n\t\tif (decompositionContext) {\n\t\t\ttry {\n\t\t\t\tconst mcpProv = IssueManagementProviderFactory.create(provider as IssueProvider, settings ?? undefined)\n\t\t\t\tconst children = await mcpProv.getChildIssues({ number: decompositionContext.identifier })\n\t\t\t\tTelemetryService.getInstance().track('epic.planned', {\n\t\t\t\t\tchild_count: children.length,\n\t\t\t\t\ttracker: provider,\n\t\t\t\t})\n\t\t\t} catch (error) {\n\t\t\t\tlogger.debug(`Telemetry epic.planned tracking failed: ${error instanceof Error ? error.message : error}`)\n\t\t\t}\n\t\t}\n\n\t\t// Output final JSON for --json mode (--json-stream already streamed to stdout)\n\t\tif (printOptions?.json) {\n\t\t\t// eslint-disable-next-line no-console\n\t\t\tconsole.log(JSON.stringify({\n\t\t\t\tsuccess: true,\n\t\t\t\toutput: claudeResult ?? ''\n\t\t\t}))\n\t\t}\n\n\t\tlogger.debug('Claude session completed')\n\t\tlogger.info(chalk.green('Planning session ended.'))\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/{projects-LH362JZQ.js → projects-2UOXFLNZ.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   ProjectCapabilityDetector
-} from "./chunk-TL72BGP6.js";
-import "./chunk-VOGGLPG5.js";
+} from "./chunk-MORRVYPT.js";
+import "./chunk-YQ57ORTV.js";
 import {
   MetadataManager
-} from "./chunk-KBEIQP4G.js";
+} from "./chunk-KB64WNBZ.js";
 import {
   getLogger
 } from "./chunk-6MLEBAYZ.js";
@@ -100,4 +100,4 @@ var ProjectsCommand = class {
 export {
   ProjectsCommand
 };
-//# sourceMappingURL=projects-LH362JZQ.js.map
+//# sourceMappingURL=projects-2UOXFLNZ.js.map

package/dist/prompts/CLAUDE.md

@@ -0,0 +1,62 @@
+# Swarm Mode Overview
+
+Swarm mode orchestrates parallel AI agents to implement epic issues. An epic is decomposed into child issues, each executed in an isolated worktree by an independent agent, then merged back into the epic branch.
+
+## Lifecycle
+
+```
+il plan <epic>     Decompose epic into child issues (creates the children that trigger swarm)
+il start <epic>    Create epic loom (detects children, builds dependency map)
+il spin            Launch orchestrator (auto-detects epic, enters swarm mode)
+il list --json     Monitor progress (shows swarmIssues with per-child state)
+il finish <epic>   Merge epic branch back to main
+```
+
+## Architecture
+
+**Orchestrator** (`swarm-orchestrator-prompt.txt`) — runs in the epic worktree, fully autonomous (`bypassPermissions`). Manages a DAG-based dependency scheduler: spawns child agents in parallel for unblocked issues, monitors completions, rebases + fast-forward merges children into the epic branch, spawns newly unblocked children, handles failures.
+
+**Child agents** (`iloom-swarm-worker` custom agent type) — each implements one child issue in its own worktree. Strict isolation: only works in its assigned worktree, never merges branches or closes issues (orchestrator handles that). Reports success/failure back to orchestrator then stops.
+
+## Key Files
+
+| Area | Files |
+|------|-------|
+| CLI entry | `src/commands/ignite.ts` — detects epic, calls `SwarmSetupService`, launches orchestrator |
+| Setup | `src/lib/SwarmSetupService.ts` — creates child worktrees, renders agents, generates MCP configs |
+| Dependencies | `src/utils/dependency-map.ts` — builds DAG from issue tracker APIs (sibling deps only) |
+| Child data | `src/utils/list-children.ts` — fetches child issue details from tracker |
+| Metadata | `src/lib/MetadataManager.ts` — stores `childIssues`, `dependencyMap`, per-loom state |
+| Orchestrator prompt | `templates/prompts/swarm-orchestrator-prompt.txt` (5 phases) |
+| Worker prompt | `templates/prompts/issue-prompt.txt` (rendered with `SWARM_MODE=true`) |
+| Phase agents | `templates/agents/*.md` — analyzer, planner, implementer, etc. |
+| State tracking | `src/mcp/recap-server.ts` — `set_loom_state`, `add_artifact`, `add_entry` tools |
+
+## Branch & Worktree Layout
+
+```
+main
+└── issue/<epic-id>           # Epic branch + worktree
+    ├── issue/<child-1>       # Child branch + worktree
+    ├── issue/<child-2>       # Child branch + worktree
+    └── ...
+```
+
+Each child worktree gets its own `iloom-metadata.json` with `parentLoom` reference and state tracking (`pending` → `in_progress` → `done`/`failed`).
+
+## Merge Strategy
+
+Rebase child onto epic branch (from child worktree), then `git merge --ff-only` from epic worktree. Keeps linear history. Conflicts are auto-resolved by spawning a subagent; unresolvable conflicts mark the child as failed.
+
+## State Flow
+
+Per-child: `pending` → `in_progress` → `done` | `failed`
+
+Failed children cascade: any child depending on a failed child is also marked `failed`. Other children continue unaffected.
+
+## Configuration
+
+- Worker model: `.iloom/settings.json` → `agents.iloom-swarm-worker.model` (default: `sonnet`)
+- Phase agent models: `.iloom/settings.json` → `agents.iloom-issue-implementer.model`, etc.
+- Draft PR mode: `draftPrNumber` in metadata triggers auto-push via `--force-with-lease`
+- Issue tracker: `issueManagement.provider` (`github` | `linear` | `jira`)