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
This commit is contained in:
shokollm
170
skills/kugetsu-chat/SKILL.md
Normal file
170
skills/kugetsu-chat/SKILL.md
Normal file
@@ -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)
|
||||
110
skills/kugetsu-chat/SOUL.md
Normal file
110
skills/kugetsu-chat/SOUL.md
Normal file
@@ -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*
|
||||
194
skills/kugetsu-chat/scripts/setup
Executable file
194
skills/kugetsu-chat/scripts/setup
Executable file
@@ -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 "$@"
|
||||
166
skills/kugetsu-helpers/SKILL.md
Normal file
166
skills/kugetsu-helpers/SKILL.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: kugetsu-helpers
|
||||
description: Helper tools for Hermes to interact with kugetsu. Provides routing, delegation, and status functions.
|
||||
license: MIT
|
||||
compatibility: Requires Hermes agent, kugetsu CLI, opencode sessions.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# kugetsu-helpers - Hermes Tools for Kugetsu
|
||||
|
||||
Provides tools/functions for Hermes to route messages and delegate to the PM Agent.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables Hermes (as Chat Agent) to interact with kugetsu-managed opencode sessions.
|
||||
|
||||
## Tools
|
||||
|
||||
### kugetsu_get_pm_session
|
||||
|
||||
Gets the PM Agent session ID from kugetsu index.
|
||||
|
||||
```bash
|
||||
kugetsu_get_pm_session
|
||||
```
|
||||
|
||||
**Returns:** PM agent session ID string, or empty if not initialized
|
||||
|
||||
**Example:**
|
||||
```
|
||||
PM_SESSION=$(kugetsu_get_pm_session)
|
||||
echo "PM Agent: $PM_SESSION"
|
||||
```
|
||||
|
||||
### kugetsu_delegate_to_pm
|
||||
|
||||
Delegates a task to the PM Agent via opencode.
|
||||
|
||||
```bash
|
||||
kugetsu_delegate_to_pm "<task message>"
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `task message`: The task to delegate (e.g., "fix issue #5")
|
||||
|
||||
**Returns:** PM Agent response (may be multi-line)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
kugetsu_delegate_to_pm "User wants to fix issue #5 in github.com/shoko/kugetsu"
|
||||
```
|
||||
|
||||
### kugetsu_check_status
|
||||
|
||||
Checks kugetsu initialization status.
|
||||
|
||||
```bash
|
||||
kugetsu_check_status
|
||||
```
|
||||
|
||||
**Returns:** Status string indicating:
|
||||
- "ok" - kugetsu initialized, PM agent running
|
||||
- "kugetsu_not_initialized" - Run kugetsu init first
|
||||
- "pm_agent_missing" - PM agent not found
|
||||
|
||||
### kugetsu_list_sessions
|
||||
|
||||
Lists all kugetsu-managed sessions.
|
||||
|
||||
```bash
|
||||
kugetsu_list_sessions
|
||||
```
|
||||
|
||||
**Returns:** Formatted list of sessions
|
||||
|
||||
### kugetsu_create_dev_session
|
||||
|
||||
Creates a Dev Agent session for an issue.
|
||||
|
||||
```bash
|
||||
kugetsu_create_dev_session "<issue-ref>" "<task>"
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `issue-ref`: Issue reference (e.g., "github.com/shoko/kugetsu#5")
|
||||
- `task`: Task description for the dev agent
|
||||
|
||||
**Returns:** Session creation status
|
||||
|
||||
## Implementation
|
||||
|
||||
These tools are implemented as shell functions that Hermes can call via `terminal()`.
|
||||
|
||||
### Direct Implementation (Recommended)
|
||||
|
||||
Add to Hermes SOUL.md as custom tools:
|
||||
|
||||
```
|
||||
You have access to kugetsu via terminal commands:
|
||||
|
||||
- kugetsu_get_pm_session: Get PM agent session ID
|
||||
- kugetsu_delegate_to_pm <task>: Delegate to PM agent
|
||||
- kugetsu_check_status: Check kugetsu status
|
||||
```
|
||||
|
||||
### Tool Definition Format
|
||||
|
||||
Hermes tools should call these functions via terminal():
|
||||
|
||||
```python
|
||||
{
|
||||
"name": "kugetsu_delegate",
|
||||
"description": "Delegate a task to the PM Agent",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"task": {
|
||||
"type": "string",
|
||||
"description": "Task to delegate to PM Agent"
|
||||
}
|
||||
},
|
||||
"required": ["task"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage in Hermes
|
||||
|
||||
### SOUL.md Integration
|
||||
|
||||
Add to your SOUL.md:
|
||||
|
||||
```
|
||||
You can interact with kugetsu to route tasks:
|
||||
|
||||
1. Get PM agent session: terminal(command="kugetsu_get_pm_session")
|
||||
2. Delegate to PM: terminal(command="kugetsu_delegate_to_pm 'fix issue #5'")
|
||||
3. Check status: terminal(command="kugetsu_check_status")
|
||||
```
|
||||
|
||||
### Routing Logic
|
||||
|
||||
```
|
||||
User message → Hermes
|
||||
│
|
||||
├─ Small talk → respond directly
|
||||
│
|
||||
└─ Task request → terminal(kugetsu_delegate_to_pm "<task>")
|
||||
│
|
||||
└─ PM Agent response → relay to user
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| "kugetsu not initialized" | Run `kugetsu init` | Inform user |
|
||||
| "pm_agent_missing" | PM agent not created | Run `kugetsu init` |
|
||||
| "session not found" | opencode session expired | May need reinit |
|
||||
|
||||
## Files
|
||||
|
||||
- `scripts/kugetsu-helpers.sh` - Shell implementations
|
||||
- `SKILL.md` - This documentation
|
||||
148
skills/kugetsu-helpers/scripts/kugetsu-helpers
Executable file
148
skills/kugetsu-helpers/scripts/kugetsu-helpers
Executable file
@@ -0,0 +1,148 @@
|
||||
#!/bin/bash
|
||||
# kugetsu-helpers - Shell functions for Hermes to interact with kugetsu
|
||||
#
|
||||
# These functions provide tools for routing and delegation to PM Agent.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
|
||||
INDEX_FILE="$KUGETSU_DIR/index.json"
|
||||
|
||||
kugetsu_get_pm_session() {
|
||||
if [ ! -f "$INDEX_FILE" ]; then
|
||||
echo ""
|
||||
return
|
||||
fi
|
||||
|
||||
python3 -c "import json; print(json.load(open('$INDEX_FILE')).get('pm_agent', ''))" 2>/dev/null || echo ""
|
||||
}
|
||||
|
||||
kugetsu_check_status() {
|
||||
if [ ! -f "$INDEX_FILE" ]; then
|
||||
echo "kugetsu_not_initialized"
|
||||
return
|
||||
fi
|
||||
|
||||
if ! grep -q '"pm_agent"' "$INDEX_FILE"; then
|
||||
echo "pm_agent_missing"
|
||||
return
|
||||
fi
|
||||
|
||||
PM_AGENT=$(kugetsu_get_pm_session)
|
||||
if [ -z "$PM_AGENT" ] || [ "$PM_AGENT" = "null" ]; then
|
||||
echo "pm_agent_missing"
|
||||
return
|
||||
fi
|
||||
|
||||
echo "ok"
|
||||
}
|
||||
|
||||
kugetsu_delegate_to_pm() {
|
||||
local task="${1:-}"
|
||||
|
||||
if [ -z "$task" ]; then
|
||||
echo "Error: task is required"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local pm_session=$(kugetsu_get_pm_session)
|
||||
if [ -z "$pm_session" ] || [ "$pm_session" = "null" ]; then
|
||||
echo "Error: PM agent session not found. Run 'kugetsu init' first."
|
||||
return 1
|
||||
fi
|
||||
|
||||
opencode run --continue --session "$pm_session" "$task" 2>&1
|
||||
}
|
||||
|
||||
kugetsu_list_sessions() {
|
||||
if command -v kugetsu &> /dev/null; then
|
||||
kugetsu list 2>&1
|
||||
else
|
||||
echo "kugetsu command not found"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
kugetsu_create_dev_session() {
|
||||
local issue_ref="${1:-}"
|
||||
local task="${2:-}"
|
||||
|
||||
if [ -z "$issue_ref" ] || [ -z "$task" ]; then
|
||||
echo "Error: issue_ref and task are required"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if ! command -v kugetsu &> /dev/null; then
|
||||
echo "Error: kugetsu command not found"
|
||||
return 1
|
||||
fi
|
||||
|
||||
kugetsu start "$issue_ref" "$task" 2>&1
|
||||
}
|
||||
|
||||
kugetsu_continue_dev_session() {
|
||||
local issue_ref="${1:-}"
|
||||
local update="${2:-}"
|
||||
|
||||
if [ -z "$issue_ref" ] || [ -z "$update" ]; then
|
||||
echo "Error: issue_ref and update are required"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if ! command -v kugetsu &> /dev/null; then
|
||||
echo "Error: kugetsu command not found"
|
||||
return 1
|
||||
fi
|
||||
|
||||
kugetsu continue "$issue_ref" "$update" 2>&1
|
||||
}
|
||||
|
||||
# Main entry point for CLI usage
|
||||
main() {
|
||||
local command="${1:-}"
|
||||
shift || true
|
||||
|
||||
case "$command" in
|
||||
get-pm-session)
|
||||
kugetsu_get_pm_session
|
||||
;;
|
||||
check-status)
|
||||
kugetsu_check_status
|
||||
;;
|
||||
delegate-to-pm)
|
||||
kugetsu_delegate_to_pm "$@"
|
||||
;;
|
||||
list-sessions)
|
||||
kugetsu_list_sessions
|
||||
;;
|
||||
create-dev-session)
|
||||
kugetsu_create_dev_session "$@"
|
||||
;;
|
||||
continue-dev-session)
|
||||
kugetsu_continue_dev_session "$@"
|
||||
;;
|
||||
help|--help|-h)
|
||||
cat << 'EOF'
|
||||
kugetsu-helpers - Hermes tools for kugetsu
|
||||
|
||||
Commands:
|
||||
get-pm-session Get PM agent session ID
|
||||
check-status Check kugetsu initialization status
|
||||
delegate-to-pm <task> Delegate task to PM agent
|
||||
list-sessions List all kugetsu sessions
|
||||
create-dev-session <ref> <task> Create dev agent session
|
||||
continue-dev-session <ref> <update> Continue dev agent session
|
||||
|
||||
Usage in Hermes:
|
||||
terminal(command="kugetsu_delegate_to_pm 'fix issue #5'")
|
||||
EOF
|
||||
;;
|
||||
*)
|
||||
echo "Error: Unknown command '$command'"
|
||||
echo "Run 'kugetsu-helpers help' for usage"
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
main "$@"
|
||||
218
skills/kugetsu-pm/SKILL.md
Normal file
218
skills/kugetsu-pm/SKILL.md
Normal file
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: kugetsu-pm
|
||||
description: PM (Project Manager) Agent skill for kugetsu. Handles task coordination, delegation, and Gitea integration.
|
||||
license: MIT
|
||||
compatibility: Requires kugetsu CLI, opencode sessions, Gitea API access.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# kugetsu-pm - PM Agent Skill
|
||||
|
||||
Defines the behavior of the PM (Project Manager) Agent in the kugetsu system.
|
||||
|
||||
## Overview
|
||||
|
||||
The PM Agent is a persistent opencode session managed by kugetsu. It:
|
||||
|
||||
1. **Receives** task requests from Chat Agent (via Hermes)
|
||||
2. **Coordinates** task execution via Dev Agents
|
||||
3. **Monitors** Gitea for issue updates
|
||||
4. **Notifies** users of task completion (if in notify mode)
|
||||
5. **Maintains** context across interactions
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Chat Agent (Hermes/Telegram)
|
||||
│
|
||||
├── Routes task requests
|
||||
│
|
||||
▼
|
||||
PM Agent (opencode session via kugetsu)
|
||||
│
|
||||
├── Creates Dev Agent sessions via kugetsu
|
||||
│
|
||||
▼
|
||||
Dev Agents (opencode sessions via kugetsu)
|
||||
│
|
||||
├── Work on issues autonomously
|
||||
│
|
||||
▼
|
||||
Gitea (Issues, PRs, Comments)
|
||||
```
|
||||
|
||||
## PM Agent Modes
|
||||
|
||||
| Mode | Behavior | Command |
|
||||
|------|----------|---------|
|
||||
| **notify** (default) | Send completion notifications | "pm notify" |
|
||||
| **silent** | Work quietly, no notifications | "pm silent" |
|
||||
|
||||
## Task Flow
|
||||
|
||||
### 1. Receive Task Request
|
||||
|
||||
When Chat Agent routes a task:
|
||||
```
|
||||
"fix issue #5"
|
||||
```
|
||||
|
||||
### 2. Parse and Validate
|
||||
|
||||
PM Agent extracts:
|
||||
- Action (fix, create, test, research, etc.)
|
||||
- Issue number or identifier
|
||||
- Repository context
|
||||
|
||||
### 3. Create Task Plan
|
||||
|
||||
PM Agent decides:
|
||||
- Can it be handled directly?
|
||||
- Does it need a Dev Agent?
|
||||
- What context is needed?
|
||||
|
||||
### 4. Execute via Dev Agent
|
||||
|
||||
```bash
|
||||
kugetsu start <issue-ref> "<task description>"
|
||||
```
|
||||
|
||||
### 5. Monitor and Notify
|
||||
|
||||
- PM monitors Gitea for PR status
|
||||
- When complete, notifies user (if in notify mode)
|
||||
|
||||
## Gitea Integration
|
||||
|
||||
### Context Fetching
|
||||
|
||||
PM Agent fetches from Gitea when:
|
||||
- Initial task load (no context)
|
||||
- Explicit request (agent decides)
|
||||
- Insufficient context
|
||||
|
||||
### Context Merge Strategy
|
||||
|
||||
- **Default**: Append new context to existing
|
||||
- **Threshold**: Summarize + replace at 40% of context window
|
||||
|
||||
## Session Context
|
||||
|
||||
PM Agent maintains:
|
||||
|
||||
### Managed Repositories
|
||||
```json
|
||||
{
|
||||
"repos": [
|
||||
"github.com/shoko/kugetsu",
|
||||
"gitlab.com/team/core"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Active Tasks
|
||||
```json
|
||||
{
|
||||
"tasks": {
|
||||
"issue-5": {
|
||||
"status": "in_progress",
|
||||
"dev_agent": "ses_xyz789",
|
||||
"created_at": "2026-03-30T10:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification Preferences
|
||||
```json
|
||||
{
|
||||
"mode": "notify"
|
||||
}
|
||||
```
|
||||
|
||||
## Delegation Commands
|
||||
|
||||
### Create Dev Agent Session
|
||||
|
||||
```bash
|
||||
kugetsu start <issue-ref> "<task>"
|
||||
```
|
||||
|
||||
### Continue Dev Agent Session
|
||||
|
||||
```bash
|
||||
kugetsu continue <issue-ref> "<update>"
|
||||
```
|
||||
|
||||
### List Active Sessions
|
||||
|
||||
```bash
|
||||
kugetsu list
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
PM Agent responses should be:
|
||||
- **Concise** - Telegram-friendly
|
||||
- **Action-oriented** - What's been done, what's next
|
||||
- **Clear status** - In progress, done, blocked
|
||||
|
||||
### Example Responses
|
||||
|
||||
```
|
||||
"Created task for issue #5. Dev agent started."
|
||||
"Issue #5 is complete. PR created: [link]"
|
||||
"Task blocked: Need clarification on requirements."
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Dev Agent Failure
|
||||
- Analyze failure reason
|
||||
- Retry or escalate to user
|
||||
- Log to Gitea issue comment
|
||||
|
||||
### Session Not Found
|
||||
- Check kugetsu status: `kugetsu list`
|
||||
- Inform user of issue
|
||||
- Suggest manual intervention
|
||||
|
||||
### Gitea API Errors
|
||||
- Retry with backoff
|
||||
- Cache last known state
|
||||
- Inform user if persistent
|
||||
|
||||
## Skills
|
||||
|
||||
### kugetsu (for session management)
|
||||
- Session creation and continuation
|
||||
- Worktree management
|
||||
|
||||
### github (for Gitea API)
|
||||
- Issue fetching
|
||||
- PR creation
|
||||
- Comment posting
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### PM Agent Session ID
|
||||
|
||||
The PM Agent session is stored in:
|
||||
```
|
||||
~/.kugetsu/index.json → "pm_agent" field
|
||||
```
|
||||
|
||||
### Accessing PM Agent
|
||||
|
||||
```bash
|
||||
PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('pm_agent', ''))")
|
||||
opencode run --continue --session "$PM_SESSION" "<message>"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
|
||||
- [kugetsu-chat.md](../../docs/kugetsu-chat.md)
|
||||
- [hermes-setup.md](../../docs/hermes-setup.md)
|
||||
Reference in New Issue
Block a user