> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Workflows

> Best practices for developing, testing, and deploying skills

## Development Lifecycle

<Steps>
  <Step title="Configure Environment">
    Set up environment variables

    ```bash theme={null}
    lua env
    ```

    Add API keys and configuration for sandbox
  </Step>

  <Step title="Configure Persona">
    Define your agent's personality

    ```bash theme={null}
    lua persona
    ```

    Edit persona in sandbox mode
  </Step>

  <Step title="Local Development">
    Build and test your skills locally

    ```bash theme={null}
    lua chat
    ```

    Use sandbox mode for testing
  </Step>

  <Step title="Testing">
    Test conversational flows and individual tools

    ```bash theme={null}
    lua chat  # Primary testing
    lua test  # Optional: Test specific tools
    ```
  </Step>

  <Step title="Push to Server">
    Upload your skill version to the server

    ```bash theme={null}
    lua push
    ```
  </Step>

  <Step title="Sandbox Testing">
    Test in sandbox environment before production

    ```bash theme={null}
    lua chat
    ```

    Choose sandbox mode when prompted
  </Step>

  <Step title="Deploy to Production">
    Make your skill available to all users

    ```bash theme={null}
    lua deploy
    ```
  </Step>
</Steps>

## Local Development Workflow

### Starting Development

Start by syncing with the server to get any remote changes:

```bash theme={null}
# Check for drift between server and local code
lua sync

# Test individual tools
lua test

# Test conversational flows
lua chat
```

**lua test** - Test tools one at a time with specific inputs

**lua chat** - Interactive conversation testing in sandbox or production

### The Development Loop

<Tabs>
  <Tab title="Edit">
    Edit files in `src/tools/`:

    ```typescript theme={null}
    // src/tools/MyTool.ts
    export default class MyTool implements LuaTool {
      name = "my_tool";
      description = "Updated description";
      
      async execute(input: any) {
        // Your changes here
      }
    }
    ```
  </Tab>

  <Tab title="Test Tools">
    Test individual tools:

    ```bash theme={null}
    lua test
    ```

    * Select tool from list
    * Enter test inputs
    * Verify output
  </Tab>

  <Tab title="Test Chat">
    Test conversational flows:

    ```bash theme={null}
    lua chat
    ```

    * Choose sandbox mode
    * Chat naturally with agent
    * Verify tool selection and execution
  </Tab>

  <Tab title="Iterate">
    Repeat: Edit → Test → Refine

    Test until satisfied with results
  </Tab>
</Tabs>

### Testing Features

<CardGroup cols={2}>
  <Card title="Tool Testing" icon="flask">
    Test individual tools with specific inputs
  </Card>

  <Card title="Chat Testing" icon="comments">
    Test conversational flows and tool selection
  </Card>

  <Card title="Sandbox Mode" icon="sandbox">
    Test with local changes before deploying
  </Card>

  <Card title="Production Validation" icon="check">
    Verify deployed changes work correctly
  </Card>
</CardGroup>

## Testing Workflow

### Interactive Tool Testing

Test individual tools with specific inputs:

```bash theme={null}
lua test
```

<Steps>
  <Step title="Select Tool">
    Choose from list of available tools
  </Step>

  <Step title="Enter Inputs">
    Provide values based on tool's schema
  </Step>

  <Step title="View Results">
    See execution results or errors
  </Step>

  <Step title="Iterate">
    Fix issues and test again
  </Step>
</Steps>

### Conversational Testing

Test how the AI uses your tools in natural conversation:

```bash theme={null}
lua chat
```

Select **Sandbox mode** to test with your local changes.

**Test Scenarios:**

<AccordionGroup>
  <Accordion title="Happy Path">
    Test the ideal user journey

    * "Show me products"
    * "Add laptop to cart"
    * "Checkout"
  </Accordion>

  <Accordion title="Edge Cases">
    Test unusual but valid inputs

    * Empty results
    * Maximum values
    * Optional parameters
  </Accordion>

  <Accordion title="Error Handling">
    Test invalid inputs

    * Missing required fields
    * Invalid data types
    * Out of range values
  </Accordion>

  <Accordion title="Multi-Step Flows">
    Test complex workflows

    * Create → Add → Update → Delete
    * Search → Select → Checkout
  </Accordion>
</AccordionGroup>

## Version Management

### Semantic Versioning

Use semantic versioning: `MAJOR.MINOR.PATCH`

```yaml theme={null}
# lua.skill.yaml (version is the ONLY field you should manually edit)
skills:
  - name: my-skill
    version: 1.2.3
```

<Note>
  The `lua.skill.yaml` file is auto-managed by the CLI. The **version number** is the only field you should manually edit when preparing a new release. All other fields are managed automatically.
</Note>

**When to increment:**

