@compilr-dev/agents 0.2.0 → 0.3.0

package/dist/skills/index.js

@@ -773,185 +773,8 @@ Create the directory if it doesn't exist.
 ✓ User has reviewed the note`,
         tags: ['documentation', 'session'],
     }),
-    defineSkill({
-        name: 'build',
-        description: 'Implement a backlog item end-to-end',
-        tags: ['implementation', 'coding'],
-        prompt: `You are in BUILD MODE. Implement the specified backlog item.
-
-## ITEM TO IMPLEMENT
-- **ID:** {{item_id}}
-- **Title:** {{item_title}}
-- **Type:** {{item_type}}
-- **Priority:** {{item_priority}}
-- **Description:** {{item_description}}
-
-## BEFORE STARTING
-
-1. Show the item details to the user in a clear format
-2. Use ask_user_simple to confirm: "Proceed with implementation?"
-   - Options: "Yes, let's build it", "No, pick a different item", "Cancel"
-3. If there are dependency warnings, mention them and ask if user wants to proceed anyway
-
-## CONTEXT TO READ
-
-Before implementing, read these files for context:
-- **PRD.md** (if exists): Project vision and requirements
-- **CLAUDE.md**: Coding standards and conventions
-- **Existing code**: Understand patterns already in use
-
-## IMPLEMENTATION WORKFLOW
-
-### Phase 1: Plan
-1. Use todo_write to create implementation checklist:
-   - Break down the item into concrete tasks
-   - Identify files to create or modify
-   - Note any edge cases to handle
-2. Update backlog status to 🚧 using backlog_write
-
-### Phase 2: Implement
-1. Write code following project conventions from CLAUDE.md
-2. Add tests if the project has a test framework
-3. Keep changes focused on the backlog item scope
-4. Use todo_write to track progress through tasks
-
-### Phase 3: Verify
-1. Run tests with run_tests tool
-2. Run lint with run_lint tool
-3. If tests or lint fail:
-   - Analyze the error message
-   - Fix the issue
-   - Re-run verification
-   - Repeat up to 3 times
-4. If still failing after 3 attempts:
-   - Report the issue to user
-   - Keep status as 🚧
-   - Ask for guidance
-
-### Phase 4: Complete
-1. Update backlog status to ✅ using backlog_write
-2. Create git commit with message format:
-   - feat({{item_id}}): {{item_title}} - for features
-   - fix({{item_id}}): {{item_title}} - for bugs
-   - chore({{item_id}}): {{item_title}} - for chores
-3. Update backlog with the commit SHA
-4. Clear todos with todo_write
-5. Summarize what was implemented
-
-## RULES
-
-- Follow coding standards from CLAUDE.md strictly
-- Keep commits atomic - one backlog item per commit
-- Ask user via ask_user_simple if you hit blockers
-- Don't over-engineer - implement exactly what the item describes
-- Don't add features beyond what was requested
-- Use todo_write throughout to show progress
-- Always run tests before marking complete`,
-    }),
-    defineSkill({
-        name: 'scaffold',
-        description: 'Create project foundation based on tech stack',
-        tags: ['setup', 'foundation', 'scaffolding'],
-        prompt: `You are creating the PROJECT SCAFFOLD (foundation).
-
-## PURPOSE
-
-Create the base project structure that features will be built on top of.
-This is the skeleton that makes feature implementation possible.
-
-## CONTEXT TO READ
-
-First, read these files to understand what to build:
-- **CLAUDE.md**: Tech stack, coding standards, project type
-- **PRD.md** (if exists): Project vision and requirements
-- **Existing files**: What already exists (if anything)
-
-## BEFORE STARTING
-
-1. Summarize the detected/specified tech stack
-2. Use ask_user_simple to confirm: "Create project scaffold with this stack?"
-   - Options: "Yes, create it", "No, let me specify", "Cancel"
-3. If user wants to specify, ask about tech stack preferences
-
-## SCAFFOLD BY PROJECT TYPE
-
-### Web Application (React/Vue/Svelte)
-
-Create:
-- \`src/\` folder structure:
-  - \`src/components/\` - Reusable components
-  - \`src/pages/\` or \`src/routes/\` - Page components
-  - \`src/lib/\` or \`src/utils/\` - Utility functions
-  - \`src/styles/\` - Global styles
-- \`package.json\` with dependencies
-- Build config (\`vite.config.ts\`, \`next.config.js\`, etc.)
-- \`index.html\` entry point (if applicable)
-- Basic App component with routing setup
-- CSS/Tailwind configuration
-- \`.gitignore\`
-- \`README.md\` with setup instructions
-
-### API / Backend (Node/Python/Go)
-
-Create:
-- \`src/\` folder structure:
-  - \`src/routes/\` or \`src/api/\` - API endpoints
-  - \`src/services/\` - Business logic
-  - \`src/models/\` - Data models
-  - \`src/utils/\` - Utilities
-- \`package.json\` / \`requirements.txt\` / \`go.mod\`
-- Entry point (\`src/index.ts\`, \`main.py\`, \`main.go\`)
-- Basic server setup (Express, FastAPI, Gin, etc.)
-- Health check endpoint (\`GET /health\`)
-- Environment config (\`.env.example\`)
-- \`.gitignore\`
-- \`README.md\` with setup instructions
-
-### CLI Tool (Node/Python/Rust)
-
-Create:
-- \`src/\` folder structure:
-  - \`src/commands/\` - Command handlers
-  - \`src/utils/\` - Utilities
-- \`package.json\` with \`bin\` entry / \`setup.py\` / \`Cargo.toml\`
-- Entry point with argument parsing
-- Basic command structure (help, version)
-- \`.gitignore\`
-- \`README.md\` with usage instructions
-
-### Full-Stack Application
-
-Create both frontend and backend structures:
-- \`frontend/\` or \`client/\` - Web app scaffold
-- \`backend/\` or \`server/\` - API scaffold
-- Root \`package.json\` with workspace config (if monorepo)
-- \`docker-compose.yml\` (optional)
-- \`.gitignore\`
-- \`README.md\` with setup instructions
-
-## POST-SCAFFOLD STEPS
-
-1. Install dependencies:
-   - \`npm install\` / \`pip install -r requirements.txt\` / etc.
-2. Run build to verify:
-   - \`npm run build\` / equivalent
-3. Run lint to verify:
-   - \`npm run lint\` / equivalent
-4. Create initial git commit:
-   - \`chore: initial project scaffold\`
-5. Update backlog:
-   - Mark scaffold CHORE as ✅ (if exists)
-
-## RULES
-
-- Follow conventions from CLAUDE.md
-- Use modern, widely-adopted patterns
-- Keep it minimal - only what's needed to start
-- Don't add features - just structure
-- Ensure the project builds and lints clean
-- Add helpful comments in config files
-- Include TypeScript/type hints where applicable`,
-    }),
+    // NOTE: 'build' and 'scaffold' skills moved to @compilr-dev/agents-coding
+    // because they depend on coding-specific tools (run_tests, run_lint, detect_project)
 ];
 /**
  * Default skill registry with built-in skills

package/dist/tools/builtin/ask-user-simple.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Ask User Simple Tool - Single question with simple string options
+ *
+ * A simplified version of ask_user for single questions with string options.
+ * Preferred over ask_user when you only need to ask one simple question.
+ *
+ * Features:
+ * - Single question
+ * - Simple string options (no value/label distinction)
+ * - Default value support
+ * - Factory function for custom implementations
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for ask_user_simple tool
+ */
+export interface AskUserSimpleInput {
+    /** The question to ask */
+    question: string;
+    /** Simple string options to choose from */
+    options: string[];
+    /** Default value if user skips (optional) */
+    default?: string;
+}
+/**
+ * Result from ask_user_simple tool
+ */
+export interface AskUserSimpleResult {
+    /** The selected answer */
+    answer: string;
+    /** Whether the default was used */
+    usedDefault?: boolean;
+}
+/**
+ * Options for creating custom ask_user_simple tool
+ */
+export interface AskUserSimpleToolOptions {
+    /**
+     * Custom handler for asking the question.
+     * If not provided, uses readline-based implementation.
+     */
+    onAsk?: (question: string, options: string[], defaultValue?: string) => Promise<AskUserSimpleResult>;
+}
+/**
+ * Default ask_user_simple tool using readline for basic CLI interaction.
+ * Use createAskUserSimpleTool() for custom implementations.
+ */
+export declare const askUserSimpleTool: Tool<AskUserSimpleInput>;
+/**
+ * Create a custom ask_user_simple tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskSimple = createAskUserSimpleTool({
+ *   onAsk: async (question, options, defaultValue) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserSimpleOverlay({ question, options, defaultValue });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskSimple);
+ * ```
+ */
+export declare function createAskUserSimpleTool(options?: AskUserSimpleToolOptions): Tool<AskUserSimpleInput>;

