@lumenflow/core 1.0.0

package/dist/wu-spawn-helpers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @file wu-spawn-helpers.mjs
+ * Helper functions for wu:spawn thinking mode and model configuration (WU-1577)
+ *
+ * Provides:
+ * - CLI argument parsing for thinking mode options
+ * - Validation for thinking/budget options
+ * - Execution Mode section generation
+ * - Think tool guidance generation
+ * - Help text generation
+ * - Spawn registry integration (WU-1945)
+ */
+/**
+ * Option definitions for thinking mode configuration.
+ *
+ * Note: Commander.js handles --no-thinking automatically as a negation of --thinking.
+ * When --no-thinking is used, opts.thinking is set to false.
+ * We detect this and convert to noThinking: true for clarity.
+ */
+export declare const THINKING_OPTIONS: {
+    thinking: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+    budget: {
+        name: string;
+        flags: string;
+        description: string;
+    };
+};
+/**
+ * Parse spawn-specific arguments from argv.
+ *
+ * @param {string[]} argv - Process arguments
+ * @returns {object} Parsed arguments with thinking options
+ */
+export declare function parseSpawnArgs(argv: any): import("commander").OptionValues;
+/**
+ * Validate spawn arguments for consistency.
+ *
+ * @param {object} args - Parsed arguments
+ * @throws {Error} If validation fails
+ */
+export declare function validateSpawnArgs(args: any): void;
+/**
+ * Generate the Execution Mode section for the task prompt.
+ *
+ * @param {object} options - Thinking mode options
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
+ * @param {string} [options.budget] - Token budget for thinking
+ * @returns {string} Execution Mode section or empty string if no thinking flags
+ */
+export declare function generateExecutionModeSection(options: any): string;
+/**
+ * Generate think tool guidance for the task prompt.
+ *
+ * @param {object} options - Thinking mode options
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
+ * @returns {string} Think tool guidance or empty string if not applicable
+ */
+export declare function generateThinkToolGuidance(options: any): "" | "## Think Tool Guidance\n\nWhen extended thinking is enabled, use the think tool strategically for:\n\n1. **Complex Decision Points**: Before making architectural decisions or choosing between approaches\n2. **Multi-Step Reasoning**: When planning long tool-call chains or multi-file edits\n3. **Mid-Execution Reflection**: After gathering information, before implementing changes\n4. **Error Analysis**: When troubleshooting failures or unexpected behavior\n\n### Best Practices\n\n- Use think blocks to reason through acceptance criteria before implementation\n- Document your reasoning for complex logic decisions\n- Break down large tasks into thought-through steps\n- Reflect on test results before proceeding with fixes\n\n### When NOT to Use Think Blocks\n\n- Simple file reads or writes with clear outcomes\n- Routine git operations\n- Running predefined commands like `pnpm gates`\n- When the next action is obvious and low-risk";
+/**
+ * Generate help text with examples for thinking mode options.
+ *
+ * @returns {string} Help text with option descriptions and examples
+ */
+export declare function getHelpText(): string;
+/**
+ * Records a spawn event to the spawn registry.
+ *
+ * This function is non-blocking: if the registry write fails, it returns
+ * a result with success=false but does NOT throw an error. This ensures
+ * wu:spawn succeeds even if the registry is unavailable.
+ *
+ * @param {object} options - Spawn recording options
+ * @param {string} options.parentWuId - Parent WU ID (orchestrator)
+ * @param {string} options.targetWuId - Target WU ID (spawned work)
+ * @param {string} options.lane - Lane for the spawned work
+ * @param {string} [options.baseDir] - Base directory for registry (defaults to .beacon/state)
+ * @returns {Promise<{success: boolean, spawnId: string|null, error?: string}>}
+ *
+ * @example
+ * const result = await recordSpawnToRegistry({
+ *   parentWuId: 'WU-1000',
+ *   targetWuId: 'WU-1001',
+ *   lane: 'Operations: Tooling',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Recorded: ${result.spawnId}`);
+ * }
+ */
+export declare function recordSpawnToRegistry(options: any): Promise<{
+    success: boolean;
+    spawnId: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    spawnId: any;
+    error: any;
+}>;
+/**
+ * Formats a message about spawn recording result.
+ *
+ * @param {string|null} spawnId - Spawn ID if successful, null otherwise
+ * @param {string} [errorMessage] - Error message if spawn recording failed
+ * @returns {string} Formatted message for console output
+ *
+ * @example
+ * // Successful recording
+ * formatSpawnRecordedMessage('spawn-abc1');
+ * // Returns: '[wu:spawn] Spawn recorded spawn-abc1'
+ *
+ * // Failed recording
+ * formatSpawnRecordedMessage(null, 'Registry unavailable');
+ * // Returns: '[wu:spawn] Warning: Registry write skipped (Registry unavailable)'
+ */
+export declare function formatSpawnRecordedMessage(spawnId: any, errorMessage?: any): string;

