Promote `apm marketplace add` to top-level `apm add` (and `remove`)

[danielmeppiel]

TL;DR

Promote apm marketplace add to the top-level apm add (and apm marketplace remove to apm remove). The most-typed onboarding command shrinks from 3 tokens to 2, aligning APM with cargo add, npm install, gh extension install, brew install. The legacy apm marketplace add/remove keeps working with a one-line stderr tip; no breaking change.

Problem (WHY)

The README quickstart for marketplaces today reads:

apm marketplace add github/awesome-copilot
apm install azure-cloud-development@awesome-copilot

That's two commands and the first one buries the action verb (add) under a noun-group (marketplace) the user does not think about. Every successful package manager puts its source-management verb at depth 0:

Tool	Verb	Depth
npm	npm install <pkg>	0
cargo	cargo add <crate>	0
pip	pip install <pkg>	0
brew	brew install <formula>	0
gh CLI	gh extension install OWNER/REPO	1
Claude Code	/plugin marketplace add OWNER/REPO	2 (slash UI)
APM (current)	apm marketplace add OWNER/REPO	1
APM (proposed)	apm add OWNER/REPO	0

Friction this creates:

• Tutorials, blog posts, and screencasts have to spell marketplace -- 11 chars of cognitive overhead before the verb.
• New users have to learn the noun "marketplace" before they can register their first source. The noun is plumbing, not user-facing.
• README install snippet is 3 tokens vs the 2-token snippet every developer's muscle memory expects.

There's already a precedent in the codebase: apm search was promoted from apm marketplace search to top-level (see src/apm_cli/cli.py:92). This issue extends that pattern to the highest-frequency consumer verbs.

Proposed Solution (WHAT)

New top-level commands

apm add OWNER/REPO [OWNER/REPO ...]      # NEW. Aliases `apm marketplace add`.
apm remove NAME                          # NEW. Aliases `apm marketplace remove`.

Backwards compatibility

• apm marketplace add and apm marketplace remove keep working unchanged.
• On successful invocation, the legacy command emits ONE line to stderr:

  [i] Tip: 'apm add' is now available as a top-level command. Try: apm add OWNER/REPO
  

• apm marketplace add --help text annotates "(alias: apm add)".
• No hard removal pre-1.0. No deprecation timeline.

Multi-source support (cargo parity)

apm add acme/skills contoso/security-plugins

Sources are processed left-to-right with continue-on-error for non-security failures (404, network timeouts), and fail-closed on security-class failures (signature mismatch, path-segment violation, integrity check). Exit code is non-zero if any source failed; a summary line is printed:

[*] Registering marketplace 'skills' (12 plugins)        -> success
[x] Failed to register 'bad/repo': No marketplace.json found
[*] Registering marketplace 'tools' (8 plugins)          -> success

Summary: 2 registered, 1 failed

Smart error: bare name typo

If user types apm add cool-plugin (no /):

[x] Invalid source: 'cool-plugin'. Expected OWNER/REPO format.

    Did you mean `apm install cool-plugin`?
    Use `apm add OWNER/REPO` to register a marketplace source.

Exit code: 1.

Note: Per supply-chain review, the apm install cool-plugin suggestion echoes the user input verbatim and does NOT imply the package exists or is trusted. Consider hardening this further (e.g. only suggest apm install when the bare name resolves against an already-registered source) as a follow-up.

Implementation Sketch (HOW)

Thin Click wrapper, no logic duplication. The architect lens proposes:

1. Extract the existing add() body (src/apm_cli/commands/marketplace/__init__.py:247-403) and remove() body (lines 572-605) into a new private module src/apm_cli/commands/marketplace/_source_ops.py with two functions: _do_add_source(repos, name, branch, host, verbose, invoked_as_legacy) and _do_remove_source(name, yes, verbose, invoked_as_legacy).

2. Replace the marketplace add and marketplace remove Click bodies with calls to those helpers, passing invoked_as_legacy=True.

3. Create src/apm_cli/commands/source.py defining top-level add and remove Click commands that call the same helpers with invoked_as_legacy=False.

4. Wire the new commands into src/apm_cli/cli.py immediately after install/uninstall so they render adjacently in --help.

