Listing-budget option 3: curated starter bundles and a per-plugin listing budget (design)

[kyle-sexton]

Context

#2022's operator decision (2026-08-08): execute option 2 (tighten the worst descriptions — PR in flight) AND pursue option 3 (structural). This issue is option 3's design pass, filed as its own work item because it changes doctrine and possibly CI, not just prose.

Problem

The full-install aggregate (86.5k chars pre-tighten, ~10.8x the 8k default budget) is unbounded by construction: 61 roots x a per-skill cap (1,536) with no per-plugin or per-install ceiling. Tightening descriptions (option 2) lowers the constant but not the growth law. Two structural levers:

Lever A — curated starter bundles

Named install sets documented in the marketplace README/catalog (e.g. core = source-control + guardrails + skill-quality; delivery = + implementation/testing/verification/toolchain; research = knowledge/discovery/context7/firecrawl). Bundles are documentation, not mechanism: Claude Code installs per-plugin, so a bundle is a documented recommendation with a one-line install command per set. Cheap, no CI.

Lever B — per-plugin listing budget in doctrine + gate

A documented per-plugin ceiling (e.g. sum of a plugin's listing-eligible entry chars <= N) enforced as a new advisory-or-blocking check in skill-quality's check (it already computes per-entry chars and the shared aggregate). Sizing needs data: current per-plugin distribution from check-listing-budget.sh per-root output; a plausible starting ceiling is ~2.5-3k chars/plugin (61 roots x 3k = still >8k for full installs — the budget only binds real consumers because installs are selective, which is the design's honest premise).

Proposed deliverables

1. Doctrine paragraph in docs/PLUGIN-PHILOSOPHY.md "Instruction economy": listing text is a shared budget; per-plugin ceiling named; bundles are the recommended install shape.
2. README/catalog section defining 3-5 named bundles with install commands.
3. skill-quality check extension: per-plugin subtotal + ceiling warning (advisory first; blocking only after the fleet is under the ceiling).
4. [Maintenance] Listing-budget watch: report the shared aggregate and drift #2023 (listing-budget watch) gains the per-plugin subtotals in its report so drift is visible at the granularity the ceiling binds.

Acceptance criteria

• Design reviewed/approved by the operator (bundle membership + ceiling value are operator calls).
• Deliverables 1-4 landed or explicitly descoped with rationale.

Related

• Refs Listing-budget decision: full-install aggregate is 86.5k chars (~10.8x the default budget) #2022 (parent decision), [Maintenance] Listing-budget watch: report the shared aggregate and drift #2023 (watch routine), plugins/skill-quality check (enforcement seam).

[kyle-sexton]

Design-only listing-budget option 3 (curated starter bundles). No implementation plan or acceptance criteria beyond the design note. Closing as design-recorded; reopen when ready to implement.