package/dist/wu-spawn-helpers.js

@@ -0,0 +1,271 @@
+/**
+ * @file wu-spawn-helpers.mjs
+ * Helper functions for wu:spawn thinking mode and model configuration (WU-1577)
+ *
+ * Provides:
+ * - CLI argument parsing for thinking mode options
+ * - Validation for thinking/budget options
+ * - Execution Mode section generation
+ * - Think tool guidance generation
+ * - Help text generation
+ * - Spawn registry integration (WU-1945)
+ */
+import { Command } from 'commander';
+import { SpawnRegistryStore } from './spawn-registry-store.js';
+/**
+ * Option definitions for thinking mode configuration.
+ *
+ * Note: Commander.js handles --no-thinking automatically as a negation of --thinking.
+ * When --no-thinking is used, opts.thinking is set to false.
+ * We detect this and convert to noThinking: true for clarity.
+ */
+export const THINKING_OPTIONS = {
+    thinking: {
+        name: 'thinking',
+        flags: '--thinking',
+        description: 'Enable extended thinking for complex WU execution',
+    },
+    budget: {
+        name: 'budget',
+        flags: '--budget <tokens>',
+        description: 'Token budget for extended thinking (requires --thinking)',
+    },
+};
+/**
+ * Parse spawn-specific arguments from argv.
+ *
+ * @param {string[]} argv - Process arguments
+ * @returns {object} Parsed arguments with thinking options
+ */
+export function parseSpawnArgs(argv) {
+    const program = new Command()
+        .name('wu-spawn')
+        .description('Generate Task tool invocation for sub-agent WU execution')
+        .allowUnknownOption(true)
+        .allowExcessArguments(true) // Allow positional WU ID argument
+        .exitOverride();
+    // Core options
+    program.option('-i, --id <wuId>', 'Work Unit ID (e.g., WU-123)');
+    // Thinking mode options
+    // Commander automatically creates --no-thinking when --thinking is registered
+    program.option(THINKING_OPTIONS.thinking.flags, THINKING_OPTIONS.thinking.description);
+    program.option(THINKING_OPTIONS.budget.flags, THINKING_OPTIONS.budget.description);
+    try {
+        program.parse(argv);
+    }
+    catch (err) {
+        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+            process.exit(0);
+        }
+        throw err;
+    }
+    const opts = program.opts();
+    // Handle positional argument as WU ID fallback
+    if (program.args.length > 0 && !opts.id) {
+        opts.id = program.args[0];
+    }
+    // Handle --no-thinking explicitly
+    // Check the argv array directly since Commander's handling of negated booleans varies
+    if (argv.includes('--no-thinking')) {
+        opts.noThinking = true;
+        delete opts.thinking;
+    }
+    return opts;
+}
+/**
+ * Validate spawn arguments for consistency.
+ *
+ * @param {object} args - Parsed arguments
+ * @throws {Error} If validation fails
+ */
+export function validateSpawnArgs(args) {
+    // Check mutually exclusive flags
+    if (args.thinking && args.noThinking) {
+        throw new Error('--thinking and --no-thinking are mutually exclusive');
+    }
+    // Budget requires thinking
+    if (args.budget && !args.thinking) {
+        throw new Error('--budget requires --thinking flag');
+    }
+    // Budget must be positive integer
+    if (args.budget) {
+        const budgetNum = parseInt(args.budget, 10);
+        if (isNaN(budgetNum) || budgetNum <= 0 || !Number.isInteger(budgetNum)) {
+            throw new Error('--budget must be a positive integer');
+        }
+    }
+}
+/**
+ * Generate the Execution Mode section for the task prompt.
+ *
+ * @param {object} options - Thinking mode options
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
+ * @param {string} [options.budget] - Token budget for thinking
+ * @returns {string} Execution Mode section or empty string if no thinking flags
+ */
+export function generateExecutionModeSection(options) {
+    const { thinking, noThinking, budget } = options;
+    // No section if no thinking flags specified (default behavior)
+    if (!thinking && !noThinking) {
+        return '';
+    }
+    const lines = ['## Execution Mode', ''];
+    if (thinking) {
+        lines.push('Extended thinking: **enabled**');
+        if (budget) {
+            lines.push(`Token budget: **${budget}**`);
+        }
+        lines.push('');
+        lines.push('The sub-agent will use extended thinking for complex reasoning tasks.');
+    }
+    else if (noThinking) {
+        lines.push('Extended thinking: **disabled**');
+        lines.push('');
+        lines.push('The sub-agent will execute without extended thinking mode.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate think tool guidance for the task prompt.
+ *
+ * @param {object} options - Thinking mode options
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
+ * @returns {string} Think tool guidance or empty string if not applicable
+ */
+export function generateThinkToolGuidance(options) {
+    const { thinking, noThinking } = options;
+    // No guidance if thinking is disabled or not specified
+    if (!thinking || noThinking) {
+        return '';
+    }
+    return `## Think Tool Guidance
+
+When extended thinking is enabled, use the think tool strategically for:
+
+1. **Complex Decision Points**: Before making architectural decisions or choosing between approaches
+2. **Multi-Step Reasoning**: When planning long tool-call chains or multi-file edits
+3. **Mid-Execution Reflection**: After gathering information, before implementing changes
+4. **Error Analysis**: When troubleshooting failures or unexpected behavior
+
+### Best Practices
+
+- Use think blocks to reason through acceptance criteria before implementation
+- Document your reasoning for complex logic decisions
+- Break down large tasks into thought-through steps
+- Reflect on test results before proceeding with fixes
+
+### When NOT to Use Think Blocks
+
+- Simple file reads or writes with clear outcomes
+- Routine git operations
+- Running predefined commands like \`pnpm gates\`
+- When the next action is obvious and low-risk`;
+}
+/**
+ * Generate help text with examples for thinking mode options.
+ *
+ * @returns {string} Help text with option descriptions and examples
+ */
+export function getHelpText() {
+    return `
+Thinking Mode Options:
+
+  --thinking          Enable extended thinking for complex WU execution
+  --no-thinking       Explicitly disable extended thinking (default behavior)
+  --budget <tokens>   Token budget for extended thinking (requires --thinking)
+
+Examples:
+
+  # Enable extended thinking for a complex WU
+  pnpm wu:spawn --id WU-123 --thinking
+
+  # Enable thinking with a specific token budget
+  pnpm wu:spawn --id WU-456 --thinking --budget 10000
+
+  # Explicitly disable thinking (useful for clear-spec WUs)
+  pnpm wu:spawn --id WU-789 --no-thinking
+
+Notes:
+
+  - Default behavior (no flags) preserves backward compatibility
+  - --budget requires --thinking flag to be set
+  - --thinking and --no-thinking are mutually exclusive
+  - Token budget is passed to the sub-agent's execution configuration
+`;
+}
+/**
+ * Log prefix for spawn registry messages (WU-1945)
+ */
+const LOG_PREFIX = '[wu:spawn]';
+/**
+ * Records a spawn event to the spawn registry.
+ *
+ * This function is non-blocking: if the registry write fails, it returns
+ * a result with success=false but does NOT throw an error. This ensures
+ * wu:spawn succeeds even if the registry is unavailable.
+ *
+ * @param {object} options - Spawn recording options
+ * @param {string} options.parentWuId - Parent WU ID (orchestrator)
+ * @param {string} options.targetWuId - Target WU ID (spawned work)
+ * @param {string} options.lane - Lane for the spawned work
+ * @param {string} [options.baseDir] - Base directory for registry (defaults to .beacon/state)
+ * @returns {Promise<{success: boolean, spawnId: string|null, error?: string}>}
+ *
+ * @example
+ * const result = await recordSpawnToRegistry({
+ *   parentWuId: 'WU-1000',
+ *   targetWuId: 'WU-1001',
+ *   lane: 'Operations: Tooling',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Recorded: ${result.spawnId}`);
+ * }
+ */
+export async function recordSpawnToRegistry(options) {
+    const { parentWuId, targetWuId, lane, baseDir = '.beacon/state' } = options;
+    try {
+        const store = new SpawnRegistryStore(baseDir);
+        await store.load();
+        const spawnId = await store.record(parentWuId, targetWuId, lane);
+        return {
+            success: true,
+            spawnId,
+        };
+    }
+    catch (error) {
+        // Non-blocking: return failure result instead of throwing
+        return {
+            success: false,
+            spawnId: null,
+            error: error.message,
+        };
+    }
+}
+/**
+ * Formats a message about spawn recording result.
+ *
+ * @param {string|null} spawnId - Spawn ID if successful, null otherwise
+ * @param {string} [errorMessage] - Error message if spawn recording failed
+ * @returns {string} Formatted message for console output
+ *
+ * @example
+ * // Successful recording
+ * formatSpawnRecordedMessage('spawn-abc1');
+ * // Returns: '[wu:spawn] Spawn recorded spawn-abc1'
+ *
+ * // Failed recording
+ * formatSpawnRecordedMessage(null, 'Registry unavailable');
+ * // Returns: '[wu:spawn] Warning: Registry write skipped (Registry unavailable)'
+ */
+export function formatSpawnRecordedMessage(spawnId, errorMessage = undefined) {
+    if (spawnId) {
+        return `${LOG_PREFIX} Spawn recorded ${spawnId}`;
+    }
+    if (errorMessage) {
+        return `${LOG_PREFIX} Warning: Registry write skipped (${errorMessage})`;
+    }
+    return `${LOG_PREFIX} Warning: Registry unavailable`;
+}

package/dist/wu-spawn.d.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * WU Spawn Helper
+ *
+ * Generates ready-to-use Task tool invocations for sub-agent WU execution.
+ * Includes context loading preamble, skills selection guidance, and constraints block.
+ *
+ * Usage:
+ *   pnpm wu:spawn --id WU-123
+ *   pnpm wu:spawn --id WU-123 --codex
+ *
+ * Output:
+ *   A complete Task tool invocation block with:
+ *   - Context loading preamble (CLAUDE-core.md, README, lumenflow, WU YAML)
+ *   - WU details and acceptance criteria
+ *   - Skills Selection section (sub-agent reads catalogue and selects at runtime)
+ *   - Mandatory agent advisory
+ *   - Constraints block at end (Lost in the Middle research)
+ *
+ * Skills Selection:
+ *   This command is AGENT-FACING. Unlike /wu-prompt (human-facing, skills selected
+ *   at generation time), wu:spawn instructs the sub-agent to read the skill catalogue
+ *   and select skills at execution time based on WU context.
+ *
+ * Codex Mode:
+ *   When --codex is used, outputs a Codex/GPT-friendly Markdown prompt (no antml/XML escaping).
+ *
+ * @see {@link ai/onboarding/agent-invocation-guide.md} - Context loading templates
+ */
+/**
+ * Generate effort scaling rules section (WU-1986)
+ *
+ * Based on Anthropic multi-agent research: helps agents decide when to
+ * spawn sub-agents vs handle inline.
+ *
+ * @returns {string} Effort scaling section
+ */
+export declare function generateEffortScalingRules(): string;
+/**
+ * Generate parallel tool call guidance (WU-1986)
+ *
+ * Based on Anthropic research: 3+ parallel tool calls significantly improve performance.
+ *
+ * @returns {string} Parallel tool call guidance
+ */
+export declare function generateParallelToolCallGuidance(): string;
+/**
+ * Generate iterative search heuristics (WU-1986)
+ *
+ * Based on Anthropic research: start broad, narrow focus.
+ *
+ * @returns {string} Search heuristics section
+ */
+export declare function generateIterativeSearchHeuristics(): string;
+/**
+ * Generate token budget awareness section (WU-1986)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Token budget section
+ */
+export declare function generateTokenBudgetAwareness(id: any): string;
+/**
+ * Generate structured completion format (WU-1986)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Completion format section
+ */
+export declare function generateCompletionFormat(_id: any): string;
+/**
+ * Generate agent coordination section (WU-1987)
+ *
+ * Provides guidance on mem:signal for parallel agent coordination,
+ * orchestrate:status for dashboard checks, and abandoned WU handling.
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Agent coordination section
+ */
+export declare function generateAgentCoordinationSection(id: any): string;
+/**
+ * Generate quick fix commands section (WU-1987)
+ *
+ * Provides format/lint/typecheck commands for quick fixes before gates.
+ *
+ * @returns {string} Quick fix commands section
+ */
+export declare function generateQuickFixCommands(): string;
+/**
+ * Generate Lane Selection section (WU-2107)
+ *
+ * Provides guidance on lane selection when creating new WUs.
+ * Points agents to wu:infer-lane for automated lane suggestions.
+ *
+ * @returns {string} Lane Selection section
+ */
+export declare function generateLaneSelectionSection(): string;
+/**
+ * Generate Worktree Path Guidance section (WU-2362)
+ *
+ * Provides guidance for sub-agents on working within worktrees, including
+ * how to determine the worktree root and where to create stamps.
+ *
+ * Problem: CLAUDE_PROJECT_DIR is hook-only; sub-agents inherit parent cwd (main).
+ * Solution: Use git rev-parse --show-toplevel to determine actual worktree root.
+ *
+ * @param {string|undefined} worktreePath - Worktree path from WU YAML
+ * @returns {string} Worktree path guidance section
+ */
+export declare function generateWorktreePathGuidance(worktreePath: any): string;
+/**
+ * Generate the Action section based on WU claim status (WU-1745).
+ *
+ * If WU is already claimed (has claimed_at and worktree_path), tells agent
+ * to continue in the existing worktree.
+ *
+ * If WU is unclaimed (status: ready), tells agent to run wu:claim first.
+ *
+ * @param {object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @returns {string} Action section content
+ */
+export declare function generateActionSection(doc: any, id: any): string;
+/**
+ * Generate the complete Task tool invocation
+ *
+ * @param {object} doc - WU YAML document
+ * @param {string} id - WU ID
+ * @param {object} [options={}] - Thinking mode options
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
+ * @param {string} [options.budget] - Token budget for thinking
+ * @returns {string} Complete Task tool invocation
+ */
+export declare function generateTaskInvocation(doc: any, id: any, options?: {}): string;
+export declare function generateCodexPrompt(doc: any, id: any, options?: {}): string;
+/**
+ * WU-1603: Check if a lane is currently occupied by another WU
+ *
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling")
+ * @returns {import('./lib/lane-lock.js').LockMetadata|null} Lock metadata if occupied, null otherwise
+ */
+export declare function checkLaneOccupation(lane: any): import("./lane-lock.js").LockMetadata;
+/**
+ * Options for lane occupation warning
+ */
+interface LaneOccupationWarningOptions {
+    /** Whether the lock is stale (>24h old) */
+    isStale?: boolean;
+}
+/**
+ * WU-1603: Generate a warning message when lane is occupied
+ *
+ * @param {import('./lib/lane-lock.js').LockMetadata} lockMetadata - Lock metadata
+ * @param {string} targetWuId - WU ID being spawned
+ * @param {LaneOccupationWarningOptions} [options={}] - Options
+ * @returns {string} Warning message
+ */
+export declare function generateLaneOccupationWarning(lockMetadata: any, targetWuId: any, options?: LaneOccupationWarningOptions): string;
+export {};