agent-ecosystem/docs/extensions/plugin-kit-ai-integration-plan.md

plugin-kit-ai Integration Plan for Extensions Plugins

Status: Draft
Date: 2026-04-18
Owner repos:

• claude_team
• plugin-kit-ai

Purpose

Replace the current Claude-only plugin backend in claude_team with a provider-aware backend powered by plugin-kit-ai, while keeping the existing Extensions -> Plugins UI.

The integration must support two different truths at the same time:

• Universal plugins managed through plugin-kit-ai
• Native external installed plugins that already exist in Claude or Codex and are not yet part of universal managed state

Those are different objects and must remain different in UI, state, and actions.

One-Page Summary

What we are building

• keep the current Extensions -> Plugins UI in claude_team
• bundle plugin-kit-ai as a backend engine
• use plugin-kit-ai for:
  • universal catalog
  • native discovery
  • universal lifecycle actions

What we are not building

• not embedding a second plugin UI
• not parsing prose CLI output
• not scraping repo layout from claude_team
• not pretending native installed plugins are the same thing as universal managed plugins
• not promising local scope before backend really supports it

User-visible outcome

• installed plugins come first
• universal plugins are the main storefront
• native installed Claude/Codex plugins stay visible and are labeled honestly
• install/update/remove/repair results stay target-granular

Safe delivery order

1. add stable JSON contracts to plugin-kit-ai
2. add universal catalog in plugin-kit-ai
3. add native discovery in plugin-kit-ai
4. integrate read-only mixed plugin view in claude_team
5. add universal lifecycle actions in claude_team
6. consider optional native convenience flows only later

Non-negotiable no-go items

• no auto-merge by display name
• no silent local -> project downgrade
• no destructive actions on native external entries unless backend explicitly declares them safe
• no app-side inference where backend truth is missing

Glossary

Universal plugin

A plugin from the universal plugin catalog that can be managed through plugin-kit-ai.

Native external plugin

A plugin that already exists in a native agent surface such as Claude or Codex, but is not part of plugin-kit-ai managed state.

Managed universal plugin

A universal plugin that plugin-kit-ai has installed or is tracking in ~/.plugin-kit-ai/state.json.

Catalog

The backend surface that answers:

• what universal plugins exist
• what targets and scopes they support
• what storefront metadata should be shown

Discover

The backend surface that answers:

• what native plugins already exist outside managed universal state
• what target and scopes they belong to
• whether the app may safely manage them

List

The backend surface that answers:

• what universal plugins are already managed

Doctor

The backend surface that answers:

• which managed universal plugins need attention because of drift, auth, or activation state

Hard Product Decisions

These are fixed unless a new ADR explicitly changes them.

1. Two plugin classes

The page shows:

• Universal
• Native external installed

They are never silently merged.

2. Installed-first ranking

Ranking order:

1. installed universal
2. installed native external
3. available universal

3. Universal is the main storefront

Universal plugins are the default source for new installs. Native external plugins are primarily visibility and compatibility surfaces.

4. discover before adopt

Phase 1 needs visibility, not ownership conversion.

5. No fake scope parity

If the backend target does not support a scope, the UI must not pretend it does.

Definition of Done

This migration is done only when all of the following are true:

• plugin-kit-ai exposes stable machine-readable catalog, discover, and lifecycle contracts
• claude_team renders universal and native external entries as distinct classes
• direct Claude mode works end-to-end for universal install/update/remove/repair
• multimodel Anthropic + Codex mode works end-to-end with target-granular results
• native external plugins remain visible and truthfully labeled
• the page stays useful when one backend view fails or is stale
• rollback is possible through a feature flag without destructive cleanup

If any of these is false, the migration is still in progress.

What Is Already True in plugin-kit-ai

This plan should build on real current code, not on an imagined backend.

Already present today

• integrationctl already exposes a public lifecycle facade
• target adapters already expose:
  • Capabilities
  • Inspect
  • Plan*
  • Apply*
  • Repair
• post-apply verification already re-inspects the target and rejects false-positive installs
• managed lifecycle state already exists in ~/.plugin-kit-ai/state.json
• read-only managed views already exist conceptually:
  • list
  • doctor
• lifecycle update/remove already re-resolve the source and reject identity drift if the resolved manifest no longer matches the stored integration_id

Important current gaps

• integrations CLI currently prints prose, not versioned JSON
• there is no public catalog surface yet
• there is no public discover surface yet
• current managed Report.Targets do not carry enough integration-level context for the app
• current service composition still depends on os.Getwd() for workspace semantics

Important current model split

There are two useful metadata layers today:

• the richer authored plugin model used by pluginmodel / pluginmanifest
• the narrower integrationctl.IntegrationManifest

Current integrationctl manifest loading preserves:

• name
• version
• description
• targets
• derived deliveries
• derived capability surface

But it currently drops richer authored metadata such as:

• homepage
• repository
• keywords
• author
• license

Practical consequence:

• lifecycle can already use the current IntegrationManifest
• storefront catalog cannot get all desired detail fields from the current IntegrationManifest alone

Packaging nuance from current code

• evidence registry already has an embedded fallback, which lowers packaging risk
• workspace-lock storage is still repo-root oriented

Practical consequence:

• list, doctor, add, update, remove, and repair are the right first app surfaces
• sync is not a phase-1 or phase-2 app surface
• enable and disable can stay out of the first app rollout

Current Adapter Truth From Code

These are backend facts the plan must respect.

Claude adapter

• install mode: native_cli
• supports native update: yes
• supports native remove: yes
• supports scopes: user, project
• does not currently advertise local
• requires reload after install

Codex adapter

• install mode: marketplace_prepare
• supports native update: no
• supports native remove: no
• supports scopes: user, project
• does not currently advertise local
• requires restart and a new thread
• current inspect logic distinguishes:
  • fully installed
  • disabled
  • prepared but not activated
  • degraded

Consequence for the app

The app must treat scope support as backend-owned truth.

That means:

• phase 1 and phase 2 should expose only user and project for plugin-kit-backed universal installs
• if local is important later, it must be added as a real backend capability first

Architecture Boundary

Correct boundary

• plugin-kit-ai = lifecycle engine, universal catalog backend, native discovery backend
• claude_team = frontend, state, UX, feature-flagged rollout

Wrong boundaries

• do not embed a second plugin UI
• do not parse human CLI output
• do not scrape universal repo layout directly in claude_team
• do not link Go code directly into Electron instead of using the CLI contract

Recommended Backend Basis By Surface

Different backend surfaces should be built on different existing code paths. Trying to force one internal model to answer every question would make the result worse.

Surface	Best current basis in plugin-kit-ai	Why
catalog	pluginmanifest.Inspect + publicationmodel + targetcontracts	richer authored metadata and stronger target/output truth
list	integrationctl managed state and current list service	managed universal truth already exists here
doctor	integrationctl current doctor service	managed drift/auth/activation truth already exists here
lifecycle mutate	integrationctl facade and adapters	real install/update/remove/repair engine already exists here
discover	new dedicated native discovery layer built using native surface readers and inspect helpers	external observed truth is different from managed lifecycle truth

Recommended decision

• build catalog from the richer authored-model path
• build list, doctor, and lifecycle mutations from integrationctl
• build discover as a new surface that may reuse inspect helpers, but is not just Inspect

This is the cleanest way to avoid overloading one narrow model with too many jobs.

Recommended plugin-kit-ai Implementation Ownership

One of the highest-risk failure modes is building the right contract in the wrong layer. This section fixes ownership up front.

Chosen seam by package

Concern	Recommended home in plugin-kit-ai	Why
CLI flags, --format json, envelopes, exit semantics	cli/plugin-kit-ai/cmd/plugin-kit-ai	command boundary belongs here, not business truth
catalog projection for app consumption	new helper near cli/plugin-kit-ai/internal/pluginmanifest such as internal/catalogview	catalog truth comes from authored inspection and needs a stable projection layer
managed lifecycle grouping and integration-level fields	install/integrationctl/domain + install/integrationctl/usecase	lifecycle truth already lives here and should not be reconstructed in the CLI
native discovery orchestration	new discovery usecase under install/integrationctl/usecase with types in install/integrationctl/domain	discovery is backend truth, not a frontend heuristic
target-specific native enumeration and evidence collection	existing adapter packages under install/integrationctl/adapters/<target>	adapters already own target-specific path and native-surface knowledge
source resolution	install/integrationctl/adapters/source	canonical source resolution already lives here
workspace-root normalization into target-specific native roots	install/integrationctl/adapters/pathpolicy plus adapter path helpers	app must not duplicate ProjectRoot vs EffectiveGitRoot logic

Raw internal models must not leak as app contracts

The app should not consume any of these raw internal shapes directly:

• raw pluginmanifest.Inspection
• raw integrationctl lifecycle domain.Report
• raw adapter InspectResult

Instead:

• CLI commands should project them into stable app-facing JSON contracts
• projection should happen once in plugin-kit-ai
• claude_team should consume only those projected contracts

Why this chosen seam is safer

• it keeps target/path/source truth backend-owned
• it avoids Electron reconstructing lifecycle groupings or source provenance
• it allows plugin-kit-ai to change internal models without breaking the app contract
• it makes E2E failures easier to localize to one layer

