Skip to content

Distribution-mechanics vertical: take positions on upstream marketplace schema features #3616

Description

@kyle-sexton

Deferred vertical (V7) from the playground-article corpus effort (see docs/topics/playground-integration/PLAN.md for provenance). The official plugin-distribution docs carry schema features and gotchas this marketplace should hold explicit positions on:

  • strict mode per entry (plugin.json authoritative vs marketplace-entry-as-definition); the renames field posture is already in use here, confirm it covers all historical renames; userConfig/channels as the sanctioned mechanism if any plugin ever prompts for tokens or binds message channels.
  • Install-flow gotchas to design around and document: relative-path plugin sources silently fail when a marketplace is added by direct URL rather than git; command-source / headersHelper entries are skipped on bulk install and background auto-update; version resolution is a five-tier fallback (plugin.json, marketplace entry, git SHA, archive digest, unknown); top-level bin/ directories are disallowed for org-settings distribution.
  • The two official channels have different governance (curated claude-plugins-official vs validated, SHA-pinned claude-community); decide whether any of this fleet's plugins should be submitted to claude-community, and what the submission bar implies.

Acceptance: a recorded position per feature (adopt / not-applicable / deliberately-divergent with rationale), plus any resulting marketplace.json or docs changes.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Sep 1, 2026
  2. claude commented on Sep 6, 2026

    @claude
    Contributor

    Generated by Claude Code

  3. claude commented on Sep 6, 2026

    @claude
    Contributor

    This was generated by AI during triage.

    Triage verification (2026-09-06)

    Two facts confirmed against the marketplace manifest, which narrow what is actually open:

    • The renames field is in use, so the body's "confirm it covers all historical renames" is a verifiable check rather than an open question. That part is delegable work.
    • No entry declares strict mode, so the marketplace currently sits on the default posture by omission rather than by a recorded decision. That is exactly the gap this item names.

    Triage outcome: human-gated (distribution governance)

    Why not agent-ready. Most items here are positions on how this marketplace is distributed and governed, and one is unambiguously a maintainer's call: whether any of this fleet's plugins should be submitted to the validated community channel. That commits the project to another party's submission bar and review cadence, and it is not reversible by a later commit the way an internal convention is. A triage lane must not default it.

    The schema-posture items are also genuine choices rather than conformance checks. Declaring strict mode per entry decides whether the plugin manifest or the marketplace entry is authoritative, which changes where a future contributor edits metadata and which of two files wins on disagreement. That is a maintainer's decision about the repository's shape.

    What must be decided, one recorded position each:

    1. Strict mode per entry: plugin manifest authoritative, or marketplace entry as definition. Currently unset, so today's behavior is the default rather than a choice.
    2. The token and channel configuration mechanisms as the sanctioned route if any plugin ever prompts for a credential or binds a message channel. Worth deciding before a plugin needs it, so the answer is not improvised under pressure.
    3. Community-channel submission: whether any plugin goes, and what that channel's bar implies for this fleet's practices. This is the governance decision.

    What is delegable once those are settled, and can be re-triaged as such:

    • Verifying the renames field covers all historical renames, which is a checkable claim against repository history.
    • Recording the install-flow gotchas as documented constraints to design around: relative-path plugin sources failing silently when a marketplace is added by direct URL rather than by git; command-source and header-helper entries being skipped on bulk install and background auto-update; the five-tier version-resolution fallback; and top-level binary directories being disallowed for organization-settings distribution.

    Note on the gotchas: these are upstream behaviors, not decisions, so they should be recorded with the repository's upstream-drift verification form (claim, basis, as-of date, recheck trigger) rather than as bare statements, since each can change without notice.

    Cluster: playground-integration deferred verticals

    This item is one of five deferred verticals from the playground-article corpus effort:
    #3612 (V3), #3614 (V5), #3615 (V6), #3616 (V7), #3617 (Q9). Each measures some part of this
    fleet against upstream Agent Skills or plugin-distribution guidance and records a verdict.

    They are independent enough to run separately, so no carrier is designated and no dependency edges
    were created. Two shared notes apply to all five:

    • Provenance paths are not on the default branch. The effort's plan lives on its own branch,
      so treat those references as historical rather than as files to read.
    • Recorded counts are stale. Verified 2026-09-06: the fleet is now about 262 skills, not
      the "70+" and "237" figures these bodies carry. Re-inventory before trusting any recorded count.

    This triage pass created, merged and closed nothing.


    Generated by Claude Code

  4. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Sep 6, 2026
  5. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    This was generated by AI (Claude Code audit-fix run, 2026-09-29).

    Reopened. This comes from the 2026-09-29 audit of the unattended Cursor run. PR #4951 closed this as completed with owner-reserved rows decided by the agent. Label needs-human is kept. Core-docs will mark the community, strict and bin/ rows in the playbook as "proposed, awaiting owner (#3616)" and fix the H2 placement. marketplace.json is not edited.

    Decision packet (four questions)

    Q1. strict per marketplace entry. Options: adopt the default (omit the field) or set it explicitly. Recommendation: adopt the default. Basis: the current marketplace-reference page, which the playbook cites; the executor fetches and cites it and confirms no entry sets strict.

    Q2. Submit plugins to claude-community. Options: reject, submit selected plugins, or defer. No recommendation until the owner reads the submission bar. Evidence that settles it: the current claude-community submission requirements, which the executor must fetch and quote.

    Q3. bin/ under org-managed distribution. The playbook row's premise is false: plugins/source-control/bin exists. Options: move to scripts/, record a deliberate divergence for non-org-sync distribution, or keep deferring. Recommendation: record the divergence, unless the org-plugins page bans top-level bin/ (fetch it; that page settles it).

    Q4. Renames coverage. The issue asks to confirm the map covers all historical renames. It does not. Three true renames are missing: bash-lint to bash-format and markdown-formatter to markdown-format (commit ecf02fd, #281), and bug-report to bugs (commit 3b2225b, #3232). Provenance to attribution is exempt (the shim plugin still ships); splits and file moves are not renames. Baseline 7acaf08 docs/migration-playbook.md (about line 505) says the map is frozen-historical: "nothing new is added to it".

    • Options: keep frozen and record the three uncovered names as deliberate (old-name installs get "Plugin not found"), or reverse the posture and add three keys.
    • Recommendation: keep frozen. Basis: that standing posture, locked in the docs/topics/shadowed-skill-renames history (c70d886).

    Unblocks: the playbook rows going from "proposed" to decided, and any marketplace.json change.

  6. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    This was generated by AI (Claude Code audit-fix run, 2026-09-29).

    Addendum to the decision packet above: the fetched evidence for Q1 to Q3, and the playbook change. No position is chosen.

    Playbook change. PR #5268 (Refs #3616) edits docs/migration-playbook.md only. The strict and claude-community rows now begin "proposed:". The bin/ row is marked "open: maintainer decision (move to scripts/, or record a deliberate divergence for distribution that does not use organization sync)". Each row in the section carries a source link and the section's recheck trigger names those pages. The section moved to just before "Local development loop", so it no longer splits the security-review records. .claude-plugin/marketplace.json is not touched.

    Q3 is settled on the documented constraint; the choice is still yours. The tracker packet's Q3 recommendation was conditional on whether the org-plugins page bans a top-level bin/. It does. Fetched 2026-09-29, host a marketplace, "Distribute through organization settings", repeated on sync your organization's plugins:

    Top-level bin/ directory: claude.ai rejects a plugin that has one and syncs the rest of the marketplace. The error message starts with Plugin contains a top-level bin/ directory. Keep executables in another directory, such as scripts/, and reference them as ${CLAUDE_PLUGIN_ROOT}/scripts/<name> from your hooks or MCP server configs.

    This fleet ships one: plugins/source-control/bin/ holds source-control-babysit-merge and source-control-babysit-resolve-thread. A top-level bin/ is also on PATH while the plugin is enabled. Distributed through organization sync, this catalog would lose source-control and sync the rest. The wrappers are referenced by bare name in plugins/source-control/README.md (line 102), plugins/source-control/skills/babysit-prs/SKILL.md (lines 178, 238) and its reference/guard-contract.md, and docs/conventions/permission-rule-hygiene/README.md (line 227) shows the bare name resolved on PATH. Permission rules pin the bare name, so moving the wrappers to scripts/ changes the permission-rule shape. That is why it stays your call.

    Q1 evidence. Strict mode: strict defaults to true, and no entry in .claude-plugin/marketplace.json sets it, so adopting the default records the current state.

    Q2 evidence. Anthropic's marketplaces: the community marketplace (claude-community) holds "Third-party plugins that their authors submitted to Anthropic". Publish a plugin: submission is through the developer portal, requires a paid claude.ai plan, and each version must pass the checks in the pre-submission checklist on claude.com. That is the "separate submission bar" the row names.

  7. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    Owner decision (2026-09-29): Accept the recommendation on all four questions. Q1: adopt the default (omit strict, record that no entry sets it). Q3: keep plugins/source-control/bin/ and record a deliberate divergence for distribution that does not use organization sync, noting that org sync rejects a top-level bin/. Q4: keep the renames map frozen and record the three uncovered renames (bash-lint to bash-format, markdown-formatter to markdown-format, bug-report to bugs) as deliberate. Q2: decide with evidence (claude-community submission).

    Next: an agent finishes the playbook rows for Q1, Q3 and Q4 from "proposed" to decided, and posts the claude-community submission evidence for Q2 on this issue. Q2 stays open for the owner's final call, so needs-human is kept.

  8. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Sep 29, 2026
  9. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    This was generated by AI

    Evidence for Q2 (submit plugins to claude-community). Facts only; no recommendation is made. Fetched 2026-09-29.

    Sources

    Requirements, quoted verbatim, mapped to this repo (worktree at origin/main plus the T1 commit)

    1. Paid plan and role. "Submitting requires a paid claude.ai plan. On Pro and Max you submit from your own account. On Team and Enterprise, an Owner can submit" (publish page). Directory page: "Plan: Pro, Max, Team, or Enterprise. Free accounts can't submit". Fleet: repo-side evidence cannot show which plan the owner's account holds. Operator-only.

    2. Developer portal. "You submit from the developer portal at claude.ai/directory/manage". Operator-only: submission happens in a browser session on the owner's account.

    3. One plugin per submission. "Submit one plugin at a time. In a marketplace repository with several plugins, validate and submit each plugin folder on its own." (Blocks.) Fleet: .claude-plugin/marketplace.json lists 83 plugins, each with a relative-path source such as "./plugins/source-control" (marketplace.json:362-363); there are 83 directories under plugins/. Each would be a separate submission.

    4. Per-version checks. "every version gets automated validation and a security scan, and a person reviews a new listing before it goes live" (directory page). "A first submission that fails the security scan is rejected, and a later version that fails can't go live." Fleet: the repo ships many releases per plugin (each plugin has a CHANGELOG.md, e.g. plugins/source-control/CHANGELOG.md), and every version would pass through the scan.

    5. Review cadence. "Review time isn't fixed." No SLA is stated on the fetched pages.

    6. Repository public before listing. "A GitHub repository, which must be public before the listing goes live". Fleet: gh repo view reports visibility PUBLIC for melodic-software/claude-code-plugins.

    7. README and license. "Put a README of at least 40 words in the plugin folder" and "Add a LICENSE file to the plugin folder, or set license in plugin.json" (Blocks). Fleet: 83 of 83 plugins have a plugin-root README.md (shortest prose, code blocks excluded, is plugins/provenance at 110 words); 83 of 83 plugin.json files set license (for example plugins/actionlint/.claude-plugin/plugin.json:10 "license": "MIT"); one plugin folder holds a LICENSE file besides.

    8. Version. "raise version with every release". Fleet: 83 of 83 plugin.json files set version (plugins/actionlint/.claude-plugin/plugin.json:4 is 0.10.1).

    9. Name. "Build the name around your own distinctive product or project name: not a reserved word such as claude, anthropic, official, plugin, mcp, or test as the whole name"; "Choose a name that no other organization's plugin uses". Fleet: plugin names include claude-ops, claude-config, dometrain-mcp (marketplace.json). The checklist limits reserved words to the whole name; no per-name collision check was run against the directory.

    10. Files inside the plugin folder. "Keep every file that isn't an image or font under 256 KiB", "Keep the plugin to 512 files or fewer", and "Include only text files ... Any other binary file, such as an .ico, .pdf, or .zip file or a compiled executable, is held" (Held for a reviewer). Fleet: the largest plugin by tracked files is autonomy at 411, none exceed 512. Files over 256 KiB that are not images or fonts: plugins/miro/server/dist/index.min.js, five CHANGELOG.md files (guardrails, source-control, claude-ops, work-items, claude-config), plugins/disk-hygiene/skills/clean/scripts/test_hygiene.py. One binary: plugins/session-flow/skills/keep-going/scripts/vendor/tzdata-zoneinfo.zip. Each would be held for a reviewer.

    11. Launchers and package pinning. "Pin every package that a launcher runs to an exact version, such as npx <package>@1.2.3 ... not a range or @latest." Fleet: the two .mcp.json files use no package launcher: plugins/miro/.mcp.json:4-5 runs node ${CLAUDE_PLUGIN_ROOT}/server/dist/index.min.js; plugins/dometrain-mcp/.mcp.json is an http server at https://mcp.dometrain.com/mcp. The checklist says a local MCP server should run "a file in the plugin with plain arguments", which miro does. A bundled minified file: "Commit readable source instead of compiled, packed, or minified code. Code that the security scan can't read is held for a reviewer" (miro's dist/index.min.js).

    12. Package-manager config and lockfiles. "don't include a package-manager configuration file that sets a registry, index, proxy, or other package source, such as .npmrc" and "package.json beside package-lock.json ... in the root of the plugin folder is held". Fleet: .npmrc files exist at plugins/knowledge/skills/course-digest/extraction/.npmrc and plugins/knowledge/skills/video-digest/extraction/.npmrc (content install-links=true; no registry key). Lockfile pairs sit in subfolders (plugins/miro/server, plugins/knowledge/skills/*/extraction, plugins/ai-briefing/skills/generate/output/build), not at a plugin root.

    13. Hook and MCP command paths. "In the command of a hook or an MCP server, write each path in full from ${CLAUDE_PLUGIN_ROOT}, with no other variable ... or inline program such as python3 -c" (Blocks when the plugin folder is a subfolder of the repository, which is the case for all 83 plugins). Fleet: hooks call ${CLAUDE_PLUGIN_ROOT}/hooks/exec-bash.mjs (plugins/go-format/hooks/hooks.json:12). No audit of every hook command for other variables or inline programs was run here. The checklist also holds "a program the validator can't read through, when the plugin folder is a subfolder of the repository", and recommends "keep the plugin at the root of its own repository"; here all plugins are subfolders of one repository.

    14. SHA pinning. The fetched pages do not state a SHA-pinning requirement for directory submissions. The only pinning rule is item 11 (exact versions for launcher packages). The publish page says of your own marketplace: "omit it in a git-hosted marketplace so Claude Code uses the commit SHA instead". Directory updates: "you keep the listing current by merging to the tracked branch as you normally release. The directory picks up each commit".

    15. Software Directory Policy. "every plugin in the directory also has to follow the Anthropic Software Directory Policy" (https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy). That policy page was not fetched here; compliance is not assessed.

    16. Which catalog. "Anthropic's official marketplace, claude-plugins-official, doesn't take submissions through the directory portal." The directory pages do not use the name claude-community; the repo's playbook row (docs/migration-playbook.md:1432) cites https://code.claude.com/docs/en/plugins/anthropic-marketplaces for that name, which was not re-fetched in this comment.

    The final call on claude-community submission stays with the owner; #3616 stays open with needs-human.

  10. removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Sep 30, 2026
  11. kyle-sexton commented on Sep 30, 2026

    @kyle-sexton
    MemberAuthor

    Owner decision (2026-09-29): approved consensus

    Question. Should any plugin be submitted to claude-community (reject, submit selected plugins, or defer)? Q1, Q3 and Q4 were already accepted; this was the only open question.

    Decision. "Q2: reject (do not submit any plugin to claude-community), and record it as a decision, not a permanent ban."

    Rationale. This repository is its own distribution channel, and the playbook row (docs/migration-playbook.md:1432) already reads "proposed: reject", consistent with the accepted Q1, Q3 and Q4 answers. The submission bar clashes with how this repo ships: one plugin per submission (83 submissions), a security scan on every version, and files that would be held for review (the minified plugins/miro/server/dist/index.min.js, the tzdata-zoneinfo.zip, and five CHANGELOG.md files over 256 KiB). Rejecting commits nothing external and is cheap to reverse; deferring would leave the row "proposed" indefinitely.

    Next: an agent changes the claude-community row in docs/migration-playbook.md from "proposed: reject" to a decided reject, adds a note that it can be revisited if a specific plugin gets outside demand, and updates the section text that says a "proposed" row awaits ratification. Then this issue closes with that PR.

  12. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions