Add dependencies field to plugin manifest

[pabloubal]

Problem

The current v1.0.0 schema for plugin.json has additionalProperties: false with no way to declare that a plugin depends on another plugin. Plugins that compose functionality from other plugins have no portable way to express this.

We've found it extremely useful to build our plugins ecosystem in layers with dependencies. Without dependencies there might be a tendency to either duplicate specs in the skills, or rely on each user to understand the dependencies and install them.

I see that the FUTURE_CONSIDERATIONS.md already lists dependency resolution as a planned. I just want to create this concrete proposal to move it forward.

Proposal

Version contraints might be good for external dependencies, but a challenge within a marketplace.

"dependencies": {
    "type": "object",
    "description": "Other plugins that must be resolved and loaded before this plugin.",
    "additionalProperties": {
      "$ref": "#/$defs/dependency"
    }
  }

  "$defs": {
    "dependency": {
      "title": "Plugin dependency",
      "type": "object",
      "properties": {
        "source": {
          "$ref": "#/$defs/source"
        }
      },
      "required": ["source"],
      "additionalProperties": false
    },
    "source": {
      "title": "Plugin source",
      "oneOf": [
        { "$ref": "#/$defs/localSource" },
        { "$ref": "#/$defs/externalSource" }
      ]
    },
    "localSource": {
      "title": "Local source",
      "description": "A dependency co-located in the same repository, resolved relative to the marketplace root.",
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "pattern": "^\\./"
        }
      },
      "required": ["path"],
      "additionalProperties": false
    },
    "externalSource": {
      "title": "External source",
      "description": "A dependency resolved from a remote git repository, optionally scoped to a subdirectory and ref.",
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "pattern": "^https://",
          "description": "Git repository URL."
        },
        "path": {
          "type": "string",
          "description": "Path to the plugin root within the repository. Defaults to the repository root when omitted."
        },
        "ref": {
          "type": "string",
          "description": "Git ref (tag, branch, or commit SHA). Defaults to the repository default branch when omitted."
        }
      },
      "required": ["url"],
      "additionalProperties": false
    }
  }

Example

Local dependency

{
    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name": "a-team",
    "version": "1.0.0",
    "description": "A-team workflow skills.",
    "author": { "name": "A-Team" },
    "dependencies": {
      "architecture-team": {
        "source": {
          "path": "./plugins/architecture-team"
        }
      }
    }
  }

Remote dependency

  {
    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name": "a-team",
    "version": "1.0.0",
    "description": "A-team workflow skills.",
    "author": { "name": "A-Team" },
    "dependencies": {
      "architecture-team": {
        "source": {
          "url": "https://github.com/my-org/architecture-team-plugin",
          "ref": "v2.1.0"
        }
      }
    }
  }

Current workaround

We are placing dependencies as an unknown top-level field, which the spec treats as non-fatal but schema-invalid. Using extensions["com.example.client"] is spec-conformant but not portable across clients.

Some considerations

• What is the resolution order for transitive dependencies?
• How should clients handle a missing dependency? Whether it should halt the installation of the plugin or continue.