lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/template/AGENT_CONFIGURATION.md

@@ -1,251 +0,0 @@
-# Agent Configuration Guide
-
-## Overview
-
-There are two ways to configure your Lua agent:
-
-1. **LuaAgent (Recommended)** - Unified, simple approach
-2. **Individual Components (Legacy)** - Separate exports for each component
-
-Both approaches are fully supported and backward compatible.
-
-## Approach 1: LuaAgent (Recommended)
-
-The `LuaAgent` provides a simplified, unified way to configure your agent. All components (skills, webhooks, jobs, processors) are defined in one place.
-
-### Benefits
-
-- **Simpler**: One object contains everything
-- **Clearer**: Easy to see all components at a glance
-- **Persona Sync**: Agent persona automatically syncs with `lua.skill.yaml`
-- **Better Organization**: Natural hierarchy of components
-- **Less Boilerplate**: No need to export multiple separate items
-
-### Example
-
-```typescript
-import { LuaAgent, LuaSkill } from 'lua-cli';
-import { weatherSkill } from './skills/weather';
-import { userSkill } from './skills/user';
-import { healthCheckJob } from './jobs/health-check';
-import { userWebhook } from './webhooks/user';
-
-// Define your agent with all components in one place
-export const agent = new LuaAgent({
-  name: 'my-assistant',
-  
-  // Agent personality and behavior
-  persona: `You are a helpful assistant that can provide weather information
-            and manage user accounts. Be friendly and concise.`,
-  
-  // Welcome message shown to new users
-  welcomeMessage: 'Hello! How can I help you today?',
-  
-  // Skills - collections of tools
-  skills: [weatherSkill, userSkill],
-  
-  // Webhooks - HTTP endpoints for external events
-  webhooks: [userWebhook],
-  
-  // Jobs - scheduled tasks
-  jobs: [healthCheckJob],
-  
-  // Preprocessors - modify messages before they reach the agent
-  preProcessors: [],
-  
-  // Postprocessors - modify responses before they reach the user
-  postProcessors: []
-});
-```
-
-### File Structure
-
-When using `LuaAgent`, organize your code like this:
-
-```
-src/
-├── index.ts                    # Main agent configuration
-├── skills/
-│   ├── weather-skill.ts       # Weather skill with tools
-│   └── user-skill.ts          # User management skill
-├── tools/
-│   ├── WeatherTool.ts         # Individual tool classes
-│   └── UserTool.ts
-├── webhooks/
-│   └── UserWebhook.ts         # Webhook handlers
-├── jobs/
-│   └── HealthCheckJob.ts      # Scheduled jobs
-└── processors/
-    ├── MessageFilter.ts       # Preprocessors
-    └── ResponseFormatter.ts   # Postprocessors
-```
-
-### Compilation
-
-When you run `lua compile`, the compiler will:
-
-1. Detect the `LuaAgent` in `index.ts`
-2. Extract the agent's persona and welcome message
-3. Sync them with `lua.skill.yaml`
-4. Extract all skills, webhooks, jobs, and processors
-5. Bundle and deploy everything
-
-Output during compilation:
-```
-✨ Found LuaAgent: my-assistant
-   Using new unified agent configuration approach
-✅ Synced agent persona to lua.skill.yaml
-📦 Agent contains: 2 skill(s), 1 webhook(s), 1 job(s), 0 preprocessor(s), 0 postprocessor(s)
-```
-
-## Approach 2: Individual Components (Legacy)
-
-The legacy approach exports each component type separately. This is still fully supported for backward compatibility.
-
-### Example
-
-```typescript
-import { LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
-
-// Export skills individually
-export const weatherSkill = new LuaSkill({
-  name: 'weather-skill',
-  version: '1.0.0',
-  description: 'Weather information',
-  context: 'Provides current weather data',
-  tools: [new GetWeatherTool()]
-});
-
-export const userSkill = new LuaSkill({
-  name: 'user-skill',
-  version: '1.0.0',
-  description: 'User management',
-  context: 'Manages user accounts',
-  tools: [new GetUserTool()]
-});
-
-// Export jobs individually
-export const healthCheckJob = new LuaJob({
-  name: 'health-check',
-  version: '1.0.0',
-  description: 'System health check',
-  context: 'Monitors system status',
-  schedule: { type: 'interval', seconds: 300 },
-  execute: async () => {
-    return { status: 'healthy' };
-  }
-});
-
-// Export webhooks individually
-export const userWebhook = new LuaWebhook({
-  name: 'user-webhook',
-  version: '1.0.0',
-  description: 'User event handler',
-  context: 'Processes user events',
-  execute: async ({ body }) => {
-    return { received: true };
-  }
-});
-```
-
-### Compilation
-
-When you run `lua compile`, the compiler will:
-
-1. Scan for individual `LuaSkill`, `LuaJob`, `LuaWebhook`, etc.
-2. Extract each component separately
-3. Bundle and deploy everything
-
-Output during compilation:
-```
-ℹ️  No LuaAgent found, using legacy detection for individual components
-📦 Found 2 skill(s)...
-📦 Found 1 webhook(s)...
-📦 Found 1 job(s)...
-```
-
-## Comparison
-
-| Feature | LuaAgent | Individual Components |
-|---------|----------|----------------------|
-| **Configuration Style** | Single unified object | Multiple separate exports |
-| **Persona Management** | Auto-synced with YAML | Manual YAML editing |
-| **Code Organization** | Hierarchical | Flat |
-| **Ease of Use** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
-| **Backward Compatible** | ✅ | ✅ |
-| **Use Case** | New projects, simple setup | Existing projects, gradual migration |
-
-## When to Use Each Approach
-
-### Use LuaAgent when:
-
-- ✅ Starting a new project
-- ✅ You want a simple, unified configuration
-- ✅ You want automatic persona synchronization
-- ✅ You prefer a clear hierarchy of components
-
-### Use Individual Components when:
-
-- ✅ Maintaining an existing project
-- ✅ Gradually migrating to the new approach
-- ✅ You prefer more granular control
-- ✅ Working with a legacy codebase
-
-## Migration Guide
-
-If you have an existing project using individual components, you can migrate to `LuaAgent` gradually:
-
-### Step 1: Keep Your Existing Files
-
-Don't change your skill/webhook/job definitions. They can stay in separate files.
-
-### Step 2: Create LuaAgent
-
-In your `index.ts`, import all components and create a `LuaAgent`:
-
-```typescript
-// Import existing components
-import { weatherSkill } from './skills/weather';
-import { userSkill } from './skills/user';
-import { healthCheckJob } from './jobs/health-check';
-
-// Create LuaAgent that references them
-export const agent = new LuaAgent({
-  name: 'my-assistant',
-  persona: 'Your agent persona here',
-  skills: [weatherSkill, userSkill],
-  jobs: [healthCheckJob]
-});
-```
-
-### Step 3: Remove Individual Exports
-
-Remove any `export` keywords from your skill/webhook/job files, or keep them for testing.
-
-### Step 4: Test
-
-Run `lua compile` to verify everything works:
-
-```bash
-lua compile
-```
-
-You should see:
-```
-✨ Found LuaAgent: my-assistant
-```
-
-## Examples
-
-See the following files for complete examples:
-
-- `src/index-agent-example.ts` - LuaAgent approach (recommended)
-- `src/index.ts` - Individual components approach (legacy)
-
-## Questions?
-
-- Check the main README.md for more information
-- See QUICKSTART.md for getting started
-- View WEBHOOK_JOB_EXAMPLES.md for webhook and job examples
-- Read COMPLEX_JOB_EXAMPLES.md for advanced job patterns
-