kugetsu/skills/kugetsu-pm/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
kugetsu-pm	PM (Project Manager) Agent skill for kugetsu. Handles task coordination, delegation, and Gitea integration.	MIT	Requires kugetsu CLI, opencode sessions, Gitea API access.	author version shoko 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

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

{
  "repos": [
    "github.com/shoko/kugetsu",
    "gitlab.com/team/core"
  ]
}

Active Tasks

{
  "tasks": {
    "issue-5": {
      "status": "in_progress",
      "dev_agent": "ses_xyz789",
      "created_at": "2026-03-30T10:00:00Z"
    }
  }
}

Notification Preferences

{
  "mode": "notify"
}

Delegation Commands

Create Dev Agent Session

kugetsu start <issue-ref> "<task>"

Continue Dev Agent Session

kugetsu continue <issue-ref> "<update>"

List Active Sessions

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

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
• kugetsu-chat.md
• hermes-setup.md