feat(phase3a): update SKILL.md and SOUL.md with stronger routing instructions
- SKILL.md: More explicit about MUST use this skill for delegation - SOUL.md: Explicitly instruct to invoke /kugetsu-chat skill first - Add more explicit delegation rules and error handling
This commit is contained in:
shokollm
@@ -1,137 +1,92 @@
|
||||
---
|
||||
name: kugetsu-chat
|
||||
description: Chat Agent skill for kugetsu Phase 3. Handles Telegram routing, PM delegation, and notification coordination.
|
||||
description: Kugetsu Chat Agent - REQUIRED skill for ALL non-casual Telegram messages. This skill MUST be loaded and used for task delegation.
|
||||
license: MIT
|
||||
compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "1.1"
|
||||
version: "2.0"
|
||||
---
|
||||
|
||||
# kugetsu-chat - Chat Agent Skill
|
||||
# kugetsu-chat - REQUIRED SKILL FOR KUGETSU ROUTING
|
||||
|
||||
**This skill defines how Hermes routes messages and delegates to the PM Agent.**
|
||||
**THIS SKILL MUST BE USED for any message that is not casual conversation.**
|
||||
|
||||
## Overview
|
||||
## CRITICAL: When to Use This Skill
|
||||
|
||||
The Chat Agent receives Telegram messages, classifies intent, and routes to the appropriate handler.
|
||||
**YOU MUST LOAD AND USE THIS SKILL when:**
|
||||
- Any message containing "issue", "fix", "create", "test", "implement"
|
||||
- Any message containing issue numbers like "#5", "#14", "#123"
|
||||
- Any message that looks like a task request or status query
|
||||
- Any message containing "pm", "status", "progress", "work on"
|
||||
|
||||
## Intent Classification
|
||||
**DO NOT USE THIS SKILL for:**
|
||||
- "hi", "hello", "hey"
|
||||
- "thanks", "thank you"
|
||||
- "how are you", "what's up"
|
||||
- Casual greetings
|
||||
|
||||
When you receive a message, classify its intent:
|
||||
## Required Actions
|
||||
|
||||
| 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 |
|
||||
When you MUST use this skill:
|
||||
|
||||
## 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 1: Load This Skill
|
||||
```
|
||||
/kugetsu-chat
|
||||
```
|
||||
|
||||
### Step 2: Check if kugetsu is initialized
|
||||
```
|
||||
terminal(command="~/.local/bin/kugetsu-helper check-status", timeout=10)
|
||||
```
|
||||
|
||||
### Step 3: If initialized, DELEGATE immediately
|
||||
```
|
||||
terminal(command="~/.local/bin/kugetsu-helper delegate-to-pm '<entire user message>'", timeout=120)
|
||||
```
|
||||
|
||||
### Step 4: Relay the response to the user
|
||||
|
||||
## Delegation Command
|
||||
|
||||
The ONLY command you should use for delegation:
|
||||
|
||||
```bash
|
||||
kugetsu status check
|
||||
~/.local/bin/kugetsu-helper delegate-to-pm '<user message>'
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
Example:
|
||||
```
|
||||
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)
|
||||
terminal(command="~/.local/bin/kugetsu-helper delegate-to-pm 'fix issue #5 in github.com/shoko/kugetsu'", 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
|
||||
| Status Output | Meaning | Action |
|
||||
|--------------|---------|--------|
|
||||
| `ok` | kugetsu is ready | Proceed with delegation |
|
||||
| `kugetsu_not_initialized` | Not set up | Tell user to run `kugetsu init` |
|
||||
| `pm_agent_missing` | PM not created | Tell user to run `kugetsu init` |
|
||||
|
||||
## 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', ''))"
|
||||
**DELEGATION COMMAND:**
|
||||
```
|
||||
terminal(command="~/.local/bin/kugetsu-helper delegate-to-pm '<message>'", timeout=120)
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
**CHECK STATUS:**
|
||||
```
|
||||
terminal(command="~/.local/bin/kugetsu-helper check-status", timeout=10)
|
||||
```
|
||||
|
||||
- `kugetsu-pm` - PM Agent behavior and coordination
|
||||
- `kugetsu-helpers` - Shell functions for kugetsu interaction
|
||||
## Required Files
|
||||
|
||||
## Files
|
||||
- `~/.local/bin/kugetsu-helper` - The delegation helper script
|
||||
|
||||
- `../kugetsu-helpers/scripts/kugetsu-helpers` - Helper script with delegation functions
|
||||
## Notes
|
||||
|
||||
- ALWAYS use the full path `~/.local/bin/kugetsu-helper`
|
||||
- ALWAYS use `delegate-to-pm` subcommand
|
||||
- ALWAYS wrap user message in single quotes inside the command
|
||||
- ALWAYS use timeout of at least 120 seconds for delegation
|
||||
Reference in New Issue
Block a user