Which Backend Surface Answers Which UI Question

UI question	Backend surface	Why
What universal plugins can I install?	catalog	storefront availability
What universal plugins are already managed?	list	managed truth
What managed universal plugins need attention?	doctor	drift, auth, activation
What native plugins already exist outside plugin-kit management?	discover	observed external truth
Can this plugin be installed for Claude?	catalog capability + scope metadata	install intent
Can this plugin be installed for Codex?	catalog capability + scope metadata	install intent
Can I safely uninstall this native external plugin from the app?	discover.manageability	destructive authority must come from backend
What exactly happened after install/update/remove?	lifecycle result JSON	target-granular mutation truth

Rule:

• if the answer is not available from one of these surfaces, the app should not invent it

Backend View Consistency Matrix

This section makes cross-surface ownership explicit. It should be possible to answer every “which surface wins?” question from this table alone.

| Field or question | Winning surface | Allowed fallback | Forbidden fallback | |---|---|---| | managed existence | list | none | catalog, discover, app heuristics | | managed health / degraded / auth-pending | doctor | list only for neutral installed state | catalog, discover | | universal availability | catalog | stale cached catalog with explicit stale marker | discover, app heuristics | | native external existence | discover | stale cached discovery with explicit stale marker | catalog, list | | destructive authority for native external entries | discover.manageability | none | app heuristics | | installability by target/scope | catalog plus lifecycle capability projection | conservative disable in app | inferred support from authored target alone | | managed target result after mutation | lifecycle mutate result | immediate doctor refresh | app optimism without payload evidence | | storefront detail metadata | catalog detail projection | explicit missing-detail UI | generated operational docs |

Required contradiction handling

If surfaces disagree:

• list vs catalog
  • keep the managed entry
  • mark catalog/detail support degraded if needed
• discover vs catalog
  • keep both truths
  • do not rewrite ownership
• doctor vs list
  • prefer doctor for health state
  • prefer list for managed existence
• lifecycle mutate result vs stale cached list
  • prefer the fresh mutate payload, then refetch
  • do not let stale cache overwrite the mutation outcome

Data Flow

flowchart LR
  A["universal-plugins-for-ai-agents"] --> B["plugin-kit-ai catalog"]
  C["Claude native surfaces"] --> D["plugin-kit-ai discover"]
  E["Codex native surfaces"] --> D
  F["plugin-kit-ai state.json"] --> G["plugin-kit-ai list"]
  F --> H["plugin-kit-ai doctor"]
  I["plugin-kit-ai lifecycle actions"] --> F
  B --> J["claude_team Plugins UI"]
  D --> J
  G --> J
  H --> J
  J --> I

Target Naming and Mapping

Authored target names and app-facing provider labels are not always the same thing.

Examples from current code:

• authored claude maps to app/runtime target claude
• authored codex-package maps to app/runtime target codex
• authored gemini maps to app/runtime target gemini
• authored cursor maps to app/runtime target cursor
• authored opencode maps to app/runtime target opencode

Surface-specific target id rule

The same plugin may be described through different target vocabularies depending on the backend surface:

• authored/catalog truth:
  • claude
  • codex-package
  • codex-runtime
  • gemini
  • cursor
  • cursor-workspace
  • opencode
• lifecycle-manageable truth:
  • claude
  • codex
  • gemini
  • cursor
  • opencode
• app-facing provider labeling:
  • Anthropic
  • Codex
  • optionally later other providers

This is already visible in current code:

• authored plugin metadata and pluginmanifest preserve codex-package
• integrationctl normalizes that into lifecycle target codex
• the UI should render a provider lane label such as Codex, not leak raw lifecycle ids everywhere

Recommended rule:

• never force one single target field to carry all three meanings
• preserve target ids separately by surface
• use explicit fields such as:
  • authored_targets
  • manageable_targets
  • available_app_targets

Recommended catalog rule

Catalog entries should preserve both:

• authored target identifiers
• normalized app/runtime target identifiers

Why:

• authored compatibility and generated outputs still care about authored target names
• the app needs stable provider-level labels like Anthropic and Codex
• this avoids lossy translation

App-Facing Target Subset

plugin-kit-ai understands more targets than the claude_team plugin page needs to action directly.

For this integration, the primary app-facing actionable subset should be:

• claude
• codex-package

These map to the current app-facing provider lanes:

• Anthropic
• Codex

Out of scope for first actionability

These may still exist in authored metadata, but they should not drive primary install buttons in the first rollout:

• codex-runtime
• gemini
• cursor
• cursor-workspace
• opencode

Recommended UI rule

• the backend catalog may preserve full authored target support
• claude_team should derive primary provider labels and actions only from the app-relevant subset
• broader target support may appear as secondary detail later, but should not confuse the main install surface

Important nuance

This is not because those other targets are “fake”. It is because this app rollout has a narrower action surface than the full authored/plugin backend target space.

For example:

• plugin-kit-ai lifecycle already knows targets like gemini, cursor, and opencode
• pluginmanifest and targetcontracts know even broader authored/runtime distinctions such as codex-package vs codex-runtime

But the first plugin page rollout in claude_team should optimize for a clear and reliable main surface, not for exposing the entire backend target universe at once.

Why packaged support still does not mean first-class app actionability

Current platformmeta already exposes packaged profiles for:

• claude
• codex-package
• codex-runtime

That still does not mean all three should become first-class action lanes in claude_team.

Recommended rule:

• packaged/backend support answers “can the backend understand this target family?”
• app-primary actionability answers “should this app expose install/manage actions for this target in the first rollout?”
• those questions are related but not identical

This is one of the most important places where the plan must stay conservative.

Catalog Support Projection Rules

Catalog generation should preserve three different truths without collapsing them:

1. Authored targets

What the plugin repo declares in plugin.yaml.

Examples:

• claude
• codex-package
• codex-runtime
• gemini
• cursor
• cursor-workspace
• opencode

2. Backend-manageable lifecycle targets

What the current integrationctl lifecycle can actually manage today.

From current code, that target set is:

• claude
• codex-package
• gemini
• cursor
• opencode

Notably, it does not include:

• codex-runtime
• cursor-workspace

3. App-primary action targets

What claude_team should expose as first-class install lanes in this rollout.

Recommended set:

• claude
• codex-package

Current public target universe in plugin-kit-ai

From current platformmeta code, the public target universe is already split into:

• packaged profiles:
  • claude
  • codex-package
  • codex-runtime
• tooling profiles:
  • gemini
  • cursor
  • cursor-workspace
  • opencode

This is useful context because it shows that the backend target universe is intentionally broader than the first plugin-page rollout.

Required contract rule

A catalog entry should be able to preserve all three layers separately, for example:

• authored_targets
• manageable_targets
• primary_action_targets

This keeps the system honest:

• authored truth stays intact
• backend actionability stays explicit
• app UI stays focused

Product Model

Universal plugins

Source:

• universal-plugins-for-ai-agents/plugins

Properties:

• installable through plugin-kit-ai
• available for one or more targets
• primary browse/search source
• explicit target support labels

Native external installed plugins

Properties:

• already installed in a native agent surface
• not necessarily managed by plugin-kit-ai
• still visible in UI
• clearly labeled by target ownership

Example labels:

• Installed - Anthropic only
• Installed - Codex only

Source of Truth Model

Surface	Owner	Meaning
catalog	plugin-kit-ai	what universal plugins are available
discover	plugin-kit-ai	what native plugins are already observed
list	plugin-kit-ai	what universal plugins are managed
doctor	plugin-kit-ai	health and drift for managed universal plugins
renderer cache	claude_team	temporary UI cache only

Consistency rules

• every rendered universal_installed entry must be explainable by list
• every degraded managed universal entry must be explainable by doctor
• discover may overlap conceptually with universal entries, but never redefines managed ownership
• catalog must not advertise target/scope support that lifecycle will reject under normal supported conditions

Freshness and partial-view rules

These rules matter because catalog, discover, list, and doctor do not have the same source or refresh cost.

• list is authoritative for managed existence, even if catalog is stale or temporarily missing an entry
• doctor is authoritative for managed health, even if catalog is stale
• discover is authoritative for observed native external existence, unless suppressed by stronger managed-overlap evidence
• failed or stale catalog must not make a managed entry disappear from the page
• failed or stale discover must not invent that native external entries were removed
• the app may mark data stale, but it must not rewrite ownership because one backend view is temporarily unavailable

Consistency invariants the backend contract should preserve

1. every managed entry returned by doctor must also be representable in list by the same managed grouping key
2. discover must either suppress managed overlap or mark it explicitly, but must not silently contradict list
3. catalog may omit optional storefront metadata, but must not change canonical integration_id
4. claude_team must never resolve a contradiction by guessing - it should preserve both truths and degrade the UI honestly

Identity, Matching, and Dedupe

Universal identity

Canonical key:

• integration_id

Native external identity

Canonical key:

• native_target + native_plugin_id + scope-set

Matching rule

matched_integration_id is advisory only. It does not convert a native external entry into a universal entry.

Match confidence

Recommended values:

• match_confidence: exact | heuristic | none
• match_basis: same_repo_same_plugin_id | same_marketplace_identity | manual_mapping | name_heuristic | unknown

