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

feat(phase3): Full Phase 3 implementation - Chat Agent, PM Agent, and Integration #32

Merged
shoko merged 14 commits from feat/issue-19-phase3 into main 2026-03-31 04:55:21 +02:00
Conversation 4 Commits 14 Files Changed 11 +1157 -53
shoko commented 2026-03-30 17:42:01 +02:00
Owner
Copy Link

Summary

Phase 3: Chat Integration implementation covering all phases (3a, 3b, 3c).

Phase 3a: Chat Agent Infrastructure ✅

  • kugetsu-chat skill: Entry point for Telegram routing
  • SOUL.md: Routing instructions for Hermes
  • kugetsu-chat-setup.md: Installation guide

Phase 3b: PM Agent & kugetsu CLI Extensions ✅

  • kugetsu status - Check initialization status
  • kugetsu delegate <msg> - Send message to PM Agent
  • kugetsu doctor [--fix] - Diagnose and fix issues
  • Inject kugetsu-pm at init time (once, not per-delegation)
  • Remove strict issue-ref format validation in kugetsu continue

Phase 3c: Notification System ✅

  • PM Agent writes to ~/.kugetsu/notifications.json on task events
  • kugetsu notify list - View unread notifications
  • kugetsu notify clear - Mark notifications as read
  • Gitea integration for persistent notifications (when available)
  • kugetsu-pm v2.0 updated with notification behavior documentation
  • Two review modes: PM reviews immediately OR asks dev if ready

Architecture

User (Telegram) → Hermes → kugetsu-chat skill
                        │
                        └── kugetsu delegate "<message>"
                                │
                                └── PM Agent (opencode session)
                                        │
                                        ├── PM context injected at init
                                        │
                                        ├── kugetsu start <issue-ref> <task>
                                        │         └── Dev Agent session
                                        │
                                        └── notify → ~/.kugetsu/notifications.json
                                                  └── Gitea (optional)

New kugetsu Commands

Command Description
kugetsu status Check initialization status
kugetsu delegate <msg> Send message to PM Agent
kugetsu doctor [--fix] Diagnose and fix issues
kugetsu notify list Show unread notifications
kugetsu notify clear Mark notifications as read

PM Agent Notification Flow

  1. Task assigned → Write to notifications.json
  2. Task completed → Write to notifications.json + Gitea (if issue/PR)
  3. Task blocked → Write to notifications.json
  4. Gitea failure → Write to notifications.json with note

Changes in this PR

  1. kugetsu CLI extended with status, delegate, doctor [--fix], notify commands
  2. PM Context Injection: kugetsu init reads ~/.kugetsu/pm-agent.md and injects into PM session at creation
  3. Notification System: PM Agent writes events to ~/.kugetsu/notifications.json
  4. kugetsu-chat v3.0: Updated to use kugetsu delegate instead of kugetsu-helpers
  5. kugetsu continue: Removed strict issue-ref validation, now accepts any tracked session name
  6. kugetsu-pm v2.0: Updated documentation with notification behavior

Testing

kugetsu status           # Should return: ok
kugetsu doctor           # Should show diagnosis
kugetsu doctor --fix     # Should attempt fixes
kugetsu delegate "test"  # Should delegate to PM agent
kugetsu notify list      # Should show unread notifications

Related Issues

  • Closes #19 (Phase 3: Chat Integration) - Full implementation
