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

.ai/base.md

@@ -92,18 +92,29 @@ semantics. GoDoc is part of the public API surface.
 
 Update documentation in the **same response** as the code change — never leave them out of sync.
 
-| Code area changed                                 | Documentation to update   |
-| ------------------------------------------------- | ------------------------- |
-| Component builder, reconciliation, status model   | `docs/component.md`       |
-| Primitives, field application, editors, selectors | `docs/primitives.md`      |
-| Primitive implementations                         | `docs/primitives/*.md`    |
-| Generic building blocks, custom resource wrappers | `docs/custom-resource.md` |
-| Operator structuring patterns, best practices     | `docs/guidelines.md`      |
-| Any `pkg/` export visible in the quick start      | `README.md`               |
-| Examples                                          | `examples/*/README.md`    |
+| Code area changed                                 | Documentation to update                    |
+| ------------------------------------------------- | ------------------------------------------ |
+| Component builder, reconciliation, status model   | `docs/component.md`                        |
+| Primitives, field application, editors, selectors | `docs/primitives.md`                       |
+| Primitive implementations                         | `docs/primitives/*.md`                     |
+| Generic building blocks, custom resource wrappers | `docs/custom-resource.md`                  |
+| Operator structuring patterns, best practices     | `docs/guidelines.md`                       |
+| Any `pkg/` export visible in the quick start      | `README.md`                                |
+| Examples                                          | `examples/*/README.md`                     |
+| Any file under `docs/` synced into the plugin     | Run `make sync-plugin` (CI fails on drift) |
 
 When updating documentation in markdown files, make sure to run `make fmt-md` for consistent formatting.
 
+### Claude Code plugin
+
+The repository ships a Claude Code plugin for framework consumers in `plugin/` (marketplace manifest at
+`.claude-plugin/marketplace.json`). Two rules keep it accurate:
+
+- Files under `plugin/skills/*/references/` are generated copies of `docs/` files. Never edit them by hand; edit the
+  source under `docs/` and run `make sync-plugin`.
+- When changing public API behaviour, check whether the distilled guidance in the affected `plugin/skills/*/SKILL.md` is
+  stale and update it in the same response.
+
 ### Examples
 
 If you change a method signature, type name, or behaviour in `pkg/`, search `examples/` for usages and update them.

.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "operator-component-framework",
+  "description": "Claude Code plugin marketplace for the operator-component-framework.",
+  "owner": {
+    "name": "sourcehawk",
+    "url": "https://github.com/sourcehawk"
+  },
+  "plugins": [
+    {
+      "name": "ocf",
+      "source": "./plugin",
+      "description": "Skills, scaffolding commands, and a guidelines reviewer for building Kubernetes operators with the operator-component-framework.",
+      "category": "development"
+    }
+  ]
+}

.github/copilot-instructions.md

@@ -92,18 +92,29 @@ semantics. GoDoc is part of the public API surface.
 
 Update documentation in the **same response** as the code change — never leave them out of sync.
 
-| Code area changed                                 | Documentation to update   |
-| ------------------------------------------------- | ------------------------- |
-| Component builder, reconciliation, status model   | `docs/component.md`       |
-| Primitives, field application, editors, selectors | `docs/primitives.md`      |
-| Primitive implementations                         | `docs/primitives/*.md`    |
-| Generic building blocks, custom resource wrappers | `docs/custom-resource.md` |
-| Operator structuring patterns, best practices     | `docs/guidelines.md`      |
-| Any `pkg/` export visible in the quick start      | `README.md`               |
-| Examples                                          | `examples/*/README.md`    |
+| Code area changed                                 | Documentation to update                    |
+| ------------------------------------------------- | ------------------------------------------ |
+| Component builder, reconciliation, status model   | `docs/component.md`                        |
+| Primitives, field application, editors, selectors | `docs/primitives.md`                       |
+| Primitive implementations                         | `docs/primitives/*.md`                     |
+| Generic building blocks, custom resource wrappers | `docs/custom-resource.md`                  |
+| Operator structuring patterns, best practices     | `docs/guidelines.md`                       |
+| Any `pkg/` export visible in the quick start      | `README.md`                                |
+| Examples                                          | `examples/*/README.md`                     |
+| Any file under `docs/` synced into the plugin     | Run `make sync-plugin` (CI fails on drift) |
 
 When updating documentation in markdown files, make sure to run `make fmt-md` for consistent formatting.
 
+### Claude Code plugin
+
+The repository ships a Claude Code plugin for framework consumers in `plugin/` (marketplace manifest at
+`.claude-plugin/marketplace.json`). Two rules keep it accurate:
+
+- Files under `plugin/skills/*/references/` are generated copies of `docs/` files. Never edit them by hand; edit the
+  source under `docs/` and run `make sync-plugin`.
+- When changing public API behaviour, check whether the distilled guidance in the affected `plugin/skills/*/SKILL.md` is
+  stale and update it in the same response.
+
 ### Examples
 
 If you change a method signature, type name, or behaviour in `pkg/`, search `examples/` for usages and update them.