Target-specific matching ladder

The backend should classify matches conservatively.

Recommended ladder:

Claude native external -> universal

exact only when the backend can prove the same marketplace identity, for example:

• same native plugin ref
• or same marketplace identity pair such as:
  • plugin id
  • marketplace name

heuristic only when:

• display name matches strongly
• and target is the same
• and there is no stronger conflicting candidate

none when:

• only loose name similarity exists
• or more than one universal plugin could plausibly match

Important note:

• current managed Claude installs use synthetic refs such as integration_id@integrationctl-<integration_id>
• native external Claude installs from official or third-party marketplaces may use different marketplace identities
• therefore name equality alone is not enough for exact

Codex native external -> universal

exact only when the backend can prove the same native plugin identity, for example:

• marketplace entry name equals integration id
• and the same plugin reference is observed consistently in:
  • marketplace catalog
  • config toggle ref
  • or managed plugin root path

heuristic only when:

• marketplace entry name strongly matches integration id
• but not every supporting surface is available

none when:

• only title-level similarity exists
• or multiple universal integrations could map to the same observed native name

Important note:

• current Codex-managed installs use integration_id as the marketplace entry name
• they also create related evidence in:
  • .agents/plugins/marketplace.json
  • plugin root path under plugins/<integration_id>
  • config plugin ref <integration_id>@<marketplace_name>
• that is good raw evidence, but the backend should still keep external discovery conservative

Preferred matching evidence by target

Target	Strongest evidence	Weaker evidence	Unsafe alone
Claude	plugin ref, marketplace name + plugin id pair	stable display name + target	display name alone
Codex	marketplace entry name + config plugin ref + plugin root agreement	marketplace entry name only	title similarity alone

Recommended rule:

• only the strongest evidence column may justify exact
• weaker evidence may justify heuristic
• the unsafe column must map to none

Matching invariants

• exact must be explainable from stable identity-bearing fields, not from display text
• heuristic must never unlock destructive actions
• heuristic must never collapse two entries into one
• if confidence is below exact, the UI should treat the relation as advisory only
• the app must not recalculate confidence differently from the backend
• overlap suppression and matching are different decisions
• an entry may be suppressed as managed overlap without ever being exposed as a native external match candidate

Renderer rule:

• only strong bases may drive stronger UI hints
• heuristic matches must never auto-merge entries or unlock stronger actions

Catalog Production Model

This must be explicit because the universal repo is the source of truth for available universal plugins, but it must not become the app contract directly.

Source of universal entries

Universal catalog entries should be generated from:

