docs: add Phase 3 chat architecture and overview documentation
- Add docs/kugetsu-chat.md:
- Model B architecture (separate Chat/PM agents)
- Session types (chat-agent, pm-agent, pm-agent-{repo}, issue sessions)
- Hybrid message routing
- PM Agent modes (notify/silent)
- Context management (local + Gitea fetch on-demand)
- Example flows
- Add docs/kugetsu.md:
- Overview of kugetsu system
- Quick start guide
- Links to all documentation
- Update docs/kugetsu-architecture.md:
- Add Phase 3 architecture section
- Update success criteria
- Add Phase 3 design decisions
- Add docs/telegram-setup.md:
- BotFather bot creation guide
- Security notes
- Remove ssh-keygen.sh (not needed)
This commit is contained in:
shokollm
@@ -1,8 +1,10 @@
|
||||
# Kugetsu Architecture
|
||||
|
||||
**Date:** 2025-03-27
|
||||
**Date:** 2026-03-30
|
||||
**Status:** In Progress
|
||||
|
||||
> **Note:** This document describes the overall Kugetsu architecture. For Phase 3 (Chat) specific details, see [kugetsu-chat.md](kugetsu-chat.md).
|
||||
|
||||
## 1. Overview
|
||||
|
||||
### 1.1 Background: The Name
|
||||
@@ -90,6 +92,34 @@ Your focus shifts from doing to overseeing — reviewing PRs, approving plans, m
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.1.1 Phase 3: Chat Interface (Telegram)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Human (Phone) │
|
||||
│ Telegram App │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
Telegram Protocol
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Hermes (Chat Agent Gateway - Phase 3) │
|
||||
│ - Receives Telegram messages │
|
||||
│ - Natural language interpretation │
|
||||
│ - Routes to appropriate agent │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────────────┐
|
||||
│ Chat Agent │ │ PM Agent │
|
||||
│ (casual chat) │◄───►│ (task coordination) │
|
||||
└─────────────────┘ └─────────────────────────┘
|
||||
```
|
||||
|
||||
See [kugetsu-chat.md](kugetsu-chat.md) for full Phase 3 architecture.
|
||||
|
||||
### 2.2 Agent Types
|
||||
|
||||
#### PM Agent (Project Manager)
|
||||
@@ -289,32 +319,47 @@ When a Coding Agent starts, it:
|
||||
|
||||
## 6. PoC Scope & Success Criteria
|
||||
|
||||
### 6.1 Initial PoC Setup
|
||||
### 6.1 Phases Summary
|
||||
|
||||
- **1 Repository**
|
||||
- **1 PM Agent**
|
||||
- **Multiple Coding Agents** (up to machine capacity)
|
||||
- **Tools**: Hermes (primary), OpenClaw (secondary/test)
|
||||
| Phase | Status | Description |
|
||||
|-------|--------|-------------|
|
||||
| Phase 1 | ✅ Complete | SSH + Tailscale remote access |
|
||||
| Phase 1b | ✅ Complete | Tailscale VPN setup |
|
||||
| Phase 2 | 📋 Planned | API Interface |
|
||||
| Phase 3 | 📋 Planned | Chat Integration (Telegram) |
|
||||
| Phase 4 | 📋 Planned | Web Dashboard |
|
||||
|
||||
### 6.2 Research Goals
|
||||
### 6.2 Current Implementation
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| Parallel capacity | How many Coding Agents can run simultaneously on one machine? |
|
||||
| Hermes limit | Can we bypass or modify Hermes's 3-task hard limit? |
|
||||
| OpenClaw compatibility | Does the architecture work with OpenClaw as well? |
|
||||
| Communication patterns | What works, what fails, what needs refinement? |
|
||||
- **1 Repository** (kugetsu)
|
||||
- **Session Manager**: kugetsu CLI
|
||||
- **Agent Framework**: opencode
|
||||
- **Access**: SSH + Tailscale (Phase 1)
|
||||
- **Communication Hub**: Gitea Issues/PRs
|
||||
|
||||
### 6.3 Success Criteria
|
||||
### 6.3 Research Goals
|
||||
|
||||
| Item | Description | Status |
|
||||
|------|-------------|--------|
|
||||
| Parallel capacity | How many Coding Agents can run simultaneously on one machine? | Pending |
|
||||
| Session management | Does kugetsu properly manage opencode sessions? | ✅ Working |
|
||||
| Remote access | Does SSH + Tailscale enable remote work? | ✅ Working |
|
||||
| Chat interface | Can Hermes bridge Telegram for mobile UX? | Planned (Phase 3) |
|
||||
|
||||
### 6.4 Success Criteria
|
||||
|
||||
- [x] kugetsu CLI manages sessions properly
|
||||
- [x] Remote access via SSH works
|
||||
- [x] Remote access via Tailscale works
|
||||
- [ ] PM successfully splits and assigns tasks
|
||||
- [ ] Multiple Coding Agents work in parallel
|
||||
- [ ] Coding Agents follow guidelines and create valid PRs
|
||||
- [ ] PM merges PRs to release branch
|
||||
- [ ] Human approves final merge
|
||||
- [ ] System handles at least 3 parallel agents
|
||||
- [ ] Telegram chat interface for mobile UX
|
||||
|
||||
### 6.4 Out of Scope (Phase 1)
|
||||
### 6.5 Future Phases
|
||||
|
||||
- Multiple PMs coordinating
|
||||
- Distributed/multi-machine setup
|
||||
@@ -327,14 +372,23 @@ When a Coding Agent starts, it:
|
||||
|
||||
### 7.1 Active Research
|
||||
|
||||
| Item | Question |
|
||||
|------|----------|
|
||||
| **Hermes 3-task limit** | Where does this come from? Can it be configured or bypassed? |
|
||||
| **OpenClaw parity** | Will the same architecture work with OpenClaw? |
|
||||
| **Failure recovery** | What's the best strategy for agent crashes/restarts? |
|
||||
| **Context management** | How do agents maintain context across long tasks? |
|
||||
| Item | Question | Phase |
|
||||
|------|----------|-------|
|
||||
| **Hermes 3-task limit** | Where does this come from? Can it be configured or bypassed? | Future |
|
||||
| **OpenClaw parity** | Will the same architecture work with OpenClaw? | Future |
|
||||
| **Failure recovery** | What's the best strategy for agent crashes/restarts? | All |
|
||||
| **Context management** | How do agents maintain context across long tasks? | All |
|
||||
|
||||
### 7.2 Design Decisions Pending
|
||||
### 7.2 Phase 3 Design Decisions
|
||||
|
||||
| Item | Question | Status |
|
||||
|------|---------|--------|
|
||||
| **Chat Agent implementation** | Hermes as chat agent or separate Telegram bot? | Hermes (Model A/B hybrid) |
|
||||
| **PM Agent location** | Separate opencode session or Hermes mode? | Separate session (Model B) |
|
||||
| **Session timeout** | How long until inactive sessions are paused? | Pending |
|
||||
| **Message history** | Store in Hermes context or external database? | Pending |
|
||||
|
||||
### 7.3 Design Decisions Pending
|
||||
|
||||
| Item | Question |
|
||||
|------|----------|
|
||||
@@ -360,4 +414,5 @@ When a Coding Agent starts, it:
|
||||
|
||||
## Status History
|
||||
|
||||
- 2025-03-27: Initial architecture draft
|
||||
- 2026-03-30: Added Phase 3 architecture notes, updated status
|
||||
- 2026-03-27: Initial architecture draft
|
||||
|
||||
Reference in New Issue
Block a user