package/dist/tools/builtin/ask-user-simple.js

@@ -0,0 +1,149 @@
+/**
+ * Ask User Simple Tool - Single question with simple string options
+ *
+ * A simplified version of ask_user for single questions with string options.
+ * Preferred over ask_user when you only need to ask one simple question.
+ *
+ * Features:
+ * - Single question
+ * - Simple string options (no value/label distinction)
+ * - Default value support
+ * - Factory function for custom implementations
+ */
+/* eslint-disable no-console -- Intentional console output for fallback CLI prompts */
+import * as readline from 'readline';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+// =============================================================================
+// Default Implementation (readline-based)
+// =============================================================================
+async function askSimpleWithReadline(question, options, defaultValue) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        // Print question and options
+        console.log(`\n${question}`);
+        options.forEach((opt, i) => {
+            console.log(`  ${String(i + 1)}. ${opt}`);
+        });
+        if (defaultValue) {
+            console.log(`  (Press Enter for default: ${defaultValue})`);
+        }
+        rl.question('Choice: ', (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            // Empty input - use default or first option
+            if (!trimmed) {
+                if (defaultValue) {
+                    resolve({ answer: defaultValue, usedDefault: true });
+                }
+                else {
+                    resolve({ answer: options[0], usedDefault: true });
+                }
+                return;
+            }
+            // Try to parse as number
+            const idx = parseInt(trimmed, 10) - 1;
+            if (idx >= 0 && idx < options.length) {
+                resolve({ answer: options[idx] });
+                return;
+            }
+            // Try to match option text (case-insensitive)
+            const lowerInput = trimmed.toLowerCase();
+            const matched = options.find((opt) => opt.toLowerCase() === lowerInput);
+            if (matched) {
+                resolve({ answer: matched });
+                return;
+            }
+            // No match - use default or first option
+            if (defaultValue) {
+                resolve({ answer: defaultValue, usedDefault: true });
+            }
+            else {
+                resolve({ answer: options[0], usedDefault: true });
+            }
+        });
+    });
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+/**
+ * Default ask_user_simple tool using readline for basic CLI interaction.
+ * Use createAskUserSimpleTool() for custom implementations.
+ */
+export const askUserSimpleTool = defineTool({
+    name: 'ask_user_simple',
+    description: 'Ask a single simple question with string options. ' +
+        'Use this instead of ask_user when you only need one question. ' +
+        'Provide 2-4 clear, concise options. ' +
+        'The user can select by number or by typing the option text.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the user',
+            },
+            options: {
+                type: 'array',
+                description: 'Available options (2-4 options)',
+                minItems: 2,
+                maxItems: 4,
+                items: {
+                    type: 'string',
+                },
+            },
+            default: {
+                type: 'string',
+                description: 'Default value if user skips',
+            },
+        },
+        required: ['question', 'options'],
+    },
+    execute: async (input) => {
+        try {
+            const result = await askSimpleWithReadline(input.question, input.options, input.default);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a custom ask_user_simple tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskSimple = createAskUserSimpleTool({
+ *   onAsk: async (question, options, defaultValue) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserSimpleOverlay({ question, options, defaultValue });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskSimple);
+ * ```
+ */
+export function createAskUserSimpleTool(options = {}) {
+    const handler = options.onAsk ?? askSimpleWithReadline;
+    return defineTool({
+        name: 'ask_user_simple',
+        description: askUserSimpleTool.definition.description,
+        inputSchema: askUserSimpleTool.definition.inputSchema,
+        execute: async (input) => {
+            try {
+                const result = await handler(input.question, input.options, input.default);
+                return createSuccessResult(result);
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}

package/dist/tools/builtin/ask-user.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Ask User Tool - Gather input from user via questions with options
+ *
+ * This tool allows the agent to ask the user questions with predefined options.
+ * The default implementation uses Node.js readline for basic CLI interaction.
+ * Consumers (like CLI apps) can override with custom UI implementations.
+ *
+ * Features:
+ * - Multiple questions in a single call
+ * - Options with labels, values, and descriptions
+ * - Multi-select support
+ * - Factory function for custom implementations
+ */
+import type { Tool } from '../types.js';
+/**
+ * A single option for a question
+ */
+export interface AskUserOption {
+    /** Display text for the option */
+    label: string;
+    /** Value returned when this option is selected */
+    value: string;
+    /** Optional description/explanation */
+    description?: string;
+}
+/**
+ * A question to ask the user
+ */
+export interface AskUserQuestion {
+    /** Unique identifier for this question */
+    id: string;
+    /** The question text */
+    question: string;
+    /** Available options to choose from */
+    options: AskUserOption[];
+    /** Allow multiple selections (default: false) */
+    multiSelect?: boolean;
+}
+/**
+ * Input parameters for ask_user tool
+ */
+export interface AskUserInput {
+    /** Questions to ask the user (1-4 questions) */
+    questions: AskUserQuestion[];
+}
+/**
+ * Result from ask_user tool
+ */
+export interface AskUserResult {
+    /** Answers keyed by question ID */
+    answers: Record<string, string | string[]>;
+    /** Question IDs that were skipped */
+    skipped: string[];
+}
+/**
+ * Options for creating custom ask_user tool
+ */
+export interface AskUserToolOptions {
+    /**
+     * Custom handler for asking questions.
+     * If not provided, uses readline-based implementation.
+     */
+    onAsk?: (questions: AskUserQuestion[]) => Promise<AskUserResult>;
+}
+/**
+ * Default ask_user tool using readline for basic CLI interaction.
+ * Use createAskUserTool() for custom implementations.
+ */
+export declare const askUserTool: Tool<AskUserInput>;
+/**
+ * Create a custom ask_user tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskUser = createAskUserTool({
+ *   onAsk: async (questions) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserOverlay({ questions });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskUser);
+ * ```
+ */
+export declare function createAskUserTool(options?: AskUserToolOptions): Tool<AskUserInput>;

package/dist/tools/builtin/ask-user.js

@@ -0,0 +1,195 @@
+/**
+ * Ask User Tool - Gather input from user via questions with options
+ *
+ * This tool allows the agent to ask the user questions with predefined options.
+ * The default implementation uses Node.js readline for basic CLI interaction.
+ * Consumers (like CLI apps) can override with custom UI implementations.
+ *
+ * Features:
+ * - Multiple questions in a single call
+ * - Options with labels, values, and descriptions
+ * - Multi-select support
+ * - Factory function for custom implementations
+ */
+/* eslint-disable no-console -- Intentional console output for fallback CLI prompts */
+import * as readline from 'readline';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+// =============================================================================
+// Default Implementation (readline-based)
+// =============================================================================
+async function askWithReadline(questions) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const askQuestion = (prompt) => {
+        return new Promise((resolve) => {
+            rl.question(prompt, (answer) => {
+                resolve(answer);
+            });
+        });
+    };
+    const answers = {};
+    const skipped = [];
+    try {
+        for (const q of questions) {
+            // Print question
+            console.log(`\n${q.question}`);
+            // Print options
+            q.options.forEach((opt, i) => {
+                const desc = opt.description ? ` - ${opt.description}` : '';
+                console.log(`  ${String(i + 1)}. ${opt.label}${desc}`);
+            });
+            if (q.multiSelect) {
+                console.log('  (Enter numbers separated by commas, or press Enter to skip)');
+            }
+            // Get answer
+            const prompt = q.multiSelect ? 'Choices: ' : 'Choice: ';
+            const answer = await askQuestion(prompt);
+            if (!answer.trim()) {
+                skipped.push(q.id);
+                continue;
+            }
+            if (q.multiSelect) {
+                // Parse comma-separated numbers
+                const indices = answer
+                    .split(',')
+                    .map((s) => parseInt(s.trim(), 10) - 1)
+                    .filter((i) => i >= 0 && i < q.options.length);
+                if (indices.length > 0) {
+                    answers[q.id] = indices.map((i) => q.options[i].value);
+                }
+                else {
+                    skipped.push(q.id);
+                }
+            }
+            else {
+                // Single selection
+                const idx = parseInt(answer.trim(), 10) - 1;
+                if (idx >= 0 && idx < q.options.length) {
+                    answers[q.id] = q.options[idx].value;
+                }
+                else {
+                    // Invalid input - try to use as raw value or skip
+                    skipped.push(q.id);
+                }
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return { answers, skipped };
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+/**
+ * Default ask_user tool using readline for basic CLI interaction.
+ * Use createAskUserTool() for custom implementations.
+ */
+export const askUserTool = defineTool({
+    name: 'ask_user',
+    description: 'Ask the user one or more questions with predefined options. ' +
+        'Use this to gather preferences, make decisions, or get user input during workflows. ' +
+        'Each question should have 2-4 clear options. ' +
+        'Prefer ask_user_simple for single simple questions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            questions: {
+                type: 'array',
+                description: 'Questions to ask (1-4 questions)',
+                minItems: 1,
+                maxItems: 4,
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Unique identifier for this question',
+                        },
+                        question: {
+                            type: 'string',
+                            description: 'The question text to display',
+                        },
+                        options: {
+                            type: 'array',
+                            description: 'Available options (2-4 options)',
+                            minItems: 2,
+                            maxItems: 4,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    label: {
+                                        type: 'string',
+                                        description: 'Display text for this option',
+                                    },
+                                    value: {
+                                        type: 'string',
+                                        description: 'Value returned when selected',
+                                    },
+                                    description: {
+                                        type: 'string',
+                                        description: 'Optional explanation of this option',
+                                    },
+                                },
+                                required: ['label', 'value'],
+                            },
+                        },
+                        multiSelect: {
+                            type: 'boolean',
+                            description: 'Allow selecting multiple options',
+                        },
+                    },
+                    required: ['id', 'question', 'options'],
+                },
+            },
+        },
+        required: ['questions'],
+    },
+    execute: async (input) => {
+        try {
+            const result = await askWithReadline(input.questions);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a custom ask_user tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskUser = createAskUserTool({
+ *   onAsk: async (questions) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserOverlay({ questions });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskUser);
+ * ```
+ */
+export function createAskUserTool(options = {}) {
+    const handler = options.onAsk ?? askWithReadline;
+    return defineTool({
+        name: 'ask_user',
+        description: askUserTool.definition.description,
+        inputSchema: askUserTool.definition.inputSchema,
+        execute: async (input) => {
+            try {
+                const result = await handler(input.questions);
+                return createSuccessResult(result);
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}