kugetsu/docs/kugetsu-architecture.md

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

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 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

• 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