A lightweight multi-agent orchestration system for OpenCode
Delegate. Coordinate. Verify. You direct, agents code.

---

中文文档

Why Pomelo?

OpenCode lets you talk to an AI. Pomelo turns it into a team. Instead of one agent trying to do everything — planning, coding, reviewing — Pomelo splits the work across 6 specialized agents, each with its own role, toolset, and expertise boundary.

┌─────────────────────────────────────────────────┐
│                    pomelo                         │
│              🍊  Multi-Agent Orchestration         │
├─────────────────────────────────────────────────┤
│                                                   │
│   ┌───────────────────────────┐                   │
│   │  pomelo-orchestrator       │                   │
│   │  "Director, not actor"    │                   │
│   │  🚫 No write/edit          │                   │
│   │  ✅ Delegate, Review, Ship │                   │
│   └─────┬──────┬──────┬──────┘                   │
│         │      │      │                          │
│    ┌────▼─┐ ┌─▼──┐ ┌─▼────────┐                 │
│    │backend│ │docs│ │frontend  │                 │
│    │ 🖥️   │ │ 📝 │ │ 🎨      │                 │
│    └──────┘ └────┘ └──────────┘                 │
│         │                                        │
│    ┌────▼────────┐ ┌─────────────┐               │
│    │  reviewer    │ │code-reviewer│               │
│    │  🧐 Plans    │ │ 🔍 Code     │               │
│    └─────────────┘ └─────────────┘               │
│                                                   │
│   ┌───────────────────────────┐                   │
│   │  Session Ledger            │                   │
│   │  📋 Auto-track todos      │                   │
│   │  🔗 Link spec→plan→session │                   │
│   │  ⏪ Context recovery       │                   │
│   └───────────────────────────┘                   │
└─────────────────────────────────────────────────┘

What you get

Capability	How
Task delegation	1 orchestrator → 5 sub-agents
Plan-driven development	Brainstorm → Plan → Review → Execute
Automatic todo tracking	Hook captures todowrite → Ledger
Deep code review	15 language-specific checklists
Config auto-merge	Default → Global → Project (3 layers)
Asset sync	Prompts, commands, guides → auto-synced
Context recovery	Post-compaction restart reminders

---

How it works

Agent Collaboration

User: "Add authentication to my app"
              │
              ▼
┌──────────────────────────────────────┐
│      pomelo-orchestrator              │
│  (Director — no code, only decisions) │
├──────────────────────────────────────┤
│ 1. Recognize intent → "Open-ended"   │
│ 2. brainstorming() → auth spec       │
│ 3. writing-plans() → task breakdown  │
│ 4. pomelo_review_plan() → PASS       │
│ 5. delegate_task(backend)            │
│    delegate_task(frontend)           │
│ 6. verification-before-completion()  │
└──┬──────┬──────────┬─────────────────┘
   │      │          │
   ▼      ▼          ▼
┌──────┐ ┌──────┐ ┌──────────┐
│backend│ │docs  │ │frontend  │
│models,│ │API   │ │login page│
│routes │ │docs  │ │components│
│tests  │ │      │ │          │
└──────┘ └──────┘ └──────────┘
   │                 │
   ▼                 ▼
┌──────────────────────────┐
│  pomelo-code-reviewer     │
│  🔍 review-deep → PASS    │
└──────────────────────────┘
              │
              ▼
         ✅ Done.
         Session auto-marked completed.

Built-in Agents

Agent	Mode	Default Model	Tools	Does
pomelo-orchestrator	primary	gpt-5.3-codex	bash, AFT, LSP, all pomelo tools	Task decomposition, delegation, plan review, delivery acceptance
pomelo-backend	subagent	gpt-5.2-codex	write, edit, bash, AFT, LSP	Backend implementation with tests
pomelo-frontend	subagent	gpt-5.3-codex	write, edit, bash, AFT, LSP	Frontend implementation with tests
pomelo-docs	subagent	gpt-5.4-mini-fast	write, edit, AFT, LSP	Documentation generation
pomelo-reviewer	subagent	o3	ctx_search, ctx_memory, AFT, LSP	Plan review: citations, feasibility, blockers, wire-check
pomelo-code-reviewer	subagent	gpt-5.3-codex	pomelo_review_guide, AFT, LSP	Deep code review via /review-deep

Built-in Commands

Command	What it does
/init-deep	Scan project structure, score directories (17-point system), generate layered AGENTS.md knowledge base
/review-deep	Deep code review. Scope: file / directory / commit / entire project. Loads 15 language-specific checklists on demand

Review Reference Guides (15)

react · vue · typescript · java · python · go · rust · c · cpp · qt · css-less-sass · architecture-review-guide · performance-review-guide · security-review-guide · common-bugs-checklist

---

Dependencies

Required OpenCode Plugins

These must also be present in your opencode.json plugin array:

Plugin	Provides	Why Pomelo needs it
@cortexkit/aft-opencode	aft_outline, aft_zoom, aft_search, aft_safety	Agentic File Tools — agents use these to navigate project structure
@cortexkit/opencode-magic-context	ctx_search, ctx_memory, ctx_note, ctx_reduce	Session memory & context management — reviewer uses these to gather historical context

Required Superpowers Skills

Pomelo's orchestrator agent is built on the Superpowers skill system:

