커서 플러그인: 에이전트 도구 경계 및 오케스트레이션에 대해 알 수 있는 플러그인 매니페스트

Cursor just open-sourced their plugin specification (7,421 stars, 648 forks) and it exposes production-grade agent coordination patterns that most frameworks hide behind abstractions. Each plugin is a standalone directory with a .cursor-plugin/plugin.json manifest that defines tool boundaries, orchestration flow, and agent-to-agent handoffs. The repo includes plugins like orchestrate (parallel cloud agents with planners, workers, and verifiers), thermos (parallel subagent security audits), and continual-learning (incremental memory updates). This is not a framework pitch. This is plumbing.

Why a Manifest Matters for Agent Tool Boundaries

Most agent frameworks let you register tools as Python functions or TypeScript methods. Cursor’s plugin.json takes a different approach: it treats each plugin as a scoped unit with explicit metadata, dependencies, and orchestration hints. The manifest defines:

• Name and category: scopes the plugin’s domain (e.g., “Developer Tools”).
• Description: surfaces in the marketplace and helps the orchestrator decide when to invoke.
• Entry point: the main file that exports the plugin’s logic.
• Dependencies: other plugins or SDKs required for execution.
• Orchestration hints: flags like parallel: true or requires_verification: true that tell the orchestrator how to fan out work.

This structure prevents scope creep. A plugin that audits security (like thermos) does not accidentally pull in unrelated tools. The orchestrator can reason about which plugins to invoke in parallel and which require sequential handoffs.

The Orchestrate Plugin: Fan-Out and Fan-In for Parallel Cloud Agents

The orchestrate plugin is the clearest example of production multi-agent coordination. It fans large tasks out across parallel cloud agents with distinct roles:

• Planner: breaks the task into subtasks and assigns them to workers.
• Workers: execute subtasks in parallel, each with its own context and tool set.
• Verifier: checks worker outputs for correctness and consistency before merging.

The orchestration flow looks like this:

1. User submits a task (e.g., “refactor this module and add tests”).
2. Planner agent analyzes the task and generates a work plan with subtasks.
3. Orchestrator spawns worker agents in parallel, each with a subtask and scoped context.
4. Workers execute and return structured results (e.g., JSON with file paths, diffs, and status).
5. Verifier agent checks for conflicts, missing coverage, or broken contracts.
6. Orchestrator merges verified results and returns the final output.

The plugin.json for orchestrate includes a parallel: true flag and a verification_required: true flag. The orchestrator uses these hints to decide whether to block on verification or stream partial results.

Thermos: Parallel Subagent Security Audits with Structured Handoffs

The thermos plugin handles “thermo-nuclear branch review” with parallel subagents that audit security, correctness, and code quality. Each subagent runs independently with a harsh rubric and returns a structured report. The orchestrator aggregates reports and optionally generates a merge-ready PR.

The handoff pattern is explicit:

• Subagent A: scans for SQL injection, XSS, and auth bypass.
• Subagent B: checks for race conditions, memory leaks, and concurrency bugs.
• Subagent C: enforces code style, naming conventions, and documentation coverage.

Each subagent writes to a shared state object (e.g., a JSON file in .cursor-plugin/state/thermos.json) with keys like security_findings, correctness_issues, and style_violations. The orchestrator reads this state and decides whether to block the merge or surface warnings.

The plugin.json includes a subagents array that lists each subagent’s name, role, and entry point. The orchestrator spawns them in parallel and waits for all to complete before aggregating.

Continual Learning: Incremental Memory Updates Without Rewrites

The continual-learning plugin demonstrates how to handle incremental state updates without rewriting the entire context. It parses conversation transcripts and extracts high-signal bullet points (e.g., “User prefers functional style over OOP”). These bullets append to an AGENTS.md file that other plugins can read.

The update flow:

1. Plugin receives a transcript chunk (e.g., the last 10 messages).
2. Plugin extracts actionable insights using a lightweight LLM call.
3. Plugin appends new bullets to AGENTS.md under a timestamped section.
4. Other plugins read AGENTS.md to adjust behavior (e.g., code generation style).

This avoids the “context explosion” problem where every agent call includes the full conversation history. The plugin.json includes a state_file: "AGENTS.md" field that tells the orchestrator where to persist memory.

Ralph Loop: Iterative Self-Referential AI Loops

The ralph-loop plugin implements iterative self-referential loops where an agent critiques its own output and refines it. The loop continues until the agent signals convergence or hits a max iteration limit.

The loop structure:

1. Agent generates an initial output (e.g., a function implementation).
2. Agent critiques the output using a rubric (e.g., “Does this handle edge cases?”).
3. Agent refines the output based on critique.
4. Repeat until critique score exceeds a threshold or max iterations reached.

