---
name: kugetsu-chat
description: Chat Agent skill for kugetsu Phase 3. Handles Telegram routing, PM delegation, and notification coordination.
license: MIT
compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
metadata:
  author: shoko
  version: "1.0"
---

# kugetsu-chat - Chat Agent for Kugetsu Phase 3

Handles natural language routing and PM Agent coordination for Telegram interface.

## Overview

The Chat Agent is Hermes configured with a specific SOUL.md and skills that enable:
- Receiving Telegram messages
- Intent classification (small talk, task, status, clarification)
- Routing to PM Agent when needed
- Notification coordination

## Architecture

```
User (Telegram) → Hermes (Chat Agent)
    ├── Small talk → Respond directly
    ├── Task request → Route to PM Agent
    ├── Status query → Route to PM Agent
    └── Clarification → Ask via Hermes → User
```

## Intent Classification

### Rules

| Intent | Examples | Response |
|--------|----------|----------|
| **Small talk** | "hi", "thanks", "how are you" | Respond directly, clear context if unrelated |
| **Task request** | "fix issue #5", "create test for #14" | Route to PM Agent |
| **Status query** | "status?", "what's on #7?" | Route to PM Agent |
| **Mode change** | "pm notify", "pm silent" | Route to PM Agent |
| **Clarification** | "which project?", "what repo?" | Ask user via Hermes |

### Routing Logic

```
1. Receive message
2. Classify intent:
   - If small talk → respond directly
   - If task/status/mode → delegate to PM Agent
3. If PM response needed → send to PM Agent
4. Return PM response to user
```

## PM Agent Delegation

### How Hermes Delegates to PM Agent

Hermes uses `terminal()` to interact with the PM Agent opencode session:

```bash
# Get PM agent session ID
PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('pm_agent', ''))")

# Continue PM agent session with task
opencode run --continue --session "$PM_SESSION" "User request: $MESSAGE"
```

### PM Agent Modes

| Mode | Behavior | Storage |
|------|----------|---------|
| **notify** (default) | PM sends completion notifications | Session context |
| **silent** | PM works quietly, no notifications | Session context |

Toggle with: "pm notify" / "pm silent"

## Notification Flow

```
PM Agent completes task
    → Checks mode
    → If notify → Routes via Hermes → Telegram message to user
    → If silent → No notification
```

## Session Context

### Chat Agent Context
- Short-term conversation memory
- User preferences
- Last routing decision

### PM Agent Context
- Managed repositories
- Active tasks
- Notification preferences
- Long-term project memory

## Skills

### kugetsu-chat-skill

Defines Chat Agent behavior:
- Intent classification prompt
- Routing rules
- Response formatting

### kugetsu-pm-skill (for PM Agent session)

Defines PM Agent behavior:
- Task coordination
- Gitea integration
- Notification handling

## Implementation Notes

### Hermes Gateway

Hermes gateway must be running:
```bash
hermes gateway start
```

Or run interactively:
```bash
hermes gateway run
```

### kugetsu init

Before using chat, ensure kugetsu is initialized:
```bash
kugetsu init
```

This creates:
- Base session
- PM agent session

### PM Agent Session

The PM agent session ID is stored in:
```
~/.kugetsu/index.json → "pm_agent" field
```

## Troubleshooting

### Hermes not receiving Telegram messages
1. Check `hermes gateway status`
2. Verify Telegram bot token in config
3. Ensure bot has been started by user

### PM Agent not responding
1. Check `kugetsu list` shows pm-agent
2. Verify pm-agent session is running: `opencode session list`
3. Check PM agent logs

### Routing not working
1. Check intent classification in Hermes context
2. Verify kugetsu is initialized
3. Check PM agent session is accessible

## Related Documentation

- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
- [kugetsu-chat-architecture.md](../../docs/kugetsu-chat.md)
- [telegram-setup.md](../../docs/telegram-setup.md)