shoko/kugetsu
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(phase3): add notification system and kugetsu notify command

Browse Source 
Phase 3c implementation - Notification System:

### New kugetsu commands:
- `kugetsu notify list` - Show unread notifications from PM Agent
- `kugetsu notify clear` - Mark notifications as read

### Notification system:
- PM Agent writes task events to ~/.kugetsu/notifications.json
- Events: task_complete, task_blocked, task_assigned
- Supports issue_ref and gitea_url for linking
- Hermes/Chat Agent reads notifications on user messages

### kugetsu-pm v2.0:
- Updated documentation with notification behavior
- PM Agent monitors Gitea for task completion
- Two review modes: PM reviews immediately OR asks dev if ready
- Notification triggers documented

### File renamed:
- phase3a-setup.md → kugetsu-chat-setup.md (more descriptive)

### Hermes gateway analysis:
- Gateway is a client (connects to Telegram), not a server
- Cannot push messages directly to Telegram from external process
- Notifications stored locally for Hermes to pick up on next user message
This commit is contained in:
shokollm
2026-03-31 02:19:50 +00:00
parent b3171ed632
commit 3d00ddbc1b
3 changed files with 255 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
skills/kugetsu-pm/SKILL.md
View File

@@ -1,11 +1,11 @@
---
name: kugetsu-pm
description: PM (Project Manager) Agent skill for kugetsu. Handles task coordination, delegation, and Gitea integration.
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: "1.0"
version: "2.0"
---
# kugetsu-pm - PM Agent Skill
@@ -18,37 +18,44 @@ 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)
3. **Monitors** Gitea for issue/PR updates
4. **Notifies** users of task completion and status changes
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)
User (Telegram) → Hermes → Chat Agent → PM Agent
│
├── kugetsu start → Dev Agent
│ └── Work on issue
│
└── notify ← Gitea (optional)
└── ~/.kugetsu/notifications.json
```
## PM Agent Modes
## Notification System
| Mode | Behavior | Command |
|------|----------|---------|
| **notify** (default) | Send completion notifications | "pm notify" |
| **silent** | Work quietly, no notifications | "pm silent" |
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
@@ -79,77 +86,73 @@ PM Agent decides:
kugetsu start <issue-ref> "<task description>"
```
### 5. Monitor and Notify
### 5. Monitor for Completion
- PM monitors Gitea for PR status
- When complete, notifies user (if in notify mode)
PM Agent monitors Gitea for task completion by checking:
- Issue comments
- PR commits
- PR status (merged/open)
## 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"
]
}
**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
```
### Active Tasks
```json
{
"tasks": {
"issue-5": {
"status": "in_progress",
"dev_agent": "ses_xyz789",
"created_at": "2026-03-30T10:00:00Z"
}
}
}
```
### 6. Review Decision
### Notification Preferences
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
{
"mode": "notify"
"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
### Create Dev Agent Session
### 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>"
```
### List Active Sessions
### Check Notifications
```bash
kugetsu list
kugetsu notify list
kugetsu notify clear
```
## Response Format
@@ -165,6 +168,7 @@ PM Agent responses should be:
"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
@@ -172,7 +176,7 @@ PM Agent responses should be:
### Dev Agent Failure
- Analyze failure reason
- Retry or escalate to user
- Log to Gitea issue comment
- Log to notifications.json
### Session Not Found
- Check kugetsu status: `kugetsu list`
@@ -182,18 +186,7 @@ PM Agent responses should be:
### 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
- Log to notifications.json (user will be notified there)
## Implementation Notes
@@ -204,15 +197,36 @@ The PM Agent session is stored in:
~/.kugetsu/index.json → "pm_agent" field
```
### Accessing PM Agent
### PM Context File (Optional)
```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>"
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)
- [hermes-setup.md](../../docs/hermes-setup.md)
- [kugetsu-chat-setup.md](../../docs/kugetsu-chat-setup.md)
- [hermes-setup.md](../../docs/hermes-setup.md)