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