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 notifications.	MIT	Requires kugetsu CLI, opencode sessions, Gitea API access.	author version shoko 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

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:

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

{
  "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

kugetsu delegate "<message>"

Create Dev Agent Session

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

Continue Dev Agent Session

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

Check Notifications

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:

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