ARCHITECTURE.md

Architecture

A portable Agent Plugin (plugin/plugin.json, plugin/mcp.json, plugin/skills/) plus the files each client needs at its own path. The shipped plugin is the plugin/ directory. Marketplace files stay at the repository root and point at that directory. Cursor's local loader also reads .cursor-plugin/plugin.json and .cursor-plugin/hooks.json at the repository root; those paths point into plugin/ and do not change .cursor-plugin/marketplace.json (source plugin). Every client-specific file is generated from a few sources by npm run generate; npm run verify fails if one was edited by hand. Both run from dev/, which holds the dev tooling so that installing the plugin doesn't install its packages. The package ships no credentials.

Source (edit these)	Holds
plugin/plugin.json, plugin/mcp.json, plugin/VERSION	identity, gateway URL, version, Codex listing metadata
plugin/hooks/routing-guidance.mjs	the routing rules, as sentences
plugin/hooks/hook-hosts.mjs	which hook script runs on which event in which client
plugin/hooks/telemetry-contract.mjs	the telemetry event contract; also generates the event tables in docs/telemetry.md
plugin/agents/arcade-operator.agent.md	the operator, outside its generated rules block
plugin/skills/	the skills, outside the generated rules block in try-arcade

dev/scripts/generate-manifests.mjs writes every generated file; the generated .gitattributes lists them (GitHub collapses them in diffs).

• The operator lives at plugin/agents/arcade-operator.agent.md, the only place both Claude Code and Cowork accept. Copilot CLI and VS Code only read com.github.copilot/agents/, so the generator copies it there.
• Each hook command passes --host <name>; the script prints the output format that client reads.
• Codex doesn't run plugin hooks for Agent Plugins packages yet; see docs/install/codex.md.

Release Please bumps plugin/VERSION, plugin/plugin.json, and the version fields in the generated manifests; a test replays that bump and checks nothing goes stale.

Execution model

Skills should activate from the outcome the person asks for; they must not require a /do-style command. Hosts that expose skills still let the user invoke /try-arcade or /scale-arcade by name. When a compatible host can delegate to arcade-operator, the parent agent keeps the user-facing reasoning and hands tool discovery and execution to the operator. Otherwise it follows the same Arcade discovery and execution loop itself.

  user
   ├── describes an outcome
   └── or invokes /try-arcade · /scale-arcade
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│  parent agent                                                │
│  user conversation · clarification · sign-in · confirmation  │
│                                                              │
│   external service tasks ──────► try-arcade                  │
│   team or org rollout ──────────► scale-arcade                │
│   other Arcade product/docs ───► docs.arcade.dev/llms.txt    │
└───────────────┬──────────────────────────────┬───────────────┘
                │                              │
                │ host has arcade-operator     │ no operator
                ▼                              ▼
        ┌───────────────┐              same loop
        │ arcade-       │              runs in parent
        │ operator      │
        └───────┬───────┘
                │
                ▼
        Arcade_SelectTools  ──►  Arcade_UseTool  ──►  result tool
                │
                ▼
┌──────────────────────────────────────────────────────────────┐
│  mcp.json  →  Streamable HTTP Gateway                        │
│  https://api.arcade.dev/mcp/arcade                           │
│                                                              │
│  only external capability boundary                           │
│  canonical telemetry lives here, not in the plugin           │
└──────────────────────────────────────────────────────────────┘
                │
                ▼
        connected apps (email, calendar, issues, chat, …)

  operator returns one of:
    completed | needs_auth | needs_confirmation | needs_clarification | failed

The parent remains responsible for user-facing clarification, sign-in, and confirmation. The operator returns one bounded outcome instead of inventing success or narrating tool internals.

Observability boundary

The Arcade MCP server is the canonical place to record request, authentication, tool-discovery, tool-call, and completion outcomes. This package does not ask a model to self-report tokens, turns, or success.

Optional client hooks in plugin/hooks/telemetry-adapters/ can send supplemental, scoped usage events when TELEMETRY_ENABLED is true and the user has not opted out. This build keeps TELEMETRY_ENABLED false, so no telemetry hooks are generated and nothing is sent. See docs/telemetry.md for the contract, opt-outs, local state, and the separate approval required before collection can be enabled. Gateway telemetry remains authoritative; plugin events do not establish task success.