<Tabs>
  <Tab title="PATCH (1.2.3 → 1.2.4)">
    Bug fixes and minor improvements

    * Fixed error handling
    * Updated descriptions
    * Performance improvements
  </Tab>

  <Tab title="MINOR (1.2.3 → 1.3.0)">
    New features, backward compatible

    * Added new tool
    * New optional parameters
    * Enhanced functionality
  </Tab>

  <Tab title="MAJOR (1.2.3 → 2.0.0)">
    Breaking changes

    * Removed tool
    * Changed required parameters
    * Renamed tools
  </Tab>
</Tabs>

### Pushing Versions

```bash theme={null}
# Increment version in lua.skill.yaml (only field you should edit):
# skills:
#   - name: my-skill
#     version: 1.1.0

# Push to server
lua push
```

Each push creates a new version that can be deployed independently.

## Advanced Agent Features

Beyond skills and tools, lua-cli supports webhooks, jobs, and message processing:

### LuaAgent Configuration

```typescript theme={null}
import { LuaAgent, LuaSkill, LuaWebhook, LuaJob, PreProcessor, PostProcessor } from 'lua-cli';

export const agent = new LuaAgent({
  name: "my-agent",
  persona: "You are a helpful assistant...",
  
  // Skills with tools
  skills: [skill1, skill2],
  
  // HTTP endpoints for external events
  webhooks: [stripeWebhook, shopifyWebhook],
  
  // Scheduled tasks
  jobs: [dailyReportJob, cleanupJob],
  
  // Message filtering before agent
  preProcessors: [profanityFilter, rateLimiter],
  
  // Response formatting after agent
  postProcessors: [addDisclaimer, addBranding]
});
```

### Webhooks

Receive events from external services:

```typescript theme={null}
import { LuaWebhook } from 'lua-cli';

const paymentWebhook = new LuaWebhook({
  name: 'payment-webhook',
  execute: async (event) => {
    if (event.type === 'payment.succeeded') {
      // Handle payment confirmation
    }
  }
});
```

**Test webhooks:**

```bash theme={null}
lua test
# Select: Webhook → payment-webhook
```

### Jobs

Schedule automated tasks:

```typescript theme={null}
import { LuaJob } from 'lua-cli';

const dailyReportJob = new LuaJob({
  name: 'daily-report',
  schedule: {
    type: 'cron',
    pattern: '0 9 * * *'  // Every day at 9 AM
  },
  execute: async (jobInstance) => {
    const user = await jobInstance.user();
    await user.send([{
      type: 'text',
      text: 'Your daily report is ready!'
    }]);
  }
});
```

### PreProcessors

Filter messages before they reach your agent:

```typescript theme={null}
import { PreProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Filter inappropriate content',
  execute: async (user, messages, channel) => {
    const text = messages.map(m => m.type === 'text' ? m.text : '').join(' ');
    if (containsProfanity(text)) {
      return {
        action: 'block',
        response: "Please keep the conversation respectful."
      };
    }
    return { action: 'proceed' };
  }
});
```

### PostProcessors

Format responses after agent generation:

```typescript theme={null}
import { PostProcessor } from 'lua-cli';

const addDisclaimer = new PostProcessor({
  name: 'add-disclaimer',
  description: 'Add legal disclaimer to responses',
  execute: async (user, message, response, channel) => {
    return {
      modifiedResponse: response + "\n\n_This is AI-generated content._"
    };
  }
});
```

**Learn more:**

* [LuaAgent API](/api/luaagent)
* [LuaWebhook API](/api/luawebhook)
* [LuaJob API](/api/luajob)
* [PreProcessor API](/api/preprocessor)
* [PostProcessor API](/api/postprocessor)

## Deployment Workflow

### Sandbox Testing

Before deploying to production, test in sandbox:

```bash theme={null}
# Push latest version
lua push

# Test in sandbox
lua chat

# Select sandbox mode when prompted
# Verify everything works
```

### Deploying to Production

When ready, deploy to all users:

```bash theme={null}
lua deploy
```

<Steps>
  <Step title="Select Version">
    Choose which version to deploy from list
  </Step>

  <Step title="Confirm">
    Confirm the deployment (shows warning)
  </Step>

  <Step title="Deploy">
    Version is deployed to production
  </Step>

  <Step title="Verify">
    Test with real users or in production chat
  </Step>
</Steps>

<Warning>
  **Deployment is immediate!** All users will get the new version right away.
</Warning>

## Best Practices

### Development

<Tabs>
  <Tab title="Start Simple">
    Build one tool at a time

    * Create basic version
    * Test thoroughly
    * Add complexity gradually
  </Tab>

  <Tab title="Test Iteratively">
    Test changes quickly

    * Use `lua test` for tool logic
    * Use `lua chat` for conversations
    * Iterate based on results
  </Tab>

  <Tab title="Test Edge Cases">
    Don't just test happy paths

    * Invalid inputs
    * Empty results
    * Error conditions
  </Tab>
</Tabs>

### Version Control

