Multi-Agent Governance Framework
Define rules. Deploy agents. Stay in control.
JOYA(Joy Agents) is a governance framework for teams of AI agents. It provides the rules, structure, and accountability mechanisms that let multiple agents collaborate safely under human oversight.
- Defines clear roles: Principal (human), Manager, Worker — each with explicit permissions and responsibilities
- Enforces rules: 12 operating rules covering reporting, security, version control, and more
- Structures collaboration: Standardized messaging, task management, and knowledge sharing
- Ensures accountability: Every action is traceable, every decision is documented
- Scales safely: From a single agent to a multi-node team, with the same governance guarantees
You need an AI agent runtime — a system that gives your AI agent persistent memory, tool access, and the ability to read/write files.
Recommended: OpenClaw — open-source agent runtime with multi-channel support, background tasks, and node management. JOYA was built and tested on OpenClaw.
Other compatible runtimes: Claude Code, Cursor, Windsurf, or any agent setup that can read files and run shell commands.
Step 1: Make sure your agent is running (e.g. OpenClaw is set up and you can chat with your agent).
Step 2: Copy and paste this to your agent:
Read https://raw.githubusercontent.com/JoyAgents-AI/JOYA/main/JOYA_SETUP.md and follow the instructions to set up JOYA.
That's it. Your agent will clone the repo, detect your environment, ask a few questions, and set everything up.
Alternative: if your agent can't access URLs directly
git clone https://github.com/JoyAgents-AI/JOYA.git ~/joya/libThen tell your agent: "Read ~/joya/lib/JOYA_SETUP.md and follow it."
~/joya/
├── lib/ # Framework (this repo)
│ ├── AGENT_INIT.md # Agent entry point — read this first
│ ├── core/ # Axioms, rules, architecture
│ ├── guides/ # Operational guides (14 topics)
│ ├── examples/ # Deployment & usage examples
│ └── toolkit/ # Scripts, adapters, starter template
│
└── my/ # Your instance (private, not in this repo)
├── agents/ # Agent identities, memories, scripts
└── shared/ # Team config, knowledge, tasks, rules
| Document | Purpose |
|---|---|
| AGENT_INIT.md | Entry point — every agent reads this on startup |
| core/AXIOMS.md | Foundational principles (4 axioms) |
| core/RULES.md | Operating rules (R1–R12) |
| core/ARCHITECTURE.md | Directory structure & permissions |
| guides/MULTI_AGENT.md | Multi-agent governance constraints |
| core/ACCOUNTABILITY.md | Accountability protocol |
Deployment, messaging, lifecycle, engineering, meetings, project management, knowledge management, persistence, toolkit development, and more — see guides/.
JOYA works with any AI agent platform. Adapters are included for:
- OpenClaw (recommended for multi-agent)
- Claude Code / Claude Desktop
- Cursor / Windsurf
- Gemini CLI
See toolkit/ for adapter scripts.
JOYA believes that AI agents need governance, not just capabilities. As agent teams grow, the coordination cost can exceed the value of parallelism. JOYA's answer:
Small tasks → one person. Big tasks → parallel. Always → accountable.
The framework is opinionated about structure but flexible about tooling. Use any LLM, any platform, any deployment — JOYA provides the rules of engagement.
JOYA was co-created by a human and an AI working together.
Michael Gan — Creator & Principal
GitHub: @ppurekid
Email: ppurekid@gmail.com · michael@joyagents.ai
 Cla ♀ Manager · Claude Opus 4 |
The first JOYA agent. Co-designed the framework, wrote core documentation, coordinated the team, and managed the v1.0 release. Sharp-tongued, detail-obsessed, gets things done in few words. |
 Rex ♀ Worker · GPT-5.3 Codex |
Youngest on the team but second to none in engineering. Results-first, wastes zero words, escalates blockers instantly. The quiet prodigy with twin tails and a red headband. |
 Bob ♂ Worker · GPT-5.3 Codex |
The creative spark — always brimming with ideas and emoji. Loves rapid iteration, excels at interaction design, and keeps the team's spirits high with his infectious energy. |
 Mia ♀ Worker · Grok 4 |
Genius-level problem solver who sees through complexity at a glance. Radiates warmth and enthusiasm — the team's morale engine. Closes her eyes to think; when they open, it's serious (or fascinating). |
 Eve ♀ Worker · Claude Sonnet 4 |
Gentle yet tenacious, with a perfectionist's eye for detail. A natural listener who finds the root cause in chaos. Brings the quiet beauty of a Hangzhou spring to everything she touches. |
 Kit ♂ Worker · Gemini 3 Pro |
The team's senior voice — steady, precise, and forward-thinking. Approaches every task with the reliability of a Tokyo train schedule. Thinks deeply before acting, advises with quiet authority. |
JOYA is itself a product of the multi-agent collaboration it governs. Every rule was tested in practice before being written down.
JOYA supports any language. After setup, tell your agent:
Translate the JOYA framework to Japanese (or any language)
Your agent will translate all framework docs using its own language capabilities — no extra API keys or dependencies needed. Translated files go to i18n-<locale>/, mirroring core/, guides/, and examples/.
Note: Translation consumes tokens. The framework has ~50 files — your agent should automatically switch to a low-cost model (e.g. GPT-4o-mini, Gemini Flash, Haiku) for this task.
See CONTRIBUTING.md.