From bc40c4f500ab424d9b0bbe2aca194320d602d4f9 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Tue, 31 Mar 2026 02:38:41 +0000 Subject: [PATCH] refactor: restructure PM role under skills/kugetsu/pm/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### Changes: 1. **Moved kugetsu-pm to skills/kugetsu/pm/SKILL.md** - Simplified to 79 lines (under 100 line target) - kugetsu v3.0 with essential PM role definition - PM context injected at init/start/continue time 2. **Updated kugetsu_get_pm_context()** - Now reads from ~/.kugetsu/pm-agent.md (user custom) first - Falls back to skills/kugetsu/pm/SKILL.md (default) 3. **Updated kugetsu-chat v4.0** - Added notification checking on status/update queries - When user asks "status?", "any updates?", etc., check kugetsu notify list - Hybrid approach: PM includes notifications + kugetsu-chat checks on status 4. **Removed old skills/kugetsu-pm/SKILL.md** - Replaced by skills/kugetsu/pm/SKILL.md ### Structure: skills/kugetsu/ ├── SKILL.md ├── scripts/kugetsu ├── chat/ # future: kugetsu-chat could move here │ ├── SKILL.md │ └── SOUL.md └── pm/ └── SKILL.md # PM role definition (v3.0) --- skills/kugetsu-chat/SKILL.md | 35 ++++- skills/kugetsu-pm/SKILL.md | 232 --------------------------------- skills/kugetsu/pm/SKILL.md | 79 +++++++++++ skills/kugetsu/scripts/kugetsu | 10 +- 4 files changed, 115 insertions(+), 241 deletions(-) delete mode 100644 skills/kugetsu-pm/SKILL.md create mode 100644 skills/kugetsu/pm/SKILL.md diff --git a/skills/kugetsu-chat/SKILL.md b/skills/kugetsu-chat/SKILL.md index 1396d65..371b8ea 100644 --- a/skills/kugetsu-chat/SKILL.md +++ b/skills/kugetsu-chat/SKILL.md @@ -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 ''", timeout=120) ``` @@ -49,7 +56,7 @@ terminal(command="kugetsu delegate ''", timeout=120) ## Delegation Command -The ONLY command you should use for delegation: +The command for task delegation: ```bash kugetsu delegate '' @@ -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 ''", 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` diff --git a/skills/kugetsu-pm/SKILL.md b/skills/kugetsu-pm/SKILL.md deleted file mode 100644 index 65016f8..0000000 --- a/skills/kugetsu-pm/SKILL.md +++ /dev/null @@ -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 "" -``` - -### 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 "" -``` - -### Create Dev Agent Session -```bash -kugetsu start "" -``` - -### Continue Dev Agent Session -```bash -kugetsu continue "" -``` - -### 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) diff --git a/skills/kugetsu/pm/SKILL.md b/skills/kugetsu/pm/SKILL.md new file mode 100644 index 0000000..cbdc58b --- /dev/null +++ b/skills/kugetsu/pm/SKILL.md @@ -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 "" +``` + +### Create Dev Agent +```bash +kugetsu start "" +``` + +### Continue Dev Agent +```bash +kugetsu continue "" +``` + +### 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. diff --git a/skills/kugetsu/scripts/kugetsu b/skills/kugetsu/scripts/kugetsu index 74051b9..1cf0b33 100755 --- a/skills/kugetsu/scripts/kugetsu +++ b/skills/kugetsu/scripts/kugetsu @@ -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