Skill	Phase
brainstorming	Phase 1: Requirements analysis → spec
writing-plans	Phase 2: Plan creation
executing-plans	Phase 3: Implementation execution
dispatching-parallel-agents	Phase 3: Parallel task dispatch
subagent-driven-development	Phase 3: Sub-agent driven development
test-driven-development	Phase 3: Test-first coding
systematic-debugging	Phase 3: Bug investigation
verification-before-completion	Phase 4: Acceptance
requesting-code-review	Phase 4: Code review

npm Dependencies

Package	Version
jsonc-parser	>=3.0	Runtime — JSONC config parsing
@opencode-ai/plugin	>=1.0.0	Peer — OpenCode plugin SDK

---

Installation

Add to your project's opencode.json:

{
  "plugin": [
    "@cortexkit/aft-opencode",
    "@cortexkit/opencode-magic-context",
    "@suknna/pomelo-core"
  ]
}

That's it. OpenCode auto-installs the npm package on next start, and Pomelo's postinstall hook creates ~/.config/opencode/pomelo.jsonc. No manual config merging needed — Pomelo auto-injects agent definitions, permissions, and tools.

---

Configuration

3-layer merge

DEFAULT_POMELO_CONFIG
    ↓ overridden by
~/.config/opencode/pomelo.jsonc (global)
    ↓ overridden by
.opencode/pomelo.jsonc (project)

Configuration files use JSONC (comments and trailing commas supported).

User-configurable fields

Pomelo only exposes 3 fields. Everything else (agent mode, permissions, storage paths, sync policy) is fixed internally.

{
  // ── Agent model overrides ──
  // Override model per agent. Mode (primary/subagent) comes from template frontmatter.
  "agent": {
    // "pomelo-orchestrator": { "model": "openai/gpt-5.3-codex" },
    // "pomelo-backend": { "model": "openai/gpt-5.2-codex" }
  },

  "disabled_commands": [
    // "init-deep",
    // "review-deep"
  ],
  "disabled_agents": [
    // "pomelo-docs",
    // "pomelo-code-reviewer"
  ]
}

Complete annotated example: demo/pomelo.jsonc

---

Architecture

src/
├── index.ts              Plugin entry: load config → register tools/hooks → sync assets
├── cli.ts                CLI entry: init / doctor
├── config.ts             Runtime config interface (PomeloConfig)
├── config-loader.ts      Config loading with 3-layer merge
├── default-config.ts     Built-in default config
├── tools/                4 tools exposed to agents
│   ├── delegate-task.ts           Delegate work to sub-agent
│   ├── pomelo-review-guide.ts     Load review checklists (15 guides)
│   ├── pomelo-review-plan.ts      Review plan via reviewer agent
│   └── pomelo-session-lookup.ts   Query session ledger
├── hooks/                3 lifecycle hooks
│   ├── session-start.ts           Inject restart reminder
│   ├── context-injector.ts        Inject recovery reminder on compaction
│   └── todo-ledger-sync.ts        Auto-sync todos to session ledger
├── shared/               Shared data layer
│   ├── types.ts
│   ├── session-ledger-store.ts
│   ├── compatibility-sync.ts
│   └── project-config.ts
└── compatibility/        Asset subsystem
    ├── builtin-assets.ts
    ├── sync-engine.ts
    ├── effective-assets.ts
    ├── ownership.ts
    └── doctor.ts

Startup Data Flow

Plugin starts
  ├─ 1. Load config (3-layer merge)
  ├─ 2. Init SessionLedgerStore → .pomelo_mem/session-ledger.json
  ├─ 3. Compute effective assets (filter disabled + user overrides)
  ├─ 4. Sync compatibility assets
  │     ├─ commands   → ~/.config/opencode/commands/*.md
  │     ├─ agents     → ~/.local/share/opencode/pomelo/agents/*.md
  │     ├─ templates  → ~/.local/share/opencode/pomelo/templates/*.jsonc
  │     └─ references → ~/.local/share/opencode/pomelo/references/*.md
  ├─ 5. Register tools (4 tools)
  ├─ 6. Register hooks (3 hooks)
  └─ 7. Inject agent definitions into OpenCode

---

Runtime Behavior

Postinstall (runs automatically)

1. Ensures ~/.config/opencode/ exists
2. Copies assets/pomelo.jsonc → ~/.config/opencode/pomelo.jsonc (if missing)
3. Syncs built-in command assets to ~/.config/opencode/commands/

On every plugin start

1. Syncs compatibility assets (agents, commands, references, templates)
2. Only overwrites files with Pomelo's ownership header: <!-- pomelo:asset=<kind>:<name> version=<version> -->

During session

• todowrite calls → auto-persist to session ledger
• Session compaction → inject recovery reminder + ledger summary
• All todos completed → auto-mark session as completed

---

---

Design Principles

• Orchestrator never codes — write and edit are disabled on the orchestrator agent
• No project scanning cache — AFT/LSP provide real-time structure; Pomelo stores nothing
• Single source of truth — Plan files live in docs/superpowers/plans/, not in .pomelo_mem/
• Ownership headers — Pomelo only overwrites files it created (guarded by <!-- pomelo:asset=... -->)
• KISS — No bundler, no framework, no database. Just TypeScript + OpenCode SDK.

---

Acknowledgements

• Superpowers — Skill system that drives the orchestrator's workflow (brainstorming, planning, TDD, debugging, verification)
• awesome-skills/code-review-skill — Source of the 15 language-specific review reference guides
• oh-my-openagent — Architecture inspiration for plugin-level config loading
• OpenCode — Plugin host platform
• AFT — Agentic File Tools, the structural navigation layer

---

License

MIT