<CodeGroup>
  ```bash .gitignore theme={null}
  # Always ignore
  .env
  .env.local
  node_modules/
  dist/
  .lua/

  # Keep these
  .env.example
  lua.skill.yaml
  src/
  ```

  ```bash Commit Messages theme={null}
  # Good commit messages
  git commit -m "feat: add search functionality to products"
  git commit -m "fix: handle empty basket in checkout"
  git commit -m "docs: update tool descriptions"
  ```
</CodeGroup>

### Testing

<AccordionGroup>
  <Accordion title="Test Before Pushing">
    Always test locally before pushing:

    ```bash theme={null}
    lua test  # Test tools
    lua chat  # Test conversations (sandbox mode)
    lua push  # Then push
    ```
  </Accordion>

  <Accordion title="Test in Sandbox">
    Test pushed versions in sandbox before deploying:

    ```bash theme={null}
    lua push
    lua chat  # Choose sandbox mode
    # If good, then deploy
    lua deploy
    ```
  </Accordion>

  <Accordion title="Document Test Cases">
    Keep a list of test scenarios:

    * Happy path flows
    * Edge cases to verify
    * Known issues to watch for
  </Accordion>
</AccordionGroup>

### Deployment

<Warning>
  **Pre-Deployment Checklist:**

  * ✅ Synced with server: `lua sync`
  * ✅ Tested all tools with `lua test`
  * ✅ Tested conversational flows with `lua chat`
  * ✅ Updated version number
  * ✅ Updated tool descriptions
  * ✅ Checked error messages
  * ✅ Tested in sandbox mode
  * ✅ Verified environment variables
</Warning>

## Common Workflows

### Quick Fix Workflow

```bash theme={null}
# 1. Make the fix
vim src/tools/MyTool.ts

# 2. Test locally
lua test

# 3. Push and deploy
lua push
lua deploy
```

### Feature Development Workflow

```bash theme={null}
# 1. Create feature branch
git checkout -b feature/new-tool

# 2. Develop and test
lua test  # Test tool logic
lua chat  # Test in conversation

# 3. Test thoroughly
lua test  # All tools
lua chat  # All scenarios

# 4. Commit changes
git add .
git commit -m "feat: add new tool"

# 5. Push to server
lua push

# 6. Merge to main
git checkout main
git merge feature/new-tool

# 7. Deploy to production
lua deploy
```

### Multi-Developer Workflow

```bash theme={null}
# Developer 1: Working on Skill A
cd skill-a
lua sync  # Get any changes from teammates
lua test
lua chat  # Independent sandbox

# Developer 2: Working on Skill B
cd skill-b
lua sync  # Get any changes from teammates
lua test
lua chat  # Independent sandbox

# Each developer has independent sandbox
# Sync helps prevent conflicts when deploying
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Chat not working">
    **Problem**: Cannot start chat session

    **Solutions**:

    1. Run `lua auth configure` to set up API key
    2. Ensure `lua.skill.yaml` exists (run `lua init`)
    3. Deploy skills with `lua push` before using sandbox
    4. Check network connection
  </Accordion>

  <Accordion title="Skills not appearing in sandbox">
    **Problem**: Local changes not reflected

    **Solutions**:

    1. Ensure you selected "Sandbox" mode
    2. Check compilation succeeded
    3. Verify skills pushed to sandbox successfully
    4. Try running `lua push` first
  </Accordion>

  <Accordion title="Deploy showing old version">
    **Problem**: Deployed but still seeing old behavior

    **Solutions**:

    1. Verify correct version was deployed
    2. Check `lua.skill.yaml` version number
    3. Test in production mode with `lua chat`
    4. Check if deploy actually succeeded
  </Accordion>

  <Accordion title="Can't push - version exists">
    **Problem**: Version already pushed to server

    **Solution**: Increment version number:

    ```yaml theme={null}
    skills:
      - name: my-skill
        version: 1.0.1  # Increment this
    ```
  </Accordion>

  <Accordion title="Drift detected during compile">
    **Problem**: Server has different persona/name than local code

    **Solutions**:

    1. Run `lua sync` to see the diff and choose action
    2. Use `lua sync --accept` to auto-update from server
    3. Use `lua sync --push` to push local changes to server

    **Note**: By default, `lua compile` does NOT check for drift. Use `lua compile --sync` to enable drift detection.

    This happens when someone updated the agent from the admin dashboard.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="AI Agent Building Guide" icon="robot" href="/ai-guide">
    Complete workflow for AI IDEs (Cursor, Windsurf, Copilot)
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete command documentation
  </Card>

  <Card title="Build Your First Skill" icon="hammer" href="/getting-started/first-skill">
    Follow a complete tutorial
  </Card>

  <Card title="Non-Interactive Mode" icon="code" href="/cli/non-interactive-mode">
    Automate commands for CI/CD and scripting
  </Card>
</CardGroup>