7c94a59bb6
- SOUL.md: only personality/voice guidance (no routing logic) - SKILL.md: definitive routing behavior + delegation process - Add context passing via temp file for long tasks - Add error handling table with user-friendly messages This aligns with Hermes docs: SOUL.md = identity, SKILL.md = behavior
137 lines
4.0 KiB
Markdown
137 lines
4.0 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.1"
|
|
---
|
|
|
|
# kugetsu-chat - Chat Agent Skill
|
|
|
|
**This skill defines how Hermes routes messages and delegates to the PM Agent.**
|
|
|
|
## Overview
|
|
|
|
The Chat Agent receives Telegram messages, classifies intent, and routes to the appropriate handler.
|
|
|
|
## Intent Classification
|
|
|
|
When you receive a message, classify its intent:
|
|
|
|
| Intent | Examples | Action |
|
|
|--------|----------|--------|
|
|
| **Small talk** | "hi", "thanks", "how are you", "hello" | Respond directly |
|
|
| **Task request** | "fix issue #5", "create test for #14", "implement feature" | Route to PM Agent |
|
|
| **Status query** | "status?", "what's on #7?", "progress?" | Route to PM Agent |
|
|
| **Mode command** | "pm notify", "pm silent", "work silently" | Route to PM Agent |
|
|
| **Clarification** | "which project?", "what repo?" | Ask user for clarification |
|
|
|
|
## Delegation Process
|
|
|
|
When you need to delegate to the PM Agent:
|
|
|
|
### Step 1: Get PM Agent Session
|
|
|
|
```bash
|
|
PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))")
|
|
```
|
|
|
|
### Step 2: Check if kugetsu is initialized
|
|
|
|
```bash
|
|
kugetsu status check
|
|
```
|
|
|
|
If this fails, inform the user: "kugetsu is not initialized. Please run `kugetsu init` first."
|
|
|
|
### Step 3: Delegate to PM Agent
|
|
|
|
Use `terminal()` to continue the PM Agent session:
|
|
|
|
```
|
|
terminal(command="opencode run --continue --session $PM_SESSION 'User request: <message>'", timeout=120)
|
|
```
|
|
|
|
### Step 4: Relay Response
|
|
|
|
Return the PM Agent's response to the user via Telegram.
|
|
|
|
## Delegation via kugetsu-helpers
|
|
|
|
Alternatively, use the kugetsu-helpers script:
|
|
|
|
```bash
|
|
terminal(command="kugetsu-delegate '<task message>'", timeout=120)
|
|
```
|
|
|
|
Or check status first:
|
|
|
|
```bash
|
|
terminal(command="kugetsu-check-status", timeout=10)
|
|
```
|
|
|
|
## Context Passing
|
|
|
|
If the task message is too long for terminal parameters, write to a temp file:
|
|
|
|
```bash
|
|
# Write context to file
|
|
echo "Task: fix issue #5
|
|
Repo: github.com/shoko/kugetsu
|
|
User: Please fix the authentication bug
|
|
" > /tmp/task-context.txt
|
|
|
|
# Pass file path to PM
|
|
terminal(command="opencode run --continue --session $PM_SESSION --workdir /tmp \"Read /tmp/task-context.txt and execute\"", timeout=120)
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
| Error | User Message | Resolution |
|
|
|-------|--------------|------------|
|
|
| kugetsu not initialized | "kugetsu is not set up yet. Please run `kugetsu init` first." | User runs kugetsu init |
|
|
| PM agent missing | "PM agent not found. Run `kugetsu init` to create it." | User runs kugetsu init |
|
|
| Session expired | "The PM agent session may have expired. Please run `kugetsu destroy --pm-agent -y && kugetsu init` to reinitialize." | User reinitializes |
|
|
|
|
## PM Agent Modes
|
|
|
|
When routing to PM Agent, you can include mode preferences:
|
|
|
|
- "pm notify" → PM sends notifications on completion (default)
|
|
- "pm silent" → PM works quietly, no notifications
|
|
|
|
## Response Formatting
|
|
|
|
When relaying PM Agent responses:
|
|
- Keep messages concise (Telegram-friendly)
|
|
- Don't add your own commentary unless helpful
|
|
- Format links and code blocks clearly
|
|
|
|
## When NOT to Route
|
|
|
|
Do NOT route to PM Agent for:
|
|
- Greetings and casual conversation
|
|
- Questions about how the system works
|
|
- Help with Telegram itself
|
|
- Simple questions you can answer directly
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Check if kugetsu is ready
|
|
cat ~/.kugetsu/index.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if d.get('pm_agent') else 'NOT INITIALIZED')"
|
|
|
|
# Get PM session ID
|
|
python3 -c "import json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))"
|
|
```
|
|
|
|
## Related Skills
|
|
|
|
- `kugetsu-pm` - PM Agent behavior and coordination
|
|
- `kugetsu-helpers` - Shell functions for kugetsu interaction
|
|
|
|
## Files
|
|
|
|
- `../kugetsu-helpers/scripts/kugetsu-helpers` - Helper script with delegation functions |