Kuroryuu Multi-Agent Orchestration Patterns

Kuroryuu is a multi-agent orchestration system enabling Claude Code instances to coordinate as leaders and workers. This skill provides comprehensive guidance on patterns, protocols, and common workflows.

Quick Reference Index

Bootstrap Questions

Question	Answer Location
How do I start a session?	`KURORYUU_BOOTSTRAP.md` → Session Start section
What's the difference between leader/worker?	`KURORYUU_LEADER.md` vs `KURORYUU_WORKER.md`
How do I become a leader?	Run `/k-leader` or read `KURORYUU_LEADER.md`
How do I become a worker?	Run `/k-worker` or read `KURORYUU_WORKER.md`
What's the PRD-first workflow?	`KURORYUU_LEADER.md` → PRD-First Workflow section
How do I save my progress?	Run `/k-save` or use `k_checkpoint(action="save")`
How do I restore a checkpoint?	Run `/k-load` or use `k_checkpoint(action="load")`

MCP Tools Quick Reference

Tool	Purpose	Primary Actions
`k_session`	Session lifecycle	start, status, end
`k_checkpoint`	State persistence	save, load, list
`k_inbox`	Message queue	send, list, read, claim, complete
`k_rag`	Semantic search	search, index
`k_memory`	Working memory	write, read, list
`k_pty`	PTY control (all agents)	spawn_cli, talk, send_line
`k_files`	File operations	read, write, list

Architecture Documents

Document	Location	Purpose
Bootstrap	`KURORYUU_BOOTSTRAP.md`	Session start procedure
Leader Protocol	`KURORYUU_LEADER.md`	Leader responsibilities
Worker Protocol	`KURORYUU_WORKER.md`	Worker responsibilities
Laws	`KURORYUU_LAWS.md`	Operational rules
Laws Index	`KURORYUU_LAWS_INDEX.md`	Quick law lookup
Architecture	`Docs/Plans/LEADER_FOLLOWER_ARCHITECTURE.md`	System design

Core Concepts

Role Hierarchy

code

HUMAN
  │ (asks questions, approves plans)
  ▼
LEADER (one per orchestration)
  │ (delegates tasks, asks humans)
  ▼
WORKERS (many)
  │ (execute tasks, report progress)

Key Principle: Workers NEVER ask humans directly. All human interaction flows through the leader.

Session Lifecycle

code

1. Agent starts → Read KURORYUU_BOOTSTRAP.md
2. Determine role → Read KURORYUU_LEADER.md or KURORYUU_WORKER.md
3. Call k_session(action="start") → Get session_id
4. Register with Gateway → POST /v1/agents/register
5. Work loop → Execute tasks based on role
6. Save checkpoint → k_checkpoint(action="save")
7. End session → k_session(action="end")

Promise Protocol

Workers communicate status to leaders using promise tags:

Promise Tag	Meaning	Leader Action
`<promise>DONE</promise>`	Task complete	Check if all done → finalize
`<promise>PROGRESS:N%</promise>`	Partial progress	Wait for more iterations
`<promise>BLOCKED:reason</promise>`	External blocker	Investigate, clarify
`<promise>STUCK:reason</promise>`	Can't proceed	Send hint via leader_nudge.md

Common Workflows

Starting a New Session

•Read bootstrap: KURORYUU_BOOTSTRAP.md
•Determine role (first agent = leader, others = workers)

•Start session:

code

k_session(action="start", process_id="claude_code", agent_type="claude")

•Register role:

code

POST http://127.0.0.1:8200/v1/agents/register
{ "role": "leader", "agent_id": "<session_agent_id>" }

•Confirm: KURORYUU-aware. Role: leader. Session: <id>. Ready.

Saving Work (Checkpoint)

•Gather context summary

•Save checkpoint:

code

k_checkpoint(
  action="save",
  name="session",
  payload={
    "description": "Work description",
    "context_summary": "What was accomplished"
  }
)

•Optionally write worklog to Docs/worklogs/

Sending Tasks (Leader → Worker)

•Create task via inbox:

code

k_inbox(
  action="send",
  to="worker-1",
  subject="Implement feature X",
  body="Details of what to implement..."
)

•Monitor for promise responses
•If worker stuck, send hint

Receiving Tasks (Worker)

•Poll inbox:

code

k_inbox(action="list", filter="to:me,status:new")

•Claim task:

code

k_inbox(action="claim", message_id="<id>")

•Execute task
•Report progress: <promise>PROGRESS:50%</promise>

•Complete:

code

k_inbox(action="complete", message_id="<id>")

•Report done: <promise>DONE</promise>

Searching Codebase (RAG)

•Query RAG index:

code

k_rag(action="search", query="authentication flow", top_k=5)

•Review results with source files and snippets
•Read relevant files for full context

Leader-Only Operations

These operations require leader role:

PTY Control

Spawn and control worker CLIs:

code

k_pty(action="spawn_cli", cli_provider="claude", role="worker")
k_pty(action="talk", session_id="<id>", command="Implement feature X")

Task Orchestration

Create and manage tasks:

code

POST /v1/orchestration/tasks { "title": "...", "subtasks": [...] }
POST /v1/orchestration/subtasks/<id>/hint { "hint": "Try approach X" }

Prompt Files Reference

Leader prompts in ai/prompts/leader/:

Prompt	Purpose
`leader_prime.md`	Load context, check PRD
`leader_plan_feature.md`	Create implementation plan
`leader_breakdown.md`	Convert plan to subtasks
`leader_nudge.md`	Help stuck workers
`leader_finalize.md`	Complete task, trigger reviews
`leader_escalate.md`	Escalate to human
`leader_pty_module.md`	PTY control patterns

Worker prompts in ai/prompts/worker/:

Prompt	Purpose
`worker_execute.md`	Execute assigned task
`worker_report.md`	Report progress

Context Management

80% Threshold Rule

At 80% context usage (20% remaining):

•Check ai/context_check.png for context percentage
•Run /k-save immediately
•Consider ending session

Automatic Checkpoints

Save checkpoints:

•Every ~50 tool calls
•Before ending session
•When switching major tasks
•Before complex operations

Troubleshooting

MCP Tools Unavailable

•Check stack: .\run_all.ps1
•Verify MCP: claude mcp list
•Restart MCP server if needed

Gateway Unavailable

•Check Gateway: http://127.0.0.1:8200/health
•Start stack: .\run_all.ps1
•Use MCP tools directly as fallback

Session Lost

•List checkpoints: k_checkpoint(action="list")
•Load latest: k_checkpoint(action="load", checkpoint_id="latest")
•Resume from checkpoint context

Additional Resources

For detailed patterns and advanced techniques:

•references/tool-patterns.md - Detailed MCP tool usage patterns
•references/orchestration-patterns.md - Multi-agent coordination patterns

For working examples:

•<PROJECT_ROOT>\.claude\agents\ - Agent definitions
•<PROJECT_ROOT>\ai\prompts\ - Prompt templates
•<PROJECT_ROOT>\apps\mcp_core\tools_*.py - MCP tool implementations