Skip to content

plugin-release-checklist.md

Latest commit

 

History

History
276 lines (227 loc) · 10.9 KB

plugin-release-checklist.md

File metadata and controls

276 lines (227 loc) · 10.9 KB
Raw

Agent Kit Distribution Release Checklist

Use this checklist before publishing Endor Labs Agent Kit packages from endorlabs/ai-plugins.

Scope

Release all provider packages together unless the release notes explicitly state a narrower provider-only fix.

Distribution roots:

  • Claude Code: .claude-plugin/marketplace.json and plugins/claude/endor-labs-agent-kit/
  • Claude Code legacy compatibility: plugins/claude/ai-plugins/
  • Codex: .agents/plugins/marketplace.json and plugins/codex/endor-labs-agent-kit/
  • Gemini CLI: plugins/gemini/endor-labs-agent-kit/
  • Antigravity CLI: plugins/antigravity/endor-labs-agent-kit/
  • Cursor: .cursor-plugin/, generated root workflow agents/, generated root workflow skills/, generated root advisory hooks/, and assets/logo.png
  • Cursor SDK: cursor-sdk/
  • Root MCP/Gemini support context: .mcp.json and non-installable GEMINI.md

Package versions are not bumped automatically by Agent Kit maintainer merges. The source pyproject.toml version is the release version for generated package metadata; maintainers update it intentionally, regenerate artifacts, and keep CHANGELOG.md current.

Source Sync

Agent behavior is source-owned by endorlabs/endor-labs-agent-kit. Read docs/distribution-sync.md before syncing generated package artifacts and docs/for-agents.md before asking an agent to review or edit this mirror.

Regenerate in the Agent Kit source repo:

endor-agent-kit publish source/agents/*/recipe.yaml --dest . --prune --include-plugins
pytest
endor-agent-kit check-guardrails --catalog-root .
endor-agent-kit verify-provenance --catalog-root .
git diff --check

Then sync generated artifacts into ai-plugins with the source-owned mirror sync script:

AGENT_KIT_REPO="/path/to/endor-labs-agent-kit"

python3 "$AGENT_KIT_REPO/scripts/sync_ai_plugins_distribution.py" \
  --source "$AGENT_KIT_REPO" \
  --target .

Do not sync root GEMINI.md as Cursor package output, and do not create a root gemini-extension.json. Root .mcp.json and GEMINI.md are support context; Gemini CLI uses plugins/gemini/endor-labs-agent-kit/ as the installable extension.

Local Validation

Run these from the ai-plugins repo root:

for skill in skills/*; do python3 scripts/quick_validate.py "$skill"; done
claude plugin validate plugins/claude/endor-labs-agent-kit
claude plugin validate plugins/claude/ai-plugins
CODEX_PLUGIN_VALIDATOR="${CODEX_PLUGIN_VALIDATOR:-/path/to/plugin-creator/scripts/validate_plugin.py}"
python3 "$CODEX_PLUGIN_VALIDATOR" plugins/codex/endor-labs-agent-kit
test -f plugins/gemini/endor-labs-agent-kit/gemini-extension.json
test ! -e plugins/gemini/endor-labs-agent-kit.zip
antigravity plugin validate plugins/antigravity/endor-labs-agent-kit
python3 -m json.tool .claude-plugin/marketplace.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 -m json.tool .cursor-plugin/marketplace.json >/dev/null
python3 -m json.tool .cursor-plugin/plugin.json >/dev/null
python3 -m json.tool cursor-sdk/agent_definitions.json >/dev/null
python3 -m json.tool hooks/hooks.json >/dev/null
python3 -m json.tool plugins/claude/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/codex/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/gemini/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/antigravity/endor-labs-agent-kit/hooks.json >/dev/null
test ! -e plugins/claude/ai-plugins/hooks
for hook_script in hooks/*.sh plugins/*/*/hooks/*.sh; do bash -n "$hook_script"; done
python3 - <<'PY'
import py_compile

py_compile.compile("cursor-sdk/run_cursor_agent.py", cfile="/tmp/run_cursor_agent.pyc", doraise=True)
PY
python3 -m json.tool .mcp.json >/dev/null
test -f GEMINI.md
test ! -e gemini-extension.json
python3 - <<'PY'
import json
from pathlib import Path

definitions = json.loads(Path("cursor-sdk/agent_definitions.json").read_text(encoding="utf-8"))
for agent in definitions["agents"]:
    agent_name = agent["agent_name"]
    skill_id = agent["id"]
    assert Path("agents", f"{agent_name}.md").is_file(), agent_name
    assert Path("skills", skill_id, "SKILL.md").is_file(), skill_id
    assert Path("cursor-sdk", agent["prompt_file"]).is_file(), agent["prompt_file"]
PY
test -f skills/ai-sast-triage/architecture.svg
test -f skills/findings-browser/architecture.svg
test -f skills/malware-response/architecture.svg
test -f skills/sca-remediation/actions.yaml
test -f CHANGELOG.md
git diff --check

Compare generated package drift:

diff -qr /path/to/endor-labs-agent-kit/plugins ./plugins
diff -qr /path/to/endor-labs-agent-kit/.cursor-plugin ./.cursor-plugin
diff -qr /path/to/endor-labs-agent-kit/agents ./agents
diff -qr /path/to/endor-labs-agent-kit/cursor-sdk ./cursor-sdk
diff -qr /path/to/endor-labs-agent-kit/hooks ./hooks
for skill in /path/to/endor-labs-agent-kit/skills/*; do
  name=${skill##*/}
  [ "$name" = "create-endor-labs-agent" ] && continue
  diff -qr "$skill" "./skills/$name"
done
diff -q /path/to/endor-labs-agent-kit/assets/logo.png assets/logo.png

Normal provider package sync should be byte-for-byte identical, and Cursor metadata/root workflow agents, support skills, and advisory hooks should match the source-generated Cursor package. The root CHANGELOG.md should also match the source repo so release notes travel with generated distribution PRs.

Safety Gates

  • Setup must not run scans.
  • Setup must not run endorctl host-check.
  • Setup must not install tools, edit shell profiles, write credentials, or configure MCP globally without explicit user approval.
  • Live endorctl api smoke tests require explicit approval and must record namespace provenance.
  • Repository-scoped Endor evidence must preserve context.type==CONTEXT_TYPE_MAIN defaults unless the user explicitly asks for PR, CI-run, commit, or all-context scope.
  • Project lookup failures in a proven namespace must retry with --traverse before reporting project-not-found.

Tag The Release

The release tag is created on endorlabs/ai-plugins (this repository), not on the Agent Kit source repository. Public Codex and Gemini CLI installs resolve the tag directly, so create it only after the release content is merged to main:

VERSION="$(python3 -c "import json; print(next(p['version'] for p in json.load(open('.claude-plugin/marketplace.json'))['plugins'] if p['name'] == 'endor-labs-agent-kit'))")"
gh release create "$VERSION" --repo endorlabs/ai-plugins --target main \
  --title "Endor Labs Agent Kit $VERSION" --notes "See CHANGELOG.md."

The tag is the exact package version with no v prefix. Deriving VERSION from this repository's .claude-plugin/marketplace.json keeps the tag equal to the generated package metadata; do not compute it from an Agent Kit checkout, and do not run gh release create from an Agent Kit checkout without --repo endorlabs/ai-plugins (it would tag the private source repository).

Public Release Checks

Run public host install checks only after the branch and tag exist.

Claude Code:

/plugin marketplace add endorlabs/ai-plugins@<tag>
/plugin install endor-labs-agent-kit@endorlabs
/plugin install ai-plugins@endorlabs
/plugin list
/agents

ai-plugins@endorlabs is retained for existing Claude Code users. Do not enable both Claude plugin ids in the same profile for normal use because they expose the same setup skill and agents. Release notes and install docs must state that new installs should prefer endor-labs-agent-kit@endorlabs, existing users do not need an automatic migration, and the plugin does not auto-disable, uninstall, or edit Claude settings for either id.

Codex:

codex plugin marketplace add endorlabs/ai-plugins --ref <tag> --sparse .agents --sparse plugins/codex/endor-labs-agent-kit
codex plugin list --marketplace endor-labs-agent-kit
codex plugin add endor-labs-agent-kit@endor-labs-agent-kit
codex plugin remove endor-labs-agent-kit@endor-labs-agent-kit

Gemini CLI:

git clone --depth 1 --branch <tag> https://github.com/endorlabs/ai-plugins ai-plugins-gemini-release
gemini extensions install ./ai-plugins-gemini-release/plugins/gemini/endor-labs-agent-kit
gemini extensions list
gemini extensions uninstall endor-labs-agent-kit

As of 2026-06-16, Google documents that Gemini CLI access for unpaid, Google One, Google AI Pro, and Google AI Ultra consumer users transitions to Antigravity CLI on 2026-06-18. Keep Gemini package validation for supported enterprise/API-key users and extension compatibility, and run the Antigravity validation below as the forward-path CLI check for affected consumer users.

Antigravity CLI:

antigravity plugin install /absolute/path/to/ai-plugins/plugins/antigravity/endor-labs-agent-kit
antigravity plugin list
antigravity plugin uninstall endor-labs-agent-kit

Cursor package and root workflow skills:

for skill in skills/*; do python3 scripts/quick_validate.py "$skill"; done
python3 -m json.tool .cursor-plugin/marketplace.json >/dev/null
python3 -m json.tool .cursor-plugin/plugin.json >/dev/null
python3 - <<'PY'
import json
from pathlib import Path

definitions = json.loads(Path("cursor-sdk/agent_definitions.json").read_text(encoding="utf-8"))
for agent in definitions["agents"]:
    agent_name = agent["agent_name"]
    skill_id = agent["id"]
    assert Path("agents", f"{agent_name}.md").is_file(), agent_name
    assert Path("skills", skill_id, "SKILL.md").is_file(), skill_id
PY
test -f skills/ai-sast-triage/architecture.svg
test -f skills/findings-browser/architecture.svg
test -f skills/malware-response/architecture.svg
test -f skills/sca-remediation/actions.yaml
test -f hooks/hooks.json
test -f assets/logo.png

Keep Cursor validation separate from Gemini validation. Cursor uses .cursor-plugin/, agents/, skills/, hooks/, and assets/logo.png; Gemini CLI uses plugins/gemini/endor-labs-agent-kit/.

The public Cursor Marketplace listing (cursor.com/marketplace/endorlabs) is not updated automatically by pushes or tags on this repository. After tagging, refresh or resubmit the listing through the Cursor marketplace submission process, then verify from Cursor Agent chat that /add-plugin endorlabs installs the released package version. A stale listing is invisible to the drift checks above, so do not skip this step.

Cursor SDK automation:

python3 -m json.tool cursor-sdk/agent_definitions.json >/dev/null
python3 - <<'PY'
import py_compile

py_compile.compile("cursor-sdk/run_cursor_agent.py", cfile="/tmp/run_cursor_agent.pyc", doraise=True)
PY
test -f cursor-sdk/requirements.txt
test -f cursor-sdk/agents/endor-agent-kit-setup-agent.md
test -f cursor-sdk/agents/endor-malware-response-agent.md
test -f cursor-sdk/agents/endor-probe-droid-agent.md

Do not run Cursor SDK local or cloud smoke tests without explicit approval for CURSOR_API_KEY use, target repository, namespace provenance, and any possible workflow side effects.