5. Deprecation tip is emitted only when invoked_as_legacy=True AND the operation succeeds. Uses the existing _rich_info helper with [i] symbol; routed to stderr via a small extension to _rich_echo accepting a file= kwarg, OR a plain click.echo(..., err=True) fallback if the helper extension is deferred.

6. Help-text reorg (apm --help): out of scope for this PR. Promoting add/remove adjacent to install/uninstall in registration order is enough; full categorization is a separate issue once we have 3+ promoted verbs (precedent: MarketplaceGroup.format_commands).

Files touched

File	Change
src/apm_cli/commands/marketplace/_source_ops.py	NEW. Pure logic.
src/apm_cli/commands/marketplace/__init__.py	add / remove bodies become 1-line calls.
src/apm_cli/commands/source.py	NEW. Top-level Click commands.
src/apm_cli/cli.py	Register add, remove after install/uninstall.
src/apm_cli/utils/console.py	Optional: extend _rich_echo with file= kwarg.

Acceptance Criteria

• apm add OWNER/REPO registers a marketplace source (same outcome as apm marketplace add OWNER/REPO).
• apm add A/B C/D registers multiple sources; partial failure yields exit code 1 with a summary line.
• Security-class failures (signature, integrity, path traversal) abort the entire batch and return non-zero immediately. Non-security failures (404, network) are skipped with continue-on-error semantics.
• apm remove NAME removes a registered marketplace.
• apm marketplace add and apm marketplace remove still work; each prints exactly one stderr tip line on success, never on error.
• apm add cool-plugin (no slash) exits 1 with the smart-error message.
• apm add --name foo a/b c/d errors: --name requires a single source.
• apm add --help shows OWNER/REPO [OWNER/REPO ...] usage.
• apm marketplace add --help includes "(alias: apm add)".
• No emoji or non-ASCII in any output path (per .github/instructions/encoding.instructions.md).
• Existing tests/unit/marketplace/test_marketplace_commands.py tests pass unchanged (logic extracted, behavior preserved).
• New tests/unit/commands/test_source_commands.py covers: single source, multi-source success, multi-source partial failure, security-class fail-closed, bare-name smart error, --name + multi conflict, deprecation tip presence/absence.
• uv run --extra dev ruff check src/ tests/ and uv run --extra dev ruff format --check src/ tests/ pass clean.
• CHANGELOG.md [Unreleased] -> Added entry.

Docs Checklist (in same PR)

• README.md -- swap quickstart marketplace example to apm add github/awesome-copilot; one-line note on long form.
• docs/src/content/docs/reference/cli-commands.md -- add apm add and apm remove reference entries; annotate apm marketplace add/remove headings with "(alias: apm add/remove)"; add rows to the package-commands table.
• docs/src/content/docs/guides/marketplaces.md -- swap primary register/remove examples to apm add/apm remove; one inline note explains alias relationship.
• docs/src/content/docs/guides/marketplace-authoring.md -- update the consumer-facing line to apm add <owner>/<repo> (long form once in parens).
• docs/src/content/docs/enterprise/registry-proxy.md -- update proxy compatibility table cell to include apm add.
• packages/apm-guide/.apm/skills/apm-usage/commands.md -- add canonical rows for apm add OWNER/REPO and apm remove NAME; mark apm marketplace add|remove as long form so the skill teaches apm add first.
• Add :::note admonitions under the new apm add/apm remove reference headings clarifying the alias relationship.

Out of Scope (file separately)

• Promoting apm marketplace list to a top-level apm list --sources (or similar). Its UX questions (filtering, output format) deserve their own discussion. The CEO lens explicitly recommended scoping this issue to add + remove only.
• Help-text categorization (Click group reorg into "Package commands" / "Project commands" / "Advanced" sections). Lift MarketplaceGroup.format_commands pattern to root in a follow-up once 3+ verbs are promoted.
• Hardening the smart-error suggestion to only propose apm install <name> when <name> resolves against an already-registered source. Tracked as supply-chain follow-up.

Strategic Rationale

"File it. apm add OWNER/REPO is the single highest-leverage CLI ergonomics change available: it collapses the most-typed onboarding command from three tokens to two, aligns APM's command vocabulary with every peer package manager users already know, and costs near-zero implementation risk (thin wrapper, existing tests untouched). The soft deprecation cadence respects contributors and scripts already in the wild." -- apm-ceo