## Summary Phase 3: Chat Integration implementation covering all phases (3a, 3b, 3c). ### Phase 3a: Chat Agent Infrastructure ✅ - **kugetsu-chat skill**: Entry point for Telegram routing - **SOUL.md**: Routing instructions for Hermes - **kugetsu-chat-setup.md**: Installation guide ### Phase 3b: PM Agent & kugetsu CLI Extensions ✅ - [x] `kugetsu status` - Check initialization status - [x] `kugetsu delegate <msg>` - Send message to PM Agent - [x] `kugetsu doctor [--fix]` - Diagnose and fix issues - [x] Inject kugetsu-pm at init time (once, not per-delegation) - [x] Remove strict issue-ref format validation in kugetsu continue ### Phase 3c: Notification System ✅ - [x] PM Agent writes to `~/.kugetsu/notifications.json` on task events - [x] `kugetsu notify list` - View unread notifications - [x] `kugetsu notify clear` - Mark notifications as read - [x] Gitea integration for persistent notifications (when available) - [x] kugetsu-pm v2.0 updated with notification behavior documentation - [x] Two review modes: PM reviews immediately OR asks dev if ready ### Architecture ``` User (Telegram) → Hermes → kugetsu-chat skill │ └── kugetsu delegate "<message>" │ └── PM Agent (opencode session) │ ├── PM context injected at init │ ├── kugetsu start <issue-ref> <task> │ └── Dev Agent session │ └── notify → ~/.kugetsu/notifications.json └── Gitea (optional) ``` ### New kugetsu Commands | Command | Description | |---------|-------------| | `kugetsu status` | Check initialization status | | `kugetsu delegate <msg>` | Send message to PM Agent | | `kugetsu doctor [--fix]` | Diagnose and fix issues | | `kugetsu notify list` | Show unread notifications | | `kugetsu notify clear` | Mark notifications as read | ### PM Agent Notification Flow 1. Task assigned → Write to `notifications.json` 2. Task completed → Write to `notifications.json` + Gitea (if issue/PR) 3. Task blocked → Write to `notifications.json` 4. Gitea failure → Write to `notifications.json` with note ### Changes in this PR 1. **kugetsu CLI extended** with `status`, `delegate`, `doctor [--fix]`, `notify` commands 2. **PM Context Injection**: kugetsu init reads `~/.kugetsu/pm-agent.md` and injects into PM session at creation 3. **Notification System**: PM Agent writes events to `~/.kugetsu/notifications.json` 4. **kugetsu-chat v3.0**: Updated to use `kugetsu delegate` instead of kugetsu-helpers 5. **kugetsu continue**: Removed strict issue-ref validation, now accepts any tracked session name 6. **kugetsu-pm v2.0**: Updated documentation with notification behavior ### Testing ```bash kugetsu status # Should return: ok kugetsu doctor # Should show diagnosis kugetsu doctor --fix # Should attempt fixes kugetsu delegate "test" # Should delegate to PM agent kugetsu notify list # Should show unread notifications ``` ### Related Issues - Closes #19 (Phase 3: Chat Integration) - Full implementation
shoko added 5 commits 2026-03-30 17:42:01 +02:00
feat(phase3a): initial Chat Agent infrastructure 60181afe6a 
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
fix(phase3a): separate SOUL.md personality from SKILL.md routing 7c94a59bb6 
- SOUL.md: only personality/voice guidance (no routing logic)
- SKILL.md: definitive routing behavior + delegation process
- Add context passing via temp file for long tasks
- Add error handling table with user-friendly messages

This aligns with Hermes docs: SOUL.md = identity, SKILL.md = behavior
docs: add Phase 3a installation guide and update install script 227ec3a22e 
- docs/phase3a-setup.md - Complete installation guide for Phase 3a
- skills/kugetsu/scripts/kugetsu-install.sh - Updated to reflect v2.2 changes
feat(phase3a): add strong routing instructions to SOUL.md f8070246c8 
- SOUL.md now explicitly instructs Hermes to ALWAYS use kugetsu-helper for delegation
- Clear delegation rules with examples
- Separation of casual conversation vs delegation

This is the first attempt at making Hermes route via kugetsu-helper automatically.
feat(phase3a): update SKILL.md and SOUL.md with stronger routing instructions a6bbd969b6 
- SKILL.md: More explicit about MUST use this skill for delegation
- SOUL.md: Explicitly instruct to invoke /kugetsu-chat skill first
- Add more explicit delegation rules and error handling
shoko added 1 commit 2026-03-30 17:52:41 +02:00
fix(phase3a): add fix-permissions command to kugetsu-helper 6db33ea786 
Add kugetsu_fix_pm_permissions function to fix opencode session permissions
for /tmp/kugetsu directory access. This resolves permission issues when
PM agent tries to access worktree directories.

Usage: kugetsu-helper fix-permissions
shoko added 1 commit 2026-03-31 01:00:42 +02:00
docs(phase3): update status and add testing plan ef1179839d
han commented 2026-03-31 01:41:16 +02:00
First-time contributor
Copy Link

in the phase3a-setup, why the dir variable name is KUGEETSU_DIR? why the double E? I am just asking, you don't need to fix it

in the phase3a-setup, why the dir variable name is KUGEETSU_DIR? why the double E? I am just asking, you don't need to fix it
han commented 2026-03-31 01:43:04 +02:00
First-time contributor
Copy Link

| Chat Agent SOUL | ~/.hermes/SOUL-chat.md | Personality |

is SOUL.md is really necessary in this case? does SOUL-chat.md is being read by Hermes? what do you think?

> | Chat Agent SOUL | `~/.hermes/SOUL-chat.md` | Personality | is SOUL.md is really necessary in this case? does SOUL-chat.md is being read by Hermes? what do you think?
shoko added 1 commit 2026-03-31 02:02:31 +02:00
test(kugetsu-helpers): add unit test suite and fix None/null handling bc3cc8dd1e 
- Add test suite at skills/kugetsu-helpers/tests/test-kugetsu-helpers.sh
- 11 unit tests covering check-status, delegate-to-pm, get-pm-session, etc.
- Fix bug: Python print(None) outputs literal "None" string, not empty
- All tests pass
han commented 2026-03-31 02:07:45 +02:00
First-time contributor
Copy Link

opencode run --continue --session "$pm_session" "$task" 2>&1