The plugin.json includes a max_iterations: 5 field and a convergence_threshold: 0.9 field. The orchestrator enforces these limits to prevent infinite loops.

Plugin Manifest Schema: What the JSON Exposes

A typical plugin.json looks like this:

{
  "name": "orchestrate",
  "version": "1.0.0",
  "category": "Developer Tools",
  "description": "Fan large tasks out across parallel cloud agents with planners, workers, verifiers, and structured handoffs.",
  "entry": "src/index.ts",
  "parallel": true,
  "verification_required": true,
  "dependencies": ["cursor-sdk"],
  "state_file": ".cursor-plugin/state/orchestrate.json",
  "subagents": [
    {
      "name": "planner",
      "role": "task decomposition",
      "entry": "src/planner.ts"
    },
    {
      "name": "worker",
      "role": "subtask execution",
      "entry": "src/worker.ts"
    },
    {
      "name": "verifier",
      "role": "output validation",
      "entry": "src/verifier.ts"
    }
  ]
}

Enter fullscreen mode Exit fullscreen mode

The orchestrator reads this manifest and knows:

• This plugin can run in parallel.
• Verification is required before merging results.
• Three subagents must be spawned with distinct roles.
• State persists to a JSON file.

This is declarative orchestration. The plugin does not call the orchestrator API directly. The orchestrator infers behavior from the manifest.

Observability and Failure Modes

The plugin spec does not include built-in observability hooks, but the state file pattern gives you a trace. Each plugin writes structured logs to its state file (e.g., .cursor-plugin/state/thermos.json). You can tail these files to see:

• Which subagents started and completed.
• What errors occurred during execution.
• What structured outputs were returned.

Failure modes to watch:

• Subagent timeout: if a worker hangs, the orchestrator must decide whether to wait or fail fast.
• Verification conflict: if the verifier rejects worker output, the orchestrator must decide whether to retry or surface the error.
• State file corruption: if the JSON file is malformed, the orchestrator cannot read state and must reset.

The plugin.json does not expose timeout or retry policies. You must implement these in the orchestrator or in each plugin’s entry point.

Deployment Shape: Local vs. Cloud Agents

The orchestrate plugin supports both local and cloud agents. The orchestrator decides based on a runtime field in the plugin.json:

• "runtime": "local": spawn subagents as Node.js child processes on the same machine.
• "runtime": "cloud": spawn subagents as serverless functions (e.g., AWS Lambda, Cloudflare Workers).

Cloud agents require additional plumbing:

• Authentication: pass API keys or tokens to each worker.
• State synchronization: workers write to a shared state store (e.g., S3, Redis).
• Result aggregation: the orchestrator polls workers or subscribes to a message queue.

The plugin spec does not prescribe a specific cloud provider. You must implement the runtime adapter yourself.

Trade-Offs: Manifest-Driven vs. Programmatic Orchestration

Dimension Manifest-Driven (Cursor) Programmatic (LangGraph, Autogen) Tool boundary enforcement Explicit via plugin.json Implicit via function registration Orchestration visibility Declarative, readable Imperative, requires code inspection Subagent coordination Structured handoffs via state files Direct function calls or message passing Extensibility Add plugins without changing orchestrator Add tools by modifying orchestrator code Debugging Tail state files, inspect manifest Step through orchestrator code Cloud deployment Requires runtime adapter Built-in for some frameworks

Manifest-driven orchestration trades flexibility for clarity. You cannot dynamically change orchestration logic at runtime, but you can reason about the system by reading JSON files.

Security Boundaries: What the Manifest Does Not Protect

The plugin.json does not enforce security boundaries. A malicious plugin can:

• Read arbitrary files on disk.
• Make network requests to external APIs.
• Modify state files for other plugins.

You must sandbox plugins at the runtime level (e.g., run each plugin in a separate container or VM). The manifest only defines logical boundaries, not isolation.

Technical Verdict

Use Cursor’s plugin spec when:

• You need explicit tool boundaries and want to prevent scope creep in multi-agent workflows.
• You want declarative orchestration that is readable without stepping through code.
• You are building IDE-embedded agents that need structured handoffs and state persistence.
• You want to fan out work across parallel cloud agents with planners, workers, and verifiers.

Avoid it when:

• You need dynamic orchestration logic that changes at runtime based on agent feedback.
• You require built-in security sandboxing or observability hooks.
• You want a batteries-included framework with cloud deployment adapters.
• You need fine-grained control over retry policies, timeouts, and error handling at the orchestrator level.

The plugin spec is plumbing, not a framework. It exposes the coordination patterns that production IDE agents need, but you must implement the orchestrator, runtime adapters, and security boundaries yourself.

Source Links

• Cursor Plugins Repository
• Orchestrate Plugin
• Thermos Plugin
• Continual Learning Plugin