feat(phase3a): initial Chat Agent infrastructure
Phase 3a implementation - Hermes Chat Agent configuration: - kugetsu-chat/SOUL.md - Chat Agent persona and routing logic - kugetsu-chat/SKILL.md - Chat Agent skill documentation - kugetsu-chat/scripts/setup - Configuration setup script - kugetsu-pm/SKILL.md - PM Agent skill documentation - kugetsu-helpers/SKILL.md - Helper tools for Hermes-kugetsu integration - kugetsu-helpers/scripts/kugetsu-helpers - Shell functions for delegation Provides: - Intent classification (small talk, task, status, mode change) - PM Agent delegation via terminal() - kugetsu status checking - Session management helpers
This commit is contained in:
shokollm
218
skills/kugetsu-pm/SKILL.md
Normal file
218
skills/kugetsu-pm/SKILL.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user