17 KiB
17 KiB
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.
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
- Parallelization: Enable multiple issues to be worked on simultaneously
- Scalability: Support multiple repositories from a single interface
- Autonomy with Safety: Agents commit freely to feature branches; humans approve final merges
- 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 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:
- Security (vulnerabilities, secrets exposure)
- Bugs (crashes, data loss, critical functionality)
- Features (new functionality)
- Research (investigations, spikes)
Severity order within each category:
- Critical — Revenue-impacting, security holes
- High — Major functionality broken
- Medium — Non-critical bugs, minor features
- 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:
- Clones/fetches the repository
- Reads
CODING_GUIDELINES.md(falls back to base template if missing) - 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 | 🔄 In Progress | 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? | Phase 3a Testing |
6.4 Success Criteria
- kugetsu CLI manages sessions properly
- Remote access via SSH works
- 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