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
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 "$@"
|
||||
Reference in New Issue
Block a user