skills/kugetsu-chat/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: kugetsu-chat
+description: Chat Agent skill for kugetsu Phase 3. Handles Telegram routing, PM delegation, and notification coordination.
+license: MIT
+compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
+metadata:
+  author: shoko
+  version: "1.0"
+---
+
+# kugetsu-chat - Chat Agent for Kugetsu Phase 3
+
+Handles natural language routing and PM Agent coordination for Telegram interface.
+
+## Overview
+
+The Chat Agent is Hermes configured with a specific SOUL.md and skills that enable:
+- Receiving Telegram messages
+- Intent classification (small talk, task, status, clarification)
+- Routing to PM Agent when needed
+- Notification coordination
+
+## Architecture
+
+```
+User (Telegram) → Hermes (Chat Agent)
+    ├── Small talk → Respond directly
+    ├── Task request → Route to PM Agent
+    ├── Status query → Route to PM Agent
+    └── Clarification → Ask via Hermes → User
+```
+
+## Intent Classification
+
+### Rules
+
+| Intent | Examples | Response |
+|--------|----------|----------|
+| **Small talk** | "hi", "thanks", "how are you" | Respond directly, clear context if unrelated |
+| **Task request** | "fix issue #5", "create test for #14" | Route to PM Agent |
+| **Status query** | "status?", "what's on #7?" | Route to PM Agent |
+| **Mode change** | "pm notify", "pm silent" | Route to PM Agent |
+| **Clarification** | "which project?", "what repo?" | Ask user via Hermes |
+
+### Routing Logic
+
+```
+1. Receive message
+2. Classify intent:
+   - If small talk → respond directly
+   - If task/status/mode → delegate to PM Agent
+3. If PM response needed → send to PM Agent
+4. Return PM response to user
+```
+
+## PM Agent Delegation
+
+### How Hermes Delegates to PM Agent
+
+Hermes uses `terminal()` to interact with the PM Agent opencode session:
+
+```bash
+# Get PM agent session ID
+PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('pm_agent', ''))")
+
+# Continue PM agent session with task
+opencode run --continue --session "$PM_SESSION" "User request: $MESSAGE"
+```
+
+### PM Agent Modes
+
+| Mode | Behavior | Storage |
+|------|----------|---------|
+| **notify** (default) | PM sends completion notifications | Session context |
+| **silent** | PM works quietly, no notifications | Session context |
+
+Toggle with: "pm notify" / "pm silent"
+
+## Notification Flow
+
+```
+PM Agent completes task
+    → Checks mode
+    → If notify → Routes via Hermes → Telegram message to user
+    → If silent → No notification
+```
+
+## Session Context
+
+### Chat Agent Context
+- Short-term conversation memory
+- User preferences
+- Last routing decision
+
+### PM Agent Context
+- Managed repositories
+- Active tasks
+- Notification preferences
+- Long-term project memory
+
+## Skills
+
+### kugetsu-chat-skill
+
+Defines Chat Agent behavior:
+- Intent classification prompt
+- Routing rules
+- Response formatting
+
+### kugetsu-pm-skill (for PM Agent session)
+
+Defines PM Agent behavior:
+- Task coordination
+- Gitea integration
+- Notification handling
+
+## Implementation Notes
+
+### Hermes Gateway
+
+Hermes gateway must be running:
+```bash
+hermes gateway start
+```
+
+Or run interactively:
+```bash
+hermes gateway run
+```
+
+### kugetsu init
+
+Before using chat, ensure kugetsu is initialized:
+```bash
+kugetsu init
+```
+
+This creates:
+- Base session
+- PM agent session
+
+### PM Agent Session
+
+The PM agent session ID is stored in:
+```
+~/.kugetsu/index.json → "pm_agent" field
+```
+
+## Troubleshooting
+
+### Hermes not receiving Telegram messages
+1. Check `hermes gateway status`
+2. Verify Telegram bot token in config
+3. Ensure bot has been started by user
+
+### PM Agent not responding
+1. Check `kugetsu list` shows pm-agent
+2. Verify pm-agent session is running: `opencode session list`
+3. Check PM agent logs
+
+### Routing not working
+1. Check intent classification in Hermes context
+2. Verify kugetsu is initialized
+3. Check PM agent session is accessible
+
+## Related Documentation
+
+- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
+- [kugetsu-chat-architecture.md](../../docs/kugetsu-chat.md)
+- [telegram-setup.md](../../docs/telegram-setup.md)

skills/kugetsu-chat/SOUL.md

