compas-plugin-registry

Community registry for mcp__compas plugins.

Goal

A shared, versioned, fail-closed place where the community can publish and evolve compas plugins safely.

What this repo gives users

• install only required plugins (spec-adr-gate, sast-semgrep-gate, lint-unified-gate, ...)
• install by curated packs (ai-core, quality, security, starter-safe, all)
• copy required plugin files + tool adapters + script assets into target project
• keep compas core repo focused on engine/runtime, not plugin storage

Repository layout

• plugins/<plugin-id>/ — self-contained plugin package
  • plugin.toml (compas wiring)
  • package.toml (package metadata)
  • README.md
  • tools/*.toml (local tool adapters)
  • scripts/* (local adapter/runtime logic)
• scripts/compas_plugins.py — registry utility CLI (list/packs/info)
• scripts/validate_registry.py — registry validation
• registry/plugins/index.toml — catalog index
• registry/packs/index.toml — curated plugin packs
• docs/CATALOG.md — catalog generation and discoverability map

Docs

• Discover catalog and publishing flow: docs/CATALOG.md
• Docs entrypoint and map: docs/INDEX.md
• Project status (SSOT): docs/STATUS.md

Canonical plugin metadata contract (registry index + manifest)

Each plugin record in registry/plugins/index.toml (and emitted manifest v1) carries:

• governance: tier, maintainers, tags, compat, sunset
• capability metadata: capabilities, requires, runtime_kind, cost_class, artifacts_produced

Legacy compatibility note: old manifests may still use deprecated; canonical docs use sunset.

Strict mode is fail-closed for missing/invalid values.

Install flow (canonical consumer lane)

1. Install/use mcp__compas core in your project.
2. Browse catalog and pick plugin/pack IDs:
   • Hosted: https://amirtlinov.github.io/compas-plugin-registry/
   • Local: generate and open site/index.html (see docs/CATALOG.md).
3. Install selected plugins/packs from signed release manifest into your project.

By plugin IDs

ai-dx-mcp plugins install \
  --registry https://github.com/AmirTlinov/compas-plugin-registry/releases/latest/download/registry.manifest.v1.json \
  --repo-root /path/to/your/project \
  --admin-lane \
  --plugins spec-adr-gate,sast-semgrep-gate,lint-unified-gate

By packs (easier)

ai-dx-mcp plugins install \
  --registry https://github.com/AmirTlinov/compas-plugin-registry/releases/latest/download/registry.manifest.v1.json \
  --repo-root /path/to/your/project \
  --admin-lane \
  --packs starter-safe,security

Then in target project run:

ai-dx-mcp validate ratchet --repo-root /path/to/your/project
ai-dx-mcp gate ci_fast --dry-run --repo-root /path/to/your/project

Plugin operations (canonical native lane)

Use ai-dx-mcp plugins ... for install/update/uninstall/doctor flows.

ai-dx-mcp plugins list --repo-root /repo
ai-dx-mcp plugins packs --repo-root /repo
ai-dx-mcp plugins info sast-semgrep-gate --repo-root /repo
ai-dx-mcp plugins install --admin-lane --plugins sast-semgrep-gate,secrets-leak-guard --repo-root /repo
ai-dx-mcp plugins install --admin-lane --packs quality --repo-root /repo --dry-run
ai-dx-mcp plugins update --admin-lane --repo-root /repo
ai-dx-mcp plugins update --admin-lane --plugins sast-semgrep-gate --repo-root /repo --dry-run
ai-dx-mcp plugins uninstall --admin-lane --plugins spec-adr-gate --repo-root /repo
ai-dx-mcp plugins doctor --repo-root /repo

Registry source override:

ai-dx-mcp plugins install --admin-lane --registry /path/to/registry.manifest.v1.json --plugins spec-adr-gate --repo-root /repo
ai-dx-mcp plugins install --admin-lane --registry https://.../registry.manifest.v1.json --packs quality --repo-root /repo

Installer state file:

• .agents/mcp/compas/plugins.lock.json (pinning + file hashes)

Legacy aliases (p01..p22) are supported for compatibility, but canonical plugin IDs are name-based.

Plugin implementation model

• Tool-backed plugins: include executable logic via plugin-local tools/*.toml + scripts/*.
  • examples: reuse-report-gate, structured-report-ingestion, release-readiness-gate
• Hybrid plugins: combine native compas checks + executable plugin-local tools.
  • examples: boundary-arch-hardening, complexity-loc-budgets, surface-contract-guard, supply-chain-hygiene
• Baseline-generator plugins: include helper tools that materialize baseline JSON for gate checks.
  • examples: coverage-nonregression (coverage-baseline), perf-regression-budget (perf-baseline)

All community plugins in this registry are packaged for targeted install into arbitrary projects (no dependency on shared global tool folders).

Proof (end-to-end)

This repo includes a real e2e harness that installs plugins into a fresh temp repo and runs ai-dx-mcp gate:

• scripts/e2e_compas.py (see docs/E2E.md)
• includes explicit coverage/perf baseline-generation scenarios before gate execution

Adapter design rules (“adapters are not hacks”) are formalized in:

• docs/ADAPTER_CONTRACT.md

Contribution model

1. Fork + branch
2. Add/update plugin under plugins/
3. Run validator locally
4. Open PR with rationale, edge-cases, and compatibility notes

See CONTRIBUTING.md and GOVERNANCE.md.