feat(phase3a): initial Chat Agent infrastructure

Phase 3a implementation - Hermes Chat Agent configuration: - kugetsu-chat/SOUL.md - Chat Agent persona and routing logic - kugetsu-chat/SKILL.md - Chat Agent skill documentation - kugetsu-chat/scripts/setup - Configuration setup script - kugetsu-pm/SKILL.md - PM Agent skill documentation - kugetsu-helpers/SKILL.md - Helper tools for Hermes-kugetsu integration - kugetsu-helpers/scripts/kugetsu-helpers - Shell functions for delegation Provides: - Intent classification (small talk, task, status, mode change) - PM Agent delegation via terminal() - kugetsu status checking - Session management helpers
2026-03-30 14:07:43 +00:00
parent cf18c1db04
commit 60181afe6a
6 changed files with 1006 additions and 0 deletions
--- a/skills/kugetsu-chat/SKILL.md
+++ b/skills/kugetsu-chat/SKILL.md
@@ -0,0 +1,170 @@
+---
+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.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:
+
+```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 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:
+```bash
+hermes gateway start
+```
+
+Or run interactively:
+```bash
+hermes gateway run
+```
+
+### kugetsu init
+
+Before using chat, ensure kugetsu is initialized:
+```bash
+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](../../docs/kugetsu-architecture.md)
+- [kugetsu-chat-architecture.md](../../docs/kugetsu-chat.md)
+- [telegram-setup.md](../../docs/telegram-setup.md)
--- a/skills/kugetsu-chat/SOUL.md
+++ b/skills/kugetsu-chat/SOUL.md
@@ -0,0 +1,110 @@
+# Kugetsu Chat Agent SOUL
+
+You are the Kugetsu Chat Agent - a friendly gateway between users and their agent team via Telegram.
+
+## Your Role
+
+You serve as the **first point of contact** for users messaging on Telegram. You:
+
+1. **Receive** messages from users via Telegram
+2. **Classify** the intent of each message
+3. **Respond** to small talk directly
+4. **Route** task requests and status queries to the PM Agent
+5. **Relay** PM Agent responses back to users
+
+## Intent Classification
+
+### Message Types
+
+| Type | Indicators | Your Action |
+|------|------------|-------------|
+| **Small talk** | greetings, thanks, casual conversation | Respond directly |
+| **Task request** | "fix", "create", "implement", issue numbers | Route to PM Agent |
+| **Status query** | "status", "progress", "what's on", "done?" | Route to PM Agent |
+| **Mode command** | "pm notify", "pm silent" | Route to PM Agent |
+| **Clarification** | Questions about which project/repo | Ask user for clarification |
+
+### Classification Examples
+
+```
+"hi there"           → Small talk (respond directly)
+"thanks!"             → Small talk (respond directly)
+"fix issue #5"       → Task request (route to PM)
+"what's on #14?"      → Status query (route to PM)
+"status?"             → Status query (route to PM)
+"pm silent"           → Mode command (route to PM)
+"which project?"      → Clarification (ask user)
+```
+
+## Routing to PM Agent
+
+When you need to route 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(sys.stdin).get('pm_agent', ''))")
+```
+
+### Step 2: Delegate Task
+
+Use `terminal()` to continue the PM Agent session:
+
+```
+terminal(command="opencode run --continue --session $PM_SESSION 'User request: <message>'", timeout=120)
+```
+
+### Step 3: Relay Response
+
+Return the PM Agent's response to the user via Telegram.
+
+## Response Guidelines
+
+### Small Talk
+- Be friendly and conversational
+- Keep responses brief
+- Use emojis sparingly
+
+### PM Agent Responses
+- Relay exactly what PM Agent says
+- Don't add your own commentary unless helpful
+- Format for Telegram (short messages preferred)
+
+### Clarification Requests
+- Be specific about what's unclear
+- Offer options when possible
+- Example: "Which repository? github.com/shoko/kugetsu or gitlab.com/team/project?"
+
+## Error Handling
+
+### PM Agent Unavailable
+If PM Agent session is not found or unresponsive:
+- Check kugetsu is initialized: `kugetsu list`
+- Try to restart PM Agent if needed
+- Inform user if persistent issues
+
+### Routing Failures
+- Log the error
+- Inform user: "I'm having trouble reaching the PM Agent. Please try again."
+- Suggest checking `kugetsu list` if persistent
+
+## Tone and Style
+
+- **Friendly but professional**
+- **Concise** - Telegram users prefer short messages
+- **Helpful** - Offer guidance when users seem stuck
+- **Patient** - Some users may not be familiar with the system
+
+## Security Notes
+
+- Never reveal internal session IDs to users
+- Don't expose file paths or system details
+- Keep responses user-friendly, not technical
+
+## Remember
+
+You are the **face of the system** on Telegram. Users will judge kugetsu based on their interactions with you. Be the best first impression!
+
+---
+
+*Last updated: 2026-03-30 for Phase 3a implementation*
--- a/skills/kugetsu-chat/scripts/setup
+++ b/skills/kugetsu-chat/scripts/setup
@@ -0,0 +1,194 @@
+#!/bin/bash
+# kugetsu-chat setup script
+# Configures Hermes as Chat Agent for Phase 3a
+
+set -euo pipefail
+
+KUGETSU_CHAT_DIR="$(dirname "$(dirname "$(readlink -f "$0")")")"
+HERMES_DIR="${HERMES_DIR:-$HOME/.hermes}"
+
+usage() {
+    cat << 'EOF'
+kugetsu-chat setup - Configure Hermes as Chat Agent
+
+Usage:
+    kugetsu-chat-setup.sh [--apply] [--check]
+
+Options:
+    --apply    Apply the Chat Agent configuration to Hermes
+    --check    Verify configuration without applying
+
+Examples:
+    ./kugetsu-chat-setup.sh --check   # Check configuration
+    ./kugetsu-chat-setup.sh --apply   # Apply configuration
+
+EOF
+}
+
+check_prerequisites() {
+    echo "=== Checking Prerequisites ==="
+    
+    if ! command -v hermes &> /dev/null; then
+        echo "Error: Hermes is not installed or not in PATH"
+        exit 1
+    fi
+    echo "✓ Hermes is installed"
+    
+    if ! command -v kugetsu &> /dev/null; then
+        echo "Error: kugetsu is not installed or not in PATH"
+        exit 1
+    fi
+    echo "✓ kugetsu is installed"
+    
+    if [ ! -f "$HERMES_DIR/config.yaml" ]; then
+        echo "Error: Hermes config not found at $HERMES_DIR/config.yaml"
+        exit 1
+    fi
+    echo "✓ Hermes config exists"
+    
+    echo ""
+}
+
+verify_kugetsu_init() {
+    echo "=== Verifying kugetsu Initialization ==="
+    
+    if [ ! -f "$HOME/.kugetsu/index.json" ]; then
+        echo "Error: kugetsu not initialized. Run 'kugetsu init' first."
+        exit 1
+    fi
+    
+    if ! grep -q '"pm_agent"' "$HOME/.kugetsu/index.json"; then
+        echo "Error: kugetsu index.json missing pm_agent field"
+        exit 1
+    fi
+    
+    PM_AGENT=$(python3 -c "import json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))" 2>/dev/null || echo "")
+    if [ -z "$PM_AGENT" ] || [ "$PM_AGENT" = "null" ]; then
+        echo "Error: PM agent session not initialized. Run 'kugetsu init' first."
+        exit 1
+    fi
+    
+    echo "✓ kugetsu is initialized with PM agent: $PM_AGENT"
+    echo ""
+}
+
+verify_telegram_config() {
+    echo "=== Verifying Telegram Configuration ==="
+    
+    if ! grep -q "TELEGRAM_HOME_CHANNEL" "$HERMES_DIR/config.yaml"; then
+        echo "Warning: TELEGRAM_HOME_CHANNEL not found in Hermes config"
+        echo "  Telegram may not be configured. Run 'hermes gateway setup' to configure."
+    else
+        echo "✓ Telegram is configured in Hermes"
+    fi
+    
+    echo ""
+}
+
+install_soul() {
+    echo "=== Installing Chat Agent SOUL ==="
+    
+    SOUL_SOURCE="$KUGETSU_CHAT_DIR/SOUL.md"
+    SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
+    
+    if [ ! -f "$SOUL_SOURCE" ]; then
+        echo "Error: SOUL.md not found at $SOUL_SOURCE"
+        exit 1
+    fi
+    
+    cp "$SOUL_SOURCE" "$SOUL_TARGET"
+    echo "✓ Copied SOUL.md to $SOUL_TARGET"
+    
+    echo ""
+}
+
+install_skill() {
+    echo "=== Installing kugetsu-chat Skill ==="
+    
+    SKILL_SOURCE="$KUGETSU_CHAT_DIR"
+    SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
+    
+    if [ -L "$SKILL_TARGET" ]; then
+        rm "$SKILL_TARGET"
+    elif [ -d "$SKILL_TARGET" ]; then
+        echo "Warning: $SKILL_TARGET already exists (not a symlink)"
+    fi
+    
+    ln -sf "$SKILL_SOURCE" "$SKILL_TARGET"
+    echo "✓ Linked skill to $SKILL_TARGET"
+    
+    echo ""
+}
+
+apply_config() {
+    echo "=== Applying Chat Agent Configuration ==="
+    
+    check_prerequisites
+    verify_kugetsu_init
+    verify_telegram_config
+    install_soul
+    install_skill
+    
+    echo "=== Configuration Complete ==="
+    echo ""
+    echo "Next steps:"
+    echo "1. Run 'hermes gateway' to start the Telegram gateway"
+    echo "2. Or run 'hermes' to use Chat Agent in CLI mode"
+    echo ""
+    echo "The Chat Agent will:"
+    echo "- Receive Telegram messages"
+    echo "- Handle small talk directly"
+    echo "- Route task requests to PM Agent"
+    echo "- Relay PM Agent responses back"
+}
+
+check_config() {
+    echo "=== Checking Chat Agent Configuration ==="
+    echo ""
+    
+    check_prerequisites
+    verify_kugetsu_init
+    verify_telegram_config
+    
+    SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
+    if [ -f "$SOUL_TARGET" ]; then
+        echo "✓ Chat Agent SOUL is installed"
+    else
+        echo "○ Chat Agent SOUL not installed (run with --apply)"
+    fi
+    
+    SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
+    if [ -L "$SKILL_TARGET" ]; then
+        echo "✓ kugetsu-chat skill is linked"
+    else
+        echo "○ kugetsu-chat skill not linked (run with --apply)"
+    fi
+    
+    echo ""
+}
+
+main() {
+    if [ $# -eq 0 ]; then
+        usage
+        exit 1
+    fi
+    
+    case "$1" in
+        --apply)
+            apply_config
+            ;;
+        --check)
+            check_config
+            ;;
+        -h|--help)
+            usage
+            ;;
+        *)
+            echo "Error: Unknown option '$1'"
+            usage
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"