orchestra-docs

Orchestra Documentation

When to Apply

Activate this skill when:

• Finding or reading documentation for any Orchestra component
• Writing or updating documentation
• Answering questions about architecture, APIs, or configuration
• Understanding how components relate to each other
• The user asks "how does X work" for any Orchestra component

Documentation Map

Root-Level Docs

Framework Docs (docs/)

MCP Plugin Docs (plugins/mcp/)

Architecture Overview

Orchestra MCP is a Go + Rust + React monorepo with a plugin-first architecture.

orchestra-mcp/
├── app/plugins/          # Plugin runtime (Go) — the foundation
├── config/plugins.go     # Plugin registry config
├── plugins/              # All plugins live here
│   └── mcp/              # MCP Plugin (first plugin, standalone Go module)
├── cmd/server/           # Go backend entry point
├── engine/               # Rust engine (gRPC)
├── resources/            # Frontend monorepo (React/TypeScript)
├── tests/                # Test suite (unit + feature + testutil)
├── docs/                 # Framework documentation
├── proto/                # Protobuf definitions
└── database/             # PostgreSQL migrations

Plugin System (Go)

Every feature is a plugin. The runtime lives at app/plugins/ (8 files):

Plugin contracts:

• Plugin — ID, Name, Version, Dependencies, Activate, Deactivate
• HasRoutes — register Fiber routes
• HasConfig — ConfigKey, DefaultConfig
• HasCommands — CLI commands
• HasMcpTools — MCP tools
• HasMigrations, HasMiddleware, HasJobs, HasSchedule, HasServices
• Contributable — commands, menus, settings, keybindings
• HasFeatureFlag — feature flag gating
• Marketable — marketplace listing
• HasDesktopViews, HasChromeViews, HasWebViews — platform views

MCP Plugin

Standalone Go module at plugins/mcp/ (github.com/orchestra-mcp/mcp).

• 40 tools: project (5), epic (5), story (5), task (5), workflow (5), PRD (7), bugfix (2), usage (3), readme (1), artifacts (2)
• Dual-mode: standalone stdio CLI + integrated Go plugin with REST API
• Extensible: other plugins push tools via RegisterExternalTools()
• Build: cd plugins/mcp && go build -o orchestra-mcp ./src/cmd/

Plugin Folder Convention

Every plugin follows this structure (can be pushed as standalone GitHub repo):

plugins/{name}/
  go.mod                    # Standalone module
  config/                   # Plugin config structs
  providers/                # Plugin registration (bridges to app/plugins)
  src/                      # All source code
  resources/                # Bundled assets (skills, agents, views)
  tests/                    # Test suite (unit + feature)
  docs/                     # Plugin documentation
  README.md

Test Structure

tests/                      # Framework tests
  unit/plugins/             # Plugin runtime unit tests
  feature/plugins/          # Integration tests
  testutil/                 # Shared test helpers (MockPlugin, NewManager)

plugins/mcp/tests/          # MCP plugin tests
  unit/{package}/           # Unit tests by source package
  feature/                  # Integration tests

Code Quality

Three tools enforce code quality across all Go code:

Full pipeline: make check = format check + lint + tests.

Linter config excludes old-ref/ and vendor/, and relaxes errcheck/unparam/goconst for test files.

Rust Engine

CPU-heavy operations at engine/ — Tree-sitter, Tantivy, tower-lsp, rusqlite. Go communicates via gRPC.

Frontends

5 React apps in resources/ sharing @orchestra/shared and @orchestra/ui:

• desktop/ (Wails), extension/ (Chrome), dashboard/ (Web), admin/, mobile/ (React Native)

Writing New Documentation

1. Every plugin gets a README.md at its root
2. Framework-level guides go in docs/guides/
3. API references go in docs/api/
4. Plugin-specific docs go in plugins/{name}/docs/
5. Use tables for config, tools, and API references
6. Link between related docs across components