@majkapp/plugin-kit 3.5.2 → 3.5.4

package/bin/promptable-cli.js

@@ -58,6 +58,12 @@ cli.addCommand('--services',
   { description: 'Organize functions by service' }
 );
 
+// Teammates
+cli.addCommand('--teammates',
+  cli.createFullDocCommand('TEAMMATES.md'),
+  { description: 'AI teammates and agents' }
+);
+
 // Lifecycle hooks
 cli.addCommand('--lifecycle',
   cli.createFullDocCommand('LIFECYCLE.md'),

package/dist/generator/cli.js

@@ -171,6 +171,7 @@ commander_1.program
     .option('--llm:hooks', 'Show generated hooks documentation')
     .option('--llm:context', 'Show context API documentation')
     .option('--llm:services', 'Show service grouping documentation')
+    .option('--llm:teammates', 'Show AI teammates documentation')
     .option('--llm:lifecycle', 'Show lifecycle hooks documentation')
     .option('--llm:testing', 'Show testing guide')
     .option('--llm:config', 'Show project configuration guide')

package/dist/plugin-kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-kit.d.ts","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin-kit.d.ts","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EAGb,eAAe,EACf,QAAQ,EACR,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EAEb,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EAGjB,sBAAsB,EAStB,kBAAkB,EAElB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAm5BjB;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,EAAE,SAAS,MAAM;IAC/C;;;;OAIG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhG;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAExD;;;;OAIG;IACH,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnG,uEAAuE;IACvE,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAE1E,iEAAiE;IACjE,UAAU,IAAI,aAAa,CAAC,EAAE,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,MAAM;IAC9C,mDAAmD;IACnD,MAAM,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE7G,0CAA0C;IAC1C,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IAE/C,iDAAiD;IACjD,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEjD,0CAA0C;IAC1C,EAAE,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE5B,yBAAyB;IACzB,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAE3C,yBAAyB;IACzB,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAEzC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC,+DAA+D;IAC/D,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,MAAM,EAAE,UAAU,CAAC;QACnB,OAAO,EAAE,eAAe,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,GACA,IAAI,CAAC;IAER,+CAA+C;IAC/C,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,MAAM,EAAE,UAAU,CAAC;QACnB,OAAO,EAAE,mBAAmB,CAAC;KAC9B,GACA,IAAI,CAAC;IAER;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC;IAEhC,kCAAkC;IAClC,cAAc,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAErD,iBAAiB;IACjB,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAE/D,oEAAoE;IACpE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEtD,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IAE5C,+DAA+D;IAC/D,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAE9C,oFAAoF;IACpF,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC;IAElF,yEAAyE;IACzE,eAAe,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,eAAe,EAAE,GAAG,IAAI,CAAC;IAEnE,0EAA0E;IAC1E,sBAAsB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAE3E,0BAA0B;IAC1B,cAAc,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE7C,yEAAyE;IACzE,kBAAkB,CAAC,GAAG,EAAE;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;QAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,mBAAmB,EAAE,UAAU,CAAC;QAChC,WAAW,CAAC,EAAE,UAAU,CAAC;QACzB,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;QAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,kBAAkB,CAAC;KACjC,GAAG,IAAI,CAAC;IAET,wBAAwB;IACxB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAAC;IAEzC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IAEjC,2EAA2E;IAC3E,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE;QACnC,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC;YACb,WAAW,EAAE,MAAM,CAAC;YACpB,OAAO,EAAE,MAAM,CAAC;YAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;SACjB,CAAC;QACF,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;IAEvB,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElG,0BAA0B;IAC1B,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;;OAIG;IACH,eAAe,IAAI,IAAI,CAAC;IAExB;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,iBAAiB,IAAI,IAAI,CAAC;IAE1B,uBAAuB;IACvB,KAAK,IAAI,eAAe,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAClD,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,EAAE,CAAC,CAuxCnB"}

package/dist/plugin-kit.js

@@ -1326,7 +1326,8 @@ function definePlugin(id, name, version) {
             }
             // Auto-generate default teammate unless explicitly disabled
             if (_autoDefaultTeammate && packageName && _functionRegistry.functions.size > 0) {
-                const teammateId = generateTeammateId(id);
+                // Use package name as teammate ID (e.g., "@majk/task-manager-sample")
+                const teammateId = packageName;
                 const teammateName = generateTeammateName(name);
                 // Check if a teammate with this ID already exists
                 const existingTeammate = _entities.find(e => e.entityType === 'teamMember' &&

package/docs/FULL.md

@@ -11,10 +11,11 @@ Comprehensive reference for @majkapp/plugin-kit covering all features and patter
 5. [Generated Hooks](#generated-hooks)
 6. [Context API](#context-api)
 7. [Services](#services)
-8. [Lifecycle](#lifecycle)
-9. [Testing](#testing)
-10. [Configuration](#configuration)
-11. [Best Practices](#best-practices)
+8. [Teammates](#teammates)
+9. [Lifecycle](#lifecycle)
+10. [Testing](#testing)
+11. [Configuration](#configuration)
+12. [Best Practices](#best-practices)
 
 ## Quick Start
 
@@ -379,6 +380,91 @@ Group related functions together.
 .endService()
 ```
 
+## Teammates
+
+Define AI agents that users can interact with.
+
+### Auto-Generated Default Teammate
+
+Every plugin automatically gets a default teammate with access to ALL functions.
+
+**Default Behavior**:
+- Name: `"<Plugin Name> Expert"`
+- ID: Same as package name (e.g., `"@majk/my-plugin"`)
+- Functions: ALL plugin functions
+- System Prompt: Generic (customizable)
+
+### Custom Instructions
+
+```typescript
+.instructions(`You are an expert assistant for My Plugin.
+
+Your capabilities:
+- Function 1 using func1
+- Function 2 using func2
+
+When helping users:
+1. Explain what you're doing
+2. Present results clearly
+3. Suggest next steps`)
+```
+
+### Disable Default Teammate
+
+```typescript
+.noDefaultTeammate()
+```
+
+### Custom Teammates
+
+```typescript
+.teamMember([
+  {
+    id: 'viewer',
+    name: 'Viewer (Read-Only)',
+    systemPrompt: 'You are a read-only assistant...',
+    expertise: ['Data Viewing'],
+    skills: {
+      primary: ['Query'],
+      secondary: [],
+      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: [],
+    functions: [
+      'getData',       // Simple: current plugin
+      'searchData',
+      {                // Advanced: cross-plugin
+        pluginId: '@other/plugin',
+        serviceName: '@other/plugin:all',
+        functionName: 'otherFunc'
+      }
+    ]
+  }
+])
+```
+
+See `npx @majkapp/plugin-kit --teammates` for complete guide.
+
 ## Lifecycle
 
 Initialize and clean up resources.

package/docs/INDEX.md

@@ -640,6 +640,7 @@ Run `npx @majkapp/plugin-kit --screens` - Screen configuration details
 Run `npx @majkapp/plugin-kit --hooks` - Generated hooks reference
 Run `npx @majkapp/plugin-kit --context` - ctx.majk and ctx.logger APIs
 Run `npx @majkapp/plugin-kit --services` - Service grouping patterns
+Run `npx @majkapp/plugin-kit --teammates` - AI teammates and agents
 Run `npx @majkapp/plugin-kit --lifecycle` - onReady and cleanup
 Run `npx @majkapp/plugin-kit --testing` - Complete testing guide
 Run `npx @majkapp/plugin-kit --config` - vite.config.js and project setup

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.2",
+  "version": "3.5.4",
   "description": "Pure plugin definition library for MAJK - outputs plugin definitions, not HTTP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",