From 3cf738041706b7f72a46f6de398f74202c186393 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Fri, 27 Mar 2026 09:57:58 +0000 Subject: [PATCH] docs: add initial Kugetsu architecture and update README --- README.md | 41 ++-- docs/_index.md | 6 + docs/kugetsu-architecture.md | 363 +++++++++++++++++++++++++++++++++++ 3 files changed, 397 insertions(+), 13 deletions(-) create mode 100644 docs/kugetsu-architecture.md diff --git a/README.md b/README.md index 25cf1c8..69abf7d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/_index.md b/docs/_index.md index a32a237..c566d42 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -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 | diff --git a/docs/kugetsu-architecture.md b/docs/kugetsu-architecture.md new file mode 100644 index 0000000..390857b --- /dev/null +++ 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