60181afe6a
Phase 3a implementation - Hermes Chat Agent configuration: - kugetsu-chat/SOUL.md - Chat Agent persona and routing logic - kugetsu-chat/SKILL.md - Chat Agent skill documentation - kugetsu-chat/scripts/setup - Configuration setup script - kugetsu-pm/SKILL.md - PM Agent skill documentation - kugetsu-helpers/SKILL.md - Helper tools for Hermes-kugetsu integration - kugetsu-helpers/scripts/kugetsu-helpers - Shell functions for delegation Provides: - Intent classification (small talk, task, status, mode change) - PM Agent delegation via terminal() - kugetsu status checking - Session management helpers
170 lines
4.1 KiB
Markdown
170 lines
4.1 KiB
Markdown
---
|
|
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) |