.github/workflows/lint.yml

@@ -28,4 +28,29 @@ jobs:
             nodejs
 
       - name: Run linter
-        run: make lint
+        run: make lint
+
+  plugin:
+    name: Validate Claude plugin
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@v6
+
+      - name: Install tools with asdf
+        uses: asdf-vm/actions/install@v4
+        with:
+          only: nodejs
+
+      - name: Check plugin references are in sync with docs
+        run: |
+          make sync-plugin
+          git add -A plugin
+          git status --porcelain plugin
+          git diff --cached --exit-code -- plugin
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate plugin and marketplace
+        run: claude plugin validate .

Makefile

@@ -90,6 +90,28 @@ fmt-go: ## Format Go source files.
 fmt-md: prettier ## Format Markdown files.
 	$(PRETTIER) --write '**/*.md' --ignore-path .gitignore
 
+PLUGIN_SKILLS := plugin/skills
+
+.PHONY: sync-plugin
+sync-plugin: ## Sync framework docs into the Claude plugin skill references.
+	rm -rf $(PLUGIN_SKILLS)/building-components/references \
+		$(PLUGIN_SKILLS)/using-primitives/references \
+		$(PLUGIN_SKILLS)/custom-resource-wrappers/references \
+		$(PLUGIN_SKILLS)/structuring-operators/references \
+		$(PLUGIN_SKILLS)/testing-operators/references
+	mkdir -p $(PLUGIN_SKILLS)/building-components/references \
+		$(PLUGIN_SKILLS)/using-primitives/references/primitives \
+		$(PLUGIN_SKILLS)/custom-resource-wrappers/references \
+		$(PLUGIN_SKILLS)/structuring-operators/references \
+		$(PLUGIN_SKILLS)/testing-operators/references
+	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
+	cp docs/guidelines.md $(PLUGIN_SKILLS)/structuring-operators/references/guidelines.md
+	cp docs/compatibility.md $(PLUGIN_SKILLS)/structuring-operators/references/compatibility.md
+	cp docs/testing.md $(PLUGIN_SKILLS)/testing-operators/references/testing.md
+
 .PHONY: prettier
 prettier: $(PRETTIER) ## Download prettier locally if necessary.
 $(PRETTIER): $(LOCALBIN)

README.md

@@ -100,6 +100,21 @@ Full documentation, including a step-by-step tutorial, is at
 
 The full Go API reference is on [pkg.go.dev](https://pkg.go.dev/github.com/sourcehawk/operator-component-framework).
 
+## Claude Code plugin
+
+The repository ships a [Claude Code](https://code.claude.com) plugin that teaches Claude the framework's concepts and
+idioms: skills for components, primitives, custom resource wrappers, operator structure, and testing, plus scaffolding
+commands and a guidelines reviewer.
+
+Install it from this repository:
+
+```
+/plugin marketplace add sourcehawk/operator-component-framework
+/plugin install ocf
+```
+
+Then use `/ocf:docs <topic>`, `/ocf:new-component`, `/ocf:new-wrapper`, and `/ocf:review` inside your operator project.
+
 ## Contributing
 
 Contributions are welcome. Open an issue to discuss significant changes before submitting a pull request. New code

docs/component.md

@@ -26,6 +26,10 @@ For operator-structuring advice (one component per condition, thin controllers,
 Components are constructed through a builder. The builder collects resource registrations, configuration, and lifecycle
 flags, then produces an immutable `Component` ready for reconciliation.
 
+`Build()` requires `WithName` and `WithConditionType`; every other builder method is optional. If either is missing, or
+any registered resource fails validation, `Build()` returns a single aggregated error containing every failure, using
+`errors.Join`.
+
 ```go
 comp, err := component.NewComponentBuilder().
     WithName("frontend").
@@ -256,7 +260,8 @@ reconcile can be observed during this one.
 6. **Condition update.** A new component condition is derived from the aggregate resource status, the previous
    condition, and the configured grace period, then written to the owner **in memory only**. `Reconcile` never calls the
    Kubernetes status API; the controller persists with [`FlushStatus`](#persisting-status-with-flushstatus).
-7. **Resource deletion.** Resources registered for deletion are removed from the cluster.
+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.
 
 ```mermaid
 flowchart TD

plugin/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "ocf",
+  "displayName": "Operator Component Framework",
+  "version": "0.1.0",
+  "description": "Skills, scaffolding commands, and a guidelines reviewer for building Kubernetes operators with the operator-component-framework.",
+  "author": {
+    "name": "sourcehawk",
+    "url": "https://github.com/sourcehawk"
+  },
+  "homepage": "https://sourcehawk.github.io/operator-component-framework/",
+  "repository": "https://github.com/sourcehawk/operator-component-framework",
+  "license": "Apache-2.0",
+  "keywords": ["kubernetes", "operator", "controller-runtime", "go"]
+}