docs(philosophy): lock setup-lifecycle convention

[kyle-sexton]

Summary

Own design session for the setup-lifecycle convention (epic #830). Resolves the four threads in #837's body and encodes the outcome in the "Setup is explicit and repeatable" section of docs/PLUGIN-PHILOSOPHY.md. Doc-only change (+45/−3 lines); no skill edits — see Verification.

The four threads (locked)

1. Verb set — remove/reset/migrate vs state-assessing apply. The mandatory contract stays closed at check and apply. apply is state-assessing: it reads current state and converges — naming the existing idempotent-and-preserve-unrelated requirement as a verb contract, not a new bar. That subsumes the forward direction of "migrate": an apply meeting prior-shape config fills absent keys at defaults, preserves unrecognized keys, and reports (never silently rewrites) values it cannot reconcile, so an obsolete/renamed key surfaces on re-run instead of sitting silently inert. It does not translate renamed/removed keys — the fleet's clean-break stance (no shims, no migration tooling) extends to setup config; reconcile-and-report replaces a migrate verb. reset = teardown + apply. Genuine teardown is an optional apply-scoped operation (apply remove), bounded to the plugin's own tracked project config — never pluginConfigs (reconfigure/clear stays /plugin configure) — deferred with a second-adopter → owner-doc trigger.

2. Per-skill setup action vs plugin setup skill. Setup is one plugin-level setup skill, never a per-skill action. Primary rationale: setup granularity follows install granularity — a plugin installs and configures as a unit, and there is no native per-skill install anchor. One discoverable entry (/<plugin>:setup), one place disable-model-invocation is set for configuration, one owner of a config surface that is routinely shared across skills; the setup skill aggregates per-skill readiness rather than fragmenting.

3. Philosophy-doc update. Encoded in PLUGIN-PHILOSOPHY.md — not a new docs/conventions/setup-lifecycle/ owner doc. Re-derived reasoning (not incumbency): the convention registry hosts inter-plugin coordination concerns whose rules are self-contained enough for one separate owner doc; the setup contract is an intra-plugin uniform contract — like Naming and Cross-platform, which also live in the philosophy doc and carry no registry row — and its rules are distributed across and dependent on three neighboring sections (Configuration ownership = what setup may write; Prerequisites = what it declares; Two-lane = the discover-via-setup lane), so extraction would duplicate or fragment them. Honest limitation (not resolved here, out of #837's scope): the registry's inclusion criterion is fuzzy at the edges (permission-rule-hygiene, skill-layout are per-plugin contracts that did get rows — distinguished by a separate enforcement mechanism needing its own home; setup's conformance rides the general fleet audit). The conclusion holds regardless.

4. Fleet conformance. A fresh-context fleet audit found zero nonconformers among the 38 setup skills (all have disable-model-invocation: true + a check action; 35 offer apply; the 3 check-only — bug-report, dometrain, miro — are the sanctioned userConfig-only carve-out). Where teardown-like operations exist they are already apply-scoped arguments (songwriting: apply remove; machine-health: apply disable=/deprecate=/demote=/approve=), never separate lifecycle verbs — direct support for thread 1. The sharpened wording adds no requirement any existing skill violates, so this is doc-only. The lint-gap plugins (typos-format, go-format) already ship conforming check/apply setups. The only debt is two pre-existing missing-setup gaps (education userConfig-only; repo-hygiene single kill-switch) that predate #837's decisions and are a distinct concern → tracked in #988.

Fix

docs/PLUGIN-PHILOSOPHY.md "Setup is explicit and repeatable": adds the plugin-level decision, the closed verb set with the state-assessing/reconcile-and-report apply and the optional bounded teardown, and a paragraph reconciling the setup skill with the native Setup/SessionStart hook idioms the same section sanctions (complementary faces, native-first honored).

Verification

• Design independence: first-principles derivation → cross-vendor advisor pass → fresh-context adversarial stress-test (attacked all four threads; verdict "safe with specific fixes, no thread reopened"; C1/I1/I4/M1 folded into the doc text, I2/I5/M2/M3 into this rationale, I6 = ticket Fleet conformance: add setup skills for education + repo-hygiene (setup-requirement gap) #988 filed) → fresh-context independent review of the committed diff (rationale withheld).
• Fleet conformance (behavior, not just presence): spot-checked that no shipped apply overwrites blind — config-writing setups carry read-first/reconcile/preserve language; the thin formatter setups are check-centric (verify tool presence, report "already configured" on rerun, write no user-owned config). Zero conformance debt confirmed.
• Gate: markdownlint-cli2 docs/PLUGIN-PHILOSOPHY.md → 0 errors. No new links added. Emphasis/heading/list style conform (MD013 disabled repo-wide).

Locked design threads (memory-tier artifact, pasted for the durable record)

Empirical grounding (verified 2026-07-22, live fleet)

• 56 plugins; 38 ship a setup skill; 18 do not (all 18 are zero-config/zero-prereq knowledge/methodology plugins — contract-exempt).
• All 38 setup skills: name: setup + disable-model-invocation: true. 35 offer check+apply; 3 are check-only (bug-report, dometrain, miro) — all userConfig-only, the sanctioned carve-out.
• ZERO of 38 expose any top-level lifecycle verb beyond check/apply.
• Where teardown-like operations DO exist they are apply-scoped arguments, never separate verbs: songwriting: apply scaffold|remove, machine-health: apply disable=|deprecate=|demote=|approve=.
• No Setup or SessionStart hook event exists anywhere in the fleet today.
• True nonconformers to the check/apply + disable-model-invocation contract: NONE.

Source: fresh-context fleet audit (independent subagent) + direct grep verification.

Thread resolutions

Thread 1 (verbs). Contract stays two verbs, check + apply. apply state-assessing/reconciling; reset decomposes to teardown + apply; migrate rejected — clean-break (topic-docs "Adoption") generalized to setup config, a deliberately-named generalization. Teardown = optional apply-scoped apply remove, off the mandatory contract (rare, destructive, hand-reversible), with a second-adopter → owner-doc trigger.

Thread 2 (plugin-level). Re-derived from install-granularity (a plugin installs/configures as a unit; no native per-skill install anchor), single discoverable entry, shared cross-skill config surface, verb-per-skill naming grammar. The setup skill aggregates per-skill readiness.

Thread 3 (philosophy-doc). Kept in PLUGIN-PHILOSOPHY.md, not a new owner doc: setup is an intra-plugin uniform contract (like Naming/Cross-platform, also non-registry) whose rules are distributed across three neighboring sections; extraction would fragment them. Registry inclusion criterion is genuinely fuzzy at the edges (acknowledged, not redrawn here — out of scope).

Thread 4 (conformance). Zero nonconformers among 38; sharpened wording adds no requirement any existing skill violates → doc-only. Lint-gap plugins (typos-format, go-format) already conform. Two pre-existing missing-setup gaps (education, repo-hygiene) predate these decisions → tracked in #988.

Adversarial stress-test ledger (fresh-context; verdict: safe with specific fixes, no thread reopened)

• C1 (native Setup/SessionStart hooks vs mandated setup skill): complementary, not competing — skill = interactive consumer-config face no native hook exposes; hooks = unattended faces; native-first honored. Folded into the doc.
• I1 (unspecified "upgrade old shapes"): narrowed to preserve-unknown + fill-defaults + report-incompatible; no key translation. Folded into the doc.
• I2 (teardown trigger already fired?): songwriting apply remove is teardown-ish (ONE); machine-health apply disable=… is domain-data mutation, not teardown. Second-adopter trigger NOT yet met. Config-vs-data distinction folded into the doc.
• I3 (behavior audit, not presence): PASS — spot-checked no shipped apply overwrites blind (config-writers reconcile/preserve; formatter setups are check-centric).
• I4 (reversibility overgeneralized; apply remove vs pluginConfigs): teardown bounded to tracked project config, never pluginConfigs. Folded into the doc.
• I5 (thread-3 reasoning incumbency-flavored): re-derived on intra-plugin-contract vs inter-plugin-coordination; registry fuzziness acknowledged.
• I6 (follow-up must be filed): ticket Fleet conformance: add setup skills for education + repo-hygiene (setup-requirement gap) #988 filed with audit evidence.
• M1/M2/M3: teardown wording ("bare apply never removes"); install-granularity as thread-2's lead defense; "0/38 = grounds to defer with a trigger, not proof never needed."

Independent review (fresh-context, rationale withheld; verdict: ready with specific fixes)

Folded: #1 scope disable-model-invocation to setup (not plugin-wide absolute); #2 split the dense verb paragraph and move the pluginConfigs write-boundary/carve-out ahead of the teardown rule that leans on it; #3 disambiguate "no remove verb" vs apply remove at first mention; plus cheap in-section wins #4 (migrate-token collision), #6 (config-vs-data criterion stated before the example), #7 (trim mid-sentence bold). markdownlint: 0 errors.

Related

• Epic: lint/static-analysis gap closure #830 — parent epic (lint/static-analysis gap closure); Epic: setup-lifecycle convention (verbs, per-skill vs plugin setup, philosophy update) #837 was flagged there for its own design session.
• docs: add lint/static-analysis gaps brief #829 — the epic Brief / PLAN that named this setup-lifecycle thread.
• Fleet conformance: add setup skills for education + repo-hygiene (setup-requirement gap) #988 — follow-up filed by this work: add setup skills for education + repo-hygiene (pre-existing missing-setup gaps, not closed here).

Closes #837.

[claude]

Claude finished @kyle-sexton's task in 2m 4s —— View job

---

Review: docs(philosophy): lock setup-lifecycle convention

• Gather context
• Read the diff and changed file
• Review for correctness, clarity, and consistency with PLUGIN-PHILOSOPHY.md conventions
• Post findings

---

Scope: Doc-only change — one section of docs/PLUGIN-PHILOSOPHY.md (+45/−3). No code paths, no manifest changes, no links added.

---

Summary

The three new paragraphs (plugin-level, verb set, teardown) and the native-idioms complement paragraph are sound, well-grounded in the fleet audit, and consistent with the rest of the document's style. The structural choices are correct: the closed verb set is properly reasoned, apply remove as the teardown surface is consistent with the fleet's observed practice (songwriting, machine-health), and the native-idioms complement paragraph resolves the apparent tension without weakening either side.

The migrated → brought into conformance edit (L236) is a quiet improvement: "migrated" inadvertently echoed the rejected migrate verb. Good catch.

---

Findings

1. Hyphenated compound adjective is syntactically unusual — L257–258

which is what idempotent-and-preserve-unrelated-content already requires

idempotent-and-preserve-unrelated-content is being used as a compound noun-ified adjective to reference the prior bullet list. It reads correctly on close inspection, but the hyphen chain makes the first pass stumble. Rewording to something like "which is what the idempotency and preserve-unrelated-content requirements already mandate" or simply "which the existing bullet-list requirements already demand" would reduce parse friction.

Permalink:

claude-code-plugins/docs/PLUGIN-PHILOSOPHY.md

Lines 257 to 258 in 1a55b0b

	state and converges, which is what idempotent-and-preserve-unrelated-content already requires, named
	as a verb contract rather than a new bar. This subsumes forward schema evolution — an `apply` that

Fix this →

---

2. The teardown trigger has no stated enforcement — L281–282

a second plugin needing teardown graduates a shared teardown shape into an owner doc before that second adopter

The Convention Registry section (L328–330) establishes the same pattern ("A new cross-plugin convention lands in an owner doc before a second plugin adopts it"), so this is consistent. However, the registry's version is enforced by the fleet audit checking conformance per row; here the trigger has no stated enforcement path — a future auditor may not know to check for it.

Since songwriting's apply remove already exists as a first adopter, this trigger is live now. Either noting "the fleet audit checks for this" or acknowledging it rides the general fleet audit would close the gap. Minor, but the PR body's own thread 3 discussion calls the registry criterion "genuinely fuzzy at the edges" — this is the same fuzziness inside the new text itself.

Permalink:

claude-code-plugins/docs/PLUGIN-PHILOSOPHY.md

Lines 281 to 282 in 1a55b0b

	mandatory contract because it is destructive and, across the fleet today, unexercised — grounds to
	defer it with a trigger, not proof it is never needed: a second plugin needing teardown graduates a

---

3. "Satisfied in the interactive dimension" phrasing is slightly ambiguous — L300–301

The setup-skill requirement above is satisfied in the interactive dimension by the skill and may be complemented — never replaced — in the headless dimension by these idioms.

"Satisfied in the interactive dimension" could be parsed as "the requirement is only about the interactive dimension" rather than "the skill is the interactive-dimension fulfillment of the requirement." The requirement is that a setup skill exists at all; saying it's satisfied "in a dimension" reads as partial satisfaction. A tighter phrasing: "The setup skill fulfills the requirement; the headless dimension may be complemented — never replaced — by these native idioms."

Permalink: https://github.com/melodic-software/claude-code-plugins/blob/1a55b0b47b37f13293754cebe086c344dd50afdd/docs/PLUGIN-PHILOSOPHY.md#L300-L301

Fix this →

---

No issues found with

• Verb closure logic — check/apply as the only mandatory verbs is correctly stated; reset as a semantic decomposition (not a skill verb) is handled precisely.
• Schema evolution — fill-defaults + preserve-unknown + report-incompatible (L258–262) covers the relevant cases without overpromising key translation.
• Teardown boundary — bounded to tracked project config, never pluginConfigs; the distinction between teardown-of-setup-config vs. apply-scoped inventory mutation (L283–286) is correctly drawn and the machine-health pattern confirms it.
• Paragraph ordering — the section sequence (contract → verbs → write-permissions → teardown → native idioms) is coherent and each paragraph builds correctly on the last.
• markdownlint — formatting is consistent with the document's established style; no new external links introduced.

---

Verdict

Ready to merge with minor clarity fixes optional. Findings 1 and 3 are low-stakes rewording nits; finding 2 is a documentation gap that could be addressed here or tracked separately (similar to how #988 handles the missing-setup gaps). None of them affect the correctness of the design decisions or the fleet's conformance status.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a55b0b47b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 53s —— View job

---

Review: docs(philosophy): reconcile setup verb-set with versioned guided migration

• Gather context
• Read the full diff (origin/main...HEAD)
• Review the changed file
• Post findings

---

Scope: Second commit (b33cad9) on top of the 1a55b0b baseline. Doc-only, one file (+16/−12 on top of the first commit's +33/+3). The full section is reviewed below; findings from the prior review are re-verified.

---

Codex finding — resolved correctly

The Codex concern was that the absolute "clean-break stance extends to setup config" wording made /review:setup and /planning:setup internally contradictory, since their normative standards-contract binding defines a guided, versioned migration.

The new schema-evolution paragraph (L261–267) correctly resolves this without reopening any locked thread:

a plugin that versions its own config contract may carry a forward, directional, user-confirmed upgrade of a recognized older version — still under apply, never a separate verb and never a silent write (the versioned standards index is the fleet example) — while a plugin that instead takes topic-docs' clean-break path relocates by hand with no compatibility tooling. What the clean-break stance rules out for either is silent backward-compatibility shims and dual-read windows that translate a changed shape behind the user's back.

• "versioned," "forward, directional," and "user-confirmed" together correctly gate the allowed case: the plugin knows the old shape, the upgrade is one-way, and the user explicitly triggers it. No silent writes.
• The clean-break path is preserved as an equal alternative.
• Both paths agree on what is forbidden: silent shims and dual-read windows.
• "migrate" remains off the verb set; the mechanism lives under apply.

This is internally consistent with the reconcile-and-report rule above it and the write-permissions rule below.

Permalink:

claude-code-plugins/docs/PLUGIN-PHILOSOPHY.md

Lines 261 to 267 in b33cad9

	silently inert. Schema evolution is handled this way, without a separate `migrate` verb: a plugin
	that versions its own config contract may carry a forward, directional, user-confirmed upgrade of a
	recognized older version — still under `apply`, never a separate verb and never a silent write (the
	versioned standards index is the fleet example) — while a plugin that instead takes topic-docs'
	clean-break path relocates by hand with no compatibility tooling. What the clean-break stance rules
	out for either is silent backward-compatibility shims and dual-read windows that translate a changed
	shape behind the user's back. `reset` decomposes to teardown plus `apply`.

---

Prior review findings — all three resolved

Finding 1 (hyphenated compound adjective): Previous text idempotent-and-preserve-unrelated-content already requires → now the idempotency and preserve-unrelated-content requirements above already demand. Reads cleanly. ✓

Finding 2 (teardown trigger enforcement gap): Now reads a step the fleet conformance audit checks, the same enforcement every convention-registry row rides (L285–287). The enforcement path is explicit and consistent with the Convention Registry pattern. ✓

Finding 3 ("satisfied in the interactive dimension" ambiguity): Now reads The setup skill fulfills the setup-skill requirement above; the headless dimension may be complemented — never replaced — by these native idioms (L304–306). Unambiguously full satisfaction by the skill; native idioms are additive. ✓

---

No new issues found

• Verb closure integrity: The schema evolution carve-out does not introduce a new verb or a new mandatory contract surface. "User-confirmed" is a behavioral qualifier, not a verb. Thread 1 remains closed.
• Config vs. data distinction (L287–290): Correctly drawn and placed after the pluginConfigs boundary is established, so the reader already has the anchor when the criterion appears.
• reset decomposes to teardown plus apply (L267): Placement at the end of the verb paragraph is slightly abrupt, but consistent with the established doc style of terse terminal sentences.
• topic-docs' possessive (L264): Grammatically valid; the apostrophe placement on a compound noun is unusual but the meaning is unambiguous in context. Not worth changing.
• Paragraph ordering still holds: contract → verbs+schema-evolution → write-permissions → teardown → native idioms.
• markdownlint: Commit message confirms 0 errors.

---

Verdict

Ready to merge. The second commit cleanly addresses the Codex finding and all three prior review findings. No remaining issues. The schema-evolution carve-out is precisely scoped, internally consistent, and does not reopen any of the four locked threads.