feat(plugin): ship the ocf Claude Code plugin for framework consumers

[sourcehawk]

Description

Teams building operators with this framework get no assistance from AI coding agents beyond stale model memory, which invents builder methods and misses the structural guidelines. This PR ships a Claude Code plugin, named ocf, inside the repository: the repo root doubles as a plugin marketplace, so consumers install directly from this repo and Claude picks up accurate, version-grounded knowledge of the framework while they build their operators.

Changes

• plugin/ with the plugin manifest; .claude-plugin/marketplace.json at the repo root makes the repo installable via /plugin marketplace add sourcehawk/operator-component-framework followed by /plugin install ocf.
• Five skills mirroring the docs taxonomy (building-components, using-primitives, custom-resource-wrappers, structuring-operators, testing-operators): each pairs a distilled SKILL.md with mechanically synced copies of the relevant docs/ files, and instructs Claude to verify signatures with go doc against the consumer's resolved module version.
• Four commands: /ocf:docs (documentation lookup), /ocf:new-component and /ocf:new-wrapper (scaffolding dialogues), /ocf:review (dispatches the bundled reviewer agent).
• A read-only reviewer agent with a 22-item checklist derived one-to-one from docs/guidelines.md.
• make sync-plugin copies the mapped docs into the skill reference directories; a new CI job fails on any drift (including untracked additions) and runs claude plugin validate.
• docs/component.md now states two previously undocumented facts, verified against pkg/component source: registered resources are deleted in the same registration order used for reconciliation, and Build() requires WithName and WithConditionType with validation failures aggregated via errors.Join.
• Maintainer rules in .ai/base.md (regenerated instruction files included where tracked) and a README section documenting installation.

Challenges

Keeping the plugin honest was the core design problem: skill guidance drifts as the framework evolves. Three mechanisms address it: reference files are generated copies of docs/ (never hand-edited, CI-enforced), every skill carries a ground-truth section making go doc on the consumer's pinned version the final authority, and doc changes now sync in the same PR that makes them.

Testing

Each skill passed a retrieval test: a fresh agent without the skill could not answer three framework-specific check questions, while an agent reading only the SKILL.md and its references answered all of them correctly against the docs. The full suite (make all) passes, claude plugin validate . passes with zero warnings, and the sync drift check was negatively tested (a modified and an added docs file both fail CI, clean tree passes). A full local install cycle was exercised: marketplace add, plugin install, verification that all 33 skill files land in the installed layout, then uninstall.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a Claude Code plugin (“ocf”) to this repository so framework consumers can install version-grounded skills/commands/agents directly from the framework repo, and it wires CI + Makefile automation to keep the plugin’s bundled reference docs mechanically in sync with docs/.

Changes:

• Add a Claude Code plugin under plugin/ (manifest, skills + references, commands, and a reviewer agent) and a marketplace manifest at repo root.
• Add make sync-plugin to regenerate plugin reference docs from docs/, plus a CI job that fails on drift and validates the plugin.
• Update framework documentation and repo docs to describe the plugin and clarify component builder/deletion semantics.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
README.md	Documents plugin purpose, installation, and available /ocf:* commands.
docs/component.md	Documents builder validation aggregation (errors.Join) and deletion ordering semantics.
Makefile	Adds sync-plugin target to regenerate plugin reference docs from docs/.
.github/workflows/lint.yml	Adds a CI job to check plugin/doc sync drift and run claude plugin validate.
.github/copilot-instructions.md	Updates contributor guidance to include plugin sync/drift rules.
.claude-plugin/marketplace.json	Adds marketplace manifest so the repo can be installed as a plugin source.
.ai/base.md	Mirrors contributor guidance updates (including plugin sync/drift rules).
plugin/.claude-plugin/plugin.json	Defines the ocf plugin metadata (name/version/homepage/etc).
plugin/agents/reviewer.md	Adds a read-only “reviewer” agent with a guidelines checklist.
plugin/commands/docs.md	Adds /ocf:docs command for documentation lookup workflow.
plugin/commands/new-component.md	Adds /ocf:new-component scaffolding dialogue command.
plugin/commands/new-wrapper.md	Adds /ocf:new-wrapper scaffolding dialogue command.
plugin/commands/review.md	Adds /ocf:review command that dispatches the bundled reviewer agent.
plugin/skills/building-components/SKILL.md	Adds skill guidance for component building/lifecycle/status/guards.
plugin/skills/custom-resource-wrappers/SKILL.md	Adds skill guidance for wrapping CRD-backed types via pkg/generic.
plugin/skills/structuring-operators/SKILL.md	Adds skill guidance/checklist for operator structuring guidelines.
plugin/skills/testing-operators/SKILL.md	Adds skill guidance for mutation tests + golden/goldengen testing patterns.
plugin/skills/using-primitives/SKILL.md	Adds skill guidance for primitives, mutations, editors/selectors, SSA, etc.
plugin/skills/structuring-operators/references/compatibility.md	Generated copy of compatibility docs for plugin reference bundle.
plugin/skills/using-primitives/references/primitives/clusterrole.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/clusterrolebinding.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/configmap.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/cronjob.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/daemonset.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/deployment.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/ingress.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/job.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/networkpolicy.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/pdb.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/pod.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/pv.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/pvc.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/replicaset.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/role.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/rolebinding.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/secret.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/service.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/serviceaccount.md	Generated per-primitive reference doc for plugin bundle.
plugin/skills/using-primitives/references/primitives/statefulset.md	Generated per-primitive reference doc for plugin bundle.

[Copilot]

Pull request overview

Copilot reviewed 46 out of 46 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/lint.yml:56

• npm install -g @anthropic-ai/claude-code is unpinned, so CI behavior can change (and start failing) when the upstream CLI publishes a new release. For reproducible CI (and to match the repo's existing pattern of pinning tool versions like Prettier in the Makefile), pin Claude Code to an explicit version and bump it intentionally when needed.

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Validate plugin and marketplace
        run: claude plugin validate .

[Copilot]

Pull request overview

Copilot reviewed 46 out of 46 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/component.md:264

• Step 7 claims delete-flagged resources are deleted "in the same registration order used for reconciliation", but the implementation deletes c.deleteResources (and, for feature-gate disable, allManagedResources() iterates managed reconcile resources first, then delete resources). That means deletion order is not necessarily the same as overall WithResource registration order when delete entries are interleaved. Please reword to match the actual behavior (deleted in the slice/registration order and not reversed).

7. **Resource deletion.** Resources registered for deletion are removed from the cluster, in the same registration order
   used for reconciliation; the framework does not reverse it.

Makefile:110

• make sync-plugin copies docs/primitives/*.md into plugin/skills/using-primitives/references/primitives/, but those files contain relative links like ../component.md#declared-data (e.g. the generated serviceaccount.md). In the plugin layout there is no plugin/skills/using-primitives/references/component.md, so these references are broken after sync. Consider copying docs/component.md into the using-primitives references as well so existing relative links continue to resolve in the installed plugin tree.

	cp docs/component.md $(PLUGIN_SKILLS)/building-components/references/component.md
	cp docs/primitives.md $(PLUGIN_SKILLS)/using-primitives/references/primitives.md
	cp docs/primitives/*.md $(PLUGIN_SKILLS)/using-primitives/references/primitives/
	cp docs/custom-resource.md $(PLUGIN_SKILLS)/custom-resource-wrappers/references/custom-resource.md