Adapstory Developer Docs

A plugin is described by a single plugin.yaml. This page lists every field. Required fields are marked R.

Top level

apiVersion: adapstory.com/v1        # R — schema version
kind: Plugin                        # R — always Plugin
metadata: { ... }                   # R
spec:     { ... }                   # R

`metadata`

Field	Type	Required	Notes
`name`	string	R	Kebab-case, globally unique per publisher
`version`	semver	R	Strict SemVer 2.0. No `latest`
`publisher`	string	R	Matches your publisher account slug
`displayName`	string		Shown in admin UI (falls back to `name`)
`description`	string		Short summary, under 140 chars
`tags`	string[]		For discovery in the plugin catalog

`spec.runtime`

Controls how BC-19 schedules your workload.

spec:
  runtime:
    image: registry.adapstory.com/your-org/hello-learner:0.1.0   # R
    imagePullSecret: your-org-pull                               # optional
    resources:
      requests: { cpu: 100m, memory: 256Mi }                     # R
      limits:   { cpu: 500m, memory: 512Mi }                     # R
    replicas:
      min: 1
      max: 3
      targetCPUUtilization: 70
    startupProbe:
      path: /health
      port: 8080
      periodSeconds: 5
      failureThreshold: 12

image must be pinned by tag. The admission controller rejects :latest and any mutable tag pattern.

`spec.mcpTools`

Each entry registers an MCP tool with BC-01.

spec:
  mcpTools:
    - name: hello_learner                # R — kebab_case
      description: One-line purpose.     # R — LLMs read this to decide when to call
      endpoint: /mcp/hello               # R — path in your container (port from startupProbe)
      schema: mcp/hello-learner.schema.json   # R — JSON-Schema of args
      streaming: false                   # optional, default false
      timeout: 10s                       # optional, default 15s
      rateLimit:
        perTenant: 60/minute
        perUser:   10/minute

JSON-Schema for args must be JSON-Schema draft 2020-12. Keep it small — LLMs tokenise the schema on every call.

`spec.events`

Kafka integration. Events are CloudEvents 1.0.

spec:
  events:
    consumes:
      - enrollment.completed.v1
      - course.published.v1
    produces:
      - course.recommended.v1
    dlqStrategy: retry-5-then-dlq        # default

Your service subscribes to consumes topics under a consumer group named plugin.<name>.<tenant>. At-least-once delivery — be idempotent.

`spec.dataModels`

Schema extensions handled by BC-15.

spec:
  dataModels:
    extends:
      - name: bc15.course
        attributes:
          - name: recommender_score
            type: float
            range: [0.0, 1.0]
      - name: bc15.enrollment
        attributes:
          - name: nudge_last_sent_at
            type: timestamp

Rules:

Additive only. You cannot remove an attribute another plugin (or core) declared.
Non-nullable attributes need a default.
Removing an attribute across versions requires a two-step migration.

`spec.llm`

LLM Gateway settings.

spec:
  llm:
    gatewayBudget: 500000                # R — tokens/day per tenant
    defaultModel: claude-sonnet-4-6      # R — default model alias
    allowedModels:                       # optional — whitelist; defaults to all tenant-enabled
      - claude-sonnet-4-6
      - claude-haiku-4-5-20251001
    maxCostUsdPerCall: 0.50              # optional — circuit breaker
    guardrails:
      content: [no-pii, education-safe]
      prompt-injection: strict
      output-filter: profanity-mild
    caching:
      enabled: true
      ttlSeconds: 3600

`spec.secrets`

Secrets resolved through External Secrets Operator.

spec:
  secrets:
    - name: STRIPE_API_KEY
      vaultPath: adapstory/plugins/hello-learner/{tenant}/stripe
      key: api_key

{tenant} is substituted by the runtime. The secret lands as an env var in your container.

`spec.permissions`

Scopes the plugin may request at install-time. The tenant's admin must grant each.

spec:
  permissions:
    - read:learners
    - write:courses
    - call:bc-15.migrate

Undeclared scopes → denied, even if your code somehow acquires a token.

Minimal valid example

apiVersion: adapstory.com/v1
kind: Plugin
metadata:
  name: hello-learner
  version: 0.1.0
  publisher: your-org
spec:
  runtime:
    image: registry.adapstory.com/your-org/hello-learner:0.1.0
    resources:
      requests: { cpu: 100m, memory: 256Mi }
      limits:   { cpu: 500m, memory: 512Mi }
  mcpTools:
    - name: hello_learner
      description: Greet a learner by name.
      endpoint: /mcp/hello
      schema: mcp/hello-learner.schema.json
  llm:
    gatewayBudget: 50000
    defaultModel: claude-haiku-4-5-20251001

JSON Schema

The full schema is published at https://docs.adapstory.com/schemas/plugin.v1.json — you can point your IDE at it for auto-completion and validation.

Next: MCP tools.

Manifest reference