shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

fix(phase3a): separate SOUL.md personality from SKILL.md routing

Browse Source 
- 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
This commit is contained in:
shokollm
2026-03-30 14:20:21 +00:00
parent 60181afe6a
commit 7c94a59bb6
2 changed files with 130 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
skills/kugetsu-chat/SKILL.md
View File

@@ -5,166 +5,133 @@ license: MIT
compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
metadata:
author: shoko
version: "1.0"
version: "1.1"
---
# kugetsu-chat - Chat Agent for Kugetsu Phase 3
# kugetsu-chat - Chat Agent Skill
Handles natural language routing and PM Agent coordination for Telegram interface.
**This skill defines how Hermes routes messages and delegates to the PM Agent.**
## 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
```
The Chat Agent receives Telegram messages, classifies intent, and routes to the appropriate handler.
## Intent Classification
### Rules
When you receive a message, classify its intent:
| 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 |
| 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 |
### Routing Logic
## Delegation Process
```
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
```
When you need to delegate to the PM Agent:
## PM Agent Delegation
### How Hermes Delegates to PM Agent
Hermes uses `terminal()` to interact with the PM Agent opencode session:
### Step 1: Get PM Agent 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_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))")
```
### PM Agent Modes
### Step 2: Check if kugetsu is initialized
| 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
kugetsu status check
```
Or run interactively:
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
hermes gateway run
terminal(command="kugetsu-delegate '<task message>'", timeout=120)
```
### kugetsu init
Or check status first:
Before using chat, ensure kugetsu is initialized:
```bash
kugetsu init
terminal(command="kugetsu-check-status", timeout=10)
```
This creates:
- Base session
- PM agent session
## Context Passing
### PM Agent Session
If the task message is too long for terminal parameters, write to a temp file:
The PM agent session ID is stored in:
```
~/.kugetsu/index.json → "pm_agent" field
```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)
```
## Troubleshooting
## Error Handling
### 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
| 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 not responding
1. Check `kugetsu list` shows pm-agent
2. Verify pm-agent session is running: `opencode session list`
3. Check PM agent logs
## PM Agent Modes
### Routing not working
1. Check intent classification in Hermes context
2. Verify kugetsu is initialized
3. Check PM agent session is accessible
When routing to PM Agent, you can include mode preferences:
## Related Documentation
- "pm notify" → PM sends notifications on completion (default)
- "pm silent" → PM works quietly, no notifications
- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
- [kugetsu-chat-architecture.md](../../docs/kugetsu-chat.md)
- [telegram-setup.md](../../docs/telegram-setup.md)
## 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