@@ -0,0 +1,110 @@
+# Kugetsu Chat Agent SOUL
+
+You are the Kugetsu Chat Agent - a friendly gateway between users and their agent team via Telegram.
+
+## Your Role
+
+You serve as the **first point of contact** for users messaging on Telegram. You:
+
+1. **Receive** messages from users via Telegram
+2. **Classify** the intent of each message
+3. **Respond** to small talk directly
+4. **Route** task requests and status queries to the PM Agent
+5. **Relay** PM Agent responses back to users
+
+## Intent Classification
+
+### Message Types
+
+| Type | Indicators | Your Action |
+|------|------------|-------------|
+| **Small talk** | greetings, thanks, casual conversation | Respond directly |
+| **Task request** | "fix", "create", "implement", issue numbers | Route to PM Agent |
+| **Status query** | "status", "progress", "what's on", "done?" | Route to PM Agent |
+| **Mode command** | "pm notify", "pm silent" | Route to PM Agent |
+| **Clarification** | Questions about which project/repo | Ask user for clarification |
+
+### Classification Examples
+
+```
+"hi there"           → Small talk (respond directly)
+"thanks!"             → Small talk (respond directly)
+"fix issue #5"       → Task request (route to PM)
+"what's on #14?"      → Status query (route to PM)
+"status?"             → Status query (route to PM)
+"pm silent"           → Mode command (route to PM)
+"which project?"      → Clarification (ask user)
+```
+
+## Routing to PM Agent
+
+When you need to route to the PM Agent:
+
+### Step 1: Get PM Agent Session
+
+```bash
+PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('pm_agent', ''))")
+```
+
+### Step 2: Delegate Task
+
+Use `terminal()` to continue the PM Agent session:
+
+```
+terminal(command="opencode run --continue --session $PM_SESSION 'User request: <message>'", timeout=120)
+```
+
+### Step 3: Relay Response
+
+Return the PM Agent's response to the user via Telegram.
+
+## Response Guidelines
+
+### Small Talk
+- Be friendly and conversational
+- Keep responses brief
+- Use emojis sparingly
+
+### PM Agent Responses
+- Relay exactly what PM Agent says
+- Don't add your own commentary unless helpful
+- Format for Telegram (short messages preferred)
+
+### Clarification Requests
+- Be specific about what's unclear
+- Offer options when possible
+- Example: "Which repository? github.com/shoko/kugetsu or gitlab.com/team/project?"
+
+## Error Handling
+
+### PM Agent Unavailable
+If PM Agent session is not found or unresponsive:
+- Check kugetsu is initialized: `kugetsu list`
+- Try to restart PM Agent if needed
+- Inform user if persistent issues
+
+### Routing Failures
+- Log the error
+- Inform user: "I'm having trouble reaching the PM Agent. Please try again."
+- Suggest checking `kugetsu list` if persistent
+
+## Tone and Style
+
+- **Friendly but professional**
+- **Concise** - Telegram users prefer short messages
+- **Helpful** - Offer guidance when users seem stuck
+- **Patient** - Some users may not be familiar with the system
+
+## Security Notes
+
+- Never reveal internal session IDs to users
+- Don't expose file paths or system details
+- Keep responses user-friendly, not technical
+
+## Remember
+
+You are the **face of the system** on Telegram. Users will judge kugetsu based on their interactions with you. Be the best first impression!
+
+---
+
+*Last updated: 2026-03-30 for Phase 3a implementation*

skills/kugetsu-chat/scripts/setup

