# Kugetsu Phase 3a Installation Guide

Guide for setting up the Kugetsu Chat Agent (Phase 3a) on a new host/container.

## Prerequisites

1. **Hermes Agent** installed and configured
2. **Telegram bot** created via @BotFather
3. **kugetsu CLI** installed
4. **opencode** installed

## Step 1: Verify Hermes Installation

```bash
hermes version
hermes config show  # Check Telegram is configured
```

## Step 2: Link Skills to Hermes

```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

```bash
# Copy SOUL.md to Hermes home (this defines the Chat Agent personality)
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

```bash
hermes gateway status
# If stopped:
hermes gateway start
```

## Step 6: Initialize kugetsu

**WARNING:** This requires an interactive terminal (TTY) because it spawns the opencode TUI.

You must run this in an **interactive shell**, not via `ssh remote "kugetsu init"`:

```bash
# Option 1: SSH with TTY allocation
ssh -t user@host "kugetsu init"

# Option 2: Connect to existing session and run
ssh user@host
kugetsu init  # Run manually in the SSH session
```

This creates:
- **Base session** (for forking dev agents)
- **PM Agent session** (persistent coordinator)

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

```bash
# Check kugetsu status
kugetsu list

# Check PM agent exists
kugetsu-helper check-status
# Should output: ok
```

## Step 8: Test via Telegram

Start a conversation with your bot (@your_bot_username):

| Message | Expected |
|---------|----------|
| `hi` | Responds directly (small talk) |
| `status?` | Routes to PM Agent |
| `fix issue #5` | Routes to PM Agent |

## Troubleshooting

### kugetsu-helper not found
```bash
export PATH="$HOME/.local/bin:$PATH"
# Or add to ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

### Gateway not responding
```bash
hermes gateway restart
```

### PM agent missing
```bash
# Reinitialize
kugetsu destroy --pm-agent -y
kugetsu init
```

## 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 |

## Architecture Summary

```
~/.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/
├── sessions/
│   ├── base.json             # Base opencode session
│   └── pm-agent.json         # PM Agent opencode session
└── index.json                # Session registry

~/.local/bin/
└── kugetsu-helper            # CLI helper script
```

## Testing Plan (Manual)

### 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"
```

## 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