60181afe6a
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
166 lines
3.5 KiB
Markdown
166 lines
3.5 KiB
Markdown
---
|
|
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 |