202d8ccfbb
- 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)
419 lines
17 KiB
Markdown
419 lines
17 KiB
Markdown
# Kugetsu Architecture
|
|
|
|
**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
|
|
|
|
**Kugetsu** (月掴) is derived from Jujutsu Kaisen's "Tokusa no Kage Boujutsu" (术式使用・影法术, Shadow Art Style) — a technique that summons shadow creatures from the user's shadow. The term "Kugetsu" (月掴) roughly translates to "grasping the moon," evoking the imagery of pulling beings from the darkness.
|
|
|
|
In JJK, this technique allows a user to summon up to ten different creatures (Kuchisake, Nagameru, etc.), each with unique abilities. This perfectly embodies the core concept of **multi-agent orchestration**: one orchestrator managing multiple specialized agents working in parallel.
|
|
|
|
### 1.2 Concept
|
|
|
|
Kugetsu is an agent orchestration system that enables parallel task execution across multiple repositories. Inspired by the IT department metaphor, it provides a hierarchical structure where:
|
|
|
|
- **Human** acts as the executive/manager overseeing the department
|
|
- **PM (Project Manager) Agent** coordinates and delegates tasks
|
|
- **Coding Agents** execute tasks autonomously on their assigned issues
|
|
|
|
The system transforms single-threaded issue resolution into a collaborative, parallel workflow — similar to how Hermes runs multiple tasks concurrently, Kugetsu scales this to multiple specialized agents.
|
|
|
|
### 1.3 Goals
|
|
|
|
1. **Parallelization**: Enable multiple issues to be worked on simultaneously
|
|
2. **Scalability**: Support multiple repositories from a single interface
|
|
3. **Autonomy with Safety**: Agents commit freely to feature branches; humans approve final merges
|
|
4. **Research-Driven**: Understand and potentially extend agent framework limits (e.g., Hermes 3-task cap)
|
|
|
|
### 1.4 IT Department Metaphor
|
|
|
|
Traditional workflow (single developer):
|
|
```
|
|
You → Analyze Issue → Propose Solution → Implement → Review → Merge
|
|
(one issue at a time, across one or many repos)
|
|
```
|
|
|
|
Kugetsu workflow (agent team):
|
|
```
|
|
You (Executive)
|
|
└── PM Agent (Project Manager)
|
|
├── Coding Agent A → Issue 1 → PR
|
|
├── Coding Agent B → Issue 2 → PR
|
|
├── Coding Agent C → Issue 3 → PR
|
|
└── ... (up to machine capacity)
|
|
```
|
|
|
|
Your focus shifts from doing to overseeing — reviewing PRs, approving plans, managing priorities.
|
|
|
|
---
|
|
|
|
## 2. Architecture
|
|
|
|
### 2.1 High-Level Components
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Human (Executive) │
|
|
│ Final approval, strategic decisions │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
Task approval / Plan review
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Hermes / OpenClaw (Orchestrator + Gateway) │
|
|
│ - Spawn/manage agents │
|
|
│ - Message passing between PM and Coding Agents │
|
|
│ - Repository access via Git API │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────┴───────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────────────┐ ┌─────────────────────────┐
|
|
│ PM Agent (Repo A) │◄──►│ PM Agent (Repo B) │
|
|
│ - Split tasks │ │ - Split tasks │
|
|
│ - Prioritize issues │ │ - Coordinate cross-repo│
|
|
│ - Review PRs │ │ - Create release branches│
|
|
│ - Merge to release │ │ │
|
|
└─────────────────────────┘ └─────────────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Coding Agents │
|
|
│ - Work autonomously on assigned issues │
|
|
│ - Branch per issue, commit/push freely │
|
|
│ - Create PR to release branch │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 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)
|
|
- **Scope**: One or more repositories
|
|
- **Responsibilities**:
|
|
- Monitor issues (via Git API)
|
|
- Prioritize: Security → Bugs → Features/Research
|
|
- Split tasks into actionable units
|
|
- Submit task-split plan for human approval
|
|
- Assign tasks to Coding Agents
|
|
- Review PRs from Coding Agents
|
|
- Merge PRs into release branch
|
|
- Create final PR to master/main (requires human approval)
|
|
- Coordinate with other PMs for cross-repo dependencies
|
|
|
|
#### Coding Agent
|
|
- **Scope**: One issue in one repository at a time
|
|
- **Responsibilities**:
|
|
- Analyze issue and repo context
|
|
- Read repo-specific coding guidelines
|
|
- Create feature branch
|
|
- Implement solution autonomously
|
|
- Commit and push freely to feature branch
|
|
- Create PR to release branch
|
|
- Respond to feedback (PM or human comments)
|
|
- If stalled/failed: analyze, replan, retry or abandon
|
|
|
|
### 2.3 Communication Protocols
|
|
|
|
- **PM → Human**: Task-split plans, final PR approvals, escalations
|
|
- **PM → Coding Agent**: Task assignments, feedback on PRs
|
|
- **Coding Agent → PM**: Task completion, PR status, blockers
|
|
- **PM ↔ PM**: Cross-repo dependencies, shared resources
|
|
- **Human → Coding Agent**: Optional inline PR comments (via PM relay)
|
|
|
|
---
|
|
|
|
## 3. Human Interaction Points
|
|
|
|
### 3.1 Required Touchpoints
|
|
|
|
| Point | Description |
|
|
|-------|-------------|
|
|
| **Task-Split Approval** | Before execution, PM presents plan to split issue into tasks. Human approves or adjusts. |
|
|
| **Final Merge Approval** | PM creates PR to master/main. Human reviews and merges. |
|
|
|
|
### 3.2 Optional Touchpoints
|
|
|
|
| Point | Description |
|
|
|-------|-------------|
|
|
| **Inline PR Feedback** | Human (or PM) can comment on PR. Coding Agent responds. |
|
|
| **Priority Override** | Human can reprioritize issues at any time. |
|
|
| **Direct Agent Command** | Human can send instructions to PM or Coding Agent (experimental). |
|
|
|
|
---
|
|
|
|
## 4. Workflows
|
|
|
|
### 4.1 Issue Lifecycle
|
|
|
|
```
|
|
Issue Created
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ PM Detection │ ← PM monitors via Git API
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Prioritization│ ← Security > Bugs > Features > Research
|
|
└─────────────────┘ (Critical > High > Medium > Low)
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Task Splitting │ ← PM analyzes and plans
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Human Approval │ ← Human reviews task-split plan
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Agent Assignment│ ← PM assigns to Coding Agent(s)
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Implementation │ ← Coding Agent works autonomously
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ PR Creation │ ← Coding Agent → Release Branch
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ PM Review │ ← PM reviews PR
|
|
└─────────────────┘
|
|
│
|
|
├─► Request changes ──► Implementation
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ PM Merge │ ← PM merges to Release Branch
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Release Branch │ ← PM collects PRs for version
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Human Final │ ← Human approves PR to master/main
|
|
│ Approval │
|
|
└─────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Merged! │
|
|
└─────────────────┘
|
|
```
|
|
|
|
### 4.2 Priority & Ordering
|
|
|
|
Priority order:
|
|
1. **Security** (vulnerabilities, secrets exposure)
|
|
2. **Bugs** (crashes, data loss, critical functionality)
|
|
3. **Features** (new functionality)
|
|
4. **Research** (investigations, spikes)
|
|
|
|
Severity order within each category:
|
|
1. **Critical** — Revenue-impacting, security holes
|
|
2. **High** — Major functionality broken
|
|
3. **Medium** — Non-critical bugs, minor features
|
|
4. **Low** — Cosmetic, nice-to-have
|
|
|
|
*Note: Documentation tasks can bypass standard ordering as they are typically quick to resolve.*
|
|
|
|
### 4.3 Cross-Repo Dependencies
|
|
|
|
When Repo A requires a feature from Repo B:
|
|
|
|
```
|
|
PM Repo A ──► Creates issue in Repo B ──► PM Repo B
|
|
│
|
|
◄── Coordinates ────►
|
|
```
|
|
|
|
PMs communicate to align on implementation and timelines.
|
|
|
|
---
|
|
|
|
## 5. Coding Guidelines
|
|
|
|
### 5.1 Storage
|
|
|
|
- Each repository has its own `CODING_GUIDELINES.md` (or similar)
|
|
- A base template is provided in the Kugetsu root/repository
|
|
- Repo-specific guidelines override base template
|
|
|
|
### 5.2 Base Template Structure
|
|
|
|
```
|
|
# Coding Guidelines
|
|
|
|
## Style
|
|
- Language-specific conventions
|
|
- Naming conventions
|
|
|
|
## Process
|
|
- Commit message format
|
|
- Branch naming convention
|
|
- PR requirements
|
|
|
|
## Quality
|
|
- Test coverage expectations
|
|
- Documentation requirements
|
|
|
|
## Security
|
|
- No hardcoded secrets
|
|
- Input validation
|
|
```
|
|
|
|
### 5.3 Agent Initialization
|
|
|
|
When a Coding Agent starts, it:
|
|
1. Clones/fetches the repository
|
|
2. Reads `CODING_GUIDELINES.md` (falls back to base template if missing)
|
|
3. Applies guidelines throughout implementation
|
|
|
|
---
|
|
|
|
## 6. PoC Scope & Success Criteria
|
|
|
|
### 6.1 Phases Summary
|
|
|
|
| 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 Current Implementation
|
|
|
|
- **1 Repository** (kugetsu)
|
|
- **Session Manager**: kugetsu CLI
|
|
- **Agent Framework**: opencode
|
|
- **Access**: SSH + Tailscale (Phase 1)
|
|
- **Communication Hub**: Gitea Issues/PRs
|
|
|
|
### 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.5 Future Phases
|
|
|
|
- Multiple PMs coordinating
|
|
- Distributed/multi-machine setup
|
|
- Custom agent framework development
|
|
- Security hardening
|
|
|
|
---
|
|
|
|
## 7. Open Questions & Research Items
|
|
|
|
### 7.1 Active Research
|
|
|
|
| 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 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 |
|
|
|------|----------|
|
|
| **PM persistence** | Stateful (resumes where left off) or stateless (re-reads issue state)? |
|
|
| **Agent isolation** | Separate processes, containers, or something else? |
|
|
| **Checkpointing** | Should agents save progress mid-task? |
|
|
| **Notification system** | How does human get alerted for approvals? |
|
|
|
|
---
|
|
|
|
## 8. Terminology
|
|
|
|
| Term | Definition |
|
|
|------|------------|
|
|
| **Kugetsu** | The orchestration system itself |
|
|
| **PM Agent** | Project Manager agent responsible for task coordination |
|
|
| **Coding Agent** | Agent that implements solutions to issues |
|
|
| **Release Branch** | Branch where PM collects PRs before final merge |
|
|
| **Task-Split Plan** | PM's proposed breakdown of an issue into actionable tasks |
|
|
| **Hermes/OpenClaw** | Agent frameworks that Kugetsu leverages |
|
|
|
|
---
|
|
|
|
## Status History
|
|
|
|
- 2026-03-30: Added Phase 3 architecture notes, updated status
|
|
- 2026-03-27: Initial architecture draft
|