[FEATURE] TargetProfile: plugin-bin-contract abstraction for multi-harness bin/ deployment

[sergio-sisternes-epam]

Is your feature request related to a problem? Please describe.

Plugin bin/ deployment is currently hard-wired to Claude Code's skills-directory plugin contract. As new harnesses adopt executable-deployment patterns (e.g. Codex CLI, Gemini CLI), each harness will need its own bin/ placement, PATH setup, and reload mechanism. Without an abstraction, the _deploy_plugin_bin function will grow per-harness branches and the gate logic (deny, scope, trust-posture) will be duplicated.

This was identified as item 6 in the advisory review panel on PR #1591 (tracked in #1620).

Describe the solution you'd like

Introduce a TargetProfile (or similar) abstraction that encapsulates the per-harness bin/ deployment contract:

• bin_dir(project_root, scope) -- where to place executables for this harness
• bin_path_mechanism -- how the harness discovers deployed bins (PATH env, config entry, manifest)
• reload_hint -- user-facing instruction to activate new executables (e.g. /reload-plugins, restart)
• requires_plugin_manifest -- whether the harness needs .claude-plugin/plugin.json or equivalent
• supported_scopes -- which install scopes (user, project) support bin/ deployment

Each TargetProfile would implement the contract for its harness, and _deploy_plugin_bin would delegate to the active profile instead of hard-coding Claude-specific logic.

Describe alternatives you've considered

• Keep the current approach and add per-harness if branches as needed (simpler short-term, scales poorly).
• Use a registry/dict mapping harness names to deployment functions (lighter than a full class hierarchy, but less extensible).

Additional context

• Parent issue: Plugin bin/ deploy: trust-posture, producer docs, and hardening follow-ups (from #1591 review panel) #1620 (item 6)
• The current Claude-only implementation is stable and well-tested; this is a forward-looking design issue, not a regression.
• Priority: low -- only becomes relevant when a second harness adopts bin/ deployment.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/multi-target
area/marketplace
type/feature
status/needs-design

Note: Human-applied type/feature is retained as authoritative. type/architecture may be a more precise fit for this issue -- a maintainer may relabel if preferred. Human-applied status/needs-design is also retained and confirmed by the panel.

Milestone

null -- needs-design issues are milestone-free per triage rules.

Suggested next action

Draft a design document specifying the TargetProfile interface contract (method signatures, scope semantics, and gate-preservation requirements), link it back to this issue, and tag it as type/architecture for the implementing PR review.

Suggested issue comment

Thanks for the thorough write-up and for linking back to #1620 item 6
-- the paper trail is helpful.

The `TargetProfile` abstraction direction is sound. The existing
`status/needs-design` label is correct: before the interface lands in
code, the following must be settled in a design document:

1. **Interface shape**: The proposed methods (`bin_dir`, `bin_path_
   mechanism`, `reload_hint`, `requires_plugin_manifest`,
   `supported_scopes`) look right, but the concrete signatures,
   return types, and scope enum values need to be pinned.

2. **Gate preservation**: The current Claude-specific implementation
   passes through the deny/scope/trust-posture gate logic. Each
   `TargetProfile` implementation must route through the same gates --
   the design doc must state this contract explicitly so future
   harness implementors cannot accidentally bypass it.

3. **Harness registry shape**: Should `TargetProfile` subclasses be
   registered via a dict, a plugin entry-point, or explicit imports?
   The design should match the pattern used for the existing
   `BaseIntegrator` registry.

Once a design doc is linked here, we can review and move to
`status/accepted` for implementation.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The TargetProfile abstraction is an internal architecture issue with no direct user-facing UX change in scope. End users continue to see the same apm install behavior; only plugin harness extension becomes easier. The issue is explicitly low-priority and forward-looking. No UX concerns; the abstraction is a prerequisite for multi-harness bin/ deployment parity, which is the eventual user-visible goal.

Supply Chain Security Expert -- Risk-Surface Reviewer

The _deploy_plugin_bin function handles security-sensitive operations: deploying executables to harness bin directories with specific permission gates (deny, scope, trust-posture). The TargetProfile abstraction must preserve these gates across all implementations -- this is the primary security constraint. The issue author explicitly acknowledges this ("gate logic (deny, scope, trust-posture)"), which is a positive signal. The design document must specify gate-preservation as a hard contract, not an implementor courtesy. area/marketplace applies because bin/ deployment is part of the marketplace plugin install flow.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with established interaction history; first-contributor tone-tuning does not apply.

Python Architect -- Architecture Reviewer

The TargetProfile proposal is a Strategy pattern for plugin bin deployment. The proposed interface covers the right abstractions. Implementation candidates: Protocol (preferred for duck-typing flexibility) or ABC (preferred if runtime checks are needed). The natural home is src/apm_cli/integration/ alongside the existing BaseIntegrator pattern. Key open questions that block coding: (1) method signatures and return types; (2) how harness registry lookup works (dict, entry-point, imports); (3) gate-preservation contract specification. The human-applied status/needs-design is correct -- these three questions need design-doc answers before a PR can land safely. Feasibility is high once the interface is settled; the existing Claude implementation becomes the reference ConcreteTargetProfile.

Doc Writer -- Documentation Reviewer

Not activated -- TargetProfile is an internal architecture abstraction. The implementing PR changes plugin-harness internals, not user-facing CLI behavior or end-user documentation. If and when the abstraction enables new user-facing harness support, a corresponding docs update will be needed at that time.

APM CEO -- Triage Arbiter

The direction is sound, the priority is correctly low, and the human-applied status/needs-design is authoritative. The Security Expert's gate-preservation concern is the critical design constraint the document must address -- not just interface shape. The panel endorses the existing triage direction. theme/portability is the primary mega-theme (multi-harness bin/ deployment is a portability feature enabling Codex CLI, Gemini CLI, etc.). area/marketplace is added because this is squarely in the marketplace plugin install path.

{
  "decision": "needs-design",
  "decision_detail": "Interface shape, scope semantics, and gate-preservation contract must be specified in a design document before implementation.",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/marketplace"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design document specifying the TargetProfile interface contract (method signatures, scope semantics, gate-preservation requirements) and link it back to this issue.",
  "comment_markdown": "Thanks for the thorough write-up and for linking back to #1620 item 6 -- the paper trail is helpful.\n\nThe `TargetProfile` abstraction direction is sound. The existing `status/needs-design` label is correct: before the interface lands in code, the following must be settled in a design document:\n\n1. **Interface shape**: The proposed methods (`bin_dir`, `bin_path_mechanism`, `reload_hint`, `requires_plugin_manifest`, `supported_scopes`) look right, but the concrete signatures, return types, and scope enum values need to be pinned.\n\n2. **Gate preservation**: The current Claude-specific implementation passes through the deny/scope/trust-posture gate logic. Each `TargetProfile` implementation must route through the same gates -- the design doc must state this contract explicitly so future harness implementors cannot accidentally bypass it.\n\n3. **Harness registry shape**: Should `TargetProfile` subclasses be registered via a dict, a plugin entry-point, or explicit imports? The design should match the pattern used for the existing `BaseIntegrator` registry.\n\nOnce a design doc is linked here, we can review and move to `status/accepted` for implementation."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 151.1 AIC · ⌖ 20 AIC · ⊞ 9.2K · ◷