kugetsu/skills/kugetsu-pm/SKILL.md

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