# Conversation History Templates

This directory contains Handlebars templates for formatting conversation history in agent prompts.

## Quick Start

### Option 1: Use Default Helper (Recommended)

Simply use the `formatConversation` helper in your agent's system prompt:

```yaml
agents:
  - id: "my_agent"
    inline:
      system_prompt: |
        You are a helpful assistant.

        {{{formatConversation messages platform}}}

        Current task: ...
```

This will automatically load and use `conversation-history-default.hbs`.

### Option 2: Custom Template via Documents

Define a custom template in your `agents.yaml`:

```yaml
documents:
  my-conversation-format: |
    {{#if messages}}
    📜 Chat History ({{length messages}} messages):

    {{#each messages}}
    {{#if isAssistant}}🤖{{else}}👤{{/if}} {{{truncate text 300}}}
    {{/each}}
    {{/if}}

agents:
  - id: "my_agent"
    inline:
      system_prompt: |
        You are a helpful assistant.

        {{{documents.my-conversation-format.content}}}

        Current task: ...
```

### Option 3: Fully Custom (Advanced)

Use raw Handlebars syntax directly in your system prompt:

```yaml
system_prompt: |
  You are a helpful assistant.

  {{#if messages}}
  Previous conversation:
  {{#each messages}}
  {{#if metadata.slack.user_profile}}
  **{{metadata.slack.user_profile.display_name}}**: {{{text}}}
  {{else if isAssistant}}
  **Assistant**: {{{text}}}
  {{else}}
  **User**: {{{text}}}
  {{/if}}
  {{/each}}
  {{/if}}
```

## Template Files

### conversation-history-default.hbs

Default template used by `formatConversation` helper. **You can edit this file** to change the default formatting for all agents using the helper.

Features:
- Shows user display names from Slack metadata
- Truncates long messages to 500 chars
- Platform-specific formatting (Slack vs CLI)

### conversation-history-custom.md

Example template showing advanced customization with emojis, different truncation lengths, and custom metadata usage.

## Available Variables

When rendering conversation templates, you have access to:

- `messages` - Array of message objects
- `platform` - 'slack' or 'cli'

### Message Object Fields

Each message in the `messages` array has:

- `text` - Message content
- `isAssistant` - `true` if from bot, `false` if from user
- `metadata.slack` - Slack-specific metadata (if platform is 'slack')
  - `user_id` - Slack user ID (e.g., "U123456")
  - `username` - Slack username (e.g., "john_doe")
  - `user_profile.display_name` - Display name (e.g., "John Doe")
  - `user_profile.real_name` - Real name
  - `user_profile.image_72` - Profile image URL
  - `bot_id` - Bot ID (if message is from bot)
  - `bot_profile.name` - Bot name
  - `bot_profile.app_id` - App ID

## Available Handlebars Helpers

- `{{length array}}` - Get length of array/string
- `{{{truncate text 500}}}` - Truncate with "(...+N chars)" indicator
- `{{#if (eq a b)}}` - Equality check
- `{{#if (ne a b)}}` - Not equal check
- `{{#if (and a b)}}` - Logical AND
- `{{#if (or a b)}}` - Logical OR
- `{{{json object}}}` - JSON stringify
- `{{{formatConversation messages platform}}}` - Format with default template

## Maintenance

To update the default conversation format:

1. Edit `conversation-history-default.hbs`
2. No rebuild needed - changes take effect immediately
3. Test with: `codecrew q "@your_agent test message"`

## Examples

### Minimal Format

```handlebars
{{#if messages}}
Recent messages:
{{#each messages}}
- {{{truncate text 200}}}
{{/each}}
{{/if}}
```

### With Timestamps (if available)

```handlebars
{{#if messages}}
{{#each messages}}
[{{timestamp}}] {{#if isAssistant}}Bot{{else}}User{{/if}}: {{{text}}}
{{/each}}
{{/if}}
```

### Slack-Specific Rich Format

```handlebars
{{#if (eq platform "slack")}}
💬 Slack Thread ({{length messages}} messages):

{{#each messages}}
{{#if metadata.slack.user_profile}}
👤 **{{metadata.slack.user_profile.display_name}}** (@{{metadata.slack.username}})
{{else if metadata.slack.bot_profile}}
🤖 **{{metadata.slack.bot_profile.name}}**
{{else}}
{{#if isAssistant}}🤖 Assistant{{else}}👤 User{{/if}}
{{/if}}

💬 {{{truncate text 400}}}

---
{{/each}}
{{/if}}
```