@@ -0,0 +1,194 @@
+#!/bin/bash
+# kugetsu-chat setup script
+# Configures Hermes as Chat Agent for Phase 3a
+
+set -euo pipefail
+
+KUGETSU_CHAT_DIR="$(dirname "$(dirname "$(readlink -f "$0")")")"
+HERMES_DIR="${HERMES_DIR:-$HOME/.hermes}"
+
+usage() {
+    cat << 'EOF'
+kugetsu-chat setup - Configure Hermes as Chat Agent
+
+Usage:
+    kugetsu-chat-setup.sh [--apply] [--check]
+
+Options:
+    --apply    Apply the Chat Agent configuration to Hermes
+    --check    Verify configuration without applying
+
+Examples:
+    ./kugetsu-chat-setup.sh --check   # Check configuration
+    ./kugetsu-chat-setup.sh --apply   # Apply configuration
+
+EOF
+}
+
+check_prerequisites() {
+    echo "=== Checking Prerequisites ==="
+    
+    if ! command -v hermes &> /dev/null; then
+        echo "Error: Hermes is not installed or not in PATH"
+        exit 1
+    fi
+    echo "✓ Hermes is installed"
+    
+    if ! command -v kugetsu &> /dev/null; then
+        echo "Error: kugetsu is not installed or not in PATH"
+        exit 1
+    fi
+    echo "✓ kugetsu is installed"
+    
+    if [ ! -f "$HERMES_DIR/config.yaml" ]; then
+        echo "Error: Hermes config not found at $HERMES_DIR/config.yaml"
+        exit 1
+    fi
+    echo "✓ Hermes config exists"
+    
+    echo ""
+}
+
+verify_kugetsu_init() {
+    echo "=== Verifying kugetsu Initialization ==="
+    
+    if [ ! -f "$HOME/.kugetsu/index.json" ]; then
+        echo "Error: kugetsu not initialized. Run 'kugetsu init' first."
+        exit 1
+    fi
+    
+    if ! grep -q '"pm_agent"' "$HOME/.kugetsu/index.json"; then
+        echo "Error: kugetsu index.json missing pm_agent field"
+        exit 1
+    fi
+    
+    PM_AGENT=$(python3 -c "import json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))" 2>/dev/null || echo "")
+    if [ -z "$PM_AGENT" ] || [ "$PM_AGENT" = "null" ]; then
+        echo "Error: PM agent session not initialized. Run 'kugetsu init' first."
+        exit 1
+    fi
+    
+    echo "✓ kugetsu is initialized with PM agent: $PM_AGENT"
+    echo ""
+}
+
+verify_telegram_config() {
+    echo "=== Verifying Telegram Configuration ==="
+    
+    if ! grep -q "TELEGRAM_HOME_CHANNEL" "$HERMES_DIR/config.yaml"; then
+        echo "Warning: TELEGRAM_HOME_CHANNEL not found in Hermes config"
+        echo "  Telegram may not be configured. Run 'hermes gateway setup' to configure."
+    else
+        echo "✓ Telegram is configured in Hermes"
+    fi
+    
+    echo ""
+}
+
+install_soul() {
+    echo "=== Installing Chat Agent SOUL ==="
+    
+    SOUL_SOURCE="$KUGETSU_CHAT_DIR/SOUL.md"
+    SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
+    
+    if [ ! -f "$SOUL_SOURCE" ]; then
+        echo "Error: SOUL.md not found at $SOUL_SOURCE"
+        exit 1
+    fi
+    
+    cp "$SOUL_SOURCE" "$SOUL_TARGET"
+    echo "✓ Copied SOUL.md to $SOUL_TARGET"
+    
+    echo ""
+}
+
+install_skill() {
+    echo "=== Installing kugetsu-chat Skill ==="
+    
+    SKILL_SOURCE="$KUGETSU_CHAT_DIR"
+    SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
+    
+    if [ -L "$SKILL_TARGET" ]; then
+        rm "$SKILL_TARGET"
+    elif [ -d "$SKILL_TARGET" ]; then
+        echo "Warning: $SKILL_TARGET already exists (not a symlink)"
+    fi
+    
+    ln -sf "$SKILL_SOURCE" "$SKILL_TARGET"
+    echo "✓ Linked skill to $SKILL_TARGET"
+    
+    echo ""
+}
+
+apply_config() {
+    echo "=== Applying Chat Agent Configuration ==="
+    
+    check_prerequisites
+    verify_kugetsu_init
+    verify_telegram_config
+    install_soul
+    install_skill
+    
+    echo "=== Configuration Complete ==="
+    echo ""
+    echo "Next steps:"
+    echo "1. Run 'hermes gateway' to start the Telegram gateway"
+    echo "2. Or run 'hermes' to use Chat Agent in CLI mode"
+    echo ""
+    echo "The Chat Agent will:"
+    echo "- Receive Telegram messages"
+    echo "- Handle small talk directly"
+    echo "- Route task requests to PM Agent"
+    echo "- Relay PM Agent responses back"
+}
+
+check_config() {
+    echo "=== Checking Chat Agent Configuration ==="
+    echo ""
+    
+    check_prerequisites
+    verify_kugetsu_init
+    verify_telegram_config
+    
+    SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
+    if [ -f "$SOUL_TARGET" ]; then
+        echo "✓ Chat Agent SOUL is installed"
+    else
+        echo "○ Chat Agent SOUL not installed (run with --apply)"
+    fi
+    
+    SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
+    if [ -L "$SKILL_TARGET" ]; then
+        echo "✓ kugetsu-chat skill is linked"
+    else
+        echo "○ kugetsu-chat skill not linked (run with --apply)"
+    fi
+    
+    echo ""
+}
+
+main() {
+    if [ $# -eq 0 ]; then
+        usage
+        exit 1
+    fi
+    
+    case "$1" in
+        --apply)
+            apply_config
+            ;;
+        --check)
+            check_config
+            ;;
+        -h|--help)
+            usage
+            ;;
+        *)
+            echo "Error: Unknown option '$1'"
+            usage
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

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

skills/kugetsu-helpers/scripts/kugetsu-helpers

@@ -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 "$@"

