shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(kugetsu): add status, delegate, doctor commands; inject PM context at init

Browse Source 
This commit implements Phase 3b/3c architectural improvements:

### New kugetsu CLI commands:
- `kugetsu status` - Check initialization status (replaces kugetsu-helper check-status)
- `kugetsu delegate <msg>` - Send message to PM agent (new command)
- `kugetsu doctor [--fix]` - Diagnose and fix kugetsu issues

### PM Context Injection:
- kugetsu init now reads ~/.kugetsu/pm-agent.md (if exists) and injects
  it into the PM agent session at creation time
- PM context is loaded ONCE at init, not on every delegation
- This improves efficiency - kugetsu-pm content read once, not 10 times

### kugetsu-chat updated:
- Now uses `kugetsu delegate` instead of kugetsu-helper
- Now uses `kugetsu status` instead of kugetsu-helper check-status
- Simplified - no longer depends on kugetsu-helpers

### kugetsu continue:
- Removed strict issue-ref format validation
- Now accepts any session name that is tracked in index.json["issues"]
- Issue-ref format is a guideline, not a hard requirement

### Documentation updated:
- phase3a-setup.md - Updated to reflect new kugetsu commands
- kugetsu-install.sh - Simplified Phase 3a setup instructions

### Breaking changes:
- kugetsu-helpers is no longer required for Phase 3a Chat Agent
- kugetsu-chat skill v3.0 now requires kugetsu CLI with new commands
This commit is contained in:
shokollm
2026-03-31 01:09:12 +00:00
parent bc3cc8dd1e
commit b3171ed632
5 changed files with 290 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
docs/phase3a-setup.md
View File

