feat(phase3a): initial Chat Agent infrastructure
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
This commit is contained in:
shokollm
170
skills/kugetsu-chat/SKILL.md
Normal file
170
skills/kugetsu-chat/SKILL.md
Normal file
@@ -0,0 +1,170 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user