"Safe as-is because it delegates to validated code. Conditions: smart-error suggestions must not endorse arbitrary user input as a known package; continue-on-error must treat security-class failures as batch-aborting, not skippable." -- supply-chain-security-expert

References

• Claude Code plugin marketplaces: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
• Claude Code plugin discovery: https://docs.claude.com/en/docs/claude-code/discover-plugins
• gh CLI extension install: https://cli.github.com/manual/gh_extension_install
• npm install: https://docs.npmjs.com/cli/v10/commands/npm-install
• cargo add: https://doc.rust-lang.org/cargo/commands/cargo-add.html
• Existing precedent (apm search promotion): src/apm_cli/cli.py:92
• Existing alias pattern (apm info -> apm view, hidden, no tip): src/apm_cli/cli.py:64-73
• Related: [cli-consistency] CLI Consistency Report — 2026-04-30 #1070 CLI Consistency Report

Orchestration Provenance

This issue was synthesized via the genesis-skill orchestration pattern: parallel fan-out across oss-growth-hacker + devx-ux-expert (research wave), fused python-architect + cli-logging-ux for design, doc-writer for docs delta, parallel sanity gate from supply-chain-security-expert + apm-ceo. Both gate verdicts incorporated in Acceptance Criteria.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/cli
area/marketplace
type/feature
status/accepted
priority/high

Milestone

null -- no open milestone confirmed at triage time; assign to the next minor (0.12.0) when that milestone is created.

Suggested next action

Open a PR implementing the _source_ops.py extraction and source.py top-level commands as described in the implementation sketch; link this issue and check off the acceptance criteria and docs checklist in the PR body.

Suggested issue comment

Thanks for the thorough proposal, @danielmeppiel -- the depth-0 alignment with npm/cargo/pip/brew is exactly the kind of ergonomics investment APM needs at this stage.

The panel accepts this as proposed. Key notes for the implementing PR:

- Follow the thin-wrapper pattern: extract `add`/`remove` logic to `_source_ops.py`, call it from both the legacy `apm marketplace add/remove` path (with `invoked_as_legacy=True`) and the new top-level commands (with `invoked_as_legacy=False`). No logic duplication.
- Security constraint from supply-chain review: security-class failures (signature mismatch, path-segment violation, integrity check) must be batch-aborting and fail-closed. Continue-on-error applies only to non-security failures (404, network timeout).
- The smart-error suggestion for bare names (`Did you mean apm install cool-plugin?`) must not imply the package exists or is trusted. Acceptable as-is per the proposal's own note; the hardening follow-up can be a separate issue.
- Docs checklist is comprehensive and must ship in the same PR. Note: the `area/docs-site` label was not added to this issue to stay within the 6-label cap, but the implementing PR should carry it as a reminder.
- No emoji or non-ASCII in any output path; use `[i]`, `[*]`, `[x]`, `[+]` symbols throughout (see `.github/instructions/encoding.instructions.md`).

Precedent: `apm search` was already promoted from `apm marketplace search` at `src/apm_cli/cli.py:92` -- same pattern, same wiring location.

Ready to proceed. The acceptance criteria and docs checklist in the issue body are the definition of done.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps directly to the onboarding flow for registering marketplace sources, which is the first action a new user takes after apm install. The depth table (npm/cargo/pip/brew all at depth 0; current APM at depth 1) is concrete and correct. The precedent (apm search promotion at cli.py:92) demonstrates the pattern is already accepted in this codebase. Backwards-compat via soft deprecation tip on success is textbook ergonomics: no scripts break, new muscle memory is rewarded. The smart-error for bare-name typo (apm add cool-plugin -> exit 1 + suggestion) is a quality-of-life win that new users hit frequently.

Supply Chain Security Expert -- Risk-Surface Reviewer

This touches area/marketplace, a supply-chain sensitive surface. The proposal addresses the key risks explicitly: fail-closed on security-class failures (signature mismatch, path-segment violation, integrity check); continue-on-error scoped to non-security failures only; the thin-wrapper design delegates to already-validated code with no new attack surface introduced. The note about not endorsing arbitrary bare-name input as a known trusted package is sound and the follow-up hardening is appropriately scoped as a separate issue. No theme/security override needed; theme/portability is the correct primary theme. area/marketplace is the relevant risk-surface sub-theme alongside area/cli.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author danielmeppiel is a COLLABORATOR with a comprehensive, multi-specialist-reviewed proposal; tone calibration for a new contributor is not warranted and would be condescending here.