in the kugetsu-helpers, why does it use opencode CLI instead of using the kugetsu CLI? kugetsu CLI is wrapper of opencode CLI that handle custom sessions, also should handle git worktree etc. can you run deep analysis to compare and suggest if we should keep both kugetsu-helpers and kugetsu? also do we still keep need kugetsu-helpers to run opencode cli directly instead of kugetsu cli? take your time. ask any clarifying question as you need

> opencode run --continue --session "$pm_session" "$task" 2>&1 in the kugetsu-helpers, why does it use opencode CLI instead of using the kugetsu CLI? kugetsu CLI is wrapper of opencode CLI that handle custom sessions, also should handle git worktree etc. can you run deep analysis to compare and suggest if we should keep both kugetsu-helpers and kugetsu? also do we still keep need kugetsu-helpers to run opencode cli directly instead of kugetsu cli? take your time. ask any clarifying question as you need
shoko changed title from feat(phase3): Chat Agent integration with kugetsu routing to feat(phase3): Full Phase 3 implementation - Chat Agent, PM Agent, and Integration 2026-03-31 02:56:20 +02:00
shoko added 1 commit 2026-03-31 03:09:21 +02:00
feat(kugetsu): add status, delegate, doctor commands; inject PM context at init b3171ed632 
This commit implements Phase 3b/3c architectural improvements:

### New kugetsu CLI commands:
- `kugetsu status` - Check initialization status (replaces kugetsu-helper check-status)
- `kugetsu delegate <msg>` - Send message to PM agent (new command)
- `kugetsu doctor [--fix]` - Diagnose and fix kugetsu issues

### PM Context Injection:
- kugetsu init now reads ~/.kugetsu/pm-agent.md (if exists) and injects
  it into the PM agent session at creation time
- PM context is loaded ONCE at init, not on every delegation
- This improves efficiency - kugetsu-pm content read once, not 10 times

### kugetsu-chat updated:
- Now uses `kugetsu delegate` instead of kugetsu-helper
- Now uses `kugetsu status` instead of kugetsu-helper check-status
- Simplified - no longer depends on kugetsu-helpers

### kugetsu continue:
- Removed strict issue-ref format validation
- Now accepts any session name that is tracked in index.json["issues"]
- Issue-ref format is a guideline, not a hard requirement

### Documentation updated:
- phase3a-setup.md - Updated to reflect new kugetsu commands
- kugetsu-install.sh - Simplified Phase 3a setup instructions

### Breaking changes:
- kugetsu-helpers is no longer required for Phase 3a Chat Agent
- kugetsu-chat skill v3.0 now requires kugetsu CLI with new commands
shoko added 1 commit 2026-03-31 04:19:58 +02:00
feat(phase3): add notification system and kugetsu notify command 3d00ddbc1b 
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
shoko added 1 commit 2026-03-31 04:38:50 +02:00
refactor: restructure PM role under skills/kugetsu/pm/ bc40c4f500 
### 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)
shoko added 1 commit 2026-03-31 04:46:51 +02:00
docs: replace git.fbrns.co with git.example.com in documentation d35f006ed2 
Sensitive URL replaced to prevent accidental exposure.
shoko added 1 commit 2026-03-31 04:48:32 +02:00
refactor: remove obsolete kugetsu-helpers skill 93ebb55f57 
kugetsu-helpers was a shim layer that is no longer needed since:
- kugetsu status replaces check-status
- kugetsu delegate replaces delegate-to-pm
- kugetsu doctor --fix replaces fix-permissions
- kugetsu list/start/continue cover remaining functions

All functionality is now in the kugetsu CLI directly.
shoko added 1 commit 2026-03-31 04:52:39 +02:00
test(kugetsu): add unit tests for status, delegate, doctor, notify commands 9e1ff74330 
Added 10 new tests:
- kugetsu status (5 tests): uninitialized, base missing, pm-agent missing, Python None handling, session expired
- kugetsu delegate (2 tests): no message, pm-agent missing
- kugetsu doctor (1 test): basic command execution
- kugetsu notify (2 tests): list with no file, clear with no file

Total tests: 38 (all passing)
han approved these changes 2026-03-31 04:54:27 +02:00
han left a comment
First-time contributor
Copy Link

lgtm

lgtm
shoko merged commit 08e40e5396 into main 2026-03-31 04:55:21 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
han
Labels
Clear labels
0.2.x-only
Available only in 0.2.x, not backportable
 0.3.x-only
Available only in 0.3.x, not backportable
 backport
Backport compatible - can merge to 0.1.x
 blocked
Issue needs clarification/discussion before it can be worked on
 bug
Bug report
 critical
Critical - blocking parallel work
 feature
New feature
 foundation
Foundation work for 0.2.x
 high
High priority - workflow improvements
 meta
Meta issue tracking multiple issues
 need-review
PR needs review before merge
 parallelization
Issues related to parallelization
 ready
Issue is clear and ready to be implemented/delegated
 ready-to-merge
PR approved and ready to merge
 task-delegation
Issues related to task-delegation
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
shoko
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: shoko/kugetsu#32
Delete Branch "feat/issue-19-phase3"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?