convention: codify batch-1 operator precedents — two-lane defaults (discover via setup, never pre-prescribe) + built-in-first customization gate

[kyle-sexton]

Source

Operator decision-session batch 1 (2026-07-19) produced two fleet-wide precedents inside issue-specific rulings. They constrain every plugin, so they belong in docs/PLUGIN-PHILOSOPHY.md (and the portability lint lane #531 should eventually enforce them), not buried in issue comments.

Precedent 1 — two-lane convention posture (from the #415 ruling, operator verbatim there)

1. Shipped defaults must be good-practice defaults that cannot conflict in an arbitrary consuming repo.
2. The general path: the plugin's setup action/skill discovers the consuming repo's conventions (branch naming, commit structure, patterns) and externalizes them as configuration extensibility points. Pre-prescribed conventions are hardcoded assumptions — dependencies to be externalized.

Precedent 2 — built-in-first customization gate (from the #423 ruling, operator verbatim there)

Before building any custom config surface (YAML concern files, bespoke seams), verify against current official Claude Code plugin documentation whether native mechanisms (plugin userConfig, environment, built-in per-repo config) can host the need. Custom extensibility points are the fallback only where the built-in surface genuinely cannot support it.

Acceptance

• Both precedents stated once in PLUGIN-PHILOSOPHY (SSOT), linked from MIGRATION-PLAYBOOK where relevant.
• ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 lint-lane backlog notes them as future mechanical checks.
• Rulings on planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415/verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 remain the decision provenance; the doc is the living home.

Cross-links

#415, #423 (source rulings) · #531 (enforcement lane) · #556 (decision-session skill that produced these)

[kyle-sexton]

This was generated by AI during triage.

T1 — routing status: ready. Clear scope: transcribe two already-ratified operator precedents (#415, #423 rulings) into docs/PLUGIN-PHILOSOPHY.md, no new design decision.

Sites + fix pattern: (1) docs/PLUGIN-PHILOSOPHY.md — add both precedents once as SSOT; (2) docs/MIGRATION-PLAYBOOK.md (or equivalent) — link, don't restate; (3) leave a backlog note on #531 (portability lint lane) that these two precedents are future mechanical-check candidates — do not edit #531 itself (already status: ready).