kugetsu/skills/kugetsu-chat/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
kugetsu-chat	Chat Agent skill for kugetsu Phase 3. Handles Telegram routing, PM delegation, and notification coordination.	MIT	Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.	author version shoko 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:

# 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:

hermes gateway start

Or run interactively:

hermes gateway run

kugetsu init

Before using chat, ensure kugetsu is initialized:

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
• kugetsu-chat-architecture.md
• telegram-setup.md