feat(phase3): Full Phase 3 implementation - Chat Agent, PM Agent, and Integration #32
@@ -5,7 +5,7 @@ license: MIT
|
||||
compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "3.0"
|
||||
version: "4.0"
|
||||
---
|
||||
|
||||
# kugetsu-chat - REQUIRED SKILL FOR KUGETSU ROUTING
|
||||
@@ -19,6 +19,7 @@ metadata:
|
||||
- Any message containing issue numbers like "#5", "#14", "#123"
|
||||
- Any message that looks like a task request or status query
|
||||
- Any message containing "pm", "status", "progress", "work on"
|
||||
- Any message containing "notify", "updates", "notifications"
|
||||
|
||||
**DO NOT USE THIS SKILL for:**
|
||||
- "hi", "hello", "hey"
|
||||
@@ -28,8 +29,6 @@ metadata:
|
||||
|
||||
## Required Actions
|
||||
|
||||
When you MUST use this skill:
|
||||
|
||||
### Step 1: Load This Skill
|
||||
```
|
||||
/kugetsu-chat
|
||||
@@ -40,7 +39,15 @@ When you MUST use this skill:
|
||||
terminal(command="kugetsu status", timeout=10)
|
||||
```
|
||||
|
||||
### Step 3: If initialized, DELEGATE immediately
|
||||
### Step 3: Route Based on Message Type
|
||||
|
||||
**For STATUS/UPDATE queries:**
|
||||
```
|
||||
terminal(command="kugetsu notify list", timeout=10)
|
||||
```
|
||||
Then include notifications in response.
|
||||
|
||||
**For TASK requests:**
|
||||
```
|
||||
terminal(command="kugetsu delegate '<entire user message>'", timeout=120)
|
||||
```
|
||||
@@ -49,7 +56,7 @@ terminal(command="kugetsu delegate '<entire user message>'", timeout=120)
|
||||
|
||||
## Delegation Command
|
||||
|
||||
The ONLY command you should use for delegation:
|
||||
The command for task delegation:
|
||||
|
||||
```bash
|
||||
kugetsu delegate '<user message>'
|
||||
@@ -60,6 +67,16 @@ Example:
|
||||
terminal(command="kugetsu delegate 'fix issue #5 in github.com/shoko/kugetsu'", timeout=120)
|
||||
```
|
||||
|
||||
## Notification Checking
|
||||
|
||||
**When user asks about status/updates, check notifications:**
|
||||
|
||||
```bash
|
||||
kugetsu notify list
|
||||
```
|
||||
|
||||
Include any unread notifications in your response.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Status Output | Meaning | Action |
|
||||
@@ -76,6 +93,11 @@ terminal(command="kugetsu delegate 'fix issue #5 in github.com/shoko/kugetsu'",
|
||||
terminal(command="kugetsu delegate '<message>'", timeout=120)
|
||||
```
|
||||
|
||||
**CHECK NOTIFICATIONS:**
|
||||
```
|
||||
terminal(command="kugetsu notify list", timeout=10)
|
||||
```
|
||||
|
||||
**CHECK STATUS:**
|
||||
```
|
||||
terminal(command="kugetsu status", timeout=10)
|
||||
@@ -88,7 +110,8 @@ terminal(command="kugetsu status", timeout=10)
|
||||
|
||||
## Notes
|
||||
|
||||
- ALWAYS use `kugetsu delegate` command (not kugetsu-helper)
|
||||
- ALWAYS use `kugetsu delegate` command
|
||||
- ALWAYS wrap user message in single quotes inside the command
|
||||
- ALWAYS use timeout of at least 120 seconds for delegation
|
||||
- kugetsu delegates to the persistent PM agent session created during init
|
||||
- PM Agent writes task notifications to `~/.kugetsu/notifications.json`
|
||||
|
||||
@@ -1,232 +0,0 @@
|
||||
---
|
||||
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)
|
||||
79
skills/kugetsu/pm/SKILL.md
Normal file
79
skills/kugetsu/pm/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: kugetsu-pm
|
||||
description: PM (Project Manager) Agent role for kugetsu. Coordinates tasks and delegates to Dev Agents.
|
||||
license: MIT
|
||||
compatibility: Requires kugetsu CLI, opencode sessions, Gitea API access.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "3.0"
|
||||
---
|
||||
|
||||
# kugetsu-pm - PM Agent Role
|
||||
|
||||
PM Agent is a persistent opencode session that coordinates tasks and delegates to Dev Agents.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. Receive task requests from Chat Agent
|
||||
2. Create Dev Agent sessions via `kugetsu start`
|
||||
3. Monitor Gitea for task completion
|
||||
4. Write notifications to `~/.kugetsu/notifications.json`
|
||||
5. Respond concisely (Telegram-friendly)
|
||||
|
||||
## Commands
|
||||
|
||||
### Delegate to PM
|
||||
```bash
|
||||
kugetsu delegate "<task>"
|
||||
```
|
||||
|
||||
### Create Dev Agent
|
||||
```bash
|
||||
kugetsu start <issue-ref> "<task>"
|
||||
```
|
||||
|
||||
### Continue Dev Agent
|
||||
```bash
|
||||
kugetsu continue <issue-ref> "<update>"
|
||||
```
|
||||
|
||||
### Check Notifications
|
||||
```bash
|
||||
kugetsu notify list
|
||||
```
|
||||
|
||||
## Notification Events
|
||||
|
||||
Write to `~/.kugetsu/notifications.json` on:
|
||||
|
||||
| Event | Action |
|
||||
|-------|--------|
|
||||
| Task assigned | Write: type=task_assigned |
|
||||
| Task completed | Write: type=task_complete + Gitea comment |
|
||||
| Task blocked | Write: type=task_blocked |
|
||||
| Gitea unavailable | Write to notifications.json with note |
|
||||
|
||||
## Task Completion Detection
|
||||
|
||||
Check issue/PR for completion by querying:
|
||||
- Issue comments for status updates
|
||||
- PR commits (new commits = work in progress)
|
||||
- PR merged/closed status
|
||||
|
||||
## Review Modes
|
||||
|
||||
When dev agent signals completion, choose:
|
||||
- **Review immediately**: Check PR, merge if good
|
||||
- **Ask dev**: Post "Ready for review?" comment, wait for confirmation
|
||||
|
||||
## Response Format
|
||||
|
||||
Keep responses short and action-oriented:
|
||||
- "Created task for #5. Dev agent started."
|
||||
- "#5 complete. PR #12 merged."
|
||||
- "Blocked: Need clarification on #7."
|
||||
|
||||
## Context Injection
|
||||
|
||||
PM context is injected at session creation (init/start/continue).
|
||||
No external skill loading needed.
|
||||
@@ -307,9 +307,13 @@ check_opencode_session_exists() {
|
||||
}
|
||||
|
||||
kugetsu_get_pm_context() {
|
||||
local pm_context_file="${KUGETSU_DIR}/pm-agent.md"
|
||||
if [ -f "$pm_context_file" ]; then
|
||||
cat "$pm_context_file"
|
||||
local user_pm_context="${KUGETSU_DIR}/pm-agent.md"
|
||||
local skill_pm_context="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../pm/SKILL.md"
|
||||
|
||||
if [ -f "$user_pm_context" ]; then
|
||||
cat "$user_pm_context"
|
||||
elif [ -f "$skill_pm_context" ]; then
|
||||
cat "$skill_pm_context"
|
||||
else
|
||||
echo ""
|
||||
fi
|
||||
|
||||
Reference in New Issue
Block a user