kugetsu/skills/kugetsu-pm/SKILL.md

---
name: kugetsu-pm
description: PM (Project Manager) Agent skill for kugetsu. Handles task coordination, delegation, and notifications.
license: MIT
compatibility: Requires kugetsu CLI, opencode sessions, Gitea API access.
metadata:
  author: shoko
  version: "2.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/PR updates
4. **Notifies** users of task completion and status changes
5. **Maintains** context across interactions

## Architecture

```
User (Telegram) → Hermes → Chat Agent → PM Agent
                                          │
                                          ├── kugetsu start → Dev Agent
                                          │                   └── Work on issue
                                          │
                                          └── notify ← Gitea (optional)
                                                     └── ~/.kugetsu/notifications.json
```

## Notification System

PM Agent notifies users via two channels:

### 1. Local Notifications (Default)
- PM Agent writes to `~/.kugetsu/notifications.json`
- Hermes/Chat Agent reads this file when user sends a message
- User can view with `kugetsu notify list`

### 2. Gitea Comments (When Available)
- If task is issue/PR-related, PM Agent posts to Gitea
- User receives notification via Gitea's native notification system
- If Gitea is unavailable, PM Agent logs to notifications.json with a note

### Notification Triggers

| Event | Action |
|-------|--------|
| Task assigned to Dev Agent | Write to notifications.json |
| Task completed (PR merged/closed) | Write to notifications.json + Gitea |
| Task blocked | Write to notifications.json |
| Dev agent needs review | Two options: review immediately OR ask dev if ready |

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

PM Agent monitors Gitea for task completion by checking:
- Issue comments
- PR commits
- PR status (merged/open)

**Query pattern for completion:**
```bash
# Check if issue/PR has recent activity
curl -s "https://git.fbrns.co/api/v1/repos/{owner}/{repo}/issues/{number}/comments"
# Check for commits in PR branch
```

### 6. Review Decision

When dev agent signals completion, PM Agent chooses:

**Option A: Review immediately**
- PM Agent reviews the PR/changes
- If good, merges or approves
- If issues, posts review comments

**Option B: Ask dev if ready**
- PM Agent posts comment: "Dev work complete. Please review and confirm if ready for merge."
- Waits for dev agent confirmation
- Then proceeds with review

### 7. Notify on Completion

After task completion:
1. Write to `~/.kugetsu/notifications.json`
2. Post to Gitea issue/PR comment (if available)
3. If Gitea fails, note in notifications.json

**Notification format:**
```json
{
  "type": "task_complete",
  "message": "Issue #5 fixed. PR #12 created and merged.",
  "issue_ref": "github.com/shoko/kugetsu#5",
  "gitea_url": "https://git.fbrns.co/shoko/kugetsu/pulls/12",
  "timestamp": "2026-03-31T10:00:00Z"
}
```

## Delegation Commands

### Send message to PM Agent
```bash
kugetsu delegate "<message>"
```

### Create Dev Agent Session
```bash
kugetsu start <issue-ref> "<task>"
```

### Continue Dev Agent Session
```bash
kugetsu continue <issue-ref> "<update>"
```

### Check Notifications
```bash
kugetsu notify list
kugetsu notify clear
```

## 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."
"Dev work ready for review. Merging PR #12."
```

## Error Handling

### Dev Agent Failure
- Analyze failure reason
- Retry or escalate to user
- Log to notifications.json

### 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
- Log to notifications.json (user will be notified there)

## Implementation Notes

### PM Agent Session ID

The PM Agent session is stored in:
```
~/.kugetsu/index.json → "pm_agent" field
```

### PM Context File (Optional)

Customize PM Agent behavior by creating:
```
~/.kugetsu/pm-agent.md
```

This file is injected into the PM Agent session at init time.

### Notifications File

Location: `~/.kugetsu/notifications.json`

Format:
```json
[
  {
    "type": "task_complete|task_blocked|task_assigned",
    "message": "Human-readable message",
    "issue_ref": "github.com/user/repo#5",
    "gitea_url": "https://git.fbrns.co/user/repo/pulls/5",
    "timestamp": "ISO8601",
    "read": false
  }
]
```

## Related Documentation

- [kugetsu-architecture.md](../../docs/kugetsu-architecture.md)
- [kugetsu-chat.md](../../docs/kugetsu-chat.md)
- [kugetsu-chat-setup.md](../../docs/kugetsu-chat-setup.md)
- [hermes-setup.md](../../docs/hermes-setup.md)