@@ -21,15 +21,11 @@ hermes config show # Check Telegram is configured
```bash
# Create skill directories
mkdir -p ~/.hermes/skills/kugetsu-chat
mkdir -p ~/.hermes/skills/kugetsu-pm
mkdir -p ~/.hermes/skills/kugetsu-helpers
# Link skills from kugetsu repo (adjust path as needed)
KUGEETSU_DIR="/path/to/kugetsu" # e.g., ~/repositories/kugetsu
ln -sf "$KUGEETSU_DIR/skills/kugetsu-chat" ~/.hermes/skills/kugetsu-chat
ln -sf "$KUGEETSU_DIR/skills/kugetsu-pm ~/.hermes/skills/kugetsu-pm
ln -sf "$KUGEETSU_DIR/skills/kugetsu-helpers" ~/.hermes/skills/kugetsu-helpers
```
## Step 3: Install Chat Agent SOUL
@@ -39,18 +35,7 @@ ln -sf "$KUGEETSU_DIR/skills/kugetsu-helpers" ~/.hermes/skills/kugetsu-helpers
cp "$KUGEETSU_DIR/skills/kugetsu-chat/SOUL.md" ~/.hermes/SOUL-chat.md
```
## Step 4: Install Helper Scripts
```bash
# Copy helper script to PATH
cp "$KUGEETSU_DIR/skills/kugetsu-helpers/scripts/kugetsu-helpers" ~/.local/bin/kugetsu-helper
chmod +x ~/.local/bin/kugetsu-helper
# Verify
kugetsu-helper help
```
## Step 5: Verify Gateway is Running
## Step 4: Verify Gateway is Running
```bash
hermes gateway status
@@ -58,7 +43,7 @@ hermes gateway status
hermes gateway start
```
## Step 6: Initialize kugetsu
## Step 5: Initialize kugetsu
**WARNING:** This requires an interactive terminal (TTY) because it spawns the opencode TUI.
@@ -75,22 +60,22 @@ kugetsu init # Run manually in the SSH session
This creates:
- **Base session** (for forking dev agents)
- **PM Agent session** (persistent coordinator)
- **PM Agent session** (persistent coordinator, loaded with kugetsu-pm context)
If you get `Error: init requires a terminal (TTY)`, you're running via non-interactive SSH. Use `-t` flag or connect directly.
## Step 7: Verify Setup
## Step 6: Verify Setup
```bash
# Check kugetsu status
kugetsu list
# Check PM agent exists
kugetsu-helper check-status
kugetsu status
# Should output: ok
# List all sessions
kugetsu list
```
## Step 8: Test via Telegram
## Step 7: Test via Telegram
Start a conversation with your bot (@your_bot_username):
@@ -102,7 +87,7 @@ Start a conversation with your bot (@your_bot_username):
## Troubleshooting
### kugetsu-helper not found
### kugetsu command not found
```bash
export PATH="$HOME/.local/bin:$PATH"
# Or add to ~/.bashrc
@@ -114,22 +99,46 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
hermes gateway restart
```
### PM agent missing
### PM agent issues
```bash
# Reinitialize
# Diagnose
kugetsu doctor
# Fix (if needed)
kugetsu doctor --fix
# Or reinitialize
kugetsu destroy --pm-agent -y
kugetsu init
```
## kugetsu Commands
| Command | Description |
|---------|-------------|
| `kugetsu init` | Initialize base + PM agent sessions |
| `kugetsu status` | Check if kugetsu is ready |
| `kugetsu delegate <msg>` | Send message to PM agent |
| `kugetsu doctor [--fix]` | Diagnose and fix issues |
| `kugetsu start <issue-ref> <msg>` | Start dev agent for issue |
| `kugetsu continue <issue-ref> <msg>` | Continue existing issue session |
| `kugetsu list` | List all tracked sessions |
| `kugetsu prune [--force]` | Clean up orphaned sessions |
## File Locations
| File | Location | Purpose |
|------|----------|---------|
| Chat Agent SOUL | `~/.hermes/SOUL-chat.md` | Personality |
| kugetsu-chat skill | `~/.hermes/skills/kugetsu-chat/` | Routing behavior |
| kugetsu-pm skill | `~/.hermes/skills/kugetsu-pm/` | PM Agent docs |
| kugetsu-helpers | `~/.hermes/skills/kugetsu-helpers/` | Helper functions |
| Helper script | `~/.local/bin/kugetsu-helper` | CLI helper |
| kugetsu | `~/.local/bin/kugetsu` | Main CLI |
~/.kugetsu/
├── sessions/
│ ├── base.json # Base opencode session
│ └── pm-agent.json # PM Agent opencode session
├── index.json # Session registry
└── pm-agent.md # PM context (optional, injected at init)
## Architecture Summary
@@ -137,63 +146,25 @@ kugetsu init
~/.hermes/
├── SOUL-chat.md # Chat Agent personality
└── skills/
├── kugetsu-chat/ # Routing + delegation logic
├── kugetsu-pm/ # PM Agent documentation
└── kugetsu-helpers/ # Shell helpers for terminal()
└── kugetsu-chat/ # Routing + delegation via kugetsu CLI
~/.kugetsu/
├── sessions/
│ ├── base.json # Base opencode session
│ └── pm-agent.json # PM Agent opencode session
└── index.json # Session registry
├── index.json # Session registry
└── pm-agent.md # PM context (optional)
~/.local/bin/
└── kugetsu-helper # CLI helper script
└── kugetsu # Main CLI (handles delegation, status, doctor)
```
## Testing Plan (Manual)
## PM Context (Optional)
### Test 1: Casual Conversation
**Objective:** Verify Hermes handles small talk directly without delegation
| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Send `hi` to @your_bot_username | Bot responds with greeting |
| 2 | Send `how are you?` | Bot responds naturally |
### Test 2: Task Delegation
**Objective:** Verify Hermes delegates task to PM Agent via `kugetsu-helper`
| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Send `status?` to bot | Bot routes to PM, PM responds |
| 2 | Send `fix issue #5` to bot | PM agent receives task via opencode |
| 3 | Send `Work on issue #35` to bot | PM agent creates branch, worktree, PR |
### Test 3: Error Handling
**Objective:** Verify graceful error handling
| Step | Action | Expected Result |
|------|--------|-----------------|
| 1 | Send `status?` with PM agent stopped | Bot says "PM agent not available" |
| 2 | Send `status?` before `kugetsu init` | Bot says "kugetsu not initialized" |
### Debugging
If delegation fails:
```bash
# Check Hermes logs
hermes gateway logs
# Check PM agent is running
kugetsu-helper check-status
# Check kugetsu-helper directly
~/.local/bin/kugetsu-helper delegate-to-pm "test"
```
To customize PM Agent behavior, create `~/.kugetsu/pm-agent.md` with additional context. This file is injected into the PM Agent session at init time.
## Security Notes
- Never commit `~/.kugetsu/` or SOUL files to version control
- Bot tokens should be in environment variables, not files
- PM agent session IDs are internal - don't expose to users
- PM agent session IDs are internal - don't expose to users