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-helpers/SKILL.md
+++ b/skills/kugetsu-helpers/SKILL.md
@@ -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