@majkapp/plugin-kit 3.5.3 → 3.5.5

package/docs/TEAMMATES.md

@@ -0,0 +1,585 @@
+# Teammates - AI Agents for Your Plugin
+
+Every MAJK plugin can provide AI teammates (agents) that users can interact with. These teammates have access to your plugin's functions and provide natural language interfaces to your plugin's capabilities.
+
+## Quick Start
+
+```typescript
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  .function('getData', {
+    description: 'Get data from the system',
+    input: { type: 'object', properties: {}, additionalProperties: false },
+    output: { type: 'object', properties: { data: { type: 'array' } } },
+    handler: async (_, ctx) => ({ data: [] })
+  })
+
+  // Customize the auto-generated teammate's instructions
+  .instructions(`You are an expert assistant for My Plugin.
+Help users retrieve and analyze data efficiently.`)
+
+  .build();
+```
+
+## Auto-Generated Default Teammate
+
+**Every plugin automatically gets a default teammate** with these characteristics:
+
+- **Name**: `"<Plugin Name> Expert"` (e.g., "Task Manager Expert")
+- **ID**: Same as your package name (e.g., `"@majk/task-manager"`)
+- **Functions**: ALL plugin functions automatically included
+- **System Prompt**: Generic or customized via `.instructions()`
+
+### How It Works
+
+When you define functions in your plugin:
+
+```typescript
+.function('searchTasks', { /* ... */ })
+.function('createTask', { /* ... */ })
+.function('updateTask', { /* ... */ })
+```
+
+MAJK automatically creates a teammate that can call all three functions. Users can then interact with your plugin through natural conversation:
+
+> **User**: "Show me all tasks due this week"
+>
+> **Task Manager Expert**: *calls searchTasks({ dueDate: '2024-11-17' })*
+>
+> "Here are your tasks due this week: ..."
+
+### Customizing Instructions
+
+Use `.instructions()` to customize the auto-generated teammate's system prompt:
+
+```typescript
+.instructions(`You are an expert assistant for the Weather Plugin.
+
+Your capabilities:
+- Get current weather conditions using getCurrentWeather
+- Retrieve 7-day forecasts using getWeeklyForecast
+- Search historical weather data using searchHistory
+
+When helping users:
+1. Always ask for location if not provided
+2. Present weather data in a clear, formatted way
+3. Proactively suggest relevant queries (e.g., "Would you like the extended forecast?")
+4. Use appropriate units based on user's region
+
+Be concise but informative. Focus on actionable weather insights.`)
+```
+
+**Best Practices for Instructions**:
+- Clearly list available functions and their purpose
+- Provide guidance on how to interact with users
+- Set expectations for response format
+- Include domain-specific knowledge relevant to your plugin
+
+### Disabling Auto-Generated Teammate
+
+If you want complete control over teammates (no default):
+
+```typescript
+.noDefaultTeammate()
+```
+
+Use this when:
+- You want to define all teammates manually
+- Your plugin is purely infrastructure (no user-facing agent needed)
+- You have multiple specialized teammates and don't want a general-purpose one
+
+## Custom Teammates
+
+In addition to (or instead of) the auto-generated teammate, you can define custom teammates with specialized roles and limited function access.
+
+### Basic Custom Teammate
+
+```typescript
+.teamMember([
+  {
+    id: 'weather-viewer',
+    name: 'Weather Viewer (Read-Only)',
+    systemPrompt: 'You are a read-only assistant for viewing weather data. You can query and display information but cannot modify settings or create alerts.',
+    expertise: ['Weather Data', 'Read-Only Operations'],
+    skills: {
+      primary: ['Data Query', 'Weather Display'],
+      secondary: ['Data Analysis'],
+      languages: [],
+      frameworks: [],
+      tools: []
+    },
+    personality: {
+      workStyle: 'methodical',
+      codeStyle: 'concise',
+      reviewStyle: 'pragmatic',
+      communicationStyle: 'explanatory'
+    },
+    metadata: {
+      totalTasks: 0,
+      successfulTasks: 0,
+      projectHistory: [],
+      codeStats: {
+        linesWritten: 0,
+        filesModified: 0,
+        testsWritten: 0,
+        reviewsPassed: 0,
+        commitsCreated: 0
+      }
+    },
+    mcpServerIds: [],
+
+    // Specify which functions this teammate can access
+    functions: [
+      'getCurrentWeather',
+      'getWeeklyForecast',
+      'searchHistory'
+      // NOT included: 'createAlert', 'updateSettings'
+    ]
+  }
+])
+```
+
+### Function Access Control
+
+The `functions` field controls which plugin functions a teammate can call:
+
+#### Simple Mode (String Array)
+
+Just list function names from your plugin:
+
+```typescript
+functions: [
+  'searchTasks',  // ✅ Can search
+  'getTasks',     // ✅ Can view
+  'uiLog'         // ✅ Can debug
+  // ❌ Cannot use 'deleteTask' - not included
+]
+```
+
+**How it works**:
+- Each string is automatically expanded to reference the current plugin
+- Example: `'searchTasks'` becomes `{ pluginId: '@myorg/my-plugin', serviceName: '@myorg/my-plugin:all', functionName: 'searchTasks' }`
+
+#### Advanced Mode (Cross-Plugin Functions)
+
+Reference functions from other plugins:
+
+```typescript
+functions: [
+  // Current plugin functions (simple)
+  'searchTasks',
+  'getTasks',
+
+  // Other plugin functions (explicit)
+  {
+    pluginId: '@majk/calendar',
+    serviceName: '@majk/calendar:all',
+    functionName: 'getEvents'
+  },
+  {
+    pluginId: '@majk/notifications',
+    serviceName: '@majk/notifications:all',
+    functionName: 'sendAlert'
+  }
+]
+```
+
+**Use cases for cross-plugin access**:
+- Coordinator teammates that orchestrate multiple plugins
+- Integration teammates that bridge different systems
+- Specialized workflows that span multiple domains
+
+### Multiple Specialized Teammates
+
+Define teammates for different roles or expertise levels:
+
+```typescript
+.teamMember([
+  {
+    id: 'task-viewer',
+    name: 'Task Viewer (Beginner-Friendly)',
+    systemPrompt: 'You are a friendly assistant for viewing tasks. Explain everything clearly and guide users step-by-step.',
+    functions: ['getTasks', 'searchTasks'],
+    // ... full teammate config
+  },
+  {
+    id: 'task-manager',
+    name: 'Task Manager (Power User)',
+    systemPrompt: 'You are an advanced task management assistant. Assume users are familiar with the system and want concise, powerful operations.',
+    functions: ['getTasks', 'searchTasks', 'createTask', 'updateTask', 'deleteTask', 'bulkUpdate'],
+    // ... full teammate config
+  },
+  {
+    id: 'task-reporter',
+    name: 'Task Reporter (Analytics)',
+    systemPrompt: 'You specialize in task analytics and reporting. Generate insights, trends, and actionable recommendations.',
+    functions: ['getTasks', 'searchTasks', 'generateReport', 'getStatistics'],
+    // ... full teammate config
+  }
+])
+```
+
+## Complete Example from Quickstart
+
+```typescript
+const plugin = definePlugin('sample-plugin', 'Sample Plugin', '1.0.0')
+  .pluginRoot(path.join(__dirname, '..'))
+
+  .function('getSampleItems', {
+    description: 'Get sample items from the API',
+    input: { type: 'object', properties: {}, additionalProperties: false },
+    output: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+          value: { type: 'number' }
+        }
+      }
+    },
+    handler: async (_, ctx) => [
+      { id: '1', name: 'Item 1', value: 100 }
+    ],
+    tags: ['sample', 'query']
+  })
+
+  .function('doSampleAction', {
+    description: 'Perform a sample action via the API',
+    input: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        value: { type: 'number' }
+      },
+      required: ['name', 'value']
+    },
+    output: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        success: { type: 'boolean' }
+      }
+    },
+    handler: async (input, ctx) => ({
+      id: 'action-1',
+      success: true
+    }),
+    tags: ['sample', 'action']
+  })
+
+  /**
+   * ============================================================
+   * AUTO-GENERATED TEAMMATE (AI AGENT)
+   * ============================================================
+   *
+   * Every plugin automatically gets a default teammate (AI agent) that:
+   * - Is named "<Plugin Name> Expert" (e.g., "Sample Plugin Expert")
+   * - Has access to ALL plugin functions automatically
+   * - Gets a default system prompt (can be customized below)
+   * - Is identified by ID: same as package name (e.g., "@majk/sample-plugin")
+   *
+   * This auto-teammate appears in MAJK's teammate selector and can be
+   * invoked by users to interact with your plugin's capabilities through
+   * natural conversation.
+   *
+   * You can customize the system prompt using .instructions(), or disable
+   * the auto-teammate entirely with .noDefaultTeammate().
+   *
+   * ============================================================
+   */
+  .instructions(`You are an expert assistant for the Sample Plugin. Your role is to help users work with sample data and perform sample actions efficiently.
+
+Your capabilities:
+- Query sample items from the API using getSampleItems
+- Perform sample actions using doSampleAction
+- Access UI debugging logs when needed
+
+When helping users:
+1. Proactively suggest relevant actions based on their requests
+2. Explain what each function does before using it
+3. Present results in a clear, organized format
+4. Guide users through multi-step workflows when appropriate
+
+Remember: This is a template plugin - in production, you would have domain-specific knowledge and capabilities!`)
+
+  /**
+   * ============================================================
+   * CUSTOM TEAMMATES (OPTIONAL)
+   * ============================================================
+   *
+   * In addition to the auto-generated teammate, you can define custom
+   * teammates with specialized roles and limited function access.
+   *
+   * This is useful for:
+   * - Role-based access (e.g., read-only teammates)
+   * - Specialized assistants (e.g., reporting vs. data entry)
+   * - Different expertise levels (e.g., beginner-friendly vs. expert)
+   *
+   * Custom teammates use the `functions` field to specify which
+   * functions they can access. Use simple strings for current plugin
+   * functions, or full objects for cross-plugin capabilities.
+   *
+   * ============================================================
+   */
+  .teamMember([
+    {
+      id: 'sample-viewer',
+      name: 'Sample Viewer (Read-Only)',
+      systemPrompt: 'You are a read-only assistant for viewing sample data. You can query and display information but cannot perform actions or modifications. Help users explore and understand their sample data.',
+      expertise: ['Data Viewing', 'Read-Only Operations', 'Sample Plugin'],
+      skills: {
+        primary: ['Data Query', 'Information Display'],
+        secondary: ['Data Analysis', 'Reporting'],
+        languages: [],
+        frameworks: [],
+        tools: []
+      },
+      personality: {
+        workStyle: 'methodical',
+        codeStyle: 'concise',
+        reviewStyle: 'pragmatic',
+        communicationStyle: 'explanatory'
+      },
+      metadata: {
+        totalTasks: 0,
+        successfulTasks: 0,
+        projectHistory: [],
+        codeStats: {
+          linesWritten: 0,
+          filesModified: 0,
+          testsWritten: 0,
+          reviewsPassed: 0,
+          commitsCreated: 0
+        }
+      },
+      mcpServerIds: [],
+
+      // SIMPLE MODE: Just list function names!
+      // This teammate only has access to query functions, not action functions.
+      // Compare this to the auto-generated teammate which gets ALL functions.
+      functions: [
+        'getSampleItems',  // ✅ Can view data
+        'uiLog'            // ✅ Can log for debugging
+        // ❌ Cannot use 'doSampleAction' - not included!
+      ]
+    }
+  ])
+
+  .build();
+```
+
+## API Reference
+
+### .instructions(text: string)
+
+Customize the auto-generated default teammate's system prompt.
+
+**Parameters**:
+- `text` (string): The system prompt for the teammate
+
+**Returns**: FluentBuilder (chainable)
+
+**Example**:
+```typescript
+.instructions(`You are an expert in X. Your capabilities: ...`)
+```
+
+### .noDefaultTeammate()
+
+Disable automatic default teammate generation.
+
+**Parameters**: None
+
+**Returns**: FluentBuilder (chainable)
+
+**Example**:
+```typescript
+.noDefaultTeammate()
+```
+
+### .teamMember(members: TeamMemberEntity[])
+
+Define custom teammates with specialized roles and function access.
+
+**Parameters**:
+- `members` (TeamMemberEntity[]): Array of teammate definitions
+
+**TeamMemberEntity Structure**:
+```typescript
+{
+  id: string;                    // Unique identifier
+  name: string;                  // Display name
+  systemPrompt: string;          // AI instructions
+  expertise: string[];           // Areas of expertise
+  skills: {
+    primary: string[];
+    secondary: string[];
+    languages: string[];
+    frameworks: string[];
+    tools: string[];
+  };
+  personality: {
+    workStyle: 'methodical' | 'agile' | 'exploratory';
+    codeStyle: 'concise' | 'verbose' | 'documented';
+    reviewStyle: 'pragmatic' | 'thorough' | 'nitpicky';
+    communicationStyle: 'concise' | 'explanatory' | 'socratic';
+  };
+  metadata: {
+    totalTasks: number;
+    successfulTasks: number;
+    projectHistory: any[];
+    codeStats: {
+      linesWritten: number;
+      filesModified: number;
+      testsWritten: number;
+      reviewsPassed: number;
+      commitsCreated: number;
+    };
+  };
+  mcpServerIds: string[];        // MCP servers this teammate can access
+  functions?: Array<string | {   // Functions this teammate can call
+    pluginId: string;
+    serviceName: string;
+    functionName: string;
+  }>;
+}
+```
+
+**Returns**: FluentBuilder (chainable)
+
+**Example**:
+```typescript
+.teamMember([{
+  id: 'my-teammate',
+  name: 'My Teammate',
+  systemPrompt: '...',
+  functions: ['func1', 'func2'],
+  // ... other fields
+}])
+```
+
+## Use Cases
+
+### 1. Read-Only vs Full-Access
+
+Create separate teammates for viewing vs. modifying data:
+
+```typescript
+.teamMember([
+  {
+    id: 'viewer',
+    name: 'Data Viewer',
+    functions: ['getData', 'searchData', 'exportData']
+  },
+  {
+    id: 'editor',
+    name: 'Data Editor',
+    functions: ['getData', 'searchData', 'createData', 'updateData', 'deleteData']
+  }
+])
+```
+
+### 2. Beginner vs Expert
+
+Different interaction styles for different user levels:
+
+```typescript
+.instructions(`You are a beginner-friendly assistant. Always explain concepts clearly and guide users step-by-step.`)
+
+.teamMember([
+  {
+    id: 'expert',
+    name: 'Expert Mode',
+    systemPrompt: 'You are an advanced assistant for power users. Be concise and assume technical knowledge.',
+    functions: ['all', 'advanced', 'functions']
+  }
+])
+```
+
+### 3. Specialized Workflows
+
+Create teammates for specific tasks:
+
+```typescript
+.teamMember([
+  {
+    id: 'reporter',
+    name: 'Report Generator',
+    systemPrompt: 'You specialize in generating reports and analytics.',
+    functions: ['getData', 'aggregateData', 'generateReport', 'exportReport']
+  },
+  {
+    id: 'importer',
+    name: 'Data Importer',
+    systemPrompt: 'You specialize in importing and validating data.',
+    functions: ['validateData', 'importData', 'verifyImport']
+  }
+])
+```
+
+### 4. Cross-Plugin Orchestration
+
+Create a coordinator that uses multiple plugins:
+
+```typescript
+.teamMember([
+  {
+    id: 'workflow-coordinator',
+    name: 'Workflow Coordinator',
+    systemPrompt: 'You orchestrate complex workflows across multiple systems.',
+    functions: [
+      'triggerWorkflow',  // Current plugin
+      { pluginId: '@majk/tasks', serviceName: '@majk/tasks:all', functionName: 'createTask' },
+      { pluginId: '@majk/calendar', serviceName: '@majk/calendar:all', functionName: 'scheduleEvent' },
+      { pluginId: '@majk/notifications', serviceName: '@majk/notifications:all', functionName: 'notify' }
+    ]
+  }
+])
+```
+
+## Best Practices
+
+1. **Clear Role Definition**: Each teammate should have a clear, focused purpose
+2. **Appropriate Function Access**: Only grant access to functions needed for the role
+3. **Detailed System Prompts**: Provide clear instructions about capabilities and behavior
+4. **Consistent Naming**: Use descriptive names that indicate the teammate's role
+5. **Test Instructions**: Verify teammates behave as expected through conversation
+6. **Document Functions**: Ensure function descriptions are clear so teammates understand how to use them
+
+## Troubleshooting
+
+### Teammate Not Appearing
+
+**Problem**: Your custom teammate doesn't show up in MAJK.
+
+**Solution**:
+- Ensure `id` is unique
+- Verify all required fields are present
+- Check build logs for validation errors
+
+### Functions Not Working
+
+**Problem**: Teammate can't call expected functions.
+
+**Solution**:
+- Verify function names in `functions` array match actual function definitions
+- Check that functions are defined BEFORE `.teamMember()` call
+- For cross-plugin functions, ensure `pluginId` and `serviceName` are correct
+
+### Auto-Generated Teammate Has Wrong Name
+
+**Problem**: Default teammate name doesn't match expectations.
+
+**Solution**: The name is `"<Plugin Name> Expert"` based on the `name` parameter in `definePlugin()`. To change it, update the plugin name or use `.noDefaultTeammate()` and create a custom one.
+
+## Related Documentation
+
+- [Functions](./FUNCTIONS.md) - Define functions that teammates can call
+- [Services](./SERVICES.md) - Group functions into services
+- [Context API](./CONTEXT.md) - PluginContext available to functions
+- [Testing](./TESTING.md) - Test teammates and function calls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majkapp/plugin-kit",
-  "version": "3.5.3",
+  "version": "3.5.5",
   "description": "Pure plugin definition library for MAJK - outputs plugin definitions, not HTTP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",