Python Architect -- Architecture Reviewer

The implementation sketch is clean and feasible. The _source_ops.py extraction with invoked_as_legacy parameter correctly separates the deprecation-tip concern from the business logic -- no conditional branches inside the core functions, just a flag passed in by the caller. The thin Click wrapper in source.py is the right pattern; cli.py registration adjacent to install/uninstall is the correct placement. Cross-cutting impact is bounded: 5 files, no schema changes, no primitive changes, no new data model. The existing tests/unit/marketplace/test_marketplace_commands.py suite passing unchanged is a strong acceptance signal. Design is clear enough for direct PR implementation; status/accepted is appropriate with no prior design doc required.

Doc Writer -- Documentation Reviewer

Docs work is explicitly and comprehensively scoped in the issue's Docs Checklist section: README quickstart swap, cli-commands.md new entries with alias annotations, marketplaces.md primary example swap, marketplace-authoring.md consumer-facing line update, registry-proxy.md table update, and commands.md in the apm-guide skill package. All proposed vocabulary (apm add OWNER/REPO, "long form in parens", :::note admonitions for alias relationship) is well-aligned with existing README and docs terminology. area/docs-site was not added as a label to stay within the 6-label cap; the implementing PR should carry it. The suggested issue comment is clear and grounded in user vocabulary.

APM CEO -- Triage Arbiter

apm add OWNER/REPO is the single highest-leverage CLI ergonomics change in the current backlog: it collapses the most-typed onboarding command from three tokens to two, aligns APM's command vocabulary with every peer package manager users already know, and costs near-zero implementation risk (thin wrapper, existing tests untouched, no schema changes). The soft deprecation cadence respects contributors and scripts already in the wild. The implementation sketch is complete enough to land directly in a PR. Priority is high because this is a first-impression surface that every new user hits. Decision: accept with priority/high; milestone to next minor when created.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/marketplace"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a PR implementing the _source_ops.py extraction and source.py top-level commands as described in the implementation sketch; link this issue and check off the acceptance criteria and docs checklist in the PR body.",
  "comment_markdown": "Thanks for the thorough proposal, @danielmeppiel -- the depth-0 alignment with npm/cargo/pip/brew is exactly the kind of ergonomics investment APM needs at this stage.\n\nThe panel accepts this as proposed. Key notes for the implementing PR:\n\n- Follow the thin-wrapper pattern: extract `add`/`remove` logic to `_source_ops.py`, call it from both the legacy `apm marketplace add/remove` path (with `invoked_as_legacy=True`) and the new top-level commands (with `invoked_as_legacy=False`). No logic duplication.\n- Security constraint from supply-chain review: security-class failures (signature mismatch, path-segment violation, integrity check) must be batch-aborting and fail-closed. Continue-on-error applies only to non-security failures (404, network timeout).\n- The smart-error suggestion for bare names must not imply the package exists or is trusted. Acceptable as-is; hardening follow-up can be a separate issue.\n- Docs checklist is comprehensive and must ship in the same PR.\n- No emoji or non-ASCII in any output path; use [i], [*], [x], [+] symbols throughout.\n\nPrecedent: `apm search` was already promoted from `apm marketplace search` at `src/apm_cli/cli.py:92` -- same pattern, same wiring location.\n\nReady to proceed. The acceptance criteria and docs checklist in the issue body are the definition of done."
}

---

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.

Note

🔒 Integrity filter blocked 10 items

The following items were blocked because they don't meet the GitHub integrity level.

• [BUG] apm compile silently drops global instructions (no applyTo) from generated AGENTS.md #1072 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [BUG] apm pack fails when apm.yml has dependencies and marketplace #1058 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [BUG] apm compile falsely flags parent directory of subdirectory virtual package as orphaned #1050 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [BUG] apm compile for Claude includes broken dependency links #1047 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Add a marketplace with just a full repository URL #1027 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] fetch path from gitlab repository using git clone instead of API #1014 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [BUG] apm doesn't pick up git credentials on apm install with https #1013 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• cm-labs.md #1012 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] set up gitignore for deployed files #990 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Allow customizing skill integration target directory #891 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel for issue #1075 · ● 891.1K · ◷