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

docs: add initial Kugetsu architecture and update README

Browse Source
This commit is contained in:
shokollm
2026-03-27 09:57:58 +00:00
parent d023b6258d
commit 3cf7380417
3 changed files with 397 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@@ -1,22 +1,37 @@
# kugetsu
# Kugetsu
Research notes and documentation repository.
> **Name background:** _to be documented_
> **Name background:** Kugetsu (月掴, "grasping the moon") is derived from Jujutsu Kaisen's "Tokusa no Kage Boujutsu" (Shadow Art Style) — a technique that summons up to ten different creatures from the user's shadow. This project embodies the concept of one orchestrator managing multiple specialized agents working in parallel.
## Overview
This repository contains research findings, experiments, and documentation on various topics.
Kugetsu is an **agent orchestration system** that enables parallel task execution across multiple repositories. Inspired by the IT department metaphor:
## Structure
- **Human** acts as executive, reviewing and approving
- **PM (Project Manager) Agent** coordinates and delegates tasks
- **Coding Agents** execute tasks autonomously on assigned issues
```
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── docs/
└── ...
```
The core idea: instead of working through issues one-by-one, a PM spawns multiple coding agents in parallel — similar to Hermes running multiple tasks, but scaled to a full team workflow.
## Why
When you have 10 issues, typically you work through them sequentially. With Kugetsu:
- PM prioritizes and splits tasks
- Coding agents work in parallel on their own branches
- PM reviews and merges to a release branch
- Human provides final approval to master/main
This means your focus shifts from doing to overseeing — reviewing PRs, not writing code.
## Status
**Phase 1: Research & PoC**
Current focus: Documenting architecture and researching Hermes/OpenClaw capabilities for multi-agent parallelization.
## Documentation
- [Architecture](./docs/kugetsu-architecture.md) — Full system design
- [Research Index](./docs/_index.md) — All research topics
## License

6
docs/_index.md
View File

@@ -4,6 +4,12 @@ Overview of research topics and notes.
## Topics
### Architecture
| Topic | Status | Last Updated |
|-------|--------|--------------|
| [Kugetsu Architecture](./kugetsu-architecture.md) | In Progress | 2025-03-27 |
### AI Agents
| Topic | Status | Last Updated |

363
docs/kugetsu-architecture.md Normal file
View File

@@ -0,0 +1,363 @@
# Kugetsu Architecture
**Date:** 2025-03-27
**Status:** In Progress
## 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.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 Initial PoC Setup
- **1 Repository**
- **1 PM Agent**
- **Multiple Coding Agents** (up to machine capacity)
- **Tools**: Hermes (primary), OpenClaw (secondary/test)
### 6.2 Research Goals
| 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? |
### 6.3 Success Criteria
- [ ] 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
### 6.4 Out of Scope (Phase 1)
- Multiple PMs coordinating
- Distributed/multi-machine setup
- Custom agent framework development
- Security hardening
---
## 7. Open Questions & Research Items
### 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? |
### 7.2 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
- 2025-03-27: Initial architecture draft