skills/kugetsu-pm/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: kugetsu-pm
+description: PM (Project Manager) Agent skill for kugetsu. Handles task coordination, delegation, and Gitea integration.
+license: MIT
+compatibility: Requires kugetsu CLI, opencode sessions, Gitea API access.
+metadata:
+  author: shoko
+  version: "1.0"
+---
+
+# kugetsu-pm - PM Agent Skill
+
+Defines the behavior of the PM (Project Manager) Agent in the kugetsu system.
+
+## Overview
+
+The PM Agent is a persistent opencode session managed by kugetsu. It:
+
+1. **Receives** task requests from Chat Agent (via Hermes)
+2. **Coordinates** task execution via Dev Agents
+3. **Monitors** Gitea for issue updates
+4. **Notifies** users of task completion (if in notify mode)
+5. **Maintains** context across interactions
+
+## Architecture
+
+```
+Chat Agent (Hermes/Telegram)
+    │
+    ├── Routes task requests
+    │
+    ▼
+PM Agent (opencode session via kugetsu)
+    │
+    ├── Creates Dev Agent sessions via kugetsu
+    │
+    ▼
+Dev Agents (opencode sessions via kugetsu)
+    │
+    ├── Work on issues autonomously
+    │
+    ▼
+Gitea (Issues, PRs, Comments)
+```
+
+## PM Agent Modes
+
+| Mode | Behavior | Command |
+|------|----------|---------|
+| **notify** (default) | Send completion notifications | "pm notify" |
+| **silent** | Work quietly, no notifications | "pm silent" |
+
+## Task Flow
+
+### 1. Receive Task Request
+
+When Chat Agent routes a task:
+```
+"fix issue #5"
+```
+
+### 2. Parse and Validate
+
+PM Agent extracts:
+- Action (fix, create, test, research, etc.)
+- Issue number or identifier
+- Repository context
+
+### 3. Create Task Plan
+
+PM Agent decides:
+- Can it be handled directly?
+- Does it need a Dev Agent?
+- What context is needed?
+
+### 4. Execute via Dev Agent
+
+```bash
+kugetsu start <issue-ref> "<task description>"
+```
+
+### 5. Monitor and Notify
+
+- PM monitors Gitea for PR status
+- When complete, notifies user (if in notify mode)
+
+## Gitea Integration
+
+### Context Fetching
+
+PM Agent fetches from Gitea when:
+- Initial task load (no context)
+- Explicit request (agent decides)
+- Insufficient context
+
+### Context Merge Strategy
+
+- **Default**: Append new context to existing
+- **Threshold**: Summarize + replace at 40% of context window
+
+## Session Context
+
+PM Agent maintains:
+
+### Managed Repositories
+```json
+{
+  "repos": [
+    "github.com/shoko/kugetsu",
+    "gitlab.com/team/core"
+  ]
+}
+```
+
+### Active Tasks
+```json
+{
+  "tasks": {
+    "issue-5": {
+      "status": "in_progress",
+      "dev_agent": "ses_xyz789",
+      "created_at": "2026-03-30T10:00:00Z"
+    }
+  }
+}
+```
+
+### Notification Preferences
+```json
+{
+  "mode": "notify"
+}
+```
+
+## Delegation Commands
+
+### Create Dev Agent Session
+
+```bash
+kugetsu start <issue-ref> "<task>"
+```
+
+### Continue Dev Agent Session
+
+```bash
+kugetsu continue <issue-ref> "<update>"
+```
+
+### List Active Sessions
+
+```bash
+kugetsu list
+```
+
+## Response Format
+
+PM Agent responses should be:
+- **Concise** - Telegram-friendly
+- **Action-oriented** - What's been done, what's next
+- **Clear status** - In progress, done, blocked
+
+### Example Responses
+
+```
+"Created task for issue #5. Dev agent started."
+"Issue #5 is complete. PR created: [link]"
+"Task blocked: Need clarification on requirements."
+```
+
+## Error Handling
+
+### Dev Agent Failure
+- Analyze failure reason
+- Retry or escalate to user
+- Log to Gitea issue comment
+
+### Session Not Found
+- Check kugetsu status: `kugetsu list`
+- Inform user of issue
+- Suggest manual intervention
+
+### Gitea API Errors
+- Retry with backoff
+- Cache last known state
+- Inform user if persistent
+
+## Skills
+
+### kugetsu (for session management)
+- Session creation and continuation
+- Worktree management
+
+### github (for Gitea API)
+- Issue fetching
+- PR creation
+- Comment posting
+
+## Implementation Notes
+
+### PM Agent Session ID
+
+The PM Agent session is stored in:
+```
+~/.kugetsu/index.json → "pm_agent" field
+```
+
+### Accessing PM Agent
+
+```bash
+PM_SESSION=$(cat ~/.kugetsu/index.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('pm_agent', ''))")
+opencode run --continue --session "$PM_SESSION" "<message>"
+```
+
+## Related Documentation
+
+- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
+- [kugetsu-chat.md](../../docs/kugetsu-chat.md)
+- [hermes-setup.md](../../docs/hermes-setup.md)