docs: add initial Kugetsu architecture and update README

2026-03-27 09:57:58 +00:00
parent d023b6258d
commit 3cf7380417
3 changed files with 397 additions and 13 deletions
--- a/docs/kugetsu-architecture.md
+++ b/docs/kugetsu-architecture.md
@@ -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