• 777genius/universal-plugins-for-ai-agents/plugins/*

using plugin-kit-ai, not using app-side parsing.

Recommended pipeline

1. select a pinned revision of universal-plugins-for-ai-agents
2. enumerate plugin directories under plugins/*
3. load each plugin through the richer authored plugin model, ideally the same pluginmanifest.Inspect path that already exposes:
   • manifest metadata
   • publication model
   • target contract details
4. derive normalized catalog entries
5. write a bundled snapshot for app packaging
6. optionally refresh from the same source later

Why publicationmodel is helpful but not enough on its own

Current publicationmodel.Model is useful for catalog generation because it already normalizes:

• package targets
• package families
• channel families
• install model
• authored docs
• managed artifacts

But by itself it does not carry the full storefront metadata set the app wants, such as:

• homepage
• repository
• keywords
• author
• license

Those live in the richer authored manifest path exposed through pluginmanifest.Inspection.Manifest.

Recommended rule:

• catalog generation should use pluginmanifest.Inspect as the main authored inspection entry point
• then combine:
  • Inspection.Manifest for storefront metadata
  • Inspection.Publication for publication/channel/package projection
  • Inspection.Targets plus target contracts for support and surface details

The app must not try to reconstruct that combination on its own.

Why this should not use the current narrow lifecycle loader only

The current integrationctl manifest loader is enough for lifecycle planning, but it preserves only:

• name
• version
• description
• targets
• derived deliveries

That is not enough on its own for the desired storefront contract.

Recommended resolution:

• treat catalog generation as its own backend translation layer
• allow that layer to read richer authored metadata
• still keep the final catalog output normalized and versioned

Why pluginmanifest.Inspect is a better catalog basis than the current lifecycle loader

From current code, pluginmanifest.Inspect already carries much richer input than integrationctl.Loader, including:

• authored manifest metadata
• publication model
• target contract fields such as install model, activation model, native root, portable kinds, native surfaces, and managed artifacts

That makes it a much better source for storefront and support badges.

Performance boundary

Current source resolution for lifecycle work may clone GitHub or git URL sources. That is acceptable for install/update style mutations.

It is not acceptable as the way to build the storefront catalog.

Catalog generation should work from:

• a pinned local checkout
• a prepared snapshot
• or another batch-friendly backend path

It should not resolve each storefront entry by cloning sources independently at runtime.

Alias rule

The first-party alias map is useful for CLI shortcuts like plugin-kit-ai add notion. It is not the storefront contract.

Source Reference Semantics

Source semantics must stay explicit. This is another place where the app should not invent meaning.

Current lifecycle source truth

From current integrationctl code, lifecycle source resolution already distinguishes:

• requested source ref
• resolved source ref
• local materialized path
• source digest

Examples:

• local path request:
  • requested kind local_path
  • resolved kind local_path
• GitHub repo-path request:
  • requested kind github_repo_path
  • resolved kind git_commit
• git URL request:
  • requested kind git_url
  • resolved kind git_commit

This is good and should be preserved in the app-facing lifecycle contract.

Alias semantics

Current first-party aliases are only convenience input forms such as:

• context7
• stripe
• notion

They resolve to concrete GitHub repo-path refs under the universal plugin repository.

Recommended rule:

• aliases are accepted CLI input
• aliases are not canonical identity
• aliases should not become the only stored source value in app state

Catalog source semantics

Catalog source semantics are different from lifecycle source semantics.

For the first app rollout, catalog entries should be treated as coming from a curated catalog snapshot with its own provenance, for example:

• snapshot source kind
• catalog revision
• generated-by backend version

The catalog should not pretend that every card was individually resolved through runtime lifecycle source resolution.

Recommended contract rule

Keep these source layers separate:

• requested_source_ref
  • lifecycle input truth
• resolved_source_ref
  • lifecycle resolved truth
• catalog_source
  • storefront snapshot provenance

The app should never collapse those into one ambiguous source string.

Recommended UI rule

• install detail may show requested and resolved source refs for managed universal installs
• storefront cards should usually show catalog provenance only when needed for debugging or advanced detail
• aliases may be accepted in user-facing install flows, but the stored and rendered lifecycle truth should remain normalized requested/resolved refs

Workspace Root and Project Scope Semantics

Project-scoped installs need one more rule-set because current target adapters do not all interpret project roots the same way.

Current code reality

plugin-kit-ai already distinguishes:

• user scope
• project scope
• stored workspace_root on managed installation records

But current adapters derive effective native roots differently:

• Claude
  • project settings path uses ProjectRoot(workspace_root, project_root)
• Codex
  • project marketplace root uses EffectiveGitRoot(workspace_root, project_root)
• OpenCode
  • project assets/config roots also use EffectiveGitRoot(workspace_root, project_root)
• Cursor
  • project config path currently uses ProjectRoot(workspace_root, project_root)

This means the same raw workspace path can lead to different effective native roots depending on target semantics.

Why this matters

If the app assumes one global meaning for workspace_root, it can easily:

• install into the wrong repo root
• render the wrong project target path in detail
• refresh the wrong context after mutation
• mis-explain project scope differences between providers

Recommended rule

• the app passes the raw user-selected workspace_root
• the backend owns target-specific effective-root normalization
• the app must not try to emulate EffectiveGitRoot or ProjectRoot logic itself

Recommended contract additions

Where useful, lifecycle and discovery payloads may expose explicit derived fields such as:

• workspace_root
  • raw project context that was requested or persisted
• effective_native_root
  • target-specific derived root actually used for native files
• native_scope_root
  • optional friendlier alias if that reads better in the contract

Phase-1 minimum:

• workspace_root is required for project-scoped managed installs
• missing project workspace_root must remain a hard backend error
• target-specific effective root may be additive if not ready immediately

Recommended app rule

• UI selection should talk in terms of the chosen project/workspace
• backend detail and diagnostics may show the effective native root when it differs
• app logic for mutation, refresh, and cache keys should continue to use the raw workspace context plus target, not a home-grown rewritten root

Why this should stay backend-owned

Current target adapters already encode platform-specific expectations.

Examples:

• Codex project installs intentionally anchor to effective git root
• Claude project installs intentionally target project-local settings path

Trying to centralize those rules in Electron would duplicate platform policy and create drift.

Metadata Truth Table

One of the biggest ways this migration can go wrong is promising metadata that the backend does not actually know reliably.

Metadata that already exists today in authored source

From current authored plugin source, plugin-kit-ai can already obtain:

• integration_id
• version
• description
• homepage
• repository
• license
• keywords
• declared targets

Important caveat

The current integrationctl manifest loader does not carry all of those fields forward today.

So there are two safe paths:

1. extend integrationctl manifest loading to preserve richer metadata
2. build catalog from the richer authored-model path and translate it into the catalog contract

What must not happen:

• the app inventing those fields
• the app scraping raw repo files directly
• two different backend paths returning contradictory storefront metadata

Metadata the backend can derive safely

The backend can also derive:

• generated delivery_kinds
• available_targets
• supported_scopes_by_target from target adapter capabilities
• readme location using a stable default rule
• provenance fields such as source ref, revision, manifest digest, generated-by version

Metadata that is not a safe phase-1 assumption

These fields are optional curation data, not phase-1 requirements:

• category
• icon_url
• install_count
• popularity
• featured_rank

Recommended default

Phase 1 should require only:

• name
• description
• version
• homepage / repository
• keywords
• target support
• scope support
• README/detail

If category, icon, or popularity are absent, the UI should hide or degrade those features honestly.

Storefront Detail and README Semantics

The plugin detail surface must use the authored human guide, not arbitrary generated root docs.

Current code reality

plugin-kit-ai already generates root-facing docs such as:

• README.md
• GENERATED.md
• boundary guidance docs

But those are operational/generated root entrypoints. They are not the best source of storefront detail content.

Current code also makes the authored README explicit:

• the managed root README.md points readers back to plugin/README.md
• generated docs inventory also treats root docs differently from managed outputs

That is a strong signal that the authored README remains the source of truth for human-facing plugin detail.

Recommended detail rule

For universal catalog entries, the default detail source should be:

• authored plugin/README.md

Not:

• generated root README.md
• GENERATED.md
• boundary docs like AGENTS.md

Why this matters

If the app accidentally uses generated root docs as storefront detail:

• the detail view becomes noisy and operational
• it may emphasize generate/normalize workflows instead of plugin value
• the same plugin can appear to have unstable detail content depending on packaging mode

Recommended contract shape

The catalog contract should prefer an explicit detail reference such as:

• detail_kind: "authored_readme"
• detail_ref

Recommended phase-1 default:

• detail_kind = "authored_readme"
• detail_ref points to the authored README location within the catalog source snapshot

Recommended app rule

• plugin cards use catalog summary fields
• plugin detail loads the authored detail reference when available
• if detail content is missing, the app should degrade honestly instead of substituting generated operational docs

Catalog Field Ownership Matrix

This makes the contract much easier to implement because it is explicit about where each field should come from.

Catalog field	Recommended source in plugin-kit-ai	Notes
integration_id	authored manifest name	stable universal identity
display_name	authored manifest name initially	future curation can improve presentation
description	authored manifest description	required
version	authored manifest version	required
homepage_url	richer authored model	not present in current narrow lifecycle manifest
repository_url	richer authored model	not present in current narrow lifecycle manifest
keywords	richer authored model	phase-1 safe metadata
authored_targets	authored manifest targets	preserve exact authored truth
manageable_targets	lifecycle target mapping / registered adapters	what backend can actually act on
primary_action_targets	app rollout policy	narrower than full backend target universe
available_app_targets	backend target projection	provider-facing labels for claude_team
supported_scopes_by_target	target adapter capabilities	backend-owned truth
capabilities	delivery mapping and/or target contract data	do not invent in app
readme_url	catalog translation layer	use a stable default rule
category	optional curation metadata	do not block phase 1
icon_url	optional curation metadata	do not block phase 1
catalog_revision	catalog generation pipeline	provenance
generated_by_plugin_kit_version	CLI/backend build info	provenance

Important rule

If a field does not have a trustworthy backend source yet, phase 1 should omit or degrade it instead of synthesizing it in the app.

Effective Metadata Projection

Catalog generation must distinguish between:

• shared plugin metadata
• target-specific effective metadata

This matters because current plugin-kit-ai code already allows target-specific metadata overlays, especially for package-style targets such as codex-package.

Shared metadata

Shared metadata should come from the authored manifest layer:

• name
• version
• description
• base homepage
• base repository
• base license
• base keywords
• base author

This is the safest metadata for:

• mixed-target storefront cards
• cross-target search
• universal identity

Target-specific effective metadata

For some targets, especially codex-package, the effective generated package metadata is:

• base manifest metadata
• plus allowed target-specific overrides from targets/<target>/package.yaml

Current code already proves this path exists:

• codex-package generation merges base manifest metadata with optional targets/codex-package/package.yaml
• validation checks the generated Codex package metadata against that merged expectation

Recommended catalog rule

The catalog contract should preserve both layers explicitly:

• shared metadata for the universal entry itself
• optional effective_target_metadata for targets that project different package metadata

Example shape:

• shared_metadata
• effective_target_metadata.codex

At minimum, per-target effective metadata may include:

• homepage
• repository
• license
• keywords
• author

Recommended UI rule

• list cards should use shared metadata
• provider-specific effective metadata should appear only in target detail sections or provider-specific support details
• the app must not silently replace universal card metadata with one target's override

Why:

• otherwise a codex-package override could accidentally become the visible truth for a plugin that is still conceptually universal
• that would make shared cards unstable and misleading across providers

Recommended phase-1 default

If effective target metadata is not yet emitted in the contract:

• use shared metadata only
• do not guess target-specific homepage/repository/license in the app
• add effective target metadata later as an additive contract field

Conservative phase-1 metadata rule

For phase 1, treat target-specific effective metadata as enhancement, not as a dependency.

That means:

• search, ranking, and primary cards use shared metadata only
• target-specific metadata appears only when backend emits it explicitly
• absence of effective target metadata must never block installability rendering
• the app must not read target-specific docs or package manifests directly to reconstruct this layer

Native Discovery Model

discover is a genuinely new backend surface. It must not be implemented as a thin wrapper over current List or current per-target Inspect.

Why current per-target Inspect is not a safe discovery backend

This needs to be explicit because reusing current adapter Inspect can look tempting, but it is the wrong abstraction for external discovery.

Claude

Current Claude inspect logic is still strongly lifecycle-oriented:

• it resolves inspect identity from:
  • in.IntegrationID
  • or in.Record.IntegrationID
• native plugin-list confirmation then looks for a specific plugin ref:
  • defaulting to integration_id@integrationctl-<integration_id>
  • or a managed plugin ref from record metadata
• if that specific confirmation path does not resolve, current inspect can still fall back to installed when native files or CLI availability make the managed candidate look plausible

That is appropriate for managed lifecycle verification. It is not appropriate for general native external discovery, because external installs may use:

• a different marketplace name
• a different plugin ref
• or no managed lifecycle record at all

Codex

Current Codex inspect logic is also lifecycle-oriented:

• inspect inputs derive integration_id from the managed record
• scope/path construction depends on that managed integration identity
• state classification assumes it is inspecting a known candidate plugin root
• current observed-surface logic is built around a specific expected catalog path, plugin root, and config path
• current lifecycle classification then reasons from managed cache presence plus that expected surface bundle

That is useful for verifying a managed installation. It is not enough for general native external enumeration, which first needs to discover candidates before it can classify them.

Recommended backend rule

• discover must be its own scanner-oriented surface
• it may reuse helper functions from adapters where useful
• but it must not simply loop over current adapter Inspect without an independent candidate-enumeration layer

Critical discovery anti-patterns

These are explicitly forbidden:

1. calling current adapter Inspect on arbitrary filesystem hits and treating the result as native discovery truth
2. suppressing a discovered entry before comparing it against managed lifecycle evidence
3. upgrading a heuristic name match into an exact overlap suppression signal
4. deriving native manageability from UI assumptions instead of backend evidence
5. hiding a discovered entry only because catalog lookup failed or was stale

If implementation pressure pushes toward any of these shortcuts, the correct fix is to extend backend discovery evidence, not to make the app smarter.

Practical implementation shape

Recommended backend structure:

1. enumerate native candidates from target-specific sources
2. derive native identity and evidence for each candidate
3. suppress candidates already explained by managed lifecycle state
4. classify observed state
5. compute advisory relation to universal catalog
6. emit normalized discovery entries

This keeps discover honest:

• enumeration first
• classification second
• matching last
• read-only throughout

Claude discovery sources

• ~/.claude/plugins/installed_plugins.json
• ~/.claude/settings.json
• <project>/.claude/settings.json
• <project>/.claude/settings.local.json

Codex discovery sources

• ~/.agents/plugins/marketplace.json
• <project>/.agents/plugins/marketplace.json
• ~/.agents/plugins/plugins/<integration-id>
• <project>/.agents/plugins/plugins/<integration-id>
• ~/.codex/plugins/cache/<marketplace>/<integration-id>/local
• ~/.codex/config.toml

Required observed states

• observed_active
• observed_disabled
• observed_prepared
• observed_degraded

Recommended observed-state derivation rules

Observed-state classification should be target-specific and evidence-driven.

Codex

Current adapter code already implies a practical state ladder:

• observed_active
  • cache bundle exists
  • and marketplace catalog + plugin root are present
  • and config does not mark the plugin disabled
• observed_disabled
  • cache bundle exists
  • and config toggle is present and disabled
• observed_prepared
  • marketplace entry exists and plugin root exists
  • but activation evidence such as cache bundle is not present yet
• observed_degraded
  • only part of the expected prepared/install surface exists
  • or cache exists while managed marketplace source is missing or drifted

Important rule:

• discover should keep this richer observed-state truth
• the app should not collapse everything into plain installed/not installed

Codex evidence mapping table

The first implementation should stay conservative and evidence-driven.

Evidence seen by discovery	Recommended observed state	Why
marketplace entry + plugin root + installed cache, config not disabled	observed_active	strongest “prepared and activated” signal available today
installed cache + config toggle present and disabled	observed_disabled	disable state is explicit
marketplace entry + plugin root, but no installed cache yet	observed_prepared	package is staged but native activation is not complete
only one of marketplace entry or plugin root exists	observed_degraded	partial native surface
installed cache exists but marketplace entry or plugin root is missing	observed_degraded	drifted or partially removed managed/native surface
config references plugin, but marketplace entry and plugin root are both absent	observed_degraded	stale toggle or orphaned config

Conservative phase-1 defaults for Codex discovery

Until discovery evidence is richer, prefer these defaults:

• if evidence is ambiguous, downgrade to observed_degraded
• do not claim observed_active from config evidence alone
• do not infer exact universal matching from marketplace entry name alone
• do not infer safe removal from discovered Codex paths alone
• do not suppress a discovered Codex entry unless managed-overlap evidence includes owned objects or stable lifecycle evidence

Claude

For phase 1, Claude discovery may stay simpler:

• observed_active
  • plugin appears in native plugin list and is enabled
• observed_disabled
  • plugin appears in native plugin list and is disabled
• observed_degraded
  • settings or install evidence exists but plugin list cannot confirm a clean state
• observed_prepared
  • optional future state only if backend gains a meaningful pre-install or staged marketplace concept for external Claude installs

Recommended rule:

• do not force artificial state parity between Claude and Codex
• preserve richer Codex states where the backend can actually justify them

Required extra fields

• native_target
• native_plugin_id
• installed_scopes
• detected_source
• manageability
• matched_integration_id
• match_confidence
• match_basis
• identity_evidence
• activation_hint

Discovery manageability rule

The backend must declare whether a native external entry is:

• display_only
• safe_remove
• safe_adopt
• or another explicit future mode

The app must not infer destructive authority.

Discovery overlap suppression rule

discover must not blindly report every observed native install as native_external_installed.

Why this is necessary:

• managed universal installs also materialize into native agent surfaces
• a naive scanner would rediscover those same installs and duplicate them as native external entries

Recommended backend rule:

• discover should load managed lifecycle state, or equivalent managed evidence, before finalizing external entries
• if an observed native install is already explained by managed lifecycle state with high confidence, it should either:
  • be suppressed from discovery output, or
  • be explicitly marked as managed overlap for app-side filtering

Recommended default:

• suppress managed-overlap entries in the discovery payload
• discovery should describe only installs that are not already explained by managed lifecycle state

Managed-overlap evidence examples

Claude examples from current code:

• synthetic marketplace name pattern integrationctl-<integration_id>
• managed plugin ref recorded in lifecycle metadata
• managed materialized marketplace root under ~/.plugin-kit-ai/materialized/claude/<integration_id>

Codex examples from current code:

• managed plugin root under .agents/plugins/plugins/<integration_id>
• managed catalog entry name equal to integration_id together with lifecycle-owned native objects
• managed config ref <integration_id>@<catalog_name> when that catalog name is already tied to a managed installation

Important rule:

• suppression should prefer owned native object evidence and managed lifecycle state over name heuristics
• name equality alone is not enough to classify something as managed overlap

Managed Lifecycle Model

Existing lifecycle surfaces

• list for managed installations
• doctor for managed drift / activation / auth attention
• add, update, remove, repair for mutations

Important current gap

Current Report.Targets do not identify which integration a target belongs to.

The app needs lifecycle JSON to include integration-level context such as:

• integration_id
• managed_entry_key
• source refs
• policy scope
• workspace root

Why the current raw lifecycle report is not enough for app integration

Today the raw integrationctl lifecycle query shape is still too flat for the plugin page.

In current code:

• domain.Report contains only:
  • summary
  • targets
  • warnings
• domain.TargetReport contains per-target state such as:
  • target
  • delivery_kind
  • state
  • activation_state
  • environment_restrictions
  • manual_steps

What it does not preserve at the same level:

• integration_id
• requested_source_ref
• resolved_source_ref
• resolved_version
• policy.scope
• workspace_root
• a stable grouping boundary between one integration and another

That matters because the app needs to render cards and detail views at the integration-entry level, not as an ungrouped stream of target facts.

Recommended rule:

• plugin-kit-ai should keep its current internal normalized lifecycle model
• but the app-facing JSON contract must expose managed entries grouped by integration
• claude_team must not try to reconstruct integration grouping from flat target rows by heuristics

Required grouped lifecycle identifiers

For app-facing lifecycle JSON, each managed entry should include at minimum:

• managed_entry_key
• integration_id
• requested_source_ref
• resolved_source_ref
• resolved_version
• policy.scope
• workspace_root

Recommended rule:

• managed_entry_key should be stable for one stored installation record
• it should not depend on target row order
• it should be safe for the app to use as the primary cache and merge key for managed lifecycle entries

Without this, the frontend will eventually drift into reconstructing groups from target arrays, which is fragile and unnecessary.

Conservative phase-1 grouped lifecycle rule

Until the backend exposes a more formal record identifier, phase 1 should still require:

• one grouped managed entry per stored installation record
• stable ordering of managed_entries
• stable ordering of nested targets
• explicit grouping keys in payload, not implied grouping by adjacent rows

The app must treat missing grouping keys as a compatibility problem, not as an invitation to reconstruct them heuristically.

Critical CLI semantic to freeze

Current integrations mutating commands default to --dry-run=true.

That is good for humans in a terminal, but dangerous for app integration.

Recommended rule:

• machine-readable mutating calls from claude_team must always pass explicit execution mode
• either:
  • --dry-run=false, or
  • a future clearer flag such as --apply

The app must never rely on CLI defaults for mutating behavior.

JSON Contract Style

plugin-kit-ai already has a public JSON contract style in surfaces like validate and publication. The new integrations contracts should follow that style instead of inventing a second JSON dialect.

Required envelope rules

• top-level format
• top-level schema_version
• explicit request context fields where relevant
• top-level warning_count
• top-level warnings
• one canonical payload field rather than many competing summary shapes

Requested context rule

Current public JSON reports in plugin-kit-ai already use request-context fields such as:

• requested_target
• requested_platform

Recommended rule for the integrations surfaces:

• include explicit request-context fields when the command accepts them
• examples:
  • requested_targets
  • requested_scope
  • requested_workspace_root
  • requested_integration_id

This makes automation and debugging much safer than inferring invocation context from payload shape.

Required array guarantees

In schema version 1, the following fields should be arrays, never null:

• warnings
• entries
• managed_entries
• targets

Compatibility rules

• additive fields are allowed within the same schema_version
• semantic changes to existing fields require a new schema_version
• removing a field the app depends on requires a new schema_version
• enum meaning changes require a new schema_version

App behavior on unsupported versions

If the backend returns a newer unsupported schema:

• read-only views may continue only if safe
• lifecycle actions must be disabled
• the UI must explain the compatibility mismatch clearly

Process exit and payload semantics

This must be explicit because current plugin-kit-ai already has public JSON commands that can:

• print a valid JSON payload to stdout
• then still exit non-zero because the payload describes a failing or issue-bearing report

Current examples in code:

• validate --format json
• publication doctor --format json

Recommended rule for the integrations surfaces:

• stdout JSON is the canonical machine-readable payload
• process exit code is still meaningful, but it must not be the only signal the app uses
• claude_team should:
  • first attempt to parse a valid JSON payload from stdout
  • then interpret payload-level fields such as outcome, ok, warning_count, failure_count, issue_count
  • only fall back to process-exit-only handling when no valid contract payload exists

Without this rule, the app will misclassify structured partial failures as transport failures.

Recommended outcome semantics

For machine-readable integrations surfaces, outcome should be explicit in the payload instead of inferred only from process exit:

• read-only reports:
  • may expose ok, warning_count, and optional issue_count
• mutating results:
  • should expose explicit outcome
  • recommended values:
    • planned
    • applied
    • partial_success
    • failed

The exact enum may still evolve, but the contract must keep payload-level outcome explicit.

Recommended identifiers

• plugin-kit-ai/integrations-report
• plugin-kit-ai/integrations-result
• plugin-kit-ai/integrations-catalog
• plugin-kit-ai/integrations-discovery

Recommended Contract Drafts

These drafts are intentionally close to the current integrationctl domain model. They should extend the existing normalized result shape, not invent a second unrelated response model.

Managed lifecycle list

{
  "format": "plugin-kit-ai/integrations-report",
  "schema_version": 1,
  "report_kind": "managed_list",
  "requested_targets": [],
  "warning_count": 0,
  "warnings": [],
  "summary": "1 managed integration(s) in state.",
  "managed_entries": [
    {
      "managed_entry_key": "project:/repo:context7",
      "integration_id": "context7",
      "requested_source_ref": {
        "kind": "github_repo_path",
        "value": "github:777genius/universal-plugins-for-ai-agents//plugins/context7"
      },
      "resolved_source_ref": {
        "kind": "git_commit",
        "value": "https://github.com/777genius/universal-plugins-for-ai-agents@abc123"
      },
      "resolved_version": "0.1.0",
      "workspace_root": "/repo",
      "policy": {
        "scope": "project",
        "auto_update": true,
        "adopt_new_targets": "manual"
      },
      "targets": [
        {
          "target_id": "claude",
          "delivery_kind": "claude-marketplace-plugin",
          "capability_surface": ["mcp"],
          "state": "installed",
          "activation_state": "reload_pending",
          "source_access_state": "ok"
        }
      ]
    }
  ]
}

Universal catalog

{
  "format": "plugin-kit-ai/integrations-catalog",
  "schema_version": 1,
  "requested_targets": ["claude", "codex"],
  "warning_count": 0,
  "warnings": [],
  "source": {
    "kind": "bundled_snapshot",
    "fetched_at": "2026-04-18T12:00:00Z",
    "revision": "abc123",
    "stale": false
  },
  "entries": [
    {
      "entry_kind": "universal_catalog",
      "integration_id": "context7",
      "display_name": "Context7",
      "description": "Shared MCP plugin for documentation lookup.",
      "authored_targets": ["claude", "codex-package"],
      "manageable_targets": ["claude", "codex-package"],
      "primary_action_targets": ["claude", "codex-package"],
      "available_app_targets": ["claude", "codex"],
      "keywords": ["mcp", "docs"],
      "category": null,
      "homepage_url": "https://context7.com",
      "repository_url": "https://github.com/upstash/context7",
      "readme_url": "https://raw.githubusercontent.com/777genius/universal-plugins-for-ai-agents/main/plugins/context7/plugin/README.md",
      "version": "0.1.0",
      "effective_target_metadata": {
        "codex": {
          "homepage_url": "https://context7.com",
          "repository_url": "https://github.com/upstash/context7",
          "keywords": ["mcp", "docs"]
        }
      },
      "supported_scopes_by_target": {
        "claude": ["user", "project"],
        "codex": ["user", "project"]
      },
      "capabilities": ["mcp"],
      "source_ref": "github:777genius/universal-plugins-for-ai-agents//plugins/context7",
      "catalog_revision": "abc123",
      "generated_by_plugin_kit_version": "0.0.0"
    }
  ]
}

Native discovery

{
  "format": "plugin-kit-ai/integrations-discovery",
  "schema_version": 1,
  "requested_targets": ["claude", "codex"],
  "requested_workspace_root": "/repo",
  "warning_count": 0,
  "warnings": [],
  "entries": [
    {
      "entry_kind": "native_external_installed",
      "native_target": "claude",
      "native_plugin_id": "context7@claude-plugins-official",
      "display_name": "Context7",
      "description": "Installed from Claude marketplace.",
      "installed_scopes": ["user"],
      "detected_source": "claude_marketplace",
      "manageability": "display_only",
      "matched_integration_id": "context7",
      "match_confidence": "exact",
      "match_basis": "same_marketplace_identity",
      "identity_evidence": [
        "native_plugin_ref=context7@official-marketplace",
        "marketplace_name=official-marketplace"
      ],
      "observed_state": "observed_active",
      "activation_hint": "none"
    }
  ]
}

Mutating lifecycle result

{
  "format": "plugin-kit-ai/integrations-result",
  "schema_version": 1,
  "requested_integration_id": "context7",
  "requested_targets": ["claude", "codex"],
  "requested_scope": "project",
  "requested_workspace_root": "/repo",
  "ok": false,
  "warning_count": 0,
  "warnings": [],
  "outcome": "partial_success",
  "report": {
    "operation_id": "add-context7-...",
    "summary": "Managed targets processed for integration \"context7\".",
    "integration_id": "context7",
    "targets": [
      {
        "target_id": "claude",
        "action_class": "install_target",
        "state": "installed",
        "activation_state": "reload_pending",
        "environment_restrictions": ["reload_required"],
        "manual_steps": ["reload Claude plugins"]
      },
      {
        "target_id": "codex",
        "action_class": "install_target",
        "state": "activation_pending",
        "activation_state": "restart_pending",
        "environment_restrictions": ["native_activation_required", "new_thread_required"],
        "manual_steps": ["restart Codex", "open a new thread"]
      }
    ]
  }
}

Entry Derivation and Conflict Resolution

This is the most important renderer rule-set in the whole integration.

The app must derive the plugin list deterministically from four backend surfaces:

• catalog
• discover
• list
• doctor

It must not invent entries or merge classes by guesswork.

Backend surface ownership

Each backend surface owns a different truth:

• catalog
  • universal storefront truth
  • metadata for universal plugins
  • target support projection
  • provider-facing installability projection
• list
  • managed universal installed truth
  • policy scope
  • workspace root
  • resolved source
  • installed targets
• doctor
  • managed universal health augmentation
  • degraded/auth/activation attention
  • target-level restrictions and manual steps
• discover
  • native external installed truth
  • observed scopes
  • detected source
  • explicit manageability
  • optional relation hints to universal entries

Entry derivation algorithm

Recommended deterministic algorithm:

1. Load list and build a managed map keyed by integration_id.
2. Overlay doctor onto that managed map by integration_id + target_id.
3. Load catalog and build a universal catalog map keyed by integration_id.
4. For every managed entry:
   • create one universal_installed entry
   • enrich it from matching catalog metadata when available
   • keep lifecycle-owned fields from list/doctor
5. For every catalog entry without a managed match:
   • create one universal_available entry
6. For every discovery entry:
   • create one native_external_installed entry
   • keep it separate even if it matches a universal integration
7. Attach relation metadata between native_external_installed and universal entries only as advisory linkage, never as a merge.
8. Sort using the installed-first ranking rules already defined in this plan.

Non-negotiable derivation invariants

• doctor may augment managed entries, but must never create standalone entries
• catalog may create only universal entries
• discover may create only native external entries
• catalog must never mark an entry as installed
• discover must never mark an entry as managed
• advisory matching must never change entry_kind
• if two surfaces disagree, the surface that owns that truth wins

Field precedence rules

For universal_installed entries:

• identity:
  • from list
• installed state:
  • doctor if present
  • otherwise list
• lifecycle actions:
  • from lifecycle capabilities and current runtime support
• scope and workspace root:
  • from list
• display metadata:
  • catalog first
  • lifecycle fallback only when catalog is missing

For universal_available entries:

• identity and metadata:
  • from catalog
• supported targets and scopes:
  • from catalog
• installed state:
  • none

For native_external_installed entries:

• identity:
  • from discover
• observed state and scopes:
  • from discover
• manageability:
  • from discover
• relation to universal entries:
  • advisory only

Conflict resolution rules

If catalog says a universal plugin exists, but list has no managed installation:

• render universal_available

If list has a managed installation, but catalog entry is missing because the catalog snapshot is stale or incomplete:

• still render universal_installed
• mark catalog metadata as unavailable
• do not hide the installed entry

If discover finds a native external install that strongly matches a universal plugin:

• show both entries
• add relation hints such as Also available as universal plugin
• do not collapse them into one card

If doctor returns a degraded target while list shows the same target as installed:

• doctor wins for health/status presentation
• list remains the source of integration ownership and policy context

Renderer field ownership

Recommended renderer ownership matrix:

• entry_kind
  • derived by the app from surface class, never from heuristics
• integration_id
  • catalog or list
  • never guessed from discovery display name alone
• display_name
  • catalog for universal entries
  • discover for native external entries
• description
  • catalog for universal entries
  • discover for native external entries
• supported_targets
  • catalog
• manageable_targets
  • catalog
• primary_action_targets
  • catalog
• installed_targets
  • list, augmented by doctor
• health_state
  • doctor
• observed_scopes
  • discover
• manageability
  • discover
• resolved_source_ref
  • list
• workspace_root
  • list

Why this section matters

Without these derivation rules, the app will almost certainly drift into one of the following failure modes:

• silently merging universal and native external installs
• showing available when something is already installed
• losing managed entries when the catalog snapshot is stale
• inventing manageability for discovered native installs
• letting catalog or discover override lifecycle truth they do not own

Worked Examples

These examples are intentionally concrete. They should be used as golden fixtures for both backend contracts and app normalization.

Example 1 - managed universal install with overlap suppression

Situation:

• catalog contains universal context7
• list contains managed installation context7
• doctor says target is healthy
• native surfaces also visibly contain the installed plugin because managed lifecycle already materialized it there

Expected result:

• render one universal_installed entry for context7
• do not render a second native_external_installed copy for the same managed install
• health comes from doctor
• metadata comes from catalog

Why:

• discovery overlap suppression should remove the duplicate native observation

Example 2 - native Claude marketplace install with no managed lifecycle record

Situation:

• catalog contains universal context7
• list does not contain context7
• discover finds a Claude-native install from a marketplace source
• backend can only establish an advisory relation to universal context7

Expected result:

• render one native_external_installed entry
• optionally render the universal context7 catalog card separately if not installed through plugin-kit-ai
• show relation hint such as Also available as universal plugin
• do not collapse them into one entry
• do not show destructive managed actions unless discovery explicitly says they are safe

Example 3 - stale or partial catalog snapshot

Situation:

• list contains managed demo-plugin
• doctor contains managed demo-plugin
• catalog snapshot does not contain demo-plugin

Expected result:

• still render demo-plugin as universal_installed
• preserve lifecycle actions and managed state
• degrade catalog-derived metadata gracefully
• do not hide the entry just because storefront metadata is missing

Why:

• managed installation truth belongs to list
• catalog absence is not permission to erase installed truth

Example 4 - Codex prepared but not activated yet

Situation:

• discover finds:
  • marketplace entry
  • plugin root
  • no cache bundle yet
• backend classifies the Codex plugin as prepared but not active

Expected result:

• render native_external_installed
• show observed state prepared
• do not claim it is fully active
• if the backend has an activation hint, show it
• do not pretend this equals a healthy managed universal install

Example 5 - degraded Codex native install

Situation:

• cache bundle exists
• but expected marketplace source or plugin root is missing or drifted

Expected result:

• render native_external_installed
• show observed state degraded
• do not auto-remove or auto-adopt
• keep relation to universal entries advisory only

Example 6 - heuristic match only

Situation:

• discover finds native plugin display name Notes
• catalog contains more than one plausible universal candidate with similar wording

Expected result:

• either no match or heuristic
• no merge
• no stronger action unlock
• no exact badge or stronger “same plugin” copy

Command Semantics Matrix

The app integration should treat command classes differently.

Surface	Command class	Side effects	App expectation
catalog	read-only	none	safe to retry, safe to cache
discover	read-only	none	safe to retry, safe to cache
list	read-only	none	safe to retry, source of managed ownership
doctor	read-only	none	may report issues and still return structured JSON
add	mutating	yes	must pass explicit apply mode and explicit context
update	mutating	yes	must pass explicit apply mode
remove	mutating	yes	must pass explicit apply mode
repair	mutating	yes	must pass explicit apply mode

Read-only command rules

• read-only commands must never mutate native state
• read-only commands may return structured issues without that meaning a transport failure
• the app may cache read-only payloads
• the app may retry read-only commands automatically

Mutating command rules

• mutating commands must never rely on CLI defaults for apply behavior
• mutating commands must always receive explicit context:
  • target selection where relevant
  • scope where relevant
  • workspace root where relevant
• post-mutation refresh in the app must use the origin operation context, not global last-view state

Payload vs process-failure rule

For app integration there are two different failure classes:

• transport/process failure
  • no valid contract payload
  • process spawn failure
  • timeout
  • malformed JSON
• structured domain failure
  • valid contract payload exists
  • payload says ok=false, outcome=failed, issue_count>0, or equivalent

The app must distinguish those two classes clearly.

Why this section matters

Without a command semantics matrix, the app will eventually do one or more of these:

• treat every non-zero exit as an unstructured crash
• lose useful report payloads on domain failures
• accidentally rely on --dry-run=true
• retry mutating commands as if they were read-only

UI and Entry Model in claude_team

Normalized entry kinds

• universal_available
• universal_installed
• native_external_installed

Ranking order

1. installed universal
2. installed native external
3. available universal

Card labels

Universal:

• Universal
• Anthropic + Codex
• Anthropic only
• Codex only

Native external:

• Installed - Anthropic only
• Installed - Codex only

Detail requirements

Universal detail must show:

• keywords or tags
• category only when curated metadata exists
• target support
• scope support
• README/detail content
• lifecycle actions where supported

Native external detail must show:

• native target
• detected source
• observed scopes
• manageability
• relation to universal plugin when matched

Empty and degraded states

If catalog fails but discover works:

• show native external entries
• show a warning for universal catalog unavailability

If discover fails but catalog works:

• show universal entries
• do not claim “no installed plugins”
• show a warning that native discovery is unavailable

If backend version is unsupported:

• keep read-only view if safe
• disable lifecycle actions
• show explicit compatibility message

App Integration Mode

claude_team should integrate with plugin-kit-ai as a bundled CLI binary with versioned JSON I/O.

Not as:

• parsed human terminal output
• direct repo scraping
• an embedded second UI
• a Go library linked into Electron

Why:

• Electron already knows how to run bundled binaries
• JSON contracts are versionable and testable
• rollout and rollback stay simple
• the same backend surface can be exercised in dev and packaged builds

plugin-kit-ai Changes Required

Must-have for phase 0

1. integrations --format json around the current normalized lifecycle model
   🎯 10 🛡️ 10 🧠 4
   Approximate change size: 150-300 lines

2. integration-level fields in managed lifecycle JSON
   Needed because current Report.Targets do not identify which integration a target belongs to.
   🎯 10 🛡️ 10 🧠 5
   Approximate change size: 120-240 lines

3. integrations catalog --format json
   🎯 10 🛡️ 9 🧠 5
   Approximate change size: 180-350 lines

4. integrations discover --format json
   🎯 10 🛡️ 10 🧠 6
   Approximate change size: 220-450 lines

5. --workspace-root
   🎯 9 🛡️ 10 🧠 4
   Approximate change size: 80-180 lines

6. capability and scope metadata in catalog/discovery
   🎯 9 🛡️ 9 🧠 4
   Approximate change size: 80-160 lines

7. stable detail path or detail endpoint
   🎯 8 🛡️ 8 🧠 4
   Approximate change size: 60-140 lines

8. discovery trust/manageability metadata
   🎯 8 🛡️ 9 🧠 5
   Approximate change size: 80-180 lines

9. provenance metadata
   🎯 8 🛡️ 9 🧠 4
   Approximate change size: 60-140 lines

Explicitly not required for the first app rollout

• integrations sync
• workspace-lock driven desired-state workflows
• enable / disable UI
• native convenience uninstall
• adopt

Reason:

• they are either repo-lock oriented, lower-value than core lifecycle, or too risky before discover is proven out

claude_team Changes Required

Main-process additions

• PluginKitBinaryResolver
• PluginKitService
• PluginKitCatalogService
• PluginKitDiscoveryService
• PluginKitLifecycleService

Current app touchpoints this migration must replace or bypass

Current plugin flow in claude_team is still Claude-marketplace-shaped:

• src/main/services/extensions/catalog/PluginCatalogService.ts
• src/main/services/extensions/state/PluginInstallationStateService.ts
• src/main/services/extensions/install/PluginInstallService.ts
• src/main/services/extensions/ExtensionFacadeService.ts
• src/shared/types/extensions/plugin.ts
• src/renderer/store/slices/extensionsSlice.ts
• src/renderer/components/extensions/plugins/*

Recommended rule:

• do not keep stretching the current EnrichedPlugin model until it represents two different product classes badly
• introduce a new normalized plugin-entry layer for the plugin-kit-backed flow
• keep the legacy Claude-only model behind the feature flag until rollout is complete

Required app-side model split

Current EnrichedPlugin is shaped around one catalog plus installed counts:

• one canonical pluginId
• one marketplace-oriented metadata shape
• one merged installed-state view

That is not a safe long-term shape for mixed:

• universal_catalog
• universal_installed
• native_external_installed

Recommended rule:

• phase 1 should add a new normalized entry model for the plugin page
• old EnrichedPlugin can remain only inside the legacy backend path
• the new renderer/store layer should be built around explicit entry_kind, not around legacy marketplace assumptions

Responsibilities

PluginKitBinaryResolver

• resolve bundled binary
• resolve dev binary
• report version

PluginKitService

• execute commands
• validate format and schema_version
• apply timeouts
• normalize errors
• redact diagnostics

PluginKitCatalogService

• call catalog
• cache normalized results

PluginKitDiscoveryService

• call discover
• normalize native external entries

PluginKitLifecycleService

• call add/update/remove/repair/list/doctor
• normalize target-level results

Store and cache rules

• only one mutating operation per entryId + scope + projectPath
• catalog and discover may refresh in parallel
• stale responses must never overwrite newer state
• post-mutation refresh must use the origin operation context

Feature flag

Recommended app flag:

• extensions.plugins.backend = legacy | plugin-kit

Rollout Phases

Phase 0 - plugin-kit-ai contracts first

🎯 10 🛡️ 10 🧠 5
Approximate change size: 400-900 lines

Ship:

• JSON envelopes
• catalog
• discover
• --workspace-root
• schema docs
• source/provenance metadata

Acceptance:

• contracts are versioned and testable
• command classes are clearly read-only vs mutating
• managed lifecycle JSON includes integration-level context
• views are internally consistent across catalog, discover, list, and doctor

Phase 1 - read-only app integration

🎯 9 🛡️ 9 🧠 5
Approximate change size: 300-650 lines

Ship:

• bundled binary
• catalog rendering
• discovery rendering
• mixed-entry normalization
• ranking and labels
• feature-flagged backend switch

Acceptance:

• native external entries render truthfully
• universal catalog renders truthfully
• no misleading install button on native external entries
• page remains useful when catalog or discover partially fail
• warm-load performance remains acceptable
• plugin-kit-backed renderer state uses the new normalized entry model instead of overloading legacy EnrichedPlugin

Phase 2 - universal lifecycle actions

🎯 9 🛡️ 9 🧠 6
Approximate change size: 300-700 lines

Ship:

• install
• update
• remove
• repair
• target-level result rendering

Acceptance:

• direct Claude path green
• multimodel Anthropic + Codex path green
• user/project installs stable
• partial target results rendered truthfully
• safe retries do not corrupt state

Phase 3 - optional native convenience flows

🎯 7 🛡️ 8 🧠 7
Approximate change size: 150-400 lines

Optional:

• native uninstall where backend declares safe
• adopt where backend declares safe

Acceptance:

• no ambiguity between universal managed and native external state

Recommended First PR Sequence

PR 1 - JSON envelopes for existing lifecycle commands

Ship:

• integrations {list|doctor|add|update|remove|repair} --format json
• schema identifiers
• contract docs

Must not do:

• change lifecycle semantics
• invent catalog or discover early

PR 2 - managed lifecycle integration context

Ship:

• integration_id
• source refs
• policy scope
• workspace root
• target grouping under managed entries

Must not do:

• flatten per-target state into one integration status

PR 3 - explicit workspace root control

Ship:

• --workspace-root
• project-sensitive commands stop depending on implicit cwd

Must not do:

• silently rewrite missing workspace root into current cwd for project commands

PR 4 - universal catalog

Ship:

• normalized universal catalog JSON
• bundled snapshot story
• freshness metadata
• README/detail default rule

Must not do:

• block on category, icon, or popularity

PR 5 - native discovery

Ship:

• native external discovery JSON
• observed state
• activation hints
• manageability and match metadata

Must not do:

• auto-merge native and universal entries
• expose destructive actions without explicit backend manageability

PR 6 - claude_team read-only integration

Ship:

• bundled binary
• read-only mixed-entry rendering
• ranking
• degraded-state handling

Must not do:

• wire mutating actions before backend contracts are pinned

PR Exit Criteria

These checks are intentionally strict. A PR is not “basically done” if these are still fuzzy.

Backend contract PRs

Required:

• schema id is documented
• schema version is documented
• arrays are never null
• one golden fixture exists
• one failure fixture exists
• one compatibility test exists

Backend discovery PRs

Required:

• at least one Claude discovery fixture
• at least one Codex discovery fixture
• explicit observed-state coverage
• explicit manageability coverage
• no destructive side effects in read-only commands

App read-only integration PRs

Required:

• mixed-entry rendering works with only catalog
• mixed-entry rendering works with only discover
• degraded-state copy is truthful
• unsupported-version handling is visible and safe

App lifecycle PRs

Required:

• explicit dry-run protection
• target-level partial success rendering
• stale-response protection
• safe retry behavior

Risks and Lowest-Confidence Areas

1. Manifest model split between lifecycle and catalog

🎯 8 🛡️ 8 🧠 6

Why this is hard:

• the richer authored model and the narrower lifecycle model do not preserve the same metadata
• catalog wants richer storefront fields
• lifecycle wants compact normalized install truth

Best resolution:

• keep lifecycle and catalog as separate backend surfaces
• allow catalog generation to read the richer authored model
• normalize both into explicit JSON contracts

2. Codex native external discovery fidelity

🎯 7 🛡️ 8 🧠 7

Why this is hard:

• current Codex inspect logic distinguishes installed, activation pending, disabled, and degraded by combining multiple native surfaces
• that is richer than installed yes/no, but still not a full external discovery surface

Best resolution:

• backend-owned discovery
• explicit observed_state
• explicit activation_hint
• never collapse prepared Codex state into fully active installed state

3. Workspace-root and repo-root coupling

🎯 8 🛡️ 9 🧠 6

Why this is hard:

• current service construction still derives important paths from os.Getwd()
• workspace-lock paths are repo-root oriented
• packaged Electron app must not inherit the wrong working directory semantics

Best resolution:

• add explicit --workspace-root
• reject missing workspace root for project-sensitive commands
• keep sync and workspace-lock flows out of the first app rollout

4. Source resolution cost for lifecycle vs catalog

🎯 8 🛡️ 9 🧠 5

Why this is hard:

• lifecycle source resolution may legitimately clone remote sources
• storefront catalog must stay fast and bounded

Best resolution:

• keep catalog generation batch-oriented
• keep lifecycle resolution source-oriented
• never build the app catalog by doing one source clone per entry at runtime

5. Popularity parity

🎯 6 🛡️ 9 🧠 5

Best resolution:

• make popularity optional
• add it later only from a first-class universal metric

6. Safe native convenience actions

🎯 6 🛡️ 8 🧠 7

Best resolution:

• delay to phase 3
• require backend-declared manageability

7. App-facing target subset confusion

🎯 8 🛡️ 9 🧠 5

Why this is hard:

• plugin-kit-ai knows more targets than the app should expose as first-class plugin lanes
• if the app shows every authored target equally, users will see support the app cannot actually manage yet

Best resolution:

• preserve full authored support in backend catalog
• use only claude and codex-package for primary actionability in claude_team
• keep broader support as secondary metadata only

8. Target projection drift between authored, manageable, and app-primary targets

🎯 8 🛡️ 9 🧠 6

Why this is hard:

• these three target sets are related but not identical
• if they collapse into one field, the UI will eventually lie about support or actionability

Best resolution:

• preserve separate target fields in catalog
• test them with golden fixtures
• never let renderer heuristics rebuild one layer from another

E2E and Contract Testing

plugin-kit-ai

Must add:

• JSON contract tests for catalog, discover, list, doctor
• JSON contract tests for add/update/remove/repair
• temp-home tests
• temp-project tests
• target adapter tests for Claude and Codex
• golden fixture tests against at least one real universal plugin

claude_team

Must add:

• PluginKitService parsing tests
• mixed-entry normalization tests
• ranking tests
• badge tests
• manual-step rendering tests
• project-context tests

Failure checks

• bundled binary missing
• bundled binary wrong architecture
• schema mismatch
• project install without workspace root
• unsupported scope for selected target
• partial target success
• stale catalog with failed refresh
• repeated idempotent retries

No-Go Conditions

Do not enable by default if any of these remain true:

• universal and native external entries still auto-merge by display name
• lifecycle still depends on parsing prose
• local scope is silently remapped
• partial target failures are flattened into one misleading status
• native external entries expose destructive actions without backend-declared manageability

Open Questions With Recommended Defaults

1. Should the app call GitHub directly for universal plugins?

Recommended default: No.

Use backend catalog.

2. Should native external entries merge into universal entries when matching looks obvious?

Recommended default: No.

Keep separate and use soft relations only.

3. Should local scope be shown for universal installs in phase 1?

Recommended default: No.

Only show scopes explicitly supported by backend target metadata.

4. Should popularity sorting block the migration?

Recommended default: No.

Hide or degrade it if there is no stable universal metric.

5. Should adopt block phase 1?

Recommended default: No.

Phase 1 needs discover, not adopt.

6. Should native uninstall for discovered entries ship immediately?

Recommended default: No.

Only where backend declares safe manageability.

7. Should category or icon metadata block phase 1?

Recommended default: No.

Ship phase 1 with honest minimum storefront metadata, then add optional curation metadata later.

8. Should discover be implemented by reusing current per-target Inspect directly?

Recommended default: No.

Use Inspect as one building block, but build a real native discovery scanner above it because external discovery and managed inspection are not the same problem.

9. Should catalog be generated from the current integrationctl manifest loader only?

Recommended default: No.

Prefer the richer authored-model path such as pluginmanifest.Inspect/publication/targetcontracts, or enrich the lifecycle loader first.

10. Should the claude_team plugin page expose every target known to plugin-kit-ai as a first-class action lane?

Recommended default: No.

Use the app-relevant target subset for primary actions:

• claude
• codex-package

Keep broader authored support as optional secondary detail, not as primary actionability.

11. Should the catalog expose only one target field?

Recommended default: No.

Keep separate fields for:

• authored target support
• backend-manageable lifecycle support
• app-primary action targets

Phase-1 Conservative Defaults

These defaults are intentional. They should not be treated as missing polish or as accidental gaps.

Risky seam	Phase-1 default	Why
local scope for universal plugins	hide it	backend does not honestly support it yet
native external uninstall	do not expose	destructive authority is not proven yet
adopt	do not expose	visibility is needed before ownership conversion
popularity sorting	optional, not blocking	migration should not depend on a metric the backend does not yet own
target-specific metadata	enhance detail only	shared storefront truth should stay stable
heuristic universal matching	advisory only	avoids false ownership merge
ambiguous Codex observed state	degrade to observed_degraded	safer than over-claiming active state
stale catalog while managed installs exist	keep managed entry visible	list wins for managed existence
stale discover while catalog works	keep catalog visible and warn	do not claim “no installed plugins”
grouped lifecycle keys missing	treat as incompatible payload	do not reconstruct entry groups in app

Final Recommendation

Build this integration in three layers:

1. make plugin-kit-ai expose stable JSON contracts
2. make plugin-kit-ai the normalized backend for universal catalog, discovery, and lifecycle
3. make claude_team a frontend over those contracts

This is the most reliable path because it:

• keeps the current app UX
• reuses the existing lifecycle engine in plugin-kit-ai
• avoids false parity